Propagating SAML tokens

You can use various SAML token propagation methods to include SAML tokens in outbound web services messages.

About this task

A web services client can include two types of tokens in outbound web services messages:
  • Original SAML tokens the client received from inbound web services messages.
  • New self-issued SAML tokens.
New SAML tokens can be generated using attributes from the original SAML tokens, or using attributes from the WSPrincipal user name in the RunAs Subject. The web services policy configuration determines which SAML tokens will be propagated. You can override the policy configuration by programmatically inserting SAML tokens that you want to propagate into the Axis2 RequestContext object.

Four propagation methods are enabled. This table summarizes the propagation methods and the associated binding options:

Table 1. Propagation methods and associated binding options. Use propagation to include SAML tokens in web services messages.
SAML token propagation method Binding option Implementation details
Propagate the original SAML token. The tokenRequest binding option is set to the value, propagation. Sends 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. The tokenRequest binding option is set to the value, issueByWSCredential. Overrides 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 is 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. The tokenRequest binding option is set to the value, issueByWSPrincipal.

Beginning in version 8, specifying either issueByWSPrincipal or issueByWSCredential value has the same result. If you are not already using the issueByWSPrincipal value, it is recommended that you use the issueByWSCredential value. If you are already using the issueByWSPrincipal value, it is recommended that you eventually replace that value with the issueByWSCredential value.

 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.
Programmatically propagate a pre-existing SAML token. Insert the SAML token that you want to propagate into the RequestContext using the property, com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.SAMLTOKEN_IN_MESSAGECONTEXT. Overrides all other existing binding options.

Procedure

  1. Propagate the original SAML token by setting the tokenRequest binding option to the value, propagation, in the bindings.xml file, as shown in the steps.
    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.

    1. Click Applications > Application types > WebSphere enterprise Applications > JaxWSServicesSamples > Service client policy sets and bindings > Saml Bearer Client sample > WS-Security > Authentication and protection.
    2. Click gen_saml11token in the Authentication tokens table.
    3. Click Callback handler.
    4. Add the custom property tokenRequest and set the property value to propagation.
  2. To propagate the SAML token identity and attributes using a self-issuing SAML token, modify the outbound tokenGenerator in the bindings.xml file.
    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 the bindings.xml file when you are using this propagation method:
    • Do not set the tokenRequest binding option in the bindings.xml file.
    • Do not set the stsURI binding option in the bindings.xml file, or set the option to this value: www.websphere.ibm.com/SAML/Issuer/Self.
  3. To propagate the WSPrincipal, modify the bindings.xml file as shown in the steps.
    Set the tokenRequest binding option to the value, issueByPrincipal, in the bindings.xml file. 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 the bindings.xml file when you are using this propagation method:
    • Do not set the stsURI binding option in the bindings.xml file, or set the option to the value, www.websphere.ibm.com/SAML/Issuer/Self.

    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.

    1. Click Applications > Application types > WebSphere enterprise Applications > JaxWSServicesSamples > Service client policy sets and bindings > Saml Bearer Client sample > WS-Security > Authentication and protection.
    2. Click gen_saml11token in the Authentication tokens table.
    3. Click Callback handler.
    4. Add the custom property tokenRequest and set the property value to issueByPrincipal.
  4. To propagate a pre-existing SAML token by inserting SAMLToken in the RequestContext, follow these steps.
    Use this method to send a SAML token that you 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, as shown in the steps.
    1. Generate a SAML token using the method SAMLToken samlToken = <token type>, for example: 
      SAMLToken samlToken = samlFactory.newSAMLToken(cred, reqData, samlIssuerCfg);
    2. 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 that is configured in the bindings.xml file. 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.
  5. To propagate a user's group memberships, unique security name, and realm name contained in the com.ibm.websphere.security.cred.WSCredential object, modify the bindings.xml file as shown in the steps.
    Set the tokenRequest binding option to the value, issueByWSCredential, in the bindings.xml file. 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 as the value.
    • 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, you 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 as the value.
    • 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, you can assert the realm name from WSCredential by adding the includeRealmName=true custom property in the callback handler.
    The following limitation applies to the bindings.xml file when you use 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.
    1. Click Applications > Application types > WebSphere enterprise Applications > JaxWSServicesSamples > Service client policy sets and bindings > Saml Bearer Client sample > WS-Security > Authentication and protection.
    2. Click gen_saml11token in the Authentication tokens table.
    3. Click Callback handler.
    4. 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>