SAML single sign-on scenarios, features, and limitations

Security Assertion Markup Language (SAML) is an OASIS open standard for representing and exchanging user identity, authentication, and attribute information. SAML is fast becoming the technology of choice to provide cross-vendor single sign-on (SSO) interoperability.

The WebSphere® Application Server SAML service provider (SP) supports SAML 2.0 Identity Provider (IdP) initiated single sign-on (SSO). WebSphere IdP initiated SSO service is implemented as a Trust Association Interceptor, and proceeds according to the following workflow:

The client accesses a customer-provided front end web application, hosted on the IdP, SP, or elsewhere.
The front end web application redirects the client to the IdP.
The user authenticates to the IdP.
The IdP redirects the client to the Assertion Consumer Service (ACS) on the WebSphere Application Server by sending a SAML response over HTTP POST.
The application server processes the SAML response and creates a security context.
The application server adds an LTPA cookie to the HTTP response.
The client is redirected to the web resource or business application based on the targetUrl TAI custom property or the RelayState parameter in the HTTP request.
The application server intercepts the request, maps the LTPA cookie to a security context, and authorizes the user to access the requested web resource.
The application server sends the HTTP response back to client.

The following image shows the SAML SSO flow. In this flow, the 'Service provider' is WebSphere.

The SAML SSO component in the WebSphere Application Server includes the following:

Support for single sign-on with multiple identity providers
Support options for identity assertion and mapping the assertion identity to the user registry of the service provider
The ability to map or assert SAML token attributes to the realm, principal, unique ID, and group, and set them into the service provider security context
Support for a plug point to allow for customized identity mapping
The ability to retrieve the identity group membership from the service provider registry and populate the security context
An IdP selection filter to route the request back to the proper IdP if the request did not come from the IdP
Support for RSA-SHA1 and RSA-SHA256 signature algorithms
The ability to preserve the SAML token in the subject of the service provider for access by the application, and make it available for a downstream authenticated Enterprise JavaBeans (EJB) or Web Service call
Support for any business service that implements the POST method to act as an ACS. Using a target business servlet as an ACS is preferred, as it reduces one round trip between the browser and the service provider server.
The ability to audit key SAML assertions, including Issuer and NameID.

The following feature highlights and best practices apply to the SAML SSO features:

Assertion consumer service (ACS) in WebSphere SAML service provider:
ACS is a secured servlet that accepts a SAML protocol message and establishes the security context. An ACS URL has a predefined ContextRoot as samlsps, and a URL has the following format:
```
https://<host name>:<port>/samlsps/<any uri pattern>
```
The SAMLResponse received by the ACS will be intercepted by TAI, and upon successful validation, the request is redirected to the target application service.
Multiple security domain support:
An ACS is deployed in an application security domain, and it is expected that the ACS reside in the same security domain as the business application. If the ACS and target business application (RelayState) are in different security domains, the following are some recommended options:
- Process the SAMLResponse in the security domain of the ACS.
- Reconfigure the ACS to have the same domain as the business application.
- Use the target business service as the ACS.
Multiple single sign-on partners:
The WebSphere SAML TAI supports multiple ACS and IdP single sign-on (SingleSignOnService) partners. One SSO partner is defined as one ACS URL, and can have multiple SingleSignOnService objects. With the existence of multiple SSO partners, each SSO partnership is uniquely identified by an ACS URL.

Each SSO partner can have its own validation rules, mapping rule from assertion to subject, or a rule to start the SSO with its own IdP. For example, one SSO partner can handle ID assertion, which consists of generating a WebSphere platform subject without calling into the user registry. Another SSO partner can perform a local user registry lookup. Another example is that one SSO partner handles SSO with one IdP, and another SSO partner handles SSO with a different IdP.
WebSphere Application Server offers a "bookmark style" SSO login flow that emulates, but does not fully implement, a more traditional SP-initiated flow.
1. The client accesses a protected business application without first authenticating to the IdP or to the application server.
2. The application server intercepts the request based on configured filter definitions.
3. The application server stores the value of the original request URL on a cookie called WasSamlSpReqUrl.
4. The application server redirects the client to the IdP login page that is configured on the sso_<id>.sp.login.error.page custom property.
5. Authentication continues following the IdP-initiated SSO flow.
  1. The user authenticates to the IdP.
  2. The IdP redirects the client to the Assertion Consumer Service (ACS) on the WebSphere Application Server by sending a SAML response over HTTP POST.
  3. The application server processes the SAML response and creates a security context.
  4. The application server adds an LTPA cookie to the HTTP response.
6. The application server uses the value of the WasSamlSpReqUrl cookie to redirect the client to the original request URL.
Identity mapping and security context management:
The WebSphere SAML TAI provides a rich and flexible identity mapping, and can be classified as follows:
- Identity assertion: Map the SAML assertion to the WebSphere platform subject without a local registry. Typical ID assertion scenarios include:
  - Default: use NameID as principal, issuer as realm, selected attribute as group members.
  - Customized: configure SAML attribute as principal, realm, accessID, and group members.
- Map NameID from the IdP against the user registry of the service provider, and build the subject from the registry. The following scenarios are supported:
  - Directly map the SAML NameId to the local registry.
  - Provide a plugin point for custom mapping, and then use a new user to build the subject.
  - Map NameID to the user registry, and fall back to ID assertion.
- Combination of ID assertion and local registry:
  In addition to ID assertion, TAI searches parent groups of the asserted groups in the user registry of the service provider, and includes the parent groups into the subject. For example, authorization is granted to parent groups, but the identity provider does not know the parent group names.
Logout support:
Although the WebSphere Application Server SAML Trust Association Interceptor (TAI) does not support the Single Logout (SLO) Profile, you can configure the TAI with a logout URL to redirect the user to a custom logout page. When an HTTPServletRequest.logout method is invoked from an endpoint that is protected by the TAI, the HTTP request is redirected to this URL after the WebSphere logout is complete. For more information, see Enabling SAML web single sign-on (SSO) programmatic logout.

WebSphere Application Server supports IdP initiated SAML web SSO only.

The following specifications or scenarios are not supported by the WebSphere Application Server SAML SSO.

Enhanced Client or Proxy (ECP) Profile
Identity Provider Discovery Profile
Single Logout Profile
Name Identifier Management Profile
Artifact Resolution Profile
Assertion Query/Request Profile
Name Identifier Mapping Profile
SAML Attribute Profiles