Procedure 15.2. Configure Service Provider (SP)

1. Configure the Web Application Security For the SP

   The web application to be configured as a SP should have FORM based security enabled in its web.xml file.

   Example 15.11. web.xml Configuration for SP

   <display-name>SP</display-name>
   <description>SP</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>SP</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>SP 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 SP Application
     </description>
     <role-name>manager</role-name>
   </security-role>
   </web-app>

2. Create Security Domain for SP

   Create a Security Domain that uses SAML2LoginModule. Here is an example configuration:

   <security-domain name="sp" cache-type="default">
     <authentication>
       <login-module code="org.picketlink.identity.federation.bindings.jboss.auth.SAML2LoginModule" flag="required"/>
      </authentication>
   </security-domain>

3. Configure the SP Valve

   To configure the valve for the SP, create a jboss-web.xml in the WEB-INF directory of your SP web application.

   Example 15.12. jboss-web.xml File Configuration for SP Valves

   <jboss-web>
     <security-domain>sp</security-domain>
     <context-root>sales-post</context-root>
     <valve>
       <class-name>org.picketlink.identity.federation.bindings.tomcat.sp.ServiceProviderAuthenticator</class-name>
     </valve>
   </jboss-web>

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

   The following is an example of picketlink.xml configuration for the SP. In this configuration file you provide the URL for the SP and for the IDP, with corresponding handlers for the SP.

   Example 15.13. picketlink.xml Configuration

   <PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">
     <PicketLinkSP xmlns="urn:picketlink:identity-federation:config:2.1" ServerEnvironment="tomcat" BindingType="REDIRECT">
       <IdentityURL>${idp.url::http://localhost:8080/idp/}</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>

   By default, picketlink.xml is located in the WEB-INF directory of your 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.14. Define Dependency in META-INF/MANIFEST.MF

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

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

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