--- title: The Publish service description: To publish an STS instance, perform an HTTP POST on the /sts-publish/rest endpoint, specifying the _action=create parameter in the URL. component: pingam version: 7.4 page_id: pingam:sts:sts-publish-service canonical_url: https://docs.pingidentity.com/pingam/8.1/sts/sts-publish-service.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", "Customization", "JSON"] page_aliases: ["sts-guide:sts-publish-service.adoc"] superseded_by: https://docs.pingidentity.com/pingam/8.1/sts/sts-publish-service.html section_ids: sts-publish-rest: Publish REST STS instances --- # The Publish service To publish an STS instance, perform an HTTP POST on the `/sts-publish/rest` endpoint, specifying the `_action=create` parameter in the URL. For example, you could publish a REST STS instance named `username-transformer` in the Top Level Realm as follows: ```bash $ curl \ --request POST \ --header "iPlanetDirectoryPro: AQIC5…​" \ --header "Content-Type: application/json" \ --data '{ "invocation_context": "invocation_context_client_sdk", "instance_state": { "saml2-config": { "issuer-name":"saml2-issuer", …​ }, "deployment-config": { "deployment-url-element":"username-transformer", "deployment-realm":"/", …​ }, "persist-issued-tokens-in-cts":"false", "supported-token-transforms":[{ "inputTokenType":"USERNAME", "outputTokenType":"OPENIDCONNECT", "invalidateInterimOpenAMSession":false }], "oidc-id-token-config":{ "oidc-issuer":"test", …​ } } }' \ https://openam.example.com:8443/openam/sts-publish/rest?_action=create { "_id":"username-transformer", "_rev":"21939129", "result":"success", "url_element":"username-transformer"} } ``` The `instance_state` object in the JSON payload represents the STS instance's configuration. For a complete example of an `instance_state` object, see the sample code for the `RestSTSInstancePublisher` class in [Publish REST STS instances](#sts-publish-rest). Accessing the `sts-publish` endpoint requires administrative privileges. Authenticate as an AM administrative user, such as `amAdmin`, before attempting to publish an STS instance. In addition to publishing instances, the `sts-publish` endpoint can also return the configuration of an STS instance when you perform an HTTP GET on endpoint for the instance, such as `/sts-publish/rest/realm/deployment-URL-element`. In the endpoint, *deployment-URL-element* is the value of the STS instance's deployment URL element—one of the instance's configuration properties. *realm* is the realm in which the instance has been configured. For example, you could obtain the configuration of a REST STS instance configured in the Top Level Realm with the deployment URL element `username-transformer` as follows: ```bash $ curl \ --request GET \ --header "iPlanetDirectoryPro: AQIC5…​" \ https://openam.example.com:8443/openam/sts-publish/rest/username-transformer { "_id":"username-transformer", "_rev":"-659999943", "username-transformer":{ "saml2-config":{ "issuer-name":"saml2-issuer", …​ }, "deployment-config":{ "deployment-url-element":"username-transformer", …​ }, "persist-issued-tokens-in-cts":"false", "supported-token-transforms":[ { "inputTokenType":"USERNAME", "outputTokenType":"OPENIDCONNECT", "invalidateInterimOpenAMSession":false } ], "oidc-id-token-config":{ "oidc-issuer":"test", …​ } } } ``` You can delete STS instances by performing an HTTP DELETE on the `sts-publish` endpoint: * For REST STS instances, perform an HTTP DELETE on `/sts-publish/rest/realm/deployment-URL-element.` * For SOAP STS instances, perform an HTTP DELETE on `/sts-publish/soap/realm/deployment-URL-element.` | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------- | | | SOAP STS instances are deprecated and cannot be deployed in ths version of AM. If you delete your instances, you will not be able to redeploy them. | ## Publish REST STS instances The sample code referenced in this section provides an example of how to programmatically publish REST STS instance. The code is not intended to be a working example. Rather, it is a starting point—code that you can modify to satisfy your organization's specific requirements. 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`. After publishing a REST STS instance programmatically, you can view the instance's configuration in the AM admin UI. The instance is ready for consumption. Sample code is available for the following classes: * RestSTSInstancePublisher The `RestSTSInstancePublisher` class exposes an API to publish, delete, and update REST STS instances by calling methods that perform an HTTP POST operation on the `soap-sts/publish` endpoint. * RestSTSInstanceConfigFactory The `RestSTSInstancePublisher` class calls the `RestSTSInstanceConfigFactory` class to create a `RestSTSInstanceConfig` instance. `RestSTSInstanceConfig` objects encapsulate all the configuration information of a REST STS instance, and emit JSON values that you can post to the `sts-publish/rest` endpoint to publish a REST STS instance. * STSPublishContext The sample `STSPublishContext` class specifies the configuration necessary to publish REST and SOAP STS instances. The class provides a programmatic method for setting configuration properties—the same configuration properties available through the AM admin UI under Realms > *realm name* > STS. * CustomTokenOperationContext The sample `CustomTokenOperationContext` class specifies custom validators, token types, and transformations that a REST STS instance can support. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | 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 publish REST STS instances.The sample code imports a number of classes, introducing dependencies. Classes imported from the AM API can remain in your code, but other imported classes must be removed and replaced with code that provides similar functionality in your environment. For example, the `RestSTSInstanceConfigFactory` class uses a constant named `CommonConstants.DEFAULT_CERT_MODULE_NAME` from the imported `com.forgerock.openam.functionaltest.sts.frmwk.common.CommonConstants` utility class. This utility class is not publicly available. Therefore, you need to replace this constant with another construct.The critical part of the sample code is the idioms that programmatically set all the state necessary to publish a REST STS instance. |