PingOne Advanced Identity Cloud

SP adapter scripting API

The following bindings are available to SP adapter scripts.

An SP adapter script can be either a legacy or a next-generation script. It has access to all the common bindings for its scripting context.
Binding Description Legacy type Next-generation type

authnRequest

The original authentication request.

Only available to SSO functions.

Example JSON (next-generation) 
{
    "@class": "com.sun.identity.saml2.protocol.impl.AuthnRequestImpl",
    "extensions": {
        "@class": "com.sun.identity.saml2.protocol.impl.ExtensionsImpl",
        "elementName": "Extensions",
        "mutable": true
    },
    "version": "2.0",
    "issueInstant": 1767709485362,
    "consent": "urn:oasis:names:tc:SAML:2.0:consent:obtained",
    "subject": {
        "@class": "com.sun.identity.saml2.assertion.impl.SubjectImpl",
        "nameID": {
            "@class": "com.sun.identity.saml2.assertion.impl.NameIDImpl",
            "value": "user@example.com",
            "format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
            "nameQualifier": null,
            "spnameQualifier": null,
            "spprovidedID": null,
            "mutable": true
        },
        "subjectConfirmation": [],
        "encryptedID": null,
        "baseID": null,
        "mutable": true
    },
    "nameIDPolicy": {
        "@class": "com.sun.identity.saml2.protocol.impl.NameIDPolicyImpl",
        "format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
        "allowCreate": true,
        "spnameQualifier": "serviceprovider1",
        "mutable": true
    },
    "conditions": {
        "@class": "com.sun.identity.saml2.assertion.impl.ConditionsImpl",
        "notBefore": 1767709485000,
        "notOnOrAfter": 1767710085000,
        "conditions": [],
        "audienceRestrictions": [
            {
                "@class": "com.sun.identity.saml2.assertion.impl.AudienceRestrictionImpl",
                "audience": ["identityprovider1"],
                "mutable": true
            }
        ],
        "oneTimeUses": [],
        "proxyRestrictions": [],
        "mutable": true
    },
    "scoping": {
        "@class": "com.sun.identity.saml2.protocol.impl.ScopingImpl",
        "proxyCount": 1,
        "idpList": {
            "@class": "com.sun.identity.saml2.protocol.impl.IDPListImpl",
            "idpEntries": [
                {
                    "@class": "com.sun.identity.saml2.protocol.impl.IDPEntryImpl",
                    "providerID": "identityprovider1",
                    "name": "Primary IdP",
                    "loc": "http://idp.example.com:8080/am/SSORedirect/metaAlias/idp1",
                    "mutable": true
                }
            ],
            "getComplete": "http://sp.example.com:18080/am/idplist",
            "mutable": true
        },
        "requesterID": ["serviceprovider1"],
        "mutable": true
    },
    "providerName": "Example Service Provider",
    "forceAuthn": true,
    "protocolBinding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
    "assertionConsumerServiceURL": "http://sp.example.com:18080/am/Consumer/metaAlias/sp1",
    "requestedAuthnContext": {
        "@class": "com.sun.identity.saml2.protocol.impl.RequestedAuthnContextImpl",
        "elementName": "RequestedAuthnContext",
        "mutable": true,
        "authnContextClassRef": [
            "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport",
            "urn:oasis:names:tc:SAML:2.0:ac:classes:X509"
        ],
        "authnContextDeclRef": [],
        "comparison": "minimum"
    },
    "passive": false,
    "assertionConsumerServiceIndex": 0,
    "attributeConsumingServiceIndex": 1,
    "signature": "<ds:Signature xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>...</ds:Signature>",
    "signed": true,
    "id": "s2578166e2fae83263539cf09a502e76fca2277d56",
    "issuer": {
        "value": "serviceprovider1",
        "nameQualifier": "http://sp.example.com",
        "format": "urn:oasis:names:tc:SAML:2.0:nameid-format:entity",
        "spnameQualifier": "serviceprovider1",
        "spprovidedID": "sp-internal-id-123",
        "mutable": true
    },
    "destination": "http://idp.example.com:8080/am/SSORedirect/metaAlias/idp1",
    "mutable": true
}

An AuthnRequest object.

A JSON map.

binding

The binding used for the name identifier request.

Not available to SSO functions.

Example 
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
urn:oasis:names:tc:SAML:2.0:bindings:SOAP

String

String

failureCode

The failure code associated with the error that has occurred.

Possible values
Constant Value

SUCCESS

0

INVALID_RESPONSE

1

FEDERATION_FAILED_WRITING_ACCOUNT_INFO

3

SSO_FAILED_SESSION_ERROR

4

SSO_FAILED_ATTRIBUTE_MAPPING

5

SSO_FAILED_NO_USER_MAPPING

6

SSO_FAILED_AUTH_USER_INACTIVE

7

SSO_FAILED_AUTH_USER_LOCKED

8

SSO_FAILED_AUTH_ACCOUNT_EXPIRED

9

SSO_FAILED_SESSION_GENERATION

10

SSO_FAILED_META_DATA_ERROR

11

Only available to preSendFailureResponse.

Integer

Integer

hostedEntityId

The entity ID for the hosted SP.

String

String

idpEntityID

The entity ID for the IdP that sends the sign-on request.

Only available to preSingleSignOnRequest.

String

String

idRequest

Represents a ManageNameID request.

Only available to postNewNameIDSuccess and postTerminateNameIDSuccess.

A ManageNameIDRequest object.

Not available

idResponse

The response to a ManageNameID request. Only available to postNewNameIDSuccess and postTerminateNameIDSuccess.

A ManageNameIDResponse object

Not available.

isFederation

True if using federation, otherwise false.

Only available to the postSingleSignOnSuccess function.

A boolean type.

A Boolean object.

logoutRequest

The SLO request.

Only available to preSingleLogoutProcess and postSingleLogoutProcess.

A LogoutRequest object.

Not available.

logoutResponse

The SLO response.

Only available to preSingleLogoutProcess and postSingleLogoutProcess.

A LogoutResponse object.

Not available.

out

The stream to output logging to.

Only available to postSingleSignOnSuccess.

A PrintWriter object.

Not available.

Use the common binding, logger, instead.

profile

The protocol profile used.

Example 
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact
urn:oasis:names:tc:SAML:2.0:bindings:PAOS

Available to preSingleSignOnProcess, postSingleSignOnSuccess, and postSingleSignOnFailure.

String

String

request

The HTTP request.

Always present.

Example JSON (next-generation) 
{
  "allowTrace": false,
  "secure": true,
  "requestedSessionIdValid": true,
  "remoteAddr": "10.67.3.17",
  "requestedSessionIdFromURL": false,
  "parameterNames": {},
  "protocol": "HTTP/1.1",
  "localName": "am-5f87474849-f7b9m",
  "asyncSupported": false,
  "requestedSessionIdFromCookie": true,
  "protocolRequestId": null,
  "asyncStarted": false,
  "localAddr": "10.67.3.6",
  "contentLength": 873,
  "servletConnection": {
    "protocol": "http/1.1",
    "connectionId": "a368",
    "secure": false,
    "protocolConnectionId": ""
  },
  "attributeNames": {},
  "remotePort": 60476,
  "queryString": "ReqID=s2c48de88f798137a410875437b1a4c0fa7bd9b239&index=null&acsURL=https://sp.example.com/am/Consumer/metaAlias/alpha/sp1&spEntityID=serviceprovider1&binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
  "requestId": "cbbc",
  "characterEncoding": "UTF-8",
  "authType": null,
  "requestedSessionId": "3AECBCB5567836F65E08298982526907",
  "remoteHost": "10.67.3.17",
  "scheme": "https",
  "trailerFieldsReady": true,
  "serverName": "openam-pr-25597.forgeblocks.com",
  "remoteUser": null,
  "requestURI": "/am/SSORedirect/metaAlias/alpha/idp1",
  "method": "POST",
  "pathTranslated": "/usr/local/tomcat/webapps/am/metaAlias/alpha/idp1",
  "servletPath": "/SSORedirect",
  "cookies": [
    {
      "path": null,
      "name": "JSESSIONID",
      "maxAge": -1,
      "domain": null,
      "value": "3AECBCB5567836F65E08298982526907",
      "secure": false,
      "attributes": {},
      "comment": null,
      "version": 0,
      "httpOnly": false
    },
    {
      "path": null,
      "maxAge": -1,
      "name": "amlbcookie",
      "domain": null,
      "secure": false,
      "attributes": {},
      "comment": null,
      "value": "01",
      "version": 0,
      "httpOnly": false
    },
    {
      "value": "6WcS7CVJ-aVwtaFvZJ40bAys6vc.*AAJTSQACMDIAAlNLABxMK2o0OEpISjFsQkl5ZlFHN0p2RTBDVWJGdTQ9AAR0eXBlAANDVFMAAlMxAAIwMQ..*",
      "path": null,
      "maxAge": -1,
      "name": "58eaf95f29a4d6c",
      "domain": null,
      "secure": false,
      "attributes": {},
      "comment": null,
      "version": 0,
      "httpOnly": false
    }
  ],
  "trailerFields": {},
  "pathInfo": "/metaAlias/alpha/idp1",
  "headerNames": {},
  "requestURL": "https://idp.example.com/am/SSORedirect/metaAlias/alpha/idp1",
  "userPrincipal": null,
  "contentLengthLong": 873,
  "httpServletMapping": {
    "pattern": "/SSORedirect/*",
    "mappingMatch": "PATH",
    "servletName": "IDPSSOFederateServlet",
    "matchValue": "metaAlias/alpha/idp1"
  },
  "locales": {},
  "contextPath": "/am",
  "localPort": 8080,
  "serverPort": 443,
  "contentType": "application/x-www-form-urlencoded",
  "parameterMap": {
    "acsURL": [
      "https://sp.example.com/am/Consumer/metaAlias/alpha/sp1"
    ],
    "ReqID": [
      "s2c48de88f798137a410875437b1a4c0fa7bd9b239"
    ],
    "spEntityID": [
      "serviceprovider1"
    ],
    "binding": [
      "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
    ],
    "saml2Request": [
      "eyJ0eXA ... YPA"
    ],
    "index": [
      "null"
    ]
  },
  "locale": "en_GB"
}

A Java object.

A JSON map.

requestHelper

Provides the following methods for accessing request details:

  • public Object getAttribute(String name)

  • public void setAttribute(String name, Object value)

  • public String getHeader(String name)

  • public List<String> getHeaders(String name)

  • public String getParameter(String name)

  • public String[] getParameterValues(String name)

Always present.

Not available.

A HttpServletRequestHelper object.

res

The SSO Response received from the IdP.

Available to preSingleSignOnProcess, postSingleSignOnSuccess, and postSingleSignOnFailure.

A Response object.

Not available.

Use ssoResponse instead.

response

The HTTP response.

Always present.

Example JSON (next-generation) 
{
  "status": 200,
  "trailerFields": {
    "X-Trace-ID": [
      "trace-abc123"
    ],
    "X-Processing-Time": [
      "45ms"
    ]
  },
  "headerNames": [
    "Location",
    "X-Frame-Options",
    "X-Content-Type-Options",
    "Set-Cookie"
  ],
  "headers": {
    "Location": "http://idp.example.com:8080/am/SSORedirect/metaAlias/idp1?SAMLRequest=PHNhbWxwOkF1dGhuUmVxdWVzdCB...",
    "X-Frame-Options": "SAMEORIGIN",
    "X-Content-Type-Options": "nosniff",
    "Set-Cookie": [
      "iPlanetDirectoryPro=AQIC5wM2LY4SfcxZnBMVz...; Path=/am; Secure; HttpOnly; SameSite=None"
    ]
  },
  "locale": "en_US",
  "characterEncoding": "UTF-8",
  "bufferSize": 8192,
  "committed": true,
  "contentType": "text/html; charset=UTF-8",
  "contentLength": 1024,
  "redirectLocation": "http://idp.example.com:8080/am/SSORedirect/metaAlias/idp1?SAMLRequest=PHNhbWxwOkF1dGhuUmVxdWVzdCB..."
}

An HttpServletResponse object.

A JSON map.

session

Only available to postSingleSignOnSuccess.

Contains a representation of the user’s SSO session object.

An SSOToken object.

A ScriptedSession object.

Methods 
public String getProperty(String name)

public void setProperty(String name, String value)

ssoResponse

An SSO response object.

Example JSON (next-generation) 
{
  "@class": "com.sun.identity.saml2.protocol.impl.ResponseImpl",
  "version": "2.0",
  "issueInstant": 1767709489000,
  "destination": "http://sp.example.com:18080/am/Consumer/metaAlias/sp1",
  "extensions": {
    "@class": "com.sun.identity.saml2.protocol.impl.ExtensionsImpl",
    "elementName": "Extensions",
    "mutable": false
  },
  "consent": "urn:oasis:names:tc:SAML:2.0:consent:obtained",
  "inResponseTo": "s2578166e2fae83263539cf09a502e76fca2277d56",
  "status": {
    "@class": "com.sun.identity.saml2.protocol.impl.StatusImpl",
    "statusCode": {
      "@class": "com.sun.identity.saml2.protocol.impl.StatusCodeImpl",
      "statusCode": null,
      "value": "urn:oasis:names:tc:SAML:2.0:status:Success",
      "mutable": false
    },
    "statusMessage": "Authentication successful",
    "statusDetail": {
      "@class": "com.sun.identity.saml2.protocol.impl.StatusDetailImpl",
      "elementName": "StatusDetail",
      "mutable": false
    },
    "mutable": false
  },
  "issuer": {
    "value": "identityprovider1",
    "nameQualifier": "http://idp.example.com",
    "format": "urn:oasis:names:tc:SAML:2.0:nameid-format:entity",
    "spnameQualifier": "serviceprovider1",
    "spprovidedID": "idp-internal-id-456",
    "mutable": false
  },
  "assertion": [
    {
      "version": "2.0",
      "issueInstant": 1767709489000,
      "subject": {
        "nameID": {
          "@class": "com.sun.identity.saml2.assertion.impl.NameIDImpl",
          "value": "aFq1HqWl8/pc83OZGhkLNHFuEkCi",
          "nameQualifier": "identityprovider1",
          "format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
          "spnameQualifier": "serviceprovider1",
          "spprovidedID": "bjensen",
          "mutable": false
        },
        "subjectConfirmation": [
          {
            "subjectConfirmationData": {
              "elementName": "SubjectConfirmationData",
              "mutable": false,
              "notOnOrAfter": 1767710089000,
              "inResponseTo": "s2578166e2fae83263539cf09a502e76fca2277d56",
              "content": [],
              "recipient": "http://sp.example.com:18080/am/Consumer/metaAlias/sp1",
              "notBefore": 1767709489000,
              "address": "172.19.0.1",
              "contentType": null
            },
            "method": "urn:oasis:names:tc:SAML:2.0:cm:bearer",
            "nameID": null,
            "encryptedID": null,
            "baseID": null,
            "mutable": false
          }
        ],
        "encryptedID": null,
        "baseID": null,
        "mutable": false
      },
      "advice": {
        "@class": "com.sun.identity.saml2.assertion.impl.AdviceImpl",
        "assertionIDRef": [
          "s2abc123def456"
        ],
        "assertionURIRef": [
          "http://idp.example.com/assertions/s2abc123def456"
        ],
        "assertion": [],
        "encryptedAssertion": [],
        "mutable": false
      },
      "signature": "<ds:Signature> ... </ds:Signature>",
      "conditions": {
        "notOnOrAfter": 1767710089000,
        "conditions": [],
        "audienceRestrictions": [
          {
            "audience": [
              "serviceprovider1",
              "serviceprovider-affiliate1"
            ],
            "mutable": false
          }
        ],
        "oneTimeUses": [
          {
            "@class": "com.sun.identity.saml2.assertion.impl.OneTimeUseImpl",
            "mutable": false
          }
        ],
        "proxyRestrictions": [
          {
            "@class": "com.sun.identity.saml2.assertion.impl.ProxyRestrictionImpl",
            "count": 2,
            "audience": [
              "allowedProxy1",
              "allowedProxy2"
            ],
            "mutable": false
          }
        ],
        "notBefore": 1767708889000,
        "mutable": false
      },
      "id": "s2e8fc236980e116c65b72adede82e22cc75771f5b",
      "statements": [],
      "authnStatements": [
        {
          "authnContext": {
            "authnContextClassRef": "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport",
            "authnContextDecl": null,
            "authnContextDeclRef": "http://idp.example.com/authn-context/ppt",
            "authenticatingAuthority": [
              "identityprovider1",
              "upstream-idp1"
            ],
            "mutable": false
          },
          "subjectLocality": {
            "@class": "com.sun.identity.saml2.assertion.impl.SubjectLocalityImpl",
            "address": "172.19.0.1",
            "dnsName": "client.example.com",
            "mutable": false
          },
          "authnInstant": 1767709489000,
          "sessionIndex": "s2b464c448ed0d178eb1bcc42ed76347a973f4fd01",
          "sessionNotOnOrAfter": 1767713089000,
          "mutable": false
        }
      ],
      "authzDecisionStatements": [
        {
          "@class": "com.sun.identity.saml2.assertion.impl.AuthzDecisionStatementImpl",
          "resource": "http://sp.example.com:18080/myapp/resource",
          "decision": "Permit",
          "action": [
            {
              "namespace": "urn:oasis:names:tc:SAML:1.0:action:rwedc-negation",
              "value": "Read"
            },
            {
              "namespace": "urn:oasis:names:tc:SAML:1.0:action:rwedc-negation",
              "value": "Write"
            }
          ],
          "evidence": {
            "@class": "com.sun.identity.saml2.assertion.impl.EvidenceImpl",
            "assertionIDRef": [
              "s2evidence123"
            ],
            "assertionURIRef": [],
            "assertion": [],
            "encryptedAssertion": [],
            "mutable": false
          },
          "mutable": false
        }
      ],
      "attributeStatements": [
        {
          "@class": "com.sun.identity.saml2.assertion.impl.AttributeStatementImpl",
          "attribute": [
            {
              "@class": "com.sun.identity.saml2.assertion.impl.AttributeImpl",
              "name": "uid",
              "nameFormat": "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
              "friendlyName": "User ID",
              "attributeValue": [
                "bjensen"
              ],
              "mutable": false
            },
            {
              "@class": "com.sun.identity.saml2.assertion.impl.AttributeImpl",
              "name": "mail",
              "nameFormat": "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
              "friendlyName": "Email Address",
              "attributeValue": [
                "bjensen@example.com"
              ],
              "mutable": false
            }
          ],
          "encryptedAttribute": [],
          "mutable": false
        }
      ],
      "issuer": {
        "value": "identityprovider1",
        "nameQualifier": "http://idp.example.com",
        "format": "urn:oasis:names:tc:SAML:2.0:nameid-format:entity",
        "spnameQualifier": "",
        "spprovidedID": "",
        "mutable": false
      },
      "signed": true,
      "timeValid": true,
      "mutable": false
    }
  ],
  "encryptedAssertion": [],
  "signature": "<ds:Signature xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>...</ds:Signature>",
  "signed": true,
  "id": "s2de06317d521c14ce7e1eaef0e0fc571baafa5dd8",
  "mutable": false
}

Not available.

A JSON map.

spAdapterScriptHelper

The script helper object contains the method that provides context information when customizing the SP adapter plugin points:

  • Map<String, String> getSpAdapterEnv(String realm, String spEntityId)

    Returns a map with information about the SP Adapter environment.

Always present.

A map of Strings.

A map of Strings.

userId

The unique universal ID of the user associated with the request.

Not available to SSO functions.

String

String