Configuring SAML Web Inbound Propagation in Liberty

You can configure a Liberty server to accept a SAML token in an HTTP header as an authentication token. This feature is commonly used for a proxy or RESTful client that uses SAML on behalf of an authenticated user.

1. Add the samlWeb-2.0 Liberty feature to your server.xml file by adding the following element declaration inside the featureManager element.

   
   <feature>samlWeb-2.0</feature>

2. Enable SAML Inbound Propagation. The Liberty server provides a default samlWebSso20 element.

   
   
   <samlWebSso20 id="defaultSP">
   
   </samlWebSso20>

   You can use this default samlWebSso20 element, or create a new samlWebSso20 element to enable SAML inbound propagation by adding inboundPropagation=required.

   
   <samlWebSso20 id="defaultSP" inboundPropagation="required" >
   </samlWebSso20>

   Note: When SAML is configured and enabled, all unauthenticated requests use SAML authentication. To configure the types of requests that can and cannot use SAML authentication, you must configure an authentication filter as described in this topic.
3. You must configure the PKIX trust engine to validate the trustworthiness of the certificate in the signature through PKIX validation. Certificates that pass this validation are assumed to be trusted.
   1. Configure <PKIXTrustEngine>, and import all trusted SAML signer certificates to the default truststore of the Liberty server, or to the trustAnchor of the PKIXTrustEngine.
   2. Optional: Configure the trustedIssuers to list the issuer name of the SAML token as it appears in the SAML assertion if certificate trustworthiness is not sufficient.
   The following example is a sample configuration:

   
   <samlWebSso20 id="defaultSP"          
     inboundPropagation="required"
     headerName="saml_token"
     signatureMethodAlgorithm="SHA1">
     <pkixTrustEngine trustAnchor="serverStore" />
   </samlWebSso20>  

4. Optional: You can add headerName to define an http request header name that contains a SAML token. If this configuration attribute is not defined, the Liberty server searches for header name saml, Saml, and SAML for the SAML token. The SAML Token header in the HTTP request can be one of following formats:

   
   Authorization=[<headerName>=<SAML_HERE>]                  
   Authorization=[<headerName>="<SAML_HERE>"] 
   Authorization=[<headerName> <SAML_HERE>]
   <headerName>=[<SAML_HERE>]

   The SAML token must be Base-64 or UTF-8 encoded, and can be compressed in GZIP format.

   Note: The SAML token header name must be a URL safe string, and must not contain leading or trailing blank spaces.
5. Optional: You can configure how to create an authenticated subject from SAML. By default the Liberty service provider creates a subject from a SAML assertion directly without the requirement of a local user registry, which is equivalent to the configuration mapToUserRegistry=No. The other configuration options are mapToUserRegistry=User or mapToUserRegistry=Group.
   • mapToUserRegistry=No: The SAML issuer's name is realm, and the NameID is used to create a principal name and a unique security name in the subject, and no group member is included. You can configure the attributes: userIdentifier, realmIdentifier, groupIdentifier, and userUniqueIdentifier to create an authenticated subject with a customized user name, realm name, group memberships, and unique security identifier.
   • mapToUserRegistry=User: Choose this option if you want to validate a SAML user against your local user registry, and create the user subject based on the local user registry.
   • mapToUserRegistry=Group: Choose this option if you want to validate a SAML group against your local user registry, and create a subject to contain those validated groups. This option is similar to mapToUserRegistry=No, except that group memberships are verified against the local user registry.
6. Optional: You can implement the Liberty SAML SPI, com.ibm.wsspi.security.saml2.UserCredentialResolver as a user feature to dynamically map a SAML assertion to a Liberty subject.
7. Optional: You can configure multiple samlWebSso20 elements, and each samlWebSso20 element refers to one unique authFilter element. All authFilter elements must exclude each other. With multiple samlWebSso20 elements configured, each has its own authentication policy and consuming rules.
8. Optional: Configure signature requirements with the following considerations:

   The default signature algorithm is SHA256. If you must change the algorithm, use the signatureMethodAlgorithm attribute to modify it.

9. Optional: You can configure an SP authentication session and cookie. After SAML assertion is verified and processed, the Liberty SAML SP maintains an authenticated session between the client and the SP without using an LTPA cookie. The authenticated session timeout is set to SessionNotOnOrAfter in the <saml:AuthnStatement> if presented, or to sessionNotOnOrAfter as configured in the server.xml file, with the default being 120 minutes. The session cookie name is automatically generated, and you can customize the cookie name by using the attribute spCookieName to specify the wanted name.

   If you want the Liberty SP to create an LTPA cookie from the SAML assertion and use the LTPA cookie for subsequent authentication requests, you can add the configuration disableLtpaCookie=false. If you want to share the LTPA cookie with other servers, you must add the configuration attribute allowCustomCacheKey="false".

   Note: If you configure disableLtpaCookie="false" and allowCustomCacheKey="false", ensure that a SAML user name is not directly authenticating to a local user registry that prevents a user from having two accounts.
10. Configure the Authentication Filter. You can use authnFilter to define which samlWebSso20 element to handle the inbound propagation authentication request.

    For more information on configuring the authentication filter, see Authentication Filters.