Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

PLINK-427: IDP with TOS #15

Merged
merged 1 commit into from
May 7, 2014
Merged

PLINK-427: IDP with TOS #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
183 changes: 183 additions & 0 deletions picketlink-federation-saml-idp-terms/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,183 @@
picketlink-federation-saml-idp-terms: PicketLink Identity Provider Using a Servlet Filter and a Terms of Service Page
===============================
Author: Anil Saldhana
Level: Intermediate
Technologies: PicketLink Federation, SAML v2.0
Summary: Basic example that demonstrates how to setup an application as a SAML v2.0 Identity Provider Using a Servlet Filter.
After authentication at the Identity Provider, the user is presented a Terms of Service page where he/she can choose to accept
or reject the TOS.
Source: <https://github.com/picketlink/picketlink-quickstarts/>


What is it?
-----------

This example demonstrates the use of *PicketLink Federation* SAML v2.0 support to setup an application as an Identity Provider in *JBoss Enterprise Application Platform 6* or *WildFly*.

It provides a minimal configuration to enable your application as an Identity Provider, accordingly with the SAML v2.0 specification. An Identity Provider or IdP, is responsible to centralize authentication and issue SAML Assertions to their relying parties, also known as Service Providers.
PicketLink supports both SAML v1.1 and v2.0 versions.

