PingOne Advanced Identity Cloud

SP account mapper

Use the SP account mapper to customize how SAML 2.0 assertions are mapped to user profiles.

Script bindings

SP account mapper scripting API

Example scripted SP account mapper

This section describes how to implement an example SP account mapper that uses a script to auto-federate user accounts. It assumes that you have configured your environment for single sign-on using SAML 2.0, where Advanced Identity Cloud is the hosted SP. These example steps use a separate Advanced Identity Cloud tenant as the remote IdP.

Prepare the user profiles

  1. Create a test user on the hosted SP, for example bjensen, with an email address set to bjensen@example.com.

  2. Create a test user on the hosted IdP, for example babsjensen, with an email address also set to bjensen@example.com.

Configure auto-federation

Under Native Consoles > Access Management, go to Applications > Federation > Entity Providers and click on the name of the hosted provider.

  1. On the tenant configured as the hosted SP:

    1. Under Assertion Processing > Auto Federation:

      • Switch on Enabled.

      • Set Attribute to mail.

    2. Save your changes.

  2. On the tenant configured as the hosted IdP:

    1. Under Assertion Processing > Attribute Mapper, add the following Attribute Map:

      Name Format Uri

      urn:oasis:names:tc:SAML:2.0:attrname-format:basic

      SAML Attribute

      mail

      Local Attribute

      mail

    2. Save your changes.

Update the SP account mapper script

  1. Under Native Consoles > Access Management, go to Scripts, and click SAML2 SP Account Mapper Script.

  2. Update the script to implement any custom behavior for auto-federation. This example adds a logging statement to record the assertion map.

    ...
userID = accountMapperHelper.getAutoFedUser(nameID["value"]);
    if (userID != null && userID.length > 0) {
        //
        // insert custom code here
        //
        // update logging to output assertion and userID
        logger.error("Assertion: " + assertion);
        logger.error(debugMethod + " use AutoFedUser as userID: " + userID);
        return userID;
    } else {
        ...
    }
    Learn about the available bindings in the SP account mapper scripting API.

  3. Still in the native console, go to Applications > Federation > Entity Providers > Hosted SP Name > Assertion Processing.

  4. Under Account Mapper, select SAML2 SP Account Mapper Script from the Account Mapper Script list.

  5. Save your changes.

Try the script

  1. To verify the script works as expected, test your changes using an SP-initiated flow.

    For example:

    https://<tenant-env-sp-fqdn>/am/saml2/jsp/spSSOInit.jsp?realm=/alpha&idpEntityID=idp1&metaAlias=/alpha/sp1&binding=urn%3Aoasis%3Anames%3Atc%3ASAML%3A2.0%3Abindings%3AHTTP-POST

  2. Log into the IdP as babsjensen.

    After you’ve logged into the IdP successfully, you shouldn’t need to log into the SP because the script auto-federates the babsjensen and bjensen accounts.

  3. Verify that bjensen is logged into the SP.

    You can also check that the SP debug logs contain the customized logging output, for example:

    Assertion:
{
    "version": "2.0",
    "issueInstant": 1758805815000,
    "subject": {
        "subjectConfirmation": [
            {
    …​
}
ScriptedSPAccountMapper.getIdentity::  use AutoFedUser as userID: id=bjensen,ou=user,o=alpha,ou=services,ou=am-config

SP account mapper scripting API

The following bindings are available to SP account mapper scripts.

The SP account mapper script is a next-generation script and therefore has access to all the next-generation common bindings in addition to those described here.
Binding Description

accountMapperHelper

The helper object contains supporting methods that provide context information when customizing account mapping on the SP.

public Map<String, Object> getNameID()

Returns the NameID from the assertion as a map.

public boolean isTransientNameId(String nameIDFormat)

Returns a boolean indicating whether the NameID format is transient.

public String getTransientUserForSP()

Returns the transient user ID.

public boolean useNameIDAsSPUserID()

Returns true if the NameID should be used as the SP user ID.

public boolean isAutoFedEnabled()

Returns true if auto-federation is enabled for the entity.

public void validateUserId(String userId)

Validates the user ID.

public String getAutoFedUser(String defaultValue)

Returns the user for the auto-federation attribute or the default value if not found.

assertion

The SAML 2.0 assertion as a map of values.

Example assertion map 
{
    "version": "2.0",
    "issueInstant": 1758805815000,
    "subject": {
        "subjectConfirmation": [
            {
                "subjectConfirmationData": {
                    "elementName": "SubjectConfirmationData",
                    "mutable": false,
                    "notOnOrAfter": 1758806415000,
                    "inResponseTo": "s29f426899dd94932aec220d3294c7b1ee964b54f7",
                    "content": [
                        ""
                    ],
                    "recipient": "https://sp.example.com:18080/am/Consumer/metaAlias/alpha/sp1",
                    "notBefore": null,
                    "address": null,
                    "contentType": null
                },
                "method": "urn:oasis:names:tc:SAML:2.0:cm:bearer",
                "nameID": null,
                "mutable": false,
                "encryptedID": null,
                "baseID": null
            }
        ],
        "nameID": {
            "@class": "com.sun.identity.saml2.assertion.impl.NameIDImpl",
            "value": "KR0XstW8C97SHPfusdTrTphgbiCo",
            "nameQualifier": "idp1",
            "format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
            "mutable": false,
            "spnameQualifier": "sp1",
            "spprovidedID": ""
        },
        "mutable": false,
        "encryptedID": null,
        "baseID": null
    },
    "advice": null,
    "signature": "<ds:Signature ...</ds:Signature>",
    "conditions": {
        "notOnOrAfter": 1758806415000,
        "conditions": [],
        "audienceRestrictions": [
            {
                "audience": [
                    "sp1"
                ],
                "mutable": false
            }
        ],
        "oneTimeUses": [],
        "proxyRestrictions": [],
        "notBefore": 1758805215000,
        "mutable": false
    },
    "id": "s2637ff7cd391dda376a66738031d7fbd63771debd",
    "statements": [],
    "authnStatements": [
        {
            "authnContext": {
                "authnContextClassRef": "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport",
                "authnContextDecl": null,
                "authnContextDeclRef": null,
                "authenticatingAuthority": null,
                "mutable": false
            },
            "subjectLocality": null,
            "authnInstant": 1758805814000,
            "sessionIndex": "s2be0bc04c82ddb9e91bdf70f21bf5fc7dda59a301",
            "sessionNotOnOrAfter": null,
            "mutable": false
        }
    ],
    "authzDecisionStatements": [],
    "attributeStatements": [
        {
            "mutable": false,
            "encryptedAttribute": null,
            "attribute": [
                {
                    "name": "mail",
                    "nameFormat": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
                    "friendlyName": null,
                    "mutable": false,
                    "attributeValue": [
                        "<saml:AttributeValue ...xmlns:saml=\"urn:oasis:names:tc:SAML:2.0:assertion\">bjensen@example.com</saml:AttributeValue>"
                    ],
                    "anyAttribute": null,
                    "attributeValueString": [
                        "bjensen@example.com"
                    ]
                }
            ]
        }
    ],
    "issuer": {
        "value": "idp1",
        "nameQualifier": "",
        "format": "",
        "mutable": false,
        "spnameQualifier": "",
        "spprovidedID": ""
    },
    "signed": true,
    "mutable": false,
    "timeValid": true
}

hostedEntityId

The entity ID for the hosted SP.