--- title: Consume STS instances description: You consume a Security Token Service (STS) instance by sending REST API calls to the instance's endpoint. component: pingam version: 8.1 page_id: pingam:sts:sts-consume-rest canonical_url: https://docs.pingidentity.com/pingam/8.1/sts/sts-consume-rest.html keywords: ["Security Token Service (STS)", "Rest", "JSON", "Java"] page_aliases: ["sts-guide:sts-consume-rest.adoc"] section_ids: sts-consume-rest-endpoint: STS instance endpoint sts-consume-json-payload: JSON representation of token transformations sts-consume-rest-cli: Command-line example sts-consume-rest-programmatic: Java example --- # 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: ```json { "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](sts-configure-rest-properties.html). * `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 `` element for the generated SAML 2.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 2.0 token with the `BEARER` subject confirmation method: ```json { "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 2.0 token with the `SENDER_VOUCHES` subject confirmation method: ```json { "input_token_state": { "token_type": "X509" }, "output_token_state": { "token_type": "SAML2", "subject_confirmation": "SENDER_VOUCHES" } } ``` * Transform an OIDC token to a SAML 2.0 token with the `HOLDER_OF_KEY` subject confirmation method: ```json { "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: ```json { "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](#sts-consume-rest-programmatic) 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 2.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: ```bash $ 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": "\n saml2-issuer \n bjensen \n \n \n \n saml2-issuer-entity\n \n\n urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport \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?](https://support.pingidentity.com/s/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. |