Usually, the IdP is configured using a specific [PicketLink Authenticator](https://docs.jboss.org/author/display/PLINK/SAML+Authenticators+%28Tomcat%2CJBossAS%29).
But you can also use a simple JEE Servlet Filter to turn any application into an IdP. This example demonstrates how
you can use the PicketLink *IDPFilter* to achieve that.
In addition, this quickstart configures the TermsOfService servlet filter.

Although this example provides you a good start to understand how an Identity Provider works, it does not provide some other important security-related configurations such as signature and encryption.
We strongly recommend you to read our documentation about how to make your deployment safe and secure from a SAML perspective.

Before you run this example, you must have a security-domain configuration in your server to authenticate users and provide role mappings.

You can checkout the SAML v2.0 specification from [here](http://saml.xml.org/saml-specifications). We strongly recommend you to spend some time understanding at least the basic core concepts from it.

The latest PicketLink documentation is available [here](http://docs.jboss.org/picketlink/2/latest/).

*Note: An Identity Provider alone is not very useful without some Service Providers. Once you get this application deployed, please take a look at [About the PicketLink Federation Quickstarts](../README.md#about-the-picketlink-federation-quickstarts).*

System requirements
-------------------

All you need to build this project is Java 6.0 (Java SDK 1.6) or better, Maven 3.0 or better.

The application this project produces is designed to be run on JBoss Enterprise Application Platform 6 or WildFly.


Configure Maven
---------------

If you have not yet done so, you must [Configure Maven](http://www.jboss.org/jdf/quickstarts/jboss-as-quickstart/#configure_maven) before testing the quickstarts.

Create the Security Domain
---------------

These steps assume you are running the server in standalone mode and using the default standalone.xml supplied with the distribution.

You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-security-domain.cli` script provided in the root directory of this quickstart.

1. Before you begin, back up your server configuration file
* If it is running, stop the JBoss server.
* Backup the file: `JBOSS_HOME/standalone/configuration/standalone.xml`
* After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.

2. Start the JBoss server by typing the following:

For Linux: JBOSS_HOME/bin/standalone.sh
For Windows: JBOSS_HOME\bin\standalone.bat
3. Review the `configure-security-domain.cli` file in the root of this quickstart directory. This script adds the `idp` domain to the `security` subsystem in the server configuration and configures authentication access. Comments in the script describe the purpose of each block of commands.

4. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing JBOSS_HOME with the path to your server:

JBOSS_HOME/bin/jboss-cli.sh --connect --file=configure-security-domain.cli
You should see the following result when you run the script:

#1 /subsystem=security/security-domain=idp:add(cache-type=default)
#2 /subsystem=security/security-domain=idp/authentication=classic:add
#3 /subsystem=security/security-domain=idp/authentication=classic/login-module=UsersRoles:add(code=UsersRoles,flag=required,module-options=[usersProperties=users.properties,rolesProperties=roles.properties])
The batch executed successfully.
{"outcome" => "success"}


Review the Modified Server Configuration
-----------------------------------

If you want to review and understand newly added XML configuration, stop the JBoss server and open the `JBOSS_HOME/standalone/configuration/standalone.xml` file.

The following `idp` security-domain was added to the `security` subsystem.

<security-domain name="idp" cache-type="default">
<authentication>
<login-module code="UsersRoles" flag="required">
<module-option name="usersProperties" value="users.properties"/>
<module-option name="rolesProperties" value="roles.properties"/>
</login-module>
</authentication>
</security-domain>

The configuration above defines a security-domain which will be used by the IdP to authenticate users. This is a very simple configuration,
using a JAAS LoginModule that reads users and their corresponding roles from properties files. Both properties files, *users.properties*
and *roles.properties* are located at *src/main/resources* directory.

In a real world scenario your users and roles will not be located in properties files, but in LDAP, databases or whatever,
depending where your identity data is located.

SAML v1.1 and v2.0 IdP-Initiated Single Sign-On
-----------------------------------

Both versions of the SAML specification define a specific SSO mode called *IdP-Initiated SSO*. For more details, please take a look at the documentation below:

1. [SAML v1.1 IdP-Initiated SSO](https://docs.jboss.org/author/display/PLINK/SAML+v1.1)
2. [SAML v2.0 Unsolicited Responses](https://docs.jboss.org/author/display/PLINK/Unsolicted+Responses)

_NOTE: In order to test how this SSO mode works you must have at least one Service Provider deployed. We provide a plenty of SP example applications
along with our quickstarts, please read their instructions about how to build and deploy them.

SAML SP-Initiated Single Sign-On
-----------------------------------

The SAML v2.0 specification defines a specific SSO mode called *SP-Initiated SSO*. In this mode, the SSO flow starts at the Service Provider side.
Please, take a look at the following documentation for more details:

1. [SAML v2.0 SP-Initiated SSO](https://docs.jboss.org/author/display/PLINK/SP-Initiated+SSO)

_NOTE: In order to test how this SSO mode works you must have at least one Service Provider deployed. We provide a plenty of SP example applications
along with our quickstarts, please read their instructions about how to build and deploy them.

Start JBoss Enterprise Application Platform 6 or WildFly with the Web Profile
-------------------------

1. Open a command line and navigate to the root of the JBoss server directory.
2. The following shows the command line to start the server with the web profile:

For Linux: JBOSS_HOME/bin/standalone.sh
For Windows: JBOSS_HOME\bin\standalone.bat


Build and Deploy the Quickstart
-------------------------

_NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See [Build and Deploy the Quickstarts](../README.md#build-and-deploy-the-quickstarts) for complete instructions and additional options._

1. Make sure you have started the JBoss Server as described above.
2. Open a command line and navigate to the root directory of this quickstart.
3. Type this command to build and deploy the archive:

For EAP 6: mvn clean package jboss-as:deploy
For WildFly: mvn -Pwildfly clean package wildfly:deploy

4. This will deploy `target/picketlink-federation-saml-idp-terms.war` to the running instance of the server.


Access the application
---------------------

The application will be running at the following URL: <http://localhost:8080/idp>.

The IdP is pre-configured with a default user, whose credentials are:

Username: tomcat
Password: tomcat

*Note: An Identity Provider alone is not very useful without some Service Providers. Once you get this application deployed, please take a look at [About the PicketLink Federation Quickstarts](../README.md#about-the-picketlink-federation-quickstarts).*

Undeploy the Archive
--------------------

1. Make sure you have started the JBoss Server as described above.
2. Open a command line and navigate to the root directory of this quickstart.
3. When you are finished testing, type this command to undeploy the archive:

For EAP 6: mvn jboss-as:undeploy
For WildFly: mvn -Pwildfly wildfly:undeploy


Run the Quickstart in JBoss Developer Studio or Eclipse
-------------------------------------
You can also start the server and deploy the quickstarts from Eclipse using JBoss tools. For more information, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](../README.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts)


Debug the Application
------------------------------------

If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them.

mvn dependency:sources
mvn dependency:resolve -Dclassifier=javadoc
16 changes: 16 additions & 0 deletions picketlink-federation-saml-idp-terms/configure-security-domain.cli
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Batch script to add and configure the quickstart-domain security domain in the JBoss server

# Start batching commands
batch

# Add and configure the security domain, then add the UsersRoles JAAS LoginModule.
/subsystem=security/security-domain=idp:add(cache-type=default)
/subsystem=security/security-domain=idp/authentication=classic:add
/subsystem=security/security-domain=idp/authentication=classic/login-module=UsersRoles:add(code=UsersRoles,flag=required,module-options=[usersProperties=users.properties,rolesProperties=roles.properties])

# Run the batch commands
run-batch

# Reload the server configuration
:reload

143 changes: 143 additions & 0 deletions picketlink-federation-saml-idp-terms/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>

<groupId>org.picketlink.quickstarts</groupId>
<artifactId>picketlink-federation-saml-idp-terms</artifactId>
<version>2.6.0-SNAPSHOT</version>

<packaging>war</packaging>

<name>PicketLink Quickstart: picketlink-federation-saml-idp-terms</name>
<description>PicketLink Quickstart: PicketLink Identity Provider Using a Terms of Service Filter</description>

<url>http://www.picketlink.org</url>

<licenses>
<license>
<name>Apache License, Version 2.0</name>
<distribution>repo</distribution>
<url>http://www.apache.org/licenses/LICENSE-2.0.html</url>
</license>
</licenses>

<properties>
<!-- JBoss AS dependency versions -->
<version.jboss.maven.plugin>7.4.Final</version.jboss.maven.plugin>

<!-- WildFly dependency versions -->
<version.wildfly.maven.plugin>1.0.1.Final</version.wildfly.maven.plugin>

<!-- PicketLink dependency versions -->
<version.picketlink.javaee.bom>2.6.0-SNAPSHOT</version.picketlink.javaee.bom>

<!-- Default target container. -->
<target.container>jboss-eap</target.container>

<!-- maven-war-plugin -->
<version.war.plugin>2.1.1</version.war.plugin>

<!-- maven-compiler-plugin -->
<version.compiler.plugin>3.1</version.compiler.plugin>
<maven.compiler.target>1.6</maven.compiler.target>
<maven.compiler.source>1.6</maven.compiler.source>
</properties>

<dependencyManagement>
<dependencies>
<!-- Dependency Management for PicketLink and Java EE 6.0. -->
<dependency>
<groupId>org.picketlink</groupId>
<artifactId>picketlink-javaee-6.0</artifactId>
<version>${version.picketlink.javaee.bom}</version>
<scope>import</scope>
<type>pom</type>
</dependency>
</dependencies>
</dependencyManagement>

<dependencies>
<!-- Import the Servlet API, we use provided scope as the API is included in
JBoss AS 7 -->
<dependency>
<groupId>org.jboss.spec.javax.servlet</groupId>
<artifactId>jboss-servlet-api_3.0_spec</artifactId>
<scope>provided</scope>
</dependency>
<!-- Import the PicketLink API, we deploy this as library with the application,
and can compile against it -->
<dependency>
<groupId>org.picketlink</groupId>
<artifactId>picketlink-api</artifactId>
</dependency>

</dependencies>

<build>
<!-- Set the name of the war, used as the context root when the app is deployed -->
<finalName>${project.artifactId}</finalName>
<resources>
<resource>
<directory>src/main/resources</directory>
</resource>
<resource>
<directory>../picketlink-federation-saml-idp-basic/src/main/resources</directory>
</resource>
</resources>
<plugins>
<plugin>
<artifactId>maven-war-plugin</artifactId>
<version>${version.war.plugin}</version>
<configuration>
<!-- Java EE 6 doesn't require web.xml, Maven needs to catch up! -->
<failOnMissingWebXml>false</failOnMissingWebXml>

<classifier>${target.container}</classifier>

<!-- Instead of duplicating resources for each example application, we just reuse all resources from the
base application. -->
<webResources>
<resource>
<directory>src/main/webapp</directory>
</resource>
<resource>
<directory>../picketlink-federation-saml-idp-basic/src/main/webapp</directory>
</resource>
</webResources>
</configuration>
</plugin>
<!-- JBoss AS plugin to deploy war -->
<plugin>
<groupId>org.jboss.as.plugins</groupId>
<artifactId>jboss-as-maven-plugin</artifactId>
<version>${version.jboss.maven.plugin}</version>
<!-- TODO: Remove once EAP 6.3 is released. The IDPFilter does not exists on PL version shipped with previous EAP versions. -->
<configuration>
<skip>true</skip>
</configuration>
</plugin>
</plugins>
</build>

<profiles>
<profile>
<id>wildfly</id>
<properties>
<target.container>wildfly</target.container>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.wildfly.plugins</groupId>
<artifactId>wildfly-maven-plugin</artifactId>
<version>${version.wildfly.maven.plugin}</version>
<configuration>
<filename>${project.build.finalName}-${target.container}.${project.packaging}</filename>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>

</project>
13 changes: 13 additions & 0 deletions picketlink-federation-saml-idp-terms/remove-security-domain.cli
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Batch script to remove the quickstart-domain security domain from the JBoss server

# Start batching commands
batch

# Remove the security domain
/subsystem=security/security-domain=idp:remove

# Run the batch commands
run-batch

# Reload the server configuration
:reload