NameID mapper

Use a NameID mapper script to customize the value of the NameID attribute returned in the SAML assertion per SP.

Demonstrate a NameID adapter

Before you try the example, configure single sign-on using SAML v2.0 with PingOne Advanced Identity Cloud as the hosted IDP.

The following example modifies the NameID attribute in the assertion on the remote SP:

Create the script
Configure the remote SP
Test the script

To view the available bindings, refer to the NameID mapper scripting API.

Create the script

Under Native Consoles > Access Management, go to Realms > Realm Name > Scripts, and click +New Script.
Enter a unique name for your script, select Saml2 NameID Mapper from the Script Type drop-down list, and click Create.

The NameID mapper script type is a next-generation script only.

In the Script field, write a script to set a custom value for the NameID attribute. For example, the following script replaces instances of .com with .org in a user’s email address. Alternatively, uncomment the call to getIdentityNameID to set NameID to the user’s first and last name.

/*
 * Retrieve nameID value from Java plugin and modify
*/
function getModifiedNameID() {
  var nameIDValue = nameIDScriptHelper.getNameIDValue();

  if (nameIDValue.includes(".com")) {
      return nameIDValue.replace(".com", ".org");
  }
  return nameIDValue;
}

/*
 * Use identity binding to gather attributes
*/
function getIdentityNameID() {
  var givenName = identity.getAttributeValues("givenName")[0];
  var lastName = identity.getAttributeValues("sn")[0];

  return givenName + "_" + lastName;
}

getModifiedNameID();
//getIdentityNameID();

Save your changes and close the editor.

Configure the remote SP

Under Native Consoles > Access Management, go to Realms > Realm Name > Applications > Federation > Entity Providers > Remote SP Name > Assertion Processing.
Under Account Mapper, select your script from the SAML2 NameID Mapper Script drop-down list.
Save your changes.

Test the script

Test your changes using an SP-initiated flow.

Verify that the SAML 2.0 assertion shows an updated value, for example:

<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
             NameQualifier="idp"
             SPNameQualifier="sp">bjensen@example.org</saml:NameID>

NameID mapper scripting API

The NameID mapper script is a next-generation script and therefore has access to all the next-generation common bindings in addition to those described here.

Binding Description

Binding	Description
`hostedEntityId`	The entity ID for the hosted IdP.
`remoteEntityId`	The ID of the hosted SAML v2.0 entity.
`nameIDFormat`	The requested SAML v2.0 NameID format.
`session`	An instance of `ScriptedSession` representing the user’s single sign-on session object interface for information about SSO token and authentication information, as well as session-related properties. Only present when the session object passed by the SAML engine is an SSOToken. Retrieve session property values with the following `ScriptedSession` supported method: `public String getProperty(String name)`
`nameIDScriptHelper`	The `NameIDScriptHelper` binding provides the following supporting methods and constants for customizing the NameID value: Constants `NAMEID_FORMAT_TRANSIENT` `NAMEID_FORMAT_PERSISTENT` `NAMEID_FORMAT_UNSPECIFIED` `NAMEID_FORMAT_EMAIL` Methods `public String createNameIdentifier()` `public String getNameIDValue() throws SAML2Exception` `public boolean shouldPersistNameIDFormat()` `public String getNameIDFromSession()` Always present.
`identity`	An instance of `ScriptedIdentityScriptWrapper` representing a scriptable implementation of an identity. The `identity` binding is derived from the session, so it’s only present if the `session` object is. The `identity` object will also be missing if Advanced Identity Cloud throws an exception during its creation. If this happens, Advanced Identity Cloud records an entry in the logs.

hostedEntityId

The entity ID for the hosted IdP.

remoteEntityId

The ID of the hosted SAML v2.0 entity.

nameIDFormat

The requested SAML v2.0 NameID format.

session

An instance of ScriptedSession representing the user’s single sign-on session object interface for information about SSO token and authentication information, as well as session-related properties.

Only present when the session object passed by the SAML engine is an SSOToken.

Retrieve session property values with the following ScriptedSession supported method:

public String getProperty(String name)

nameIDScriptHelper

The NameIDScriptHelper binding provides the following supporting methods and constants for customizing the NameID value:

Constants

NAMEID_FORMAT_TRANSIENT
NAMEID_FORMAT_PERSISTENT
NAMEID_FORMAT_UNSPECIFIED
NAMEID_FORMAT_EMAIL

Methods

public String createNameIdentifier()
public String getNameIDValue() throws SAML2Exception
public boolean shouldPersistNameIDFormat()
public String getNameIDFromSession()

Always present.

identity

An instance of ScriptedIdentityScriptWrapper representing a scriptable implementation of an identity. The identity binding is derived from the session, so it’s only present if the session object is.

The identity object will also be missing if Advanced Identity Cloud throws an exception during its creation. If this happens, Advanced Identity Cloud records an entry in the logs.