Establish security context for web services clients using SAML security tokens

Establish security context for web services clients using SAML security tokens

This task describes setting the WAS policy set caller binding configuration option to establish client security context using SAML security tokens in web services SOAP request messages. We can either map SAML tokens to a user entry in a local user repository or assert SAML tokens based on a trust relationship. The second configuration option does not require accessing the local user repository. Instead, the WS-Security runtime environment populates the client security context entirely using the contents of SAML security tokens. This process is based on a trust relationship to the SAML token issuer. If a SAML token specifies the sender-vouches subject confirmation method. the process is based on a trust relationship to the message sender.

Configure a policy set caller binding and select the SAML token type to represent a web services client request.

Create the caller configuration...
WebSphere enterprise applications > application_name > Service provider policy sets and bindings > binding_name > WS-Security > Callers > New

Specify a Name, such as caller.
Enter a value for the Caller identity local part. For example...
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0

....which must match the local part of the CustomToken element in the attached WS-Security policy.
Click Apply and Save.

Optional: Map SAML security tokens to a user entry in a local user repository.
Mapping to a user entry is the default behavior when we configure a caller binding without specifying a configuration option. Alternatively and optionally, we can select this configuration option explicitly using the following steps:

On the caller binding configuration page, add a Callback handler:
com.ibm.websphere.wssecurity.callbackhandler.SAMLIdAssertionCallbackHandler

Add a Callback handler custom property, crossDomainIdAssertion, and set its value to false.

Optional: Assert SAML security tokens based on trust relationship.

On the caller binding configuration page, add a Callback handler:
com.ibm.websphere.wssecurity.callbackhandler.SAMLIdAssertionCallbackHandler

Add a Callback handler custom property, crossDomainIdAssertion, and set its value to true.

In WAS Version 7.0 Fix Pack 7 and later releases, the WS-Security runtime environment takes a SAML token Issuer name to represent the foreign security realm name. WS-Security takes the NameID element in the case of SAML 2.0 security tokens or the NameIdentifier element in the case of SAML 1.1 security tokens to represent user security name. Alternatively, we can explicitly specify which SAML token attribute to use to represent user security name. Moreover, we can also specify which SAML token attribute to use to represent user group membership. Read about SAML assertions across WAS security domains for a detailed discussion of the SAML token assertion trust model and binding configuration.
v8.x can propagate the contents of com.ibm.websphere.security.cred.WSCredential in a SAML token. We must set a tokenRequest custom property with an issueByWSCredential property value in the WS-Security binding configuration of the web services client. Read about propagating SAML tokens for a detailed description of this binding option. When the crossDomainIdAssertion property is set to true in v8.x, WS-Security checks whether a SAML token contains a SAML Attribute UniqueSecurityName with a NameFormat element with a value of com.ibm.websphere.security.cred.WSCredential. If found, WS-Security uses the NameQualifier attribute value of the NameID element or NameIdentifier element to represent the user security realm name. WS-Security also uses the UniqueSecurityName attribute value and the GroupIds attribute value to represent a unique user name and group membership. This default behavior is different between v7 and v8.x of the product. We can add a CallbackHandler property, IssuerNameForRealm, and set its value to true to configure Version 8.x to preserve the v7 behavior. Alternatively, we can add a CallbackHandler property, NameQualifierForRealm, and set its value to true to configure Version 8.x to always use the NameQualifier attribute to represent the user security realm name.

Enable and configure WAS global security.
Use the Security Configuration wizard to enable administrative security. We also need to enable application security so that the sample application can use the authenticated user subject in the security context to create a SAML token. This step involves configuring the third trust relationship verification point on the web services provider side. This step is needed to use the application server for simulating the target security domain web services provider. The WAS V8.0 authentication subsystem supports asserting user identity with a foreign realm name, and checks the foreign realm name against the list of inbound trusted authentication realms. After you complete this configuration step, WAS can create a client caller subject with a user identity in a foreign security realm.

Configure trusted security domains.

From the Global Security panel, click... Available realm definitions > Configure > Trusted authentication realms - inbound
Choose Trust realms as indicated below option.
Click Add External Realm button.
Add the SAML assertion issuer name to External realm name.
The SAML assertion issuer name provides information about the issuer of the SAML assertion, which is either inside the Issuer element in the SAML 2.0 assertion, or is the Issuer attribute in the SAML assertion.

We have configured a web service to establish a client security context using the SAML security token in the web services SOAP request messages.

Example
The following example illustrates the NameIdentifier and Attribute elements from a self-issued SAML 1.1 assertion based on WSCredential:
<saml:AttributeStatement>
    <saml:Subject>
        <saml:NameIdentifier NameQualifier="ldap.example.com:9080">uid=alice,dc=example,dc=com</saml:NameIdentifier>
        <saml:SubjectConfirmation>
            <saml:ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:bearer</saml:ConfirmationMethod>
        </saml:SubjectConfirmation>
    </saml:Subject>
    <saml:Attribute AttributeName="UniqueSecurityName" AttributeNamespace="com.ibm.websphere.security.cred.WSCredential">
        <saml:AttributeValue>uid=alice,dc=example,dc=com</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute AttributeName="GroupIds" AttributeNamespace="com.ibm.websphere.security.cred.WSCredential">
        <saml:AttributeValue>cn=development,dc=example,dc=com</saml:AttributeValue>
        <saml:AttributeValue>cn=deployment,dc=example,dc=com</saml:AttributeValue>
        <saml:AttributeValue>cn=test,dc=example,dc=com</saml:AttributeValue>
    </saml:Attribute>
</saml:AttributeStatement>
The following example illustrates the NameID and Attribute elements from a self-issued SAML 2.0 assertion based on WSCredential:
<saml2:AttributeStatement>
    <saml2:Attribute Name="UniqueSecurityName" NameFormat="com.ibm.websphere.security.cred.WSCredential" />
    <saml2:AttributeValue>uid=alice,dc=example,dc=com</saml2:AttributeValue>
    <saml2:Attribute>
        <saml2:Attribute AttributeName="GroupIds" NameFormat="com.ibm.websphere.security.cred.WSCredential" />
        <saml2:AttributeValue>cn=development,dc=example,dc=com</saml2:AttributeValue>
        <saml2:AttributeValue>cn=deployment,dc=example,dc=com</saml2:AttributeValue>
        <saml2:AttributeValue>cn=test,dc=example,dc=com</saml2:AttributeValue>
    </saml2:Attribute>
<saml2:AttributeStatement>

<saml2:NameID NameQualifier="ldap.example.com:9060">alice</saml2:NameID>
Related:

SAML concepts
SAML usage scenarios
Propagate SAML tokens
SAML assertions across WAS security domains