SAML usage scenarios
SAML function is described through four basic usage scenarios. The first three scenarios demonstrate web services single sign-on, configured using a policy set. The fourth scenario describes custom SAML single sign-on, which we can build using the SAML API and the trust client API. The scenarios demonstrate using SAML building blocks and APIs to authenticate to a Security Token Service (STS), request SAML tokens, and implement the SAML tokens to obtain access to business services.
Overview
WebSphere Application Server with SAML provides building blocks and APIs that allow us to create single sign-on and identity federation business solutions using SAML tokens. SAML policy sets are the building blocks for configuring web services applications to request SAML tokens, propagate SAML tokens in SOAP messages, and validate and authenticate SAML tokens, all without a single line of programming.
Use the SAML and WS-Trust client APIs, we can programmatically create SAML tokens, parse and validate SAML tokens, and authenticate SAML tokens received from protocols other than Web services SOAP messages. Specifically, use the SAML APIs to process custom SAML token attributes, create personalized application interfaces and perform claim-based authorization. Use the WS-Trust client API to request SAML tokens, or other types of tokens, from an STS, and to validate and exchange security tokens with an STS.
The WAS product does not include an STS for issuing SAML or any other type of security token. However, WAS with SAML does interoperate with Tivoli Federated Identity Manager and other third-party STS implementations.
Scenario 1: Web services single sign-on (SSO)
In this single sign-on (SSO) usage scenario, a user authenticates to an STS and requests SAML tokens using the bearer confirmation method. The user then uses SAML tokens to access a business services provider. The business services provider validates the SAML tokens and asserts the identity and attributes of the user based on the trust relationship between the provider and the issuing STS. The received SAML tokens are considered valid if the token signing certificates are trusted by the business services provider, and if the expiration time of the tokens is less than the business services provider local time plus a configurable clock skew.
The business services provider can access downstream services on behalf of the user using SAML tokens based on the policy configuration of the service. Using the policy configuration, the business services provider can either propagate the original SAML tokens or generate self-issued SAML based on the original user attributes. For a detailed description of how to configure policy sets and bindings for this scenario, read about configuring client and provider bindings for the SAML bearer token.
Single sign-on using a SAML bearer token has advantages over other SSO technology because SAML is an industry-standard security token, and is supported by multiple vendor products. In addition, the WAS implementation of SAML function interoperates with Tivoli Federated Identity Manager, DataPower, and other vendor products.
This diagram shows the interaction between the STS and the business services provider in the web services single sign-on usage scenario.
Figure 1. Web services single sign-on usage scenario
We can add a caller binding to the SAML provider sample bindings to select the received SAML token which represents the caller identity. The Web Services Security runtime environment uses the SAML NameId to represent the client identity and search the user security name and group membership from the configured user registry when using the default system.wss.caller JAAS login configuration.
After this scenario is successfully executed, the WS-Security runtime environment saves the SAML tokens and can reuse them to access the same business service provider, if the tokens are still valid. The token is valid if the token expiration time is less than the cache period, which is configurable. Once the business services provider has validated and authenticated the received SAML tokens, the JAAS subjects, along with corresponding SAML tokens, are saved in the authentication cache. The SAML token remains valid in the hosting application server regardless of the token expiration time. This means that the WS-Security runtime environment does not check the SAML token expiration time within the same process, because the SAML tokens remain valid in the application server process as long as the token is in the authentication cache.
SAML token expiration times are checked when the business services provider uses the SAML tokens to invoke downstream services. Outbound requests will fail if the SAML token expiration time is not less than the current time added to the cache period. This limitation also applies when the policy configuration requires use of the original SAML tokens. However, the limitation does not apply if the policy configuration uses self-issued SAML tokens instead, for example, if the business services provider has created and signed a reproduction of the original SAML tokens.
Scenario 2: Web services single sign-on (SSO) with holder-of-key validation
The single sign-on with holder-of-key validation usage scenario is similar to the previous SSO usage scenario. The SSO with holder-of-key scenario uses SAML tokens with the holder-of-key (HoK) confirmation method instead of the bearer confirmation method. SAML HoK tokens contain a key that the client uses to prove ownership of the key, and ownership of the token. This embedded key can be a shared key (also known as a symmetric key) or a X.509 certificate with a public key (also known as an asymmetric key). In the case of a shared key, the key is encrypted using the public key of the target business services provider so that only the intended business service can consume the SOAP messages.
When a client requests SAML tokens with the HoK shared key from an STS, the STS encrypts the key in the SAML tokens and sends a copy of the same key in the WS-Trust response to the requesting client. This is necessary because otherwise the client cannot read the encrypted keys in the SAML tokens. To prove ownership of the SAML tokens, the client uses the shared key to sign and to encrypt the SOAP request messages. Business services are required to validate the HoK token ownership by extracting the encrypted shared key and using it to verify the digital signature.
The following diagram shows how a web service can request a SAML token in the scenario.
Figure 2. Web services 1 requesting a SAML token from an external service
1 The user logs on with a web browser using SPNEGO and is authenticated. A JAAS subject is created.
2 The credential from the SPNEGO token is used to request a SAML token using WS-Trust. The token is signed with the trust server private key.
3 The signature of the SAML token is validated based on the trust relationship. The security credential is created using the attributes from the SAML token. The cryptographic key from the SAML token is used to decrypt the SOAP message.
As shown in the diagram, a browser client uses Kerberos credentials (represented by SPNEGO token) to access a web application. Assuming that the Kerberos credential can be delegated, the web application can request a SAML token from the STS on behalf of the client, using the delegated client Kerberos credential. For example, the web application obtains a client approval request (APREQ) Kerberos token from the key distribution center (KDC) on behalf of the client. The web application then uses the client APREQ token to authenticate to the STS and request a client SAML token from the STS on behalf of the client.
In this example, the SAML token requires the holder-of-key confirmation method using a symmetric key. The Web application uses the SAML token to access downstream business services, also on behalf of the client, so the SAML token authenticates the client to the downstream services and also protects the request messages using digital signing and encryption. For more information about how to set up bindings for the HoK token, read about configuring client and provider bindings for the SAML holder-of-key symmetric key token.
When the scenario is successfully executed, the target business services can then use the SAML token to access other downstream services using the same procedure described in the scenario, if the downstream business services can extract the embedded key. Alternatively, the business services can be configured to use self-issued SAML tokens to access downstream services to avoid distributing the private key.
Scenario 3: Web services federated identity management
In the federated identity management usage scenario, a browser client accesses a company portal web application. In this scenario, the basic user authentication data, such as user name and password, are used to request SAML tokens from an STS, and then the SAML tokens are used to obtain access to business services across security domains. The receiving business services provider validates the SAML tokens based on the trust relationship between the provider and the issuing STS, and the provider also asserts the identity and attributes of the user. This means that the user does not need to be previously defined in the user directory in the target business services. An advantage of this scenario is that it provides a more manageable way to federate business services from many business partners together, while removing the requirement to consolidate users into one user directory service.
Figure 3. A user logs on to a company portal and uses federated identity management to obtain access to business services
1 The user logs on with a user name and password and is authenticated to the company portal. A JAAS subject is created.
2 The user name and password are used to authenticate to the STS and to request a SAML token representing the user.
3 The signature of the SAML token is validated based on the trust relationship. Security credentials are created using the attributes from the SAML token. The cryptographic key from the SAML token is used to decrypt the SOAP message.
The default system login configuration, wss.caller, maps the user identities that are represented by SAML tokens to user identities in the configured user directory. A custom login module must be added to the wss.caller login configuration to assert SAML token user identities from other security domains to the application server. This custom login module extracts the SAML token user identity and other attributes and constructs the assertion properties used by the application server. Two of these properties, user name and user identity, are required by the application server. Because the two properties are provided in the identity assertion, the application server does not need to validate the user name against the local user directory.
In addition, information about user group membership can be provided to the application server. This information is used to construct the WSCredential object representing application server security credentials for the user. The user properties are passed to the application server WSWSSLoginModule using the JAAS LoginContext shared state. For detailed information about these properties, read about configuring inbound identity mapping.
Scenario 4: Custom single sign-on (SSO) solutions
The custom single sign-On (SSO) usage scenario uses the SAML token library APIs, the WS-Trust client APIs, and other application server APIs and SPIs to build customized SSO solutions to fit a specific business computing environment. The diagram for this scenario shows an example where users are authenticated and issued SAML tokens from an identity provider that has trust relationship with a company server. In this scenario, a company wants to grant users access to protected web applications based on the trust relationship, without asking the users for additional authentication.
Web application clients, such as web browsers, pass SAML tokens to the application server using the HTTPS protocol, instead of using the web services protocol. To intercept and pass along these requests, the company builds a SAML trust association interceptor (TAI) that implements the application server Trust Association Interceptor API. A SAML TAI uses the SAML token library API to validate and authenticate SAML Tokens. Alternately, the SAML TAI can use the WS-Trust client API to validate and authenticate SAML tokens against an external STS. For more information about the TAI interface, read about developing a custom interceptor for trust associations. A custom SAML TAI is not shipped with WAS.
Figure 4. A user logs on to a company server with a web browser using the HTTPS protocol, and is authenticated using a SAML TAI
1 The user logs on to an identity provider using a user name and password. The identity providers issues a SAML token to the user.
2 The SAML TAI uses the SAMLTokenFactory API to validate the SAML token, and to authenticate the SAML token to create user credentials. The SAML TAI can also use the WS-Trust client API to validate the SAML token with an external STS.
For more information about the SAML APIs, read about the WS-Trust client API and the SAML token library APIs.
A more complex solution: Multiple security domains
The previous sections of this document described four basic usage scenarios. However, we might want to assert SAML tokens across multiple security domain boundaries. For more information on this solution, see the documentation about SAML assertions across WAS security domains.