PingAM 8.0.0

Consume STS instances

You consume a Security Token Service (STS) instance by sending REST API calls to the instance’s endpoint.

STS instance endpoint

An STS instance endpoint is composed of the following:

  • The AM context

  • The string rest-sts

  • The realm in which the STS instance is configured

  • The deployment URL element (a configuration property of the STS instance)

For example, an STS instance configured in the alpha realm with the deployment URL element username-transformer exposes the endpoint /rest-sts/alpha/username-transformer.

JSON representation of token transformations

Token transformations are represented in JSON as follows:

{
  "input_token_state": {
    "token_type": "INPUT_TOKEN_TYPE"
    …​INPUT_TOKEN_TYPE_PROPERTIES…​
  },
  "output_token_state": {
    "token_type": "OUTPUT_TOKEN_TYPE"
    …​OUTPUT_TOKEN_TYPE_PROPERTIES…​
  }
}

The STS supports the following token types and properties:

Input token types

  • USERNAME

    Requires the username and password properties.

  • OPENAM

    Requires the session_id property, with an SSO token as its value.

  • X509

    No properties are required because input X.509 tokens are presented in HTTP headers or through TLS.

    Find information about X.509 tokens in the Authentication Target Mappings and Client Certificate Header Key properties in the STS configuration properties.

  • OPENIDCONNECT

    Requires the oidc_id_token property with the OIDC token as its value.

Output token types

  • SAML2

    Requires the subject_confirmation property, the value of which determines the <saml:ConfirmationMethod> element for the generated SAML v2.0 assertion. Valid values are BEARER, SENDER_VOUCHES, and HOLDER_OF_KEY.

    When generating an assertion with a holder-of-key subject confirmation method, the proof_token_state property is required. The value for this property is an object that contains the base64EncodedCertificate property.

  • OPENIDCONNECT

    Requires the nonce and allow_access properties.

The following are examples of JSON payloads that define STS token transformations:

  • Transform a username token to a SAML v2.0 token with the BEARER subject confirmation method:

    {
  "input_token_state": {
    "token_type": "USERNAME",
    "username": "bjensen",
    "password": "Ch4ng31t"
  },
  "output_token_state": {
    "token_type": "SAML2",
    "subject_confirmation": "BEARER"
  }
}

  • Transform an X.509 token to a SAML v2.0 token with the SENDER_VOUCHES subject confirmation method:

    {
  "input_token_state": {
    "token_type": "X509"
  },
  "output_token_state": {
    "token_type": "SAML2",
    "subject_confirmation": "SENDER_VOUCHES"
  }
}

  • Transform an OIDC token to a SAML v2.0 token with the HOLDER_OF_KEY subject confirmation method:

    {
  "input_token_state": {
    "token_type": "OPENIDCONNECT",
    "oidc_id_token": "eyAiYWxQ.euTNnNDExNTkyMjEyIH0.kuNlKwyvZJqaC8EYpDyPJMiEcII"
  },
  "output_token_state": {
    "token_type": "SAML2",
    "subject_confirmation": "HOLDER_OF_KEY",
    "proof_token_state": {
      "base64EncodedCertificate": "MIMbFAAOBjQAwgYkCgYEArSQ…​c/U75GB2AtKhbGS5pimrW0Y0Q=="
     }
  }
}

  • Transform an AM SSO token to an OIDC token:

    {
  "input_token_state": {
    "token_type": "OPENAM",
    "session_id": "AQIC5wM2…​TMQAA*"
  },
  "output_token_state": {
    "token_type": "OPENIDCONNECT",
    "nonce": "471564333",
    "allow_access": true
  }
}

Find more examples of JSON payloads you can send to STS instances in the comments in the Java example sample code.

Command-line example

You can use the curl command to check that a published STS instance is working as expected.

For example, if you publish a REST instance with a deployment URL element username-transformer that supports username to SAML v2.0 bearer assertion token transformation, you can send an HTTP POST request to the /rest-sts/username-transformer endpoint, setting the _action parameter to translate as follows:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--data '{
  "input_token_state": {
    "token_type": "USERNAME",
    "username": "bjensen",
    "password": "Ch4ng31t"
  },
  "output_token_state": {
    "token_type": "SAML2",
    "subject_confirmation": "BEARER"
  }
}' \
https://am.example.com:8443/am/rest-sts/username-transformer?_action=translate
{
  "issued_token":
     "<saml:Assertion
       xmlns:saml=\"urn:oasis:names:tc:SAML:2.0:assertion\"
       Version=\"2.0\"
       ID=\"s2c51ebd0ad10aae44fb76e4b400164497c63b4ce6\"
       IssueInstant=\"2016-03-02T00:14:47Z\">\n
       <saml:Issuer>saml2-issuer</saml:Issuer>
       <saml:Subject>\n
        <saml:NameID
         Format=\"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress\">bjensen
        </saml:NameID>
        <saml:SubjectConfirmation
         Method=\"urn:oasis:names:tc:SAML:2.0:cm:bearer\">\n
         <saml:SubjectConfirmationData
          NotOnOrAfter=\"2016-03-02T00:24:47Z\" >
         </saml:SubjectConfirmationData>
        </saml:SubjectConfirmation>\n
       </saml:Subject>
       <saml:Conditions
        NotBefore=\"2016-03-02T00:14:47Z\"
        NotOnOrAfter=\"2016-03-02T00:24:47Z\">\n
        <saml:AudienceRestriction>\n
         <saml:Audience>saml2-issuer-entity</saml:Audience>\n
        </saml:AudienceRestriction>\n</saml:Conditions>\n
        <saml:AuthnStatement
         AuthnInstant=\"2016-03-02T00:14:47Z\">
         <saml:AuthnContext>
          <saml:AuthnContextClassRef>
           urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
          </saml:AuthnContextClassRef>
         </saml:AuthnContext>
        </saml:AuthnStatement>
       </saml:Assertion>\n"
}

The iPlanetDirectoryPro header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

Java example

The RestSTSConsumer.java sample code provides an example of how to consume a published STS instance programmatically. Tailor this example as required to provide programmatic consumption of your own STS instances.

Learn about downloading and building PingAM sample source code in the following Knowledge Base article: How do I access and build the sample code provided for PingAM?.

You can find the STS code examples under /path/to/openam-samples-external/sts-example-code.

You can’t compile the sample code referenced in this section because it uses classes that aren’t available publicly. The code provides patterns to developers familiar with the problem domain and is intended only to assist developers who want to programmatically consume STS instances.