--- title: IDP attribute mapper description: Use this plugin to map user-configured attributes to SAML attribute objects to insert into the generated SAML assertion. component: pingam version: 7.3 page_id: pingam:saml2-guide:plugins-idp-attribute-mapper canonical_url: https://docs.pingidentity.com/pingam/8.1/am-saml2/custom-idp-attribute-mapper.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["SAML 2.0", "Single Sign-on (SSO)", "Federation", "Customization", "Java", "Scripts"] section_ids: java_implementation: Java implementation scripted_implementation: Scripted implementation customize_the_idp_attribute_mapper_script: Customize the IDP attribute mapper script scripting-api-idp-attribute-mapper: IDP attribute mapper scripting API --- # IDP attribute mapper 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 * Java interface `IDPAttributeMapper` * Default Java class `com.sun.identity.saml2.plugins.DefaultIDPAttributeMapper` 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. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Learn more in [How do I create a custom SAML2 IDP attribute mapper in PingAM?](https://support.pingidentity.com/s/article/How-do-I-create-a-custom-SAML2-IdP-attribute-mapper-in-PingAM) in the *Knowledge Base*. | ## Scripted implementation To explore the default script, including the available script properties, refer to [saml2-idp-attribute-mapper.js](../scripting-guide/sample-scripts.html#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, refer to [Manage scripts (UI)](../scripting-guide/manage-scripts-console.html). This task assumes your environment is already correctly configured for single sign-on using SAML 2.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 to modify the default script. Alternatively, create a new script of type `Saml2 IDP Attribute Mapper`. 2. In the Script field, insert one of the following example code snippets before the `return attributes;` line (around line 150): * Add a static single-value attribute: ```javascript var customSet = new java.util.HashSet(); customSet.add("test"); attributes.add(idpAttributeMapperScriptHelper.createSAMLAttribute("customSAMLAttribute", null, customSet)); ``` * Add a static multi-value attribute: ```javascript var customSet = new java.util.HashSet(); var attributes = new java.util.ArrayList(); customSet.add("test1"); customSet.add("test2"); customSet.add("test3"); attributes.add(idpAttributeMapperScriptHelper.createSAMLAttribute("customMultiValueAttribute", null, customSet)); ``` For information about the bindings that are available to the script, refer to [IDP attribute mapper scripting API](#scripting-api-idp-attribute-mapper). 3. Validate and save your changes. 4. Configure AM to use the updated IDP attribute mapper script. 1. Still in the AM admin UI, go to Applications > Federation > Entity Providers > *Hosted IDP Name* > Assertion Processing. 2. In the Attribute Mapper Script field, select SAML2 IDP Attribute Mapper Script. If you created a new script rather than modifying the default, select your script name. 3. Save your changes. 5. Test your changes and verify that the `AttributeStatement` element in the SAML assertion contains the custom attribute. * Example single-value attribute assertion: ```xml test ``` * Example multi-value attribute assertion: ```xml test1 test2 test3 ``` ## IDP attribute mapper scripting API The following properties are available to IDP attribute mapper scripts, in addition to the [common SAML 2.0 properties](customize-saml2-plugins.html#scripting-api-saml2). | Binding | Description | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `idpAttributeMapperScriptHelper` | An [IdpAttributeMapperScriptHelper](../_attachments/apidocs/com/sun/identity/saml2/plugins/scripted/IdpAttributeMapperScriptHelper.html) instance containing methods used for IDP attribute mapping. | | `remoteEntityId` | The remote entity ID. | | `session` | Contains a representation of the user's single sign-on session object.Refer to the [SSOToken](../_attachments/apidocs/com/iplanet/sso/SSOToken.html) interface for information about SSO token and authentication information, as well as session-related properties. |