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.
About this task
You can configure a Liberty server to
accept a SAML token in an HTTP header as an authentication token by enabling the
samlWeb-2.0
feature in Liberty, and setting inboundPropagation=required
in addition to other configuration
information. The configuration for inbound propagation is similar to Configuring SAML Web Browser SSO in
Liberty.
Procedure
-
Add the
samlWeb-2.0
Liberty feature to your server.xml file by adding the following element declaration inside thefeatureManager
element.<feature>samlWeb-2.0</feature>
-
Enable SAML Inbound Propagation. The Liberty server provides a default
samlWebSso20
element.<samlWebSso20 id="defaultSP"> </samlWebSso20>
You can use this defaultsamlWebSso20
element, or create a newsamlWebSso20
element to enable SAML inbound propagation by addinginboundPropagation=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. -
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.
-
Configure
<PKIXTrustEngine>
, and import all trusted SAML signer certificates to the default truststore of the Liberty server, or to thetrustAnchor
of thePKIXTrustEngine
. -
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>
-
Configure
-
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 namesaml
,Saml
, andSAML
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
orUTF-8
encoded, and can be compressed inGZIP
format.Note: The SAML token header name must be a URL safe string, and must not contain leading or trailing blank spaces. -
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 aremapToUserRegistry=User
ormapToUserRegistry=Group
.mapToUserRegistry=No
: The SAML issuer's name is realm, and theNameID
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
, anduserUniqueIdentifier
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 tomapToUserRegistry=No
, except that group memberships are verified against the local user registry.
-
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. -
Optional: You can configure multiple
samlWebSso20
elements, and eachsamlWebSso20
element refers to one uniqueauthFilter
element. AllauthFilter
elements must exclude each other. With multiplesamlWebSso20
elements configured, each has its own authentication policy and consuming rules. -
Optional: Configure signature requirements with the following considerations:
The default signature algorithm is
SHA256
. If you must change the algorithm, use thesignatureMethodAlgorithm
attribute to modify it. -
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 tosessionNotOnOrAfter
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 attributespCookieName
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 attributeallowCustomCacheKey="false"
.Note: If you configuredisableLtpaCookie="false"
andallowCustomCacheKey="false"
, ensure that a SAML user name is not directly authenticating to a local user registry that prevents a user from having two accounts. -
Configure the Authentication Filter. You can use
authnFilter
to define whichsamlWebSso20
element to handle the inbound propagation authentication request.For more information on configuring the authentication filter, see Authentication Filters.