Version 1
Created by bmozaffa on Jun 12, 2010 2:02 AM. Last modified by bmozaffa on Jun 12, 2010 4:18 AM.

    PicketLink provides a number of LoginModule implementations to simplify the process of issuing and validating security tokens, while providing seamless integration with JEE container security. A PicketLink LoginModule is typically configured as part of the security setup of a JEE container to use a Security Token Service for authenticating users. The STS may be collocated on the same container as the LoginModule or be accessed remotely through Web Service calls or other remoting technology. PicketLink LoginModules support non-PicketLink STS implementations through standard WS-Trust calls.

     

     

    Login Modules

    STSIssuingLoginModule

    • Calls the configured STS and requests a security token. Upon successfully receiving the RequestedSecurityToken, it marks the authentication as successful.
    • A call to STS typically requires authentication. This LoginModule uses credentials from one of the following sources:          
      • Its properties file, if the useOptionsCredentials module-option is set to true
      • Previous login module credentials if the password-stacking module-option is set to useFirstPass
      • From the configured CallbackHandler by supplying a Name and Password Callback
    • Upon successful authentication, the SamlCredential is inserted in the Subject's public credentials if one with the same Assertion is not found to be already present there.
    • New features included since 1.0.4 based on PLFED-87:          
        • If a Principal MappingProvider is configured, retrieves and inserts the Principal into the Subject
        • If a RoleGroup MappingProvider is configured, retrieves and inserts the user roles into the Subject
        • Roles can only be returned if they are included in the Security Token. Configure your STS to return roles through an AttributeProvider

       

      STSValidatingLoginModule

      • Calls the configured STS and validates an available security token.
      • A call to STS typically requires authentication. This LoginModule uses credentials from one of the following sources:      
        • Its properties file, if the useOptionsCredentials module-option is set to true
        • Previous login module credentials if the password-stacking module-option is set to useFirstPass
        • From the configured CallbackHandler by supplying a Name and Password Callback
      • Upon successful authentication, the SamlCredential is inserted in the Subject's public credentials if one with the same Assertion is not found to be already present there.
      • New features included since 1.0.4 based on PLFED-87:      
        • If a Principal MappingProvider is configured, retrieves and inserts the Principal into the Subject
        • If a RoleGroup MappingProvider is configured, retrieves and inserts the user roles into the Subject
        • Roles can only be returned if they are included in the  Security Token. Configure your STS to return roles through an  AttributeProvider

       

      SAML2STSLoginModule

      • This LoginModule supplies a ObjectCallback to the configured CallbackHandler and expects a SamlCredential object back. The Assertion is validated against the configured STS
      • When stacked on top of another LoginModule that has successfully authenticated, if a user ID and SAML token are shared, this LoginModule bypasses validation.
      • Upon successful authentication, the SamlCredential is inspected for a NameID and a multi-valued role attribute that will be respectively set as the ID and roles of the user.

       

      SAML2LoginModule

      • This login module is used in conjunction with other components for SAML authentication and performs no authentication itself.
      • The SPRedirectFormAuthenticator uses this login module in PicketLink's implementation of the SAML v2 HTTP Redirect Profile.
      • The Tomcat authenticator valve performs authentication through redirecting to the identity provider and getting a SAML assertion.
      • This login module is used to pass the user id and roles to the JBoss security framework to be populated in the JAAS subject.

       

      Security Configurations

      Issuing Tokens

      • The STSIssuingLoginModule uses a username and password to authenticate the user against an STS by retrieving a token.
      • A typical configuration of this LoginModule resembles the following:

       

      <application-policy name="saml-issue-token">
          <authentication>
              <login-module
                  code="org.picketlink.identity.federation.core.wstrust.auth.STSIssuingLoginModule" flag="required">          <module-option name="configFile">./picketlink-sts-client.properties</module-option>
                <module-option name="endpointURI">http://security_saml/endpoint</module-option>
              </login-module>
          </authentication>
          <mapping>
              <mapping-module
                  code="org.picketlink.identity.federation.bindings.jboss.auth.mapping.STSPrincipalMappingProvider"
                  type="principal" />
              <mapping-module
                  code="org.picketlink.identity.federation.bindings.jboss.auth.mapping.STSGroupMappingProvider"
                  type="role" />
          </mapping>
      </application-policy>

       

      The above configuration depends on the same type of environment as most standard login modules. As such, most applications can switch to this model by simply changing their declared security-domain. Providing a Principal and RoleGroup mapping provider such as the two providers above results in an authenticated Subject being populated that enables coarse-grained and role-based authorization. After authentication, the Security Token will be available and may be used to invoke other services by Single Sign-On.

       

      Single Sign-On

      • The STSValidatingLoginModule uses a TokenCallback to ask the configured CallbackHandler  an STS by retrieving a token.
      • A typical configuration resembles the following:

       

      <application-policy name="saml-validate-token">
          <authentication>
              <login-module
                  code="org.picketlink.identity.federation.core.wstrust.auth.STSValidatingLoginModule" flag="required">
                  <module-option name="configFile">./picketlink-sts-client.properties</module-option>
                  <module-option name="endpointURI">http://security_saml/endpoint</module-option>
              </login-module>
          </authentication>
          <mapping>
              <mapping-module
                  code="org.picketlink.identity.federation.bindings.jboss.auth.mapping.STSPrincipalMappingProvider"
                  type="principal" />
              <mapping-module
                  code="org.picketlink.identity.federation.bindings.jboss.auth.mapping.STSGroupMappingProvider"
                  type="role" />
          </mapping>
      </application-policy>

       

      The above configuration enables Single Sign-On for your applications and services. A token that has been issued once, either directly by contacting the STS or through a token-issuing login module, can be used to authenticate against multiple applications and services employing the above setup. Providing a Principal and RoleGroup mapping provider such as the two providers above results in an authenticated Subject being populated that enables coarse-grained and role-based authorization. After authentication, the Security Token will be available and may be used to invoke other services by Single Sign-On.

       

      SAML HTTP Redirect Profile

      • PicketLink supports the SAML HTTP Redirect Profile through a combination of handlers, Servlet and Servlet Filter components.
      • A typical configuration resembles the following:

       

      <application-policy name="saml-browser-sso">
          <authentication>
              <login-module code="org.picketlink.identity.federation.bindings.jboss.auth.SAML2LoginModule" flag="required">
              </login-module>
          </authentication>
      </application-policy>

       

      For more information on this setup refer to the article on PicketLink SAML SSO for Web Containers and the associated user guide. PicketLink includes sample Web Applications that can be downloaded from the project site and demonstrate this capability.