PingAM

SP account mapper

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

Java example

Java interface

com.sun.identity.saml2.plugins.SPAccountMapper

To create a custom SP account mapper in Java, follow the steps described in How do I create a custom SAML2 SP account mapper in PingAM? in the Knowledge Base.

Scripted example

Learn about SP account mapper scripts from the following resources:

Next-generation example script

SAML2 SP Account Mapper Script

Scripting API

SP account mapper scripting API

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 SSO using SAML 2.0, where AM is the hosted SP. These example steps use another instance of AM 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

In the AM admin UI, go to Realms > realm name > Applications > Federation > Entity Providers and click on the name of the hosted provider.

  1. On the hosted SP:

    1. Under Assertion Processing > Auto Federation:

      • Switch on Enabled.

      • Set Attribute to mail.

    2. Save your changes.

  2. On 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. In the AM admin UI, go to Realms > realm name > Scripts, and click SAML2 SP Account Mapper Script to modify the default 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 SP account mapper scripting API.

  3. In the AM admin UI, go to Realms > realm name > Applications > Federation > Entity Providers > hosted SP > Assertion Processing.

  4. Under Account Mapper, select the default script (SAML2 SP Account Mapper Script) from the Account Mapper Script drop-down 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://sp.example.com:8443/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 have logged into the IdP successfully, you don’t need to log into the SP because the script successfully auto-federated 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