Chapter 2. How To Set Up SSO with SAML v2

1. Create a security domain for an IDP.

   The IDP handles challenging a principal for their credentials, handling the authentication and authorization of that principal, and issuing the proper SAML v2 security assertions based on the result. This requires that an identity store be configured using a security domain. The only requirement around creating this security domain and identity store is that it has authentication and authorization mechanisms properly defined. This means that many different identity stores — for example, properties file, database, or LDAP — and their associated login modules, could be used to support an IDP application. For more information on security domains, see the Security Domains section of the JBoss EAP Security Architecture guide.

   The following example uses a simple UsersRoles login module using properties files.

   Management CLI Commands for Creating a Security Domain

   /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=${jboss.server.config.dir}/idp-users.properties,rolesProperties=${jboss.server.config.dir}/idp-roles.properties])
   
   reload

   The UsersRoles login module utilizes properties files to store the user/password and user/role information. For more information on the UsersRoles module, see the JBoss EAP Login Module Reference. In this example, the properties files contain the following:

   idp-users.properties

   Eric=samplePass
   Alan=samplePass

   idp-roles.properties

   Eric=All
   Alan=

2. Configure the web.xml file for an IDP.

   The web.xml file for an IDP must contain the following:

   • A <security-constraint> with a <web-resource-collection> containing a <url-pattern> that maps to the URL pattern of the secured area. Optionally, <security-constraint> can also contain an <auth-constraint> stipulating the allowed roles.
   • A <login-config> configured for FORM authentication.
   • If any roles were specified in <auth-constraint>, those roles should be defined in a <security-role>.
   • Optionally, resources used by the login form, for example images and styles, can be specified by an additional security constraint to be unsecured so they can be accessed prior to authentication, for example on the login page.

   The <security-constraint> and <security-role> elements enable administrators to setup restricted or unrestricted areas based on URL patterns and roles. This allows resources to be secured or unsecured.

   The <login-config> tag defines the login and error pages used by the IDP when authenticating users.

   Example web.xml file:

   <web-app>
     <display-name>IDP</display-name>
     <description>IDP</description>
     <!-- Define a security constraint that gives unlimited access to images -->
     <security-constraint>
       <web-resource-collection>
         <web-resource-name>Images</web-resource-name>
         <url-pattern>/images/*</url-pattern>
       </web-resource-collection>
     </security-constraint>
     <!-- Define a security constraint that requires the All role to access resources -->
     <security-constraint>
       <web-resource-collection>
         <web-resource-name>IDP</web-resource-name>
         <url-pattern>/*</url-pattern>
       </web-resource-collection>
       <auth-constraint>
         <role-name>All</role-name>
       </auth-constraint>
     </security-constraint>
     <!-- Define the Login Configuration for this Application -->
     <login-config>
       <auth-method>FORM</auth-method>
       <realm-name>IDP Application</realm-name>
       <form-login-config>
         <form-login-page>/jsp/login.jsp</form-login-page>
         <form-error-page>/jsp/error.jsp</form-error-page>
       </form-login-config>
     </login-config>
     <!-- Security roles referenced by this web application -->
     <security-role>
       <description>The role that is required to log in to the IDP Application</description>
       <role-name>All</role-name>
     </security-role>
   </web-app>

   Note

   It is recommended that a welcome page is defined in the application. By default, JBoss EAP will look for a file named index.jsp, but this can be configured using <welcome-file-list> in web.xml.

   Example login.jsp file:

   <html>
     <head></head>
     <body>
       <form id="login_form" name="login_form" method="post" action="j_security_check" enctype="application/x-www-form-urlencoded">
         <center> <p>Welcome to the <b>IDP</b></p> <p>Please login to proceed.</p> </center>
         <div style="margin-left: 15px;">
           <p> <label for="username">Username</label> <br /> <input id="username" type="text" name="j_username"/> </p>
           <p> <label for="password">Password</label> <br /> <input id="password" type="password" name="j_password" value=""/> </p>
           <center> <input id="submit" type="submit" name="submit" value="Login"/> </center>
         </div>
       </form>
     </body>
   </html>

   Example error.jsp file:

   <html>
     <head></head>
     <body>
       <p>Login failed, please go back and try again.</p>
     </body>
   </html>

3. Configure the authenticator for an IDP.

   The authenticator is responsible for the authentication of users and for issuing and validating SAML v2 security assertions. Part of the authenticator is configured in the jboss-web.xml file by defining the security domain to be used in authenticating and authorizing principals (see Step 1). You also must ensure that a <login-config> is specified in the web.xml and the necessary dependencies have been declared.

   The jboss-web.xml file must have the following:

   • A <security-domain> to specify which security domain to use for authentication and authorization.

   Example jboss-web.xml File

   <jboss-web>
     <security-domain>idp</security-domain>
     <context-root>identity</context-root>
   </jboss-web>

4. Declare the necessary dependencies for an IDP.

   The web application serving as the IDP requires a dependency to be defined in jboss-deployment-structure.xml, so that the org.picketlink classes can be located. JBoss EAP provides all necessary org.picketlink and related classes, and the application only needs to declare them as dependencies to use them.

   Using jboss-deployment-structure.xml to Declare Dependencies

   <jboss-deployment-structure>
     <deployment>
       <dependencies>
         <module name="org.picketlink" services="import"/>
       </dependencies>
     </deployment>
   </jboss-deployment-structure>

   Note

   In previous versions of JBoss EAP, you would have declared this same dependency, but would have declared a valve to install the SAML authenticators. With the introduction of Undertow in JBoss EAP 7, you now use services="import" to install the SAML authenticators.

5. Create and configure a picketlink.xml file for an IDP.

   The picketlink.xml file is responsible for the behavior of the Authenticator and is loaded at the application’s startup.

   The file must contain at least the following elements:

   • <PicketLinkIDP> defining the URL of the IDP, using <IdentityURL>, and any hosts trusted by the IDP.
   • <Handlers> defining the set of handlers needed for processing the SAML requests and responses.

   Example picketlink.xml File

   <PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
     <PicketLinkIDP xmlns="urn:picketlink:identity-federation:config:2.1">
       <IdentityURL>${idp.url::http://localhost:8080/identity/}</IdentityURL>
       <Trust>
         <Domains>localhost,example.com</Domains>
       </Trust>
     </PicketLinkIDP>
     <Handlers xmlns="urn:picketlink:identity-federation:handler:config:2.1">
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2IssuerTrustHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.RolesGenerationHandler" />
     </Handlers>
   </PicketLink>

   Warning

   Handlers are implemented using a Chain of Responsibility, with each individual handler performing logic on request and responses in the order defined in picketlink.xml. It is very important to pay attention to the order in which the handlers are configured.

   By default, picketlink.xml is located in the WEB-INF directory of the IDP web application. However, a custom path to picketlink.xml that is external to the application can be configured. This is useful in cases where multiple applications across one or more JBoss EAP instances share the same picketlink.xml configuration.

6. Optional: Setting a custom location for picketlink.xml

   You can specify a custom location for the picketlink.xml using the CONFIG_FILE parameter. This is done by adding a <context-param> element to the web.xml.

   Using the CONFIG_FILE Parameter

   <context-param>
     <param-name>CONFIG_FILE</param-name>
     <param-value>/path/to/picketlink.xml</param-value>
   </context-param>

   You can also use the org.picketlink.federation.saml.CONFIG_PROVIDER parameter to specify a custom configuration provider. This allows you to create a custom implementation that extends org.picketlink.identity.federation.web.util.SAMLConfigurationProvider to provide your own configuration logic.

   Using the org.picketlink.federation.saml.CONFIG_PROVIDER Parameter

   <context-param>
     <param-name>org.picketlink.federation.saml.CONFIG_PROVIDER</param-name>
     <param-value>MyConfigurationProvider</param-value>
   </context-param>

   Note

   The management CLI commands shown assume that you are running a JBoss EAP standalone server. For more details on using the management CLI for a JBoss EAP managed domain, see the JBoss EAP Management CLI Guide.

1. Configure a security domain for an SP.

   Since the IDP handles challenging the user for their credentials and issuing SAML v2 security assertions, the SP is in charge of validating those assertions. A security domain is still needed to perform this validation, but an identity store is not. In this case, the security domain for the SP must use SAML2LoginModule.

   Management CLI Commands for Adding Security Domain

   /subsystem=security/security-domain=sp:add(cache-type=default)
   
   /subsystem=security/security-domain=sp/authentication=classic:add
   
   /subsystem=security/security-domain=sp/authentication=classic/login-module=org.picketlink.identity.federation.bindings.jboss.auth.SAML2LoginModule:add(code=org.picketlink.identity.federation.bindings.jboss.auth.SAML2LoginModule,flag=required)
   
   reload

   Warning

   The SAML2LoginModule is intended for use only with applications using PicketLink with SAML, and should not be used without the PicketLink Service Provider Undertow ServletExtension (org.picketlink.identity.federation.bindings.wildfly.sp.SPServletExtension). Doing so presents a possible security risk, as SAML2LoginModule or SAML2CommonLoginModule will always accept the default password of EMPTY_STR. For example, this can also occur if the PicketLink Service Provider Undertow ServletExtension is not installed in the SP application. The PicketLink Service Provider Undertow ServletExtension is installed automatically when configuring the SP application for JBoss EAP. This can also occur if SAML2LoginModule is stacked with other login modules:

   <security-domain name="sp" cache-type="default">
     <authentication>
       <login-module code="org.picketlink.identity.federation.bindings.jboss.auth.SAML2LoginModule" flag="optional">
         <module-option name="password-stacking" value="useFirstPass"/>
       </login-module>
       <login-module code="UsersRoles" flag="required">
         <module-option name="usersProperties" value="users.properties"/>
         <module-option name="rolesProperties" value="roles.properties"/>
         <module-option name="password-stacking" value="useFirstPass"/>
       </login-module>
     </authentication>
   </security-domain>

   SAML2LoginModule is used to build a security context for a user based on assertions. The PicketLink SAML Authenticator, which is installed by the PicketLink Service Provider Undertow ServletExtension (org.picketlink.identity.federation.bindings.wildfly.sp.SPServletExtension), uses SAML2LoginModule and allows for authentication decisions to be deferred to an IDP, which is configured in the SP’s picketlink.xml.

   The authenticator is responsible for the authentication of principals based on the security assertions, in this case SAML assertions, issued by the IDP. They intercept each request made to the application, check if a SAML assertion is present in the request, validate the assertions, execute principal’s SAML specific validations, and create a security context for the principal in the requested application.

   Part of the authenticator is configured in the jboss-web.xml file by defining the security domain to be used in authenticating and authorizing principals. You also must ensure that a <login-config> is specified in the web.xml and the necessary dependencies have been declared, which are done in later steps.

   The jboss-web.xml file for an SP must have the following:

   • A <security-domain> to specify which security domain to use for authentication and authorization.

   Example jboss-web.xml File

   <jboss-web>
     <security-domain>sp</security-domain>
     <context-root>sales-post</context-root>
   </jboss-web>

2. Configure the web.xml file for an SP.

   The web.xml file for an SP must contain the following:

   • A <security-constraint> with a <web-resource-collection> containing a <url-pattern> that maps to the URL pattern of the secured area. Optionally, <security-constraint> can also contain an <auth-constraint> stipulating the allowed roles.
   • If any roles were specified in the <auth-constraint>, those roles should be defined in a <security-role>.
   • A <login-config> with an <auth-method> specifying FORM authentication. This is required for the SAML authenticators.

   Example web.xml File

   <web-app>
     <display-name>SP</display-name>
     <description>SP</description>
     <!-- Define a Security Constraint on this Application -->
     <security-constraint>
       <web-resource-collection>
         <web-resource-name>SP</web-resource-name>
         <url-pattern>/*</url-pattern>
       </web-resource-collection>
       <auth-constraint>
         <role-name>All</role-name>
       </auth-constraint>
     </security-constraint>
     <!-- Security roles referenced by this web application -->
     <security-role>
       <description> The role that is required to log in to the SP Application </description>
       <role-name>All</role-name>
     </security-role>
     <!-- Define the Login Configuration for this Application -->
     <login-config>
       <auth-method>FORM</auth-method>
     </login-config>
   </web-app>

   Note

   It is recommended that you define a welcome page in the application. By default, JBoss EAP looks for a file named index.jsp but this can be configured using the <welcome-file-list> in web.xml.

   The logout process attempts to redirect principals to logout.jsp on successful logout. Ensure this file is defined at the root directory of the application.

3. Declare the necessary dependencies for an SP.

   The web application serving as the SP requires a dependency to be defined in jboss-deployment-structure.xml, so that the org.picketlink classes can be located. JBoss EAP provides all necessary org.picketlink and related classes, and the application only needs to declare them as dependencies to use them.

   Using jboss-deployment-structure.xml to Declare Dependencies

   <jboss-deployment-structure>
     <deployment>
       <dependencies>
         <module name="org.picketlink" services="import"/>
       </dependencies>
     </deployment>
   </jboss-deployment-structure>

   Note

   In previous versions of JBoss EAP, you would have declared this same dependency, but would have declared a valve to install the SAML authenticators. With the introduction of Undertow in JBoss EAP 7, you do not need to manually configure your deployments with the PicketLink SAML Authenticators. Now, they are configured automatically when you define use services="import" with the org.picketlink dependency. You must declare this configuration to enable SAML to your deployment.

4. Create and Configure a picketlink.xml File for an SP.

   The picketlink.xml file is responsible for the behavior of the Authenticator, and is loaded at the application’s startup.

   The file must contain at least the following elements:

   • <PicketLinkSP> defining the URL of the IDP (<IdentityURL>) and the URL the SP (<ServiceURL>).
   • <Handlers> defining the set of handlers needed for processing the SAML requests and responses.

   Example picketlink.xml File

   <PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
     <PicketLinkSP xmlns="urn:picketlink:identity-federation:config:2.1" BindingType="POST">
       <IdentityURL>${idp.url::http://localhost:8080/identity/}</IdentityURL>
       <ServiceURL>${sales-post.url::http://localhost:8080/sales-post/}</ServiceURL>
     </PicketLinkSP>
     <Handlers xmlns="urn:picketlink:identity-federation:handler:config:2.1">
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.RolesGenerationHandler" />
     </Handlers>
   </PicketLink>

   Note

   While not recommended, the SP may also be configured to use HTTP/REDIRECT by changing BindingType="POST" to BindingType="REDIRECT".

   Warning

   Handlers are implemented using a Chain of Responsibility, with each individual handler performing logic on request and responses in the order defined in picketlink.xml. It is very important to pay attention to the order in which the handlers are configured.

   By default, picketlink.xml is located in the WEB-INF directory of the SP web application; however, a custom path to picketlink.xml that is external to the application can be configured. This is useful in cases where multiple applications across one or more JBoss EAP instances share the same picketlink.xml configuration.

5. Optional: Setting a custom location for picketlink.xml.

   You can specify a custom location for picketlink.xml using the CONFIG_FILE parameter. This is done by adding a <context-param> element to web.xml.

   Using the CONFIG_FILE Parameter

   <context-param>
     <param-name>CONFIG_FILE</param-name>
     <param-value>/path/to/picketlink.xml</param-value>
   </context-param>

   You can also use the org.picketlink.federation.saml.CONFIG_PROVIDER parameter to specify a custom configuration provider. This allows you to create a custom implementation that extends org.picketlink.identity.federation.web.util.SAMLConfigurationProvider to provide your own configuration logic.

   Using the org.picketlink.federation.saml.CONFIG_PROVIDER Parameter

   <context-param>
     <param-name>org.picketlink.federation.saml.CONFIG_PROVIDER</param-name>
     <param-value>MyConfigurationProvider</param-value>
   </context-param>

   Note

   The management CLI commands shown assume that you are running a JBoss EAP standalone server. For more details on using the management CLI for a JBoss EAP managed domain, see the JBoss EAP Management CLI Guide.

Walkthrough

1. A principal attempts to access secured resource on a SP.
2. SP performs a check on the principal. If the principal has not yet authenticated, they need to be redirected to the IDP. If they have already authenticated, then all other steps are skipped and the final step is performed.
3. The SP locates the IDP and issues an authentication request to the IDP using the principal’s browser.
4. The IDP attempts to authenticate the principal, for example challenging them with a login page, using the configured identity store.
5. After the principal is identified by the IDP, for example after a successful login, the IDP issues a response, containing SAML v2 assertions with the principal’s security-related information, to the SP using the principal’s browser.
6. The SP performs a check on the principal’s security assertions, and based on the information contained in those assertions, the SP allows or denies access to the requested resource.

1. Configure picketlink.xml.

   Add the SAML2LogOutHandler in the picketlink.xml.

2. Create a logout.jsp page.

   As part of the logout process, the user is redirected to a logout.jsp page located in the root directory of the service provider application. Ensure that this page is created.

   Example logout.jsp

   <html>
     <head></head>
     <body>
       <p>You have successfully logged out.</p>
     </body>
   </html>

3. Configure Global Logout Profile links for the SPs.

   Use GLO=true as a URL parameter in a link to an SP resource to initiate the Global Logout Profile process.

   Example Logout Link

   <a href="?GLO=true">Click to log out</a>

1. Update the extensions.

   In the JBoss EAP configuration file, standalone.xml for standalone instances or domain.xml for domains, add the org.wildfly.extension.picketlink extension:

   <extensions>
     ...
     <extension module="org.wildfly.extension.picketlink"/>
     ...
   </extensions>

2. Add the subsystems.

   In the JBoss EAP configuration file, standalone.xml for standalone instances or domain.xml for domains, add the jboss:domain:picketlink-federation:2.0 subsystem:

   <profile>
     ...
     <subsystem xmlns="urn:jboss:domain:picketlink-federation:2.0"/>
      ...
   </profile>

   Note

   Examples of configuration can also be found in EAP_HOME/docs/examples/configs/standalone-picketlink.xml.

1. Add and configure an HTTPS security realm first. Once the HTTPS security realm has been configured, configure an https-listener in the undertow subsystem that references the security realm:

   batch
   
   /core-service=management/security-realm=HTTPSRealm:add
   
   /core-service=management/security-realm=HTTPSRealm/server-identity=ssl:add(keystore-path=identity.jks, keystore-relative-to=jboss.server.config.dir, keystore-password=password1, alias=appserver)
   
   /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=security-realm, value=HTTPSRealm)
   
   run-batch

   Warning

   Red Hat recommends that SSLv2, SSLv3, and TLSv1.0 be explicitly disabled in favor of TLSv1.1 or TLSv1.2 in all affected packages.

2. Restart the JBoss EAP instance for the changes to take effect.

1. Enable Encrypt and SupportsSignatures.

   To enable encryption, the <PicketLinkIDP> and <PicketLinkSP> must be updated.

   For the IDP, add or update the Encrypt and SupportsSignatures attributes in <PicketLinkIDP> to be true:

   <PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
     ...
     <PicketLinkIDP xmlns="urn:picketlink:identity-federation:config:2.1" Encrypt="true" SupportsSignatures="true">
       ...
     </PicketLinkIDP>
   </PicketLink>

   For the SP, add or update the SupportsSignatures attribute in <PicketLinkSP> to be true:

   <PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
     ...
     <PicketLinkSP xmlns="urn:picketlink:identity-federation:config:2.1" SupportsSignatures="true">
       ...
     </PicketLinkSP>
   </PicketLink>

2. Add handlers.

   In addition, handlers must be added to <Handlers>.

   For the IDP add SAML2EncryptionHandler and SAML2SignatureValidationHandler to the picketlink.xml file:

   <PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
     ...
     <Handlers xmlns="urn:picketlink:identity-federation:handler:config:2.1">
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2IssuerTrustHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.RolesGenerationHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2EncryptionHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2SignatureValidationHandler" />
     </Handlers>
   </PicketLink>

   For the SP add SAML2SignatureGenerationHandler and SAML2SignatureValidationHandler to the picketlink.xml file:

   <PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
     ...
     <Handlers xmlns="urn:picketlink:identity-federation:handler:config:2.1">
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.RolesGenerationHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2SignatureGenerationHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2SignatureValidationHandler" />
     </Handlers>
   </PicketLink>

   Warning

   Handlers are implemented using a Chain of Responsibility, with each individual handler performing logic on request and responses in the order defined in picketlink.xml. It is very important to pay attention to the order in which the handlers are configured.

   The SAML2SignatureGenerationHandler must not be configured in the same chain as the SAML2EncryptoinHandler. This will cause SAML messages will be signed several times.

3. Configure key provider.

   Lastly, a <KeyProvider> element must be added to BOTH picketlink.xml files. This element provides the location and credentials for accessing the Java keystore used for encrypting and decrypting security assertions. An example of generating a Java keystore can be found in the JBoss EAP How to Configure Server Security guide.

   For the IDP, the element should be added to <PicketLinkIDP>:

   <PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
     ...
     <PicketLinkIDP xmlns="urn:picketlink:identity-federation:config:2.1" Encrypt="true" SupportsSignatures="true">
       ...
       <KeyProvider ClassName="org.picketlink.identity.federation.core.impl.KeyStoreKeyManager">
         <Auth Key="KeyStoreURL" Value="/my_keystore.jks" />
         <Auth Key="KeyStorePass" Value="store123" />
         <Auth Key="SigningKeyPass" Value="test123" />
         <Auth Key="SigningKeyAlias" Value="servercert" />
         <ValidatingAlias Key="idp.example.com" Value="servercert" />
         <ValidatingAlias Key="localhost" Value="servercert" />
         <ValidatingAlias Key="sp1.example.com" Value="servercert" />
         <ValidatingAlias Key="sp2.example.com" Value="servercert" />
       </KeyProvider>
       ...
     </PicketLinkIDP>
     ...
   <PicketLink>

   For the SP the element should be added to <PicketLinkSP>:

   <PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
     ...
     <PicketLinkSP xmlns="urn:picketlink:identity-federation:config:2.1" SupportsSignatures="true">
       ...
       <KeyProvider ClassName="org.picketlink.identity.federation.core.impl.KeyStoreKeyManager">
         <Auth Key="KeyStoreURL" Value="/my_keystore.jks" />
         <Auth Key="KeyStorePass" Value="store123" />
         <Auth Key="SigningKeyPass" Value="test123" />
         <Auth Key="SigningKeyAlias" Value="servercert" />
         <ValidatingAlias Key="idp.example.com" Value="servercert" />
         <ValidatingAlias Key="localhost" Value="servercert" />
       </KeyProvider>
       ...
     </PicketLinkSP>
   </PicketLink>

   Note

   In order to properly encrypt and decrypt assertions, the IDP needs to generate signatures and the SP needs to verify those signatures as well as identify where they came from. This is accomplished using the <ValidatingAlias> element. IDPs need to have a <ValidatingAlias> for each trusted server/domain that is trusted, which is every entry in the <Trust> element. SPs need to have a <ValidatingAlias> for each server/domain containing an IDP.

1. Enable SupportsSignatures.

   To enable digital signatures, the <PicketLinkIDP> and <PicketLinkSP> elements must be updated.

   For the IDP and SP, add or update the SupportsSignatures attribute in <PicketLinkSP> to be true:

   <PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
     ...
     <PicketLinkIDP xmlns="urn:picketlink:identity-federation:config:2.1" SupportsSignatures="true">
       ...
     </PicketLinkIDP>
   </PicketLink>

   <PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
     ...
     <PicketLinkSP xmlns="urn:picketlink:identity-federation:config:2.1" SupportsSignatures="true">
       ...
     </PicketLinkSP>
   </PicketLink>

2. Add handlers.

   In addition, handlers must be added to <Handlers>.

   For the IDP and SP, add SAML2SignatureGenerationHandler and SAML2SignatureValidationHandler to the picketlink.xml file:

   IDP picketlink.xml

   <PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
     ...
     <Handlers xmlns="urn:picketlink:identity-federation:handler:config:2.1">
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2IssuerTrustHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.RolesGenerationHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2SignatureGenerationHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2SignatureValidationHandler" />
     </Handlers>
   </PicketLink>

   SP picketlink.xml

   <PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
     ...
     <Handlers xmlns="urn:picketlink:identity-federation:handler:config:2.1">
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.RolesGenerationHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2SignatureGenerationHandler" />
       <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2SignatureValidationHandler" />
     </Handlers>
   </PicketLink>

   Warning

   Handlers are implemented using a Chain of Responsibility, with each individual handler performing logic on request and responses in the order defined in picketlink.xml. It is very important to pay attention to the order in which the handlers are configured.

   The SAML2SignatureGenerationHandler must not be configured in the same chain as the SAML2EncryptionHandler. This will cause SAML messages will be signed several times.

3. Configure key provider.

   Lastly, a <KeyProvider> element must be added to BOTH picketlink.xml files. This element provides the location and credentials for accessing the Java keystore used for signing security assertions. An example of generating a Java keystore can be found in the JBoss EAP How to Configure Server Security guide.

   For the IDP, the element should be added to <PicketLinkIDP>:

   <PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
     ...
     <PicketLinkIDP xmlns="urn:picketlink:identity-federation:config:2.1" SupportsSignatures="true">
       ...
       <KeyProvider ClassName="org.picketlink.identity.federation.core.impl.KeyStoreKeyManager">
         <Auth Key="KeyStoreURL" Value="/my_keystore.jks" />
         <Auth Key="KeyStorePass" Value="store123" />
         <Auth Key="SigningKeyPass" Value="test123" />
         <Auth Key="SigningKeyAlias" Value="servercert" />
         <ValidatingAlias Key="idp.example.com" Value="servercert" />
         <ValidatingAlias Key="localhost" Value="servercert" />
         <ValidatingAlias Key="sp1.example.com" Value="servercert" />
         <ValidatingAlias Key="sp2.example.com" Value="servercert" />
       </KeyProvider>
       ...
     </PicketLinkIDP>
     ...
   <PicketLink>

   For the SP the element should be added to <PicketLinkSP>:

   <PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
     ...
     <PicketLinkSP xmlns="urn:picketlink:identity-federation:config:2.1" SupportsSignatures="true">
       ...
       <KeyProvider ClassName="org.picketlink.identity.federation.core.impl.KeyStoreKeyManager">
         <Auth Key="KeyStoreURL" Value="/my_keystore.jks" />
         <Auth Key="KeyStorePass" Value="store123" />
         <Auth Key="SigningKeyPass" Value="test123" />
         <Auth Key="SigningKeyAlias" Value="servercert" />
         <ValidatingAlias Key="idp.example.com" Value="servercert" />
         <ValidatingAlias Key="localhost" Value="servercert" />
       </KeyProvider>
       ...
     </PicketLinkSP>
   </PicketLink>

   Note

   In order to properly encrypt and decrypt assertions, the IDP needs to generate signatures and the SP needs to verify those signatures as well as identify where they came from. This is accomplished using the <ValidatingAlias> element. IDPs need to have a <ValidatingAlias> for each trusted server/domain that is trusted, which is every entry in the <Trust> element. SPs need to have a <ValidatingAlias> for each server/domain containing an IDP.

1. Configure all identity providers.

   For more details on setting up identity providers, see the Setting up an IDP section.

2. Configure a WEB-INF/idpmap.properties file.

   You need to create a WEB-INF/idpmap.properties file that lists all available identity providers using the format name=url.

   Example WEB-INF/idpmap.properties

   Domain=http://localhost:8080/idp/
   Domain-Alt=http://localhost:8080/idp-alt/

3. Create an account chooser landing page.

   In order for the user to select an identity provider to authenticate against, you must create an account chooser landing page to present to them, and include it in your service provider. This page should contain links to all identity providers that you want to allow them to authenticate against.

   Example accountChooser.html

   <html>
     <head>...</head>
     <body>
       <h1>Account Chooser</h1>
       <ul>
         <li><a href="?idp=Domain">Domain</a>
         <li><a href="?idp=Domain-Alt">Domain Alt</a>
       </ul>
     </body>
   </html>

4. Configure the IdentityURL element in picketlink.xml.

   You will also need to configure the IdentityURL element in picketlink.xml to reference the account chooser landing page. For more details on configuring the rest of picketlink.xml for the service provider, please see the Setting up an SP section.

   Example picketlink.xml

   <PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
     <PicketLinkSP xmlns="urn:picketlink:identity-federation:config:2.1" BindingType="REDIRECT">
       <IdentityURL>
         <Provider Page="/accountChooser.html"/>
       </IdentityURL>
       ...
     </PicketLinkSP>
     <Handlers xmlns="urn:picketlink:identity-federation:handler:config:2.1">
       ...
     </Handlers>
   </PicketLink>

   You can configure additional options for the dynamic account chooser using the attributes available in the Provider element.

   Table 2.4. Provider Element Attributes

   Option	Type	Default	Description
   Page	String	/accountChooser.html	The name of the HTML/JSP page for listing the different IDP accounts.
   Expiration	Integer	-1	The cookie expiry in seconds. Default is -1, which means the cookie expires when the browser is closed.
   DefaultURL	String		URL of the default IDP.
   Domain	String		The domain name to be used for the cookie that is sent to the user’s browser.
   Type	String		The fully qualified name of the implementation for IDP Mapping to replace the default implementation. This implementation must implement org.picketlink.identity.federation.web.config.IdentityURLConfigurationProvider. The default implementation uses the WEB-INF/idpmap.properties file in your SP web application.

   Important

   Configuring a dynamic account chooser using the picketlink-federation subsystem is not supported.