--- 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: 8.1 page_id: pingam:sts:sts-publish-service canonical_url: https://docs.pingidentity.com/pingam/8.1/sts/sts-publish-service.html keywords: ["Security Token Service (STS)", "Rest", "Customization", "JSON"] page_aliases: ["sts-guide:sts-publish-service.adoc"] section_ids: sts-publish-rest: Publish 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 an 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://am.example.com:8443/am/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. Find a complete example of an `instance_state` object in the sample code for the `RestSTSInstancePublisher` class in [Publish 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 the endpoint for the instance, such as `/sts-publish/rest/realm/deployment-URL-element`. Where *deployment-URL-element* is the value of the STS instance's deployment URL element, which is one of the instance's configuration properties, and *realm* is the realm in which the instance has been configured. For example, you could obtain the configuration of an 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://am.example.com:8443/am/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 `/sts-publish/rest/realm/deployment-URL-element`. ## Publish STS instances The sample code referenced in this section provides an example of how to programmatically publish STS instance. The code isn't intended to be a working example. Instead, it is a starting point that you can modify to satisfy your organization's specific requirements. 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`. After publishing an 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 STS instances by calling methods that perform an HTTP POST operation on the `sts-publish/rest` endpoint. * RestSTSInstanceConfigFactory The `RestSTSInstancePublisher` class calls the `RestSTSInstanceConfigFactory` class to create a `RestSTSInstanceConfig` instance. `RestSTSInstanceConfig` objects encapsulate all the configuration information of an STS instance, and emit JSON values that you can post to the `sts-publish/rest` endpoint to publish an STS instance. * STSPublishContext The sample `STSPublishContext` class specifies the configuration necessary to publish STS instances. The class provides a programmatic method for setting configuration properties. The same configuration properties are available through the AM admin UI under Realms > *realm name* > STS. * CustomTokenOperationContext The sample `CustomTokenOperationContext` class specifies custom validators, token types, and transformations that an STS instance can support. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The sample code referenced in this section isn't compilable 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 publish 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.ADMIN_PASSWORD` from the imported `com.forgerock.openam.functionaltest.sts.frmwk.common.CommonConstants` utility class. This utility class isn't 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 an STS instance. |