Consuming REST STS Instances

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

REST STS Instance Endpoint

REST STS instances' endpoints are comprised of the following parts:

  • The AM context

  • The string rest-sts

  • The realm in which the REST STS instance is configured

  • The deployment URL element, which is one of the configuration properties of an 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 either in HTTP headers or by using TLS. For more information about X.509 tokens, see the configuration details for 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:

  1. 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"
  }
}

  2. 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"
  }
}

  3. 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=="
     }
  }
}

  4. 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, see the comments in the sample code in "Java Example".

Command-Line Example

You can use the curl command to quickly verify that a published REST STS instance operates 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 perform an HTTP POST 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.

Tip

For information on downloading and building AM sample source code, see How do I access and build the sample code provided for AM (All versions)? in the Knowledge Base.

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

Important

The sample code referenced in this section is not compilable, 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.

Read a different version of :