Consume REST STS instances

You consume a REST STS instance by sending REST API calls to the instance’s endpoint.

REST STS instance endpoint

A REST STS instance endpoint is composed of the following:

The AM context
The string rest-sts
The realm in which the REST STS instance is configured
The deployment URL element (a configuration property of the STS instance)

For example, a REST STS instance configured in the realm myRealm with the deployment URL element username-transformer exposes the endpoint /rest-sts/myRealm/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…
  }
}

REST 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. For more information about X.509 tokens, refer to the Authentication Target Mappings and Client Certificate Header Key properties in REST STS configuration properties.
OPENIDCONNECT

Requires the oidc_id_token property, with the OpenID Connect 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 REST 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": "demo",
    "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 OpenID Connect 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 OpenID Connect token:

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

For more examples of JSON payloads that you can send to REST STS instances, refer to the comments in the sample code in Java example.

Command-line example

You can use the curl command to check that a published REST 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": "demo",
        "password": "Ch4ng31t"
    },
    "output_token_state": {
        "token_type": "SAML2",
        "subject_confirmation": "BEARER"
    }
}' \
https://openam.example.com:8443/openam/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\">demo
        </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 REST STS instance programmatically. Tailor this example as required to provide programmatic consumption of your own REST 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 cannot compile the sample code referenced in this section because it uses classes that are not 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 REST STS instances.