How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I create a custom SAML2 SP attribute mapper in AM (All versions)?

Last updated May 6, 2021

The purpose of this article is to provide information on creating a custom SAML2 attribute mapper for the hosted SP in AM. This is achieved by extending the DefaultSPAttributeMapper class that implements the SPAttributeMapper interface, which requires cloning the am-external repository.

1 reader recommends this article


If you want to customize the default SP attribute mapper, for example, to map an LDAP attribute name and value to a custom format, or to add an extra attribute to the local session, you can do this by implementing a custom SPAttributeMapper. This is achieved by extending the DefaultSPAttributeMapper Java® class. This class is available from the am-external Git repository hosted on our BitBucket® Server.


Disclaimer for the following code, please review before implementing these changes. This code is just a sample; it does not include best practice for Java code (such as error handling) and will need customizing to fit your use case. Customizing SAML2 plugins is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.  


Creating a custom attribute mapper requires cloning the am-external repository. Before you begin, please follow the steps below to ensure you have access to the ForgeRock private Maven repository:

  1. Generate a ~/.m2/settings.xml file per How do I access the ForgeRock protected Maven repositories? It is essential that you create a valid settings.xml to access the Maven repositories needed for the build process. Failing to do this will cause your build to fail.
  2. Create an SSH key and add it to your Bitbucket profile to allow you to clone the source code with an SSH URL.

Creating a custom SP attribute mapper

You can create a custom SP attribute mapper as follows:

  1. Git clone the AM external repository (this repository is required for reference and building your custom class): $ git clone ssh://
  2. Check out the relevant branch. For example, 7.0.0: $ cd am-external $ git checkout releases/7.0.0  $ cd openam-federation
  3. Create a new Java project in your IDE.
  4. Add a Maven dependency to your project for the openam-federation-library. For example:<dependency>  <groupId></groupId>   <artifactId>openam-federation-library</artifactId> </dependency>

You must add openam-federation-library as a dependency. The code for this library is located in the repository you cloned in step 1 (am-external/openam-federation/openam-federation-library). You may need to add more dependencies depending on your specific customization.

  1. Create a new custom class that extends the DefaultSPAttributeMapper class, for example, CustomSPAttributeMapper. You should refer to Interface SPAttributeMapper for further information.
  2. Override the getAttributes() method to achieve your desired customization. The resulting class would look similar to this: public class CustomSPAttributeMapper extends DefaultSPAttributeMapper {    /**      * Constructor      */     public CustomSPAttributeMapper() {     }     /**     * comments to be made here      */     @Override     public Map<String,Set<String>> getAttributes (         List<Attribute> attributes,          String userID,          String hostEntityID,          String remoteEntityID,          String realm){      Map<String,Set<String>> attributes =          super.getAttributes (attributes, userID, hostEntityID, remoteEntityID, realm);               //insert business logic here such as adding a new attribute               return attributes;     } }
  3. Build a .jar file containing the custom class using the following command:$ mvn clean packageThe project will generate a .jar file containing your custom class in the target directory. For example, am-custom-mapper-7.0.0.jar.
  4. Copy the .jar file to the WEB-INF/lib/ folder where AM is deployed. For example:$ cp am-custom-mapper-7.0.0.jar /path/to/tomcat/webapps/openam/WEB-INF/lib/
  5. Update the configuration for the Hosted SP with your new custom class:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Hosted SP Name] > Assertion Processing > Attribute Mapper and replace the default class with the fully qualified name of your custom class.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [Hosted SP Name] > Assertion Processing > Attribute Mapper and replace the default class with the fully qualified name of your custom class.
  6. Restart the web application container in which AM runs.
  7. Test your changes.

See Also

How do I customize SAML2 plugins in AM (All versions)?

SAML Federation in AM

SAML v2.0 Guide › Assertion Processing

API Javadoc › Interface SPAttributeMapper

Related Training


Related Issue Tracker IDs


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.