How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated May 6, 2021

The purpose of this article is to provide information on customizing the default SAML2 plugins in AM. These plugins include account mappers, attribute mappers and adapters for both the IdP and SP.

2 readers recommend this article


If you want to customize the default account mappers, attribute mappers or adapters, you need to implement corresponding interfaces or extend an abstract class. Most of those interfaces or abstract classes have an implementation that we recommend extending when you need a custom plugin. Extending an implementation allows you to delegate the bulk of the work to the default method implementation and only perform small changes according to business requirements.

The following table shows the classes to extend and the corresponding interfaces and abstract classes:

Plugin to customize Implementation class to extend Corresponding Interface or abstract class 
IDP Account Mapper DefaultIDPAccountMapper IDPAccountMapper
SP Account Mapper DefaultLibrarySPAccountMapper SPAccountMapper
IDP Attribute Mapper DefaultLibraryIDPAttributeMapper IDPAttributeMapper
SP Attribute Mapper DefaultSPAttributeMapper SPAttributeMapper
IDP Adapter DefaultIDPAdapter SAML2IdentityProviderAdapter
SP Adapter N/A SAML2ServiceProviderAdapter (Abstract class)

These classes are available from the am-external Git repository hosted on our BitBucket® Server.

The interfaces are part of the Public API: API Javadoc › Package com.sun.identity.saml2.plugins.


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.  

Customizing a default plugin

See the following articles for specific details on customizing the different SAML2 plugins for different use cases:

The basic process is:

  1. Git clone the AM external repository.
  2. Check out the relevant branch.
  3. Create a new Java project in your IDE.
  4. Add a Maven dependency to your project for the openam-federation-library.
  5. Create a new custom class that extends the default implementation class.
  6. Override the method you want to modify and insert your business logic.
  7. Build a .jar file containing the custom class.
  8. Copy the .jar file to the WEB-INF/lib/ folder where AM is deployed.
  9. Update the configuration for the relevant hosted entity provider by replacing the default class with your new custom class.
  10. Restart the web application container in which AM runs.
  11. Test your changes.

See Also

Customizing SAML2 plugins in AM

SAML Federation in AM

SAML v2.0 Guide › Assertion Processing (IdP)

SAML v2.0 Guide › Assertion Processing (SP)

SAML v2.0 Guide › Advanced Settings (IdP)

API Javadoc › Package com.sun.identity.saml2.plugins

Related Training


Related Issue Tracker IDs

OPENAM-11474 (Custom IDP Attribute mappers may cause failures after upgrade)

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