PingAM 8.0.0

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:

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

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:

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

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.