Access Management 7.3.2

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:

$ 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.

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:

$ 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? 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.