Relying Party identity mapping
Identity mapping is a step in the Secure Verify Access federation flow that is invoked at the end of a successful single sign-on. Identity mapping can take place either through a JavaScript mapping rule or an HTTP callout.
Use of a JavaScript mapping allows administrators to modify the attributes of the session that was created for a user as a result of a federated single sign-on. Modification of attributes can be necessary because incoming data comes in several different forms, such as SAML assertions or a JSON Web Token (JWT). Sometimes this information is not complete, and more work is need to retrieve the entire profile. In other cases, the values are complete, but not in the correct form for a consuming application. For information on using HTTP callout, see External user mapping.
During the Relying Party flow, the credential (iv-cred) is built and returned to WebSEAL. At this step in the authentication process, we can use Relying Party identity mapping to perform the following actions, as needed.
- Set the principal name.
The identity mapping step of a Relying Party must set a valid principal name to use in the user session. A common way to do this is to combine claims from a JWT, such as combining the iss and sub claims. See the example mapping rule below.
- Map attributes from the id_token or /userinfo into any additional credential attributes to be present in the users session.
- Access a protected resource using the provided access_token (if one was issued), to retrieve more information to include in the session.
- Produce an attribute from the various claim sources, such as JWT claims, UserInfo, or additional callouts.
- Combine multiple attributes into a single more-consumable attribute.
- Make an advanced call to /userinfo, when the default callout provided with ISAM is not sufficient.
- Persist access or refresh tokens.
- Use UserLookupHelper to perform just in time (JIT) provisioning of an ISAM account.
- HTTP callouts
- Callout to APIs with the access_token.
JavaScript mapping rules call Java™ code from JavaScript. The set of classes that can be called are restricted. Examples include:
To view the full list of whitelisted (allowable) JavaScript classes, see JavaScript whitelist.
Identity mapping uses Secure Token Service (STS) chains. The chains use a Secure Token Service Universal User (STSUU) module to map the necessary attributes. For information on the Relying Party's use of the STSUU, see Use of STSUU for the Relying Party and Security Token Service Universal User document.
When identity mapping includes a user identity that does not exist with the registry, the ISAM point of contact must be configured accordingly.
- Review how to change the point of contact configurations for the ISAM runtime, on the federation side. See Point of contact profiles.
- Understand how external authentication (EAI) works for users that exist within the registry. See External authentication interface HTTP header reference.
Example rule
The Security Verify Access distribution includes an example identity mapping rule for Relying Party. To view it:
- Log in to the local management interface.
- Select Federation > Global Settings > Mapping Rules.
- Select OIDCRP Category OIDC, and use the Edit function to view the contents.
The example identity mapping rule OIDCRP Category OIDC demonstrates code that completes the mandatory requirement of an identity mapping rule to assign the Principal Name. The example assigns the name by combining the values of the iss and sub fields of the id_token. See the extract from the mapping rule below.
/* * Construct a basic identity made up of iss and sub */ var iss = stsuu.getAttributeContainer().getAttributeValueByName("iss"); var sub = stsuu.getAttributeContainer().getAttributeValueByName("sub"); /* * This builds a principal name from the iss and sub fields of the id_token. If * this user does not exist in the Verify Access registry, either modify to map to a * local user that is in the registry, or change the EAI authentication * settings of the federation runtime to use PAC authentication. */ stsuu.setPrincipalName(iss + "/" + sub)
To use PAC authentication, log in to the local management interface. Select Federation > Point of Contact. Select Verify Access Credential and click Set as Current.
Parent topic: Authentication with OpenID Connect Relying Party