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

We can map a local identity to a SAML 2.0 token for an identity provider. The Security Verify Access server places the local user identity information into an XML document that conforms to the security token service universal user (STSUU) schema. The identity provider issues a SAML 2.0 token to the service provider. It generates the SAML 2.0 token 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. Security Verify Access first converts the local identity to an STS Universal User. It then converts this STS Universal User into another STS Universal User using a mapping rule. After that, it converts the latter STS Universal User to a SAML 2.0 token. The 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. The alias service obtains the alias name, 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 AudienceRestriction. 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 when we want 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: Customizing SAML identity mapping