--- title: Consume REST STS instances description: You consume a REST STS instance by sending REST API calls to the instance's endpoint. component: pingam version: 7.3 page_id: pingam:sts-guide:sts-consume-rest canonical_url: https://docs.pingidentity.com/pingam/8.1/sts/sts-consume-rest.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Security Token Service (STS)", "Rest", "JSON", "Java"] section_ids: sts-consume-rest-endpoint: REST 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 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: ```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…​ } } ``` 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](sts-configure-rest-properties.html). * `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 `` 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 REST STS token transformations: 1. Transform a username token to a SAML 2.0 token with the bearer subject confirmation method: ```json { "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 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" } } ``` 3. Transform an OpenID Connect 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==" } } } ``` 4. Transform an AM SSO token to an OpenID Connect token: ```json { "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](#sts-consume-rest-programmatic). ## 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 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": "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": "\n saml2-issuer \n demo \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 REST STS instance programmatically. Tailor this example as required to provide programmatic consumption of your own REST STS instances. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For information on downloading and building AM sample source code, see [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) in the *Knowledge Base*.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. |