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.

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:

• ScriptDelegationIssuer
• ScriptAccessTokenIssuer
• ScriptRefreshTokenIssuer
• ScriptAuthorizationCodeNonceIssuer
• ScriptIdTokenIssuer
• ScriptDeviceCodeNonceIssuer

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:

• OAuthTokenProcedureContext#scopes and OAuthTokenProcedureContext#scopeNames
• OAuthTokenProcedureContext#claims and OAuthTokenProcedureContext#getClaimNames
• OAuthTokenProcedureContext#contextAttributes

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

• IntrospectionTokenProcedureContext#presentedToken

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:

• TokenProcedureContext#getWebServiceClientForUri - a client targeting an arbitrary URI, given as a string, using the default SSL context.
• TokenProcedureContext#getWebServiceClient - the same, given a java.net.URI; or a client backed by a configured HTTP client, given its id and a target URI whose host, port, path and query are applied to the configured 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:

• ScriptAccountManager - performs user account management.
• TokenProcedureAuthorizationManager - for advanced authorization use cases.
• OAuthClientConfiguration - configuration of the OAuth client making the request.
• ScriptResponse - the HTTP response the server will return. Normally used to set cookies.