AM 7.2.0

IDP attribute mapper plugin

Use this plugin to map user-configured attributes to SAML attribute objects to insert into the generated SAML assertion.

The default implementation is to retrieve the mapped attribute values from the user profile first. If the attribute values are not present in the user’s profile, then the plugin attempts to retrieve them from the user’s session.

Java implementation

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

  1. Include the openam-federation-library as a dependency in your Maven project.

  2. Write a Java class that implements the com.sun.identity.saml2.plugins.IDPAttributeMapper interface, or extends the com.sun.identity.saml2.plugins.DefaultIDPAttributeMapper class.

  3. Override the getAttributes() method to customize the list of the attributes returned.

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

  5. 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 Name > Assertion Processing.

    2. In the Attribute Mapper field, type the fully qualified name of your custom class.

    3. Save your changes.

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

For more information, see How do I create a custom SAML2 IDP attribute mapper? in the Knowledge Base.
Java interface

IDPAttributeMapper

Default Java class

com.sun.identity.saml2.plugins.DefaultIDPAttributeMapper

Scripted implementation

To view the default script, including the available script properties, see saml2-idp-attribute-mapper.js.

To view or modify the default script in the AM admin UI, go to Realms > Realm Name > Scripts and select SAML2 IDP Attribute Mapper Script.

Customize the IDP attribute mapper script

Complete the following steps to implement an example IDP attribute mapper script that modifies the SAML attributes that are inserted in the assertion returned by the IDP.

If you prefer to create a new script, reference the new script name when you configure the hosted entity provider.

For more information, see Manage scripts (UI).

This task assumes your environment is already correctly configured for single sign-on using SAML v2.0, where AM is the hosted IDP.

  1. In the AM admin UI, go to Realms > Realm Name > Scripts, and click SAML2 IDP Attribute Mapper Script.

  2. In the Script field, insert the following lines of example code to return a custom static attribute, around line 150, preceding return attributes;:

    var customSet = new java.util.HashSet();
    customSet.add("test");
    attributes.add(idpAttributeMapperScriptHelper.createSAMLAttribute("customSAMLAttribute", null, customSet));

    For information about the bindings that are available to the script, see IDP attribute mapper scripting API.

  3. Validate and save your changes.

  4. Configure AM to use the updated IDP attribute mapper script.

    1. In the AM admin UI, go to Realms > Realm Name > Applications > Federation > Entity Providers > Hosted IDP Name > Assertion Processing.

    2. In the Attribute Mapper Script field, select SAML2 IDP Attribute Mapper Script.

      Alternatively, if you created a script rather than modifying the default, select the new script name.

    3. Save your changes.

  5. Test your changes and verify that the AttributeStatement element in the SAML assertion contains the custom attribute.

    For example:

    <saml:AttributeStatement>
      <saml:Attribute Name="customSAMLAttribute">
        <saml:AttributeValue
            xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:type="xs:string">test
        </saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>

IDP attribute mapper scripting API

The following properties are available to IDP attribute mapper scripts, in addition to the common SAML v2.0 properties.

Show script properties
idpAttributeMapperScriptHelper

An IdpAttributeMapperScriptHelper instance containing methods used for IDP attribute mapping. See the IdpAttributeMapperScriptHelper interface. Always present.

remoteEntityId

The remote entity ID.

session

Contains a representation of the user’s single sign-on session object. See the SSOToken interface for information about SSO token and authentication information, as well as session-related properties.

Copyright © 2010-2022 ForgeRock, all rights reserved.