Token Procedure API#

Token script procedures are a special-case of script procedures whose job is to issue tokens. As such, they have access to all of the Common Procedure API .

The basics of how token procedures work is explained in the Token Procedures page.

Below, links to the reference documentation are provided, as well as an overview of the token procedure API’s main parts.

Context#

The context object is provided as an argument to the result function of each token procedure. This object has a number of common functions and properties that always exist. These are described in this section.

The types of the context object given to each kind of token procedure is shown at Token Procedure Context Object .

Prepared token data#

Before issuing a token, a token procedure must obtain the basic claims that the token must contain. This is referred to as the token data.

For example, the default token data for an access token can be obtained by calling the OAuthTokenProcedureContext#getDefaultAccessTokenData method.

For a delegation (which is an authorization grant from which tokens may be produced), there’s an equivalent method, OAuthTokenProcedureContext#getDefaultDelegationData.

See also OAuthTokenProcedureContext#getDefaultRefreshTokenData, OAuthTokenProcedureContext#getDefaultIdTokenData, OAuthTokenProcedureContext#getDefaultDeviceCodeData

Token Issuers#

Once a token procedure builds the token data, it must, of course, issue the token. For that, it needs to use issuers.

As with token data, procedures obtain an issuer via Token Procedure Context Object .

The most common token issuers are:

Request data#

Token procedure context objects expose the OAuthTokenProcedureContext#request object, which contains full data about the HTTP ScriptRequest sent by the OAuth OAuthClientConfiguration.

However, for convenience, it also exposes the following directly:

In cases where the client presents an existing token, the token is available as well:

Response data#

The JSON data returned by the Curity Identity Server on token requests will include the data returned by the token procedure.

The context OAuthTokenProcedureContext#defaultResponseData property returns appropriate response data the procedure may want to use for that.

Web service clients#

Token procedures can call external web services through a ScriptWebServiceClient. Unlike other procedure types , the token procedure context type doesn’t expose a single pre-configured webServiceClient property; instead, the context object provides accessor methods that build a client either from an arbitrary URI or from a configured HTTP client:

A client backed by a configured HTTP client carries the TLS, forward-proxy and timeout settings from that configuration. Referencing an unknown HTTP client id throws an error.

Example usage:

// arbitrary URI
var response = context.getWebServiceClientForUri("https://api.example.com")
    .post({
        path: "/audit",
        headers: { "Content-Type": "application/json" },
        body: { event: "token-issued", subject: context.subjectAttributes().sub }
    });

// configured HTTP client targeting a URI
var response2 = context.getWebServiceClient("health-http-client", "https://api.example.com/health")
    .get();

if (response2.statusCode !== 200) {
    logger.warn("Health service returned " + response.statusCode);
}

Utilities#

Several utilities are available to help token procedures, all accessible directly via the context object:

Was this helpful?