SP account mapper

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

Next-generation example script: SAML2 SP Account Mapper Script
Script bindings: SP account mapper scripting API

Customize auto-federation using an SP account mapper

This section describes how to implement an example SP account mapper that uses a script to customize auto-federation of user accounts. It assumes that you have configured your environment for SSO 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
Configure auto-federation
Update the SP account mapper script
Try the script

Prepare the user profiles

Create a test user on the hosted SP, for example bjensen, with an email address set to bjensen@example.com.
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.

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

Under Native Consoles > Access Management, go to Scripts, and click SAML2 SP Account Mapper Script.
Update the script to implement any custom behavior for auto-federation. This example adds a logging statement to record the assertion map.

To handle a missing NameID in the assertion, update the script to check for a null NameID and fall back to auto-federation.

Learn more in Handle a missing NameID in a script.
```
...
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 {
        ...
    }
```
The SP account mapper script type is a next-generation script only.

Learn about the available bindings in the SP account mapper scripting API.
Still in the native console, go to Applications > Federation > Entity Providers > Hosted SP Name > Assertion Processing.
Under Account Mapper, select SAML2 SP Account Mapper Script from the Account Mapper Script list.
Save your changes.

Try the script

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

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.

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

Handle a missing NameID in a script

If your IdP doesn’t always include a NameID in the assertion, update your SP account mapper script to check for a null NameID and fall back to auto-federation.

When accountMapperHelper.getNameID() returns null, call accountMapperHelper.getAutoFedUser() to resolve the user using the configured auto-federation attribute.

If there’s no NameID and the auto-federation lookup fails to find a user, the script should return null. Advanced Identity Cloud then rejects the assertion.

The following example shows a getIdentity() function with the NameID null check:

function getIdentity() {
    const debugMethod = "ScriptedSPAccountMapper.getIdentity:: ";
    var nameID = accountMapperHelper.getNameID();
    var userID = null;

    if (!nameID) {
        // No NameID in assertion — fall back to auto-federation attribute
        return accountMapperHelper.getAutoFedUser();
    }

    var isTransient = accountMapperHelper.isTransientNameId(nameID["format"]);
    if (isTransient) {
        userID = accountMapperHelper.getTransientUserForSP();
        accountMapperHelper.validateUserId(userID);
        if (userID != null && userID.length > 0) {
            logger.debug(debugMethod + " use Transient user as userID:" + userID);
            return userID;
        }
    }

    userID = accountMapperHelper.getAutoFedUser(nameID["value"]);
    if (userID != null && userID.length > 0) {
        logger.debug(debugMethod + " use AutoFedUser as userID:" + userID);
        return userID;
    } else {
        if (accountMapperHelper.useNameIDAsSPUserID() && !accountMapperHelper.isAutoFedEnabled()) {
            logger.debug(debugMethod + " use NameID value as userID:" + nameID["value"]);
            accountMapperHelper.validateUserId(nameID["value"]);
            return nameID["value"];
        } else {
            return null;
        }
    }
}

getIdentity();

SLO isn’t supported when the NameID is missing from the assertion. Learn more in Auto-federation when no NameID is present.

PingOne Advanced Identity Cloud