NameID mapper

Use this extension point to customize the value of the NameID attribute returned in the SAML assertion.

These steps assume your environment is already correctly configured for single sign-on using SAML v2.0, where AM is the hosted IdP.

Java implementation

To create a custom NameID mapper in Java, follow these high-level steps:

Clone the am-external Git repository. For example:
```
$ git clone https://github.com/ForgeRock/am-external.git
```
Learn about using AM source code in How do I access the proprietary Maven repositories?.

Check out the branch for your release version, for example:

$ cd am-external
$ git checkout releases/[.replaceable]##version##
$ cd openam-federation

Create a new Java project and add the openam-federation-library as a Maven dependency, for example:

<dependency>
  <groupId>org.forgerock.am</groupId>
  <artifactId>openam-federation-library</artifactId>
</dependency>

Write a Java class that extends the com.sun.identity.saml2.plugins.DefaultIDPAccountMapper class.

Refer to the com.sun.identity.saml2.plugins.IDPAccountMapper interface for implementation details.

Override the getNameID() method to return a customized NameID value. For example:

public class CustomIDPAccountMapper extends DefaultIDPAccountMapper{

    @Override
    public NameID getNameID(Object session, String hostEntityID, String remoteEntityID,
            String realm, String nameIDFormat) throws SAML2Exception {

        NameID myNameID = super.getNameID(session, hostEntityID, remoteEntityID, realm, nameIDFormat);

        if (remoteEntityID.equals("https://sp.example.com:8443/am") {
            myNameID.setValue(myNameID.getValue() + "@sp.example.com");
        }

        return myNameID;
    }
}

Package your custom class in a JAR file and copy to the /WEB-INF/lib folder where you deployed AM.
Configure AM to use the new Java plugin.
1. In the AM admin UI, go to Realms > Realm Name > Applications > Federation > Entity Providers > Hosted IDP > Assertion Processing.
2. In the Account Mapper field, type the fully qualified name of your custom class.
3. Save your changes.
Restart AM or the container in which it runs.
Test your changes.

Scripted implementation

Follow these steps to use a script to customize the NameID value.

Learn about NameID mapper scripts from the following resources:

To view the default script, refer to saml2-nameid-mapper.js.
To modify the default script, go to Realms > Realm Name > Scripts and select SAML2 NameID Mapper Script.
To view the available bindings, refer to the NameID mapper scripting API.

In the AM admin UI, go to Realms > Realm Name > Scripts, and create a new script of type Saml2 NameID Mapper.

The NameID mapper script type is a next-generation script only and must be written in JavaScript.

In the Script field, set a custom value for NameID. For example:

/*
 * 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();

Validate and save your changes.
Configure AM to use the updated NameID mapper script.
1. In the AM admin UI, go to Realms > Realm Name > Applications > Federation > Entity Providers > Remote SP Name > Assertion Processing.
2. Under Account Mapper, select your script from the SAML2 Name ID Mapper Script drop-down list.
3. Save your changes.

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>

PingAM 8.0.0

NameID mapper

Java implementation

Scripted implementation