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.

authnRequestHelper

Provides methods for getting and setting the destination on the authentication request.

Only available to SSO functions.

Methods 
public String getDestination()

public void setDestination(String destination)
getDestination

Returns the destination field from the authentication request. Returns null if the authentication request is null.

setDestination

Sets the destination field on the authentication request. Has no effect if the authentication request is null. Throws a SAML2Exception if the destination is marked as immutable.

Not available.

An AuthnRequestHelper object.

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