Propagate SAML tokens in outbound web services messages

Propagate SAML tokens in outbound web services messages

A web services client can include two types of tokens in outbound web services messages:

SAML tokens received from inbound web services messages
New self-issued SAML tokens

Web services policy determines which SAML tokens will be propagated. We can override the policy programmatically by inserting SAML tokens to propagate into the Axis2 RequestContext object.
New SAML tokens can be generated using attributes from either...

The original SAML tokens
Attributes from the WSPrincipal user name in the RunAs Subject

Propagation methods...

SAML token propagation method tokenRequest binding Implementation details
Propagate the original SAML token. propagation Send the original SAML token from the server where the token was received to other servers using WS-Security.
Propagate the user security name, unique security name, group IDs, and security realm name. issueByWSCredential Override the default system implementation.
The self-issued SAML token contains user security name, user unique security name, group IDs, and security realm name that are specified by the WSCredential object in user security context.

Propagate the SAML token identity and attributes. No binding option set Default system implementation.
The server self-generates a new SAML token containing the original SAML attributes, Authentication method, and NameIdentifier or SAML NameID, and sends the new self-generated SAML token to downstream servers using WS-Security. The new SAML token issuer name, issuer signing certificate, and lifetime are determined by the SAML provider configuration properties.

Propagate the WSPrincipal. issueByWSPrincipal Overrides the default system implementation.
The self-issued SAML token contains WSPrincipal information in the RunAs subject. The information is stored as NameIdentity or NameID without copying anything from the original SAML token, even if the token exists in the subject.
Propagate the original SAML token by setting the tokenRequest binding option to the value, propagation, in bindings.xml

This method sends the original SAML token to other servers using WS-Security. In order for the propagation to succeed, there must be a valid SAML token in the RunAs subject. The server extracts the SAML token from the RunAs subject in the current security context and validates the following conditions. If any of these conditions are invalid, the WS-Security runtime environment does not propagate the SAML token, and the propagation request fails.

The SAML token has not expired, and the expiration time is within the time window of the notOnOrAfter value.
The ConfirmationMethod setting in the SAML token is the same as the confirmationMethod binding option defined in the token generator configuration.
The token ValueType in the SAML token matches the ValueType in the token generator configuration.

Perform these steps to set the correct value for the tokenRequest binding option. This procedure assumes that a web services client application named JaxWSServicesSamples is deployed, and that the Saml Bearer Client sample binding is attached.

Click...
Applications > Application types > WebSphere enterprise Applications > JaxWSServicesSamples > Service client policy sets and bindings > Saml Bearer Client sample > WS-Security > Authentication and protection > Authentication tokens > gen_saml11token > Callback handler

Add the custom property tokenRequest and set the property value to propagation.

Propagate the SAML token identity and attributes using a self-issuing SAML token, modify the outbound tokenGenerator in bindings.xml

This method sends the original SAML attributes, NameIdentifier or NameID, and authentication method from the original SAML token to other servers using WS-Security. If there is no SAML token in the subject, the server uses the WSPrincipal, stored as NameIdentifier or NameID, to create a self-issued SAML token. This propagation method is the default system implementation. In this method, the binding option is not set.
The following limitations apply to bindings.xml when we are using this propagation method:

Do not set the tokenRequest binding option in bindings.xml.
Do not set the stsURI binding option in bindings.xml, or set the option to: www.websphere.ibm.com/SAML/Issuer/Self.

Propagate the WSPrincipal
Modify bindings.xml and set the tokenRequest binding option to the value, issueByPrincipal, in bindings.xml. Using this method, the self-issued SAML token is always based on the WSPrincipal even if there is a SAML token in the subject. The new SAML token contains the WSPrincipal user name as the NameId or NameIdentifier. The token does not contain any other attributes in the WSPrincipal or WSCredential objects.
The following limitation applies to bindings.xml when we are using this propagation method:

Do not set the stsURI binding option in bindings.xml, or set the option to the value, www.websphere.ibm.com/SAML/Issuer/Self.

Example how to set correct value for the tokenRequest binding. Assumes a web services client application named JaxWSServicesSamples is deployed, and that the Saml Bearer Client sample binding is attached.

Click Applications > Application types > WebSphere enterprise Applications > JaxWSServicesSamples > Service client policy sets and bindings > Saml Bearer Client sample > WS-Security > Authentication and protection.
Click gen_saml11token in the Authentication tokens table.
Click Callback handler.
Add the custom property tokenRequest and set the property value to issueByPrincipal.

Propagate a pre-existing SAML token by inserting SAMLToken in the RequestContext

Use this method to send a SAML token that we created to downstream servers using WS-Security. The propagation is automatically triggered if the WS-Security runtime detects a SAML token in the RequestContext. The pre-existing token overrides any other existing binding options. To use this propagation method, save the existing SAML token in the RequestContext by specifying com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.SAMLTOKEN_IN_MESSAGECONTEXT as the key...

Generate a SAML token using the method SAMLToken samlToken = <token type>, for example:
SAMLToken samlToken = samlFactory.newSAMLToken(cred, reqData, samlIssuerCfg);

Save the SAMLToken to the RequestContext, for example:
Map requestContext = ((BindingProvider)port).getRequestContext(); requestContext.put("com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.SAMLTOKEN_IN_MESSAGECONTEXT", samlToken );

This propagation option can co-exist with the other propagation methods, and overrides the other methods. If the SAML token in the RequestContext is expired, or the token expiration time is less than current time plus the cache cushion, the WS-Security runtime environment ignores the SAML token, and uses one of the other three propagation methods configured in bindings.xml. To avoid using the other three propagation methods, add the following binding option to the custom properties under callback handler in the TokenGenerator configuration: failOverToTokenRequest = false.
Propagate user group memberships, unique security name, and realm name

There are contained in the com.ibm.websphere.security.cred.WSCredential object and set in bindings.xml.
Set the tokenRequest binding option to the value, issueByWSCredential, in bindings.xml. Using this method, the self-issued SAML token is always based on the WSCredential even if there is a SAML token in the subject.
The new SAML 1.1 token contains the following assertions:

The NameIdentifier element contains the SecurityName value from WSCredential with the NameQualifier element set to the realm name from WSCredential. The SecurityName is obtained by calling the WSCredential.getSecurityName() method. The realm name is obtained by calling the WSCredential.getRealmName() method.
All attributes have an AttributeNamespace set to...
com.ibm.websphere.security.cred.WSCredential

The GroupIds attribute contains all group names that a user belongs to. The group names are obtained by calling the WSCredential.getGroupIds() method.
The UniqueSecurityName attribute contains the unique security name, which is obtained by calling the method...
WSCredential.getUniqueSecurityName()

Optionally, we can assert the realm name from WSCredential by adding the includeRealmName=true custom property in the callback handler.

The new SAML 2.0 token contains the following assertions:

The NameID element contains the SecurityName value from WSCredential with the NameQualifier element set to the realm name from WSCredential.

The SecurityName is obtained by calling the WSCredential.getSecurityName() method.
The realm name is obtained by calling the WSCredential.getRealmName() method.

All attributes have a NameFormat set to...
com.ibm.websphere.security.cred.WSCredential

The GroupIds attribute contains all group names that a user belongs to. The group names are obtained by calling the WSCredential.getGroupIds() method.
The UniqueSecurityName attribute contains the unique security name, which is obtained by calling the WSCredential.getUniqueSecurityName() method.
Optionally, we can assert the realm name from WSCredential by adding the includeRealmName=true custom property in the callback handler.

The following limitation applies to bindings.xml when using the propagation method:

Do not set the stsURI binding option in the bindings.xml file.

Perform these steps to set the correct value for the tokenRequest binding option. This procedure assumes that a Web services client application named JaxWSServicesSamples is deployed, and that the Saml Bearer Client sample binding is attached.

Click Applications > Application types > WebSphere enterprise Applications > JaxWSServicesSamples > Service client policy sets and bindings > Saml Bearer Client sample > WS-Security > Authentication and protection.
Click gen_saml11token in the Authentication tokens table.
Click Callback handler.
Add the tokenRequest custom property and set the property value to issueByWSCredential.
The following example illustrates the NameIdentifier and Attribute statement from a self-issued SAML 1.1 assertion based on WSCredential.
<saml:AttributeStatement>
    <saml:Subject>
        <saml:NameIdentifier NameQualifier="ldap.acme.com:9080">uid=alice,dc=acme,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=acme,dc=com</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute AttributeName="GroupIds" AttributeNamespace="com.ibm.websphere.security.cred.WSCredential">
        <saml:AttributeValue>cn=development,dc=acme,dc=com</saml:AttributeValue>
        <saml:AttributeValue>cn=deployment,dc=acme,dc=com</saml:AttributeValue>
        <saml:AttributeValue>cn=test,dc=acme,dc=com</saml:AttributeValue>
    </saml:Attribute>
</saml:AttributeStatement>
The following example illustrates the NameID and Attribute statement 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=acme,dc=com</saml2:AttributeValue>
    <saml2:Attribute>
    <saml2:Attribute AttributeName="GroupIds"
           NameFormat="com.ibm.websphere.security.cred.WSCredential">
        <saml2:AttributeValue>cn=development,dc=acme,dc=com</saml2:AttributeValue>
        <saml2:AttributeValue>cn=deployment,dc=acme,dc=com</saml2:AttributeValue>
        <saml2:AttributeValue>cn=test,dc=acme,dc=com</saml2:AttributeValue>
    </saml2:Attribute>
</saml2:AttributeStatement>
<saml2:NameID NameQualifier="ldap.acme.com:9060">alice</saml2:NameID>
To programmatically propagate a pre-existing SAML token, insert the SAML token to propagate into the RequestContext using the property, com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.SAMLTOKEN_IN_MESSAGECONTEXT. This overrides all other existing binding options.

SAML Issuer Config Properties

SAML token propagation method	tokenRequest binding	Implementation details
Propagate the original SAML token.	propagation	Send the original SAML token from the server where the token was received to other servers using WS-Security.
Propagate the user security name, unique security name, group IDs, and security realm name.	issueByWSCredential	Override the default system implementation. The self-issued SAML token contains user security name, user unique security name, group IDs, and security realm name that are specified by the WSCredential object in user security context.
Propagate the SAML token identity and attributes.	No binding option set	Default system implementation. The server self-generates a new SAML token containing the original SAML attributes, Authentication method, and NameIdentifier or SAML NameID, and sends the new self-generated SAML token to downstream servers using WS-Security. The new SAML token issuer name, issuer signing certificate, and lifetime are determined by the SAML provider configuration properties.
Propagate the WSPrincipal.	issueByWSPrincipal	Overrides the default system implementation. The self-issued SAML token contains WSPrincipal information in the RunAs subject. The information is stored as NameIdentity or NameID without copying anything from the original SAML token, even if the token exists in the subject.