IdP attribute mapper

Use the IdP attribute mapper 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 aren’t present in the user’s profile, then the IdP attribute mapper attempts to retrieve them from the authenticated session.

These steps assume your environment is already correctly configured for SSO using SAML 2.0, where AM is the hosted IdP.

Java example

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:

Include the openam-federation-library as a dependency in your Maven project.
Write a Java class that implements the com.sun.identity.saml2.plugins.IDPAttributeMapper interface, or extends the com.sun.identity.saml2.plugins.DefaultIDPAttributeMapper class.
Override the getAttributes() method to customize the list of the attributes returned.
Package your custom class in a JAR file and copy to the /WEB-INF/lib folder where you deployed AM.
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 Attribute Mapper field, type the fully qualified name of your custom class.
3. Save your changes.
Restart AM or the container in which it runs.

Learn more in How do I create a custom SAML2 IDP attribute mapper in PingAM? in the Knowledge Base.

Scripted examples

Learn about IdP attribute mapper scripts from the following resources:

Legacy example script: SAML2 IDP Attribute Mapper Script
Next-generation example script: SAML2 IDP Attribute Mapper Script (Next Gen)
Scripting API: IdP attribute mapper scripting API

Add attributes with a legacy script

Complete the following steps to implement an example IdP attribute mapper script that adds SAML attributes to the assertion returned by the IdP.

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 legacy script of type Saml2 IDP Attribute Mapper.

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:

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

Add a static multi-value attribute:

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));

Validate and save your changes.
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 > Assertion Processing.
2. Under Attribute Mapper, select your customized script from the Attribute Mapper Script drop-down list.
3. Save your changes.

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

Example single-value attribute assertion:

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

Example multi-value attribute assertion:

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

Update username with a next-generation script

In the AM admin UI, create a new script with the following values:

Name

Example Next-Generation IdP Attribute Mapper

Script Type

Saml2 IDP Attribute Mapper

Evaluator Version

Next Generation

In the Script field, replace the default script with the following:

// returns the list of attributes for the current session
var attributes = idpAttributeMapperScriptHelper.getStandardAttributes();

for (var attr of attributes) {
  if (attr.name === "username") {
    var upperCaseValues = [];
    for (var val of attr.values) {
      upperCaseValues.push(val.toUpperCase());
    }
    attr.values = upperCaseValues;
  }
}
// return the modified list of attributes
attributes;

Make sure the last line of your script is the list of the attributes to return. It must be in the following format:

[
  {
    "name:": "...",
    "nameFormat": "...",
    "values": ["..."]
  },
...
]

Validate and save your changes.
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 > Assertion Processing.
2. Add the following mapping to the Attribute Map:
  
  SAML Attribute
  
  username
  
  Local Attribute
  
  uid
3. Select your custom script, Example Next-Generation IdP Attribute Mapper, from the Attribute Mapper Script list.
4. Save your changes.

Test your changes using an SP-initiated flow to verify that the SAML assertion contains the updated username value. For example:

<saml:AttributeStatement>
  <saml:Attribute Name="username">
  <saml:AttributeValue
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:type="xs:string">BJENSEN
    </saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

If you run an SP-initiated SSO integrated mode flow, you can include a Scripted Decision node to output the assertion value using the samlApplication binding.

Learn more in Query SAML application and authentication request.