Chapter 7. About PicketLink Login Modules
A PicketLink login module is typically configured as part of the security setup to use a Security Token Service (STS) or browser-based SSO with SAML for authenticating users. The STS may be collocated on the same container as the login module or be accessed remotely through web service calls or another technology. PicketLink STS login modules support non-PicketLink STS implementations through standard WS-Trust calls. For more details on the concepts behind Security Token Services as well as browser-based SSO with SAML, please see the JBoss EAP Security Architecture guide.
7.1. STSIssuingLoginModule
Full name: org.picketlink.identity.federation.core.wstrust.auth.STSIssuingLoginModule
The STSIssuingLoginModule uses a user name and password to authenticate the user against an STS by retrieving a token. The authentication happens as follows:
- Calls the configured STS and requests for a security token. Upon successfully receiving the RequestedSecurityToken, it marks the authentication as successful.
A call to the STS typically requires authentication. This login module 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 security token is stored in the login module’s shared map with
org.picketlink.identity.federation.core.wstrust.lm.stsTokenkey.
This login module has no direct configurable attributes, but you may use module options to pass in configuration options.
Example STSIssuingLoginModule
<security-domain 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>
</security-domain>
In the above example, the specified Principal mapping provider and the RoleGroup mapping provider results in an authenticated Subject being populated that enables coarse-grained and role-based authorization. After authentication, the Security Token is available and may be used to invoke other services by Single Sign-On.
7.2. STSValidatingLoginModule
Full name: org.picketlink.identity.federation.core.wstrust.auth.STSValidatingLoginModule
The STSValidatingLoginModule uses a TokenCallback to retrieve a security token from STS.
The authentication happens as follows:
- Calls the configured STS and validates an available security token.
A call to STS typically requires authentication. This Login Module 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 security token is stored in the login module’s shared map with
org.picketlink.identity.federation.core.wstrust.lm.stsTokenkey.
This login module has no direct configurable attributes, but you may use module options to pass in configuration options.
Example STSValidatingLoginModule
<security-domain 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>
</security-domain>
The above example shows how to enable validation for an issued token, either directly by contacting the STS or through a token-issuing login module, to be used to authenticate against multiple applications and services. Providing a Principal mapping provider and a RoleGroup mapping provider results in an authenticated Subject being populated that enables coarse-grained and role-based authorization. After authentication, the Security Token is available and can be used to invoke other services by Single Sign-On.
7.3. SAML2STSLoginModule
Full name: org.picketlink.identity.federation.bindings.jboss.auth.SAML2STSLoginModule
The authentication happens as follows:
- This Login Module supplies an ObjectCallback to the configured CallbackHandler and expects a SamlCredential object back. The Assertion is validated against the configured STS.
- Upon successful authentication, the SamlCredential is inspected for a NameIDType.
- If a user ID and SAML token are shared, this Login Module bypasses validation when stacked on top of another Login Module that is successfully authenticated.
Example SAML2STSLoginModule
<security-domain name="saml-sts" cache-type="default">
<authentication>
<login-module code="org.picketlink.identity.federation.bindings.jboss.auth.SAML2STSLoginModule" flag="required" module="org.picketlink">
<module-option name="configFile" value="${jboss.server.config.dir}/sts-config.properties"/>
<module-option name="password-stacking" value="useFirstPass"/>
</login-module>
</authentication>
</security-domain>
This login module has no direct configurable attributes, but you may use module options to pass in configuration options.
7.4. SAML2LoginModule
Full name: org.picketlink.identity.federation.bindings.jboss.auth.SAML2LoginModule
The authentication happens as follows:
- This login module is used in conjunction with other components for SAML authentication and performs no authentication itself.
-
The SAML authenticator, which is installed by the PicketLink Service Provider Undertow ServletExtension (
org.picketlink.identity.federation.bindings.wildfly.sp.SPServletExtension), uses this login module to authenticate users based on a SAML assertion previously issued by an identity provider. - If the user does not have a SAML assertion for the service provider, the user is redirected to the identity provider to obtain a SAML assertion.
- This login module is used to pass the user ID and roles to the security framework to be populated in the JAAS subject.
Example SAML2LoginModule
<security-domain name="sp" cache-type="default">
<authentication>
<login-module code="org.picketlink.identity.federation.bindings.jboss.auth.SAML2LoginModule" flag="required"/>
</authentication>
</security-domain>
This login module has no direct configurable attributes.
The SAML2LoginModule is intended for use 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 since the 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 the 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>7.5. RegExUserNameLoginModule
Full name: org.picketlink.identity.federation.bindings.jboss.auth.RegExUserNameLoginModule
This login module can be used after any Certificate Login Module to extract a username, UID or other field from the principal name so that roles can be obtained from LDAP. The module has an option named regex which specifies the regular expression to be applied to the principal name, the result of which is passed on to the subsequent login module.
Example RegExUserNameLoginModule
<login-module code="org.picketlink.identity.federation.bindings.jboss.auth.RegExUserNameLoginModule" flag="required"> <module-option name="password-stacking" value="useFirstPass"/> <module-option name="regex" value="UID=(.*?),"/> </login-module>
For example, an input principal name of UID=007, EMAILADDRESS=something@something, CN=James Bond, O=SpyAgency would result in the output 007 using the above login module.
For more information on regular expressions, see the java.util.regex.Pattern class documentation.
