Map a local identity to a SAML 2.0 token (Federation)

The Security Verify Access server places the local user identity information into an XML document that conforms to the security token service universal user (STSUUSER) schema. The identity provider issues a SAML 2.0 token to the service provider. The token is generated based on the local identity of the user.

We can customize how the local identity is converted into a SAML 2.0 token using a mapping rule...

  1. Convert the local identity to an STS Universal User
  2. Convert this STS Universal User into another STS Universal User using a mapping rule.
  3. Convert the latter STS Universal User to a SAML 2.0 token.

Our mapping rule does not operate directly on local identity or SAML 2.0 token. Instead, it operates on the STS Universal User. Any modification made to an STS Universal User has an impact on the output SAML 2.0 token.

The mapping rule is responsible for the following tasks:

  1. Map Principal Attr Name to a Principal Name entry.

    When the token module generates the token, this Principal name is not directly used. Instead, the value in the Name field is sent as input to the alias service, which obtains the alias name and name identifier, for the principal, and places the returned alias in the generated token module. The type must be valid for SAML. For example:

      urn:oasis:names:tc:SAML:2.0:assertion

  2. Set the authentication method to the password mechanism. This action is required by the SAML standard.

  3. Set the audience of the audience restriction condition to the value of the STSUU element Audience Restriction. If this STSUU element is not present, the audience is set to the Provider ID of the federation partner.

  4. Populating the attribute statement of the assertion with the attributes in the AttributeList in the In-STSUU. This information becomes custom information in the token.

    Custom attributes might exist required by applications that use information that is to be transmitted between federation partners.

  5. Specify whether the assertion conditions should contain the <saml:OneTimeUse></saml:OneTimeUse> element. If so, insert a special context attribute into the STSUU as shown:

      var oneTimeUseAttr = new Attribute("AssertionIncludeOneTimeUse","urn:oasis:names:tc:SAML:2.0:assertion", "true"); stsuu.addContextAttribute(oneTimeUseAttr);

  6. Set the NameID attribute in the assertion with Transient NameId format. This action is useful to specify a name value to use instead of the default UUID generated by the runtime for Transient NameID format.

    To replace the UUID, create a principal name attribute of type urn:oasis:names:tc:SAML:2.0:nameid-format:transient, with its value provided by user.

    The examples below show the user-provided value UserGeneratedTransientId but it could be any other value. The value of the specified STSUU principal name will be set as the NameID in the SAML assertion.

    Example mapping rule 

      importPackage(Packages.com.tivoli.am.fim.trustserver.sts.uuser);
var transientNameId = "UserGeneratedTransientId";
stsuu.addPrincipalAttribute(new Attribute("name", "urn:oasis:names:tc:SAML:2.0:nameid-format:transient", transientNameId));

    Example STSUU values after mapping rule applied 

       
<stsuuser:Attribute name="name" type="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">
    <stsuuser:Value>UserGeneratedTransientId</stsuuser:Value>
</stsuuser:Attribute>

    Example SAML assertion NameID with Transient NameId formats 

      <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"
             NameQualifier="https://ip-wga/isam/sps/saml20ip/saml20"
             SPNameQualifier="https://sp-wga/isam/sps/saml20sp/saml20"
             >UserGeneratedTransientId</saml:NameID>


Parent topic: Customize SAML 2.0 identity mapping