Procedure 15.1. Configure Identity Provider (IDP)

1. Configure the web application security for the IDP

   Configure a web application as the Identity provider.

   Note

   The use of FORM based web application security is recommended as it gives you the ability to customize the login page.
   The following is an example of the web.xml configuration

   Example 15.6. web.xml Configuration for IDP

   <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 on this Application -->
   <security-constraint>
     <web-resource-collection>
     <web-resource-name>IDP</web-resource-name>
     <url-pattern>/*</url-pattern>
   </web-resource-collection>
     <auth-constraint>
     <role-name>manager</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/loginerror.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>manager</role-name>
   </security-role>
   </web-app>

2. Create Security Domain for IDP

   Create a Security Domain with authentication and authorization mechanisms defined for the IDP. Refer to Section 13.9, “Use a Security Domain in Your Application” for further details.

3. Configure the IDP Valves

   Create a jboss-web.xml file in the WEB-INF directory of your IDP web application to configure the valves for the IDP. The following is an example of jboss-web.xml file.

   Example 15.7. jboss-web.xml File Configuration for IDP Valves

   <jboss-web>
     <security-domain>idp</security-domain>
     <context-root>idp</context-root>
     <valve>
       <class-name>org.picketlink.identity.federation.bindings.tomcat.idp.IDPWebBrowserSSOValve</class-name>
     </valve>
   </jboss-web>

4. Configure the PicketLink Configuration File (picketlink.xml)

   The following is an example of picketlink.xml configuration. In this configuration file you provide the URL that gets added as the issuer in the outgoing SAML2 assertions to the service providers and the IDP.

   Example 15.8. picketlink.xml Configuration

   <PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
     <PicketLinkIDP xmlns="urn:picketlink:identity-federation:config:2.1">
       <IdentityURL>http://localhost:8080/idp/</IdentityURL>
     </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>

   By default, picketlink.xml is located in the WEB-INF directory of your IDP web application. However, you can configure a custom path to a picketlink.xml that is external to the application:

   1. Optional: Configuring a custom path to picketlink.xml

      Add two paramaters to the valve element in your application's WEB-INF/jboss-web.xml: configFile specifying for the path to picketlink.xml, and timerInterval which specifies the interval in milliseconds to reload the configuration. For example:

      <valve>
        <class-name>...</class-name>
          <param>
            <param-name>timerInterval</param-name>
            <param-value>5000</param-value>
          </param>
          <param>
            <param-name>configFile</param-name>
            <param-value>path-to/picketlink.xml</param-value>
          </param>
      </valve>

5. Declare dependencies on PicketLink module (META-INF/MANIFEST.MF, or jboss-deployment-structure.xml)

   The web application also requires a dependency defining in META-INF/MANIFEST.MF or jboss-deployment-structure.xml, so that the PicketLink classes can be located.

   Example 15.9. Define Dependency in META-INF/MANIFEST.MF

   Manifest-Version: 1.0
       Build-Jdk: 1.6.0_24
       Dependencies: org.picketlink

   Example 15.10. Define Dependency in META-INF/jboss-deployment-structure.xml

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