---
title: NameID mapper
description: Use this extension point to customize the value of the NameID attribute returned in the SAML assertion.
component: pingam
version: 8.1
page_id: pingam:am-saml2:custom-nameid-mapper
canonical_url: https://docs.pingidentity.com/pingam/8.1/am-saml2/custom-nameid-mapper.html
keywords: ["SAML 2.0", "Single Sign-on (SSO)", "Federation", "Customization", "Java", "Scripts"]
page_aliases: ["saml2-guide:custom-nameid-mapper.adoc"]
section_ids:
  java_example: Java example
  scripted_example: Scripted example
---

# 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 SSO using SAML 2.0, where AM is the hosted IdP.

## Java example

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

1. Clone the [am-external](https://github.com/ForgeRock/am-external) Git repository. For example:

   ```bash
   $ git clone https://github.com/ForgeRock/am-external.git
   ```

   Learn about using AM source code in [How do I access the proprietary Maven repositories?](https://support.pingidentity.com/s/article/How-do-I-access-the-proprietary-Maven-repositories).

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

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

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

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

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

   Refer to the [com.sun.identity.saml2.plugins.IDPAccountMapper](../_attachments/apidocs/com/sun/identity/saml2/plugins/IDPAccountMapper.html) interface for implementation details.

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

   ```bash
   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;
       }
   }
   ```

6. Package your custom class in a JAR file and copy to the `/WEB-INF/lib` folder where you deployed AM.

7. 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.

8. Restart AM or the container in which it runs.

9. Test your changes.

## Scripted example

Learn about NameID mapper scripts from the following resources:

* Next-generation example script

  [SAML2 NameID Mapper Script](../am-scripting/sample-scripts.html#saml2-nameid-mapper-js)

* Scripting API

  [NameID mapper scripting API](../am-scripting/saml2-nameid-mapper-api.html)

Follow these steps to use an example script to customize the NameID value:

1. In the AM admin UI, go to Realms > *realm name* > Scripts, and [create a new script](../am-scripting/manage-scripts-console.html) of type `Saml2 NameID Mapper`.

   |   |                                                                                                                                                   |
   | - | ------------------------------------------------------------------------------------------------------------------------------------------------- |
   |   | The NameID mapper script type is a [next-generation script](../am-scripting/next-generation-scripts.html) only and must be written in JavaScript. |

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

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

3. Validate and save your changes.

4. 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* > Assertion Processing.

   2. Under Account Mapper, select your script from the SAML2 Name ID Mapper Script drop-down list.

   3. Save your changes.

5. Test your changes using an SP-initiated flow.

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

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