Token Procedure API

Since each OAuth flow provides a specific context, this section is split with a section for each flow and a section with common properties on the context object.

Helpers

secondsUntil(momentInEpochSeconds)

A function that calculates the number of seconds until the given epoch time from now.

Arguments:
  • momentInEpochSeconds – A number representing an epoch timestamp in the future
Returns:

The number of seconds until that moment in time

appendObjectTo(inputData, outputData)

A function that appends the non-null input data safely as properties to the outputData object

Arguments:
  • inputData – The data to append from
  • outputData – The data object to append the values to

Issuers

delegationIssuer

A Delegation Issuer

delegationIssuer.issue(content)
Arguments:
  • content – The Map of properties to issue in the delegation
Returns:

A delegation object to use when issuing access tokens and refresh tokens.

tokenIssuer

A Token Issuer that issues a token not tied to a specific delegation

tokenIssuer.issue(content)
Arguments:
  • content – The Map of properties to issue in the token
Returns:

the issued token represented as a string value

delegationBasedTokenIssuer

A Token Issuer that issues tokens that must be based on a Delegation

delegationBasedTokenIssuer.issue(content, delegation)
Arguments:
  • content – The Map of properties to issue in the token
  • delegation – The delegation object received when issuing a delegation
Returns:

the issued token represented as a string value

Authorization

authorizationManager

An object containing authorization functions.

isAuthorized(subjectAttributes, action, resource)
Arguments:
  • subjectAttributes – The current subjectAttributes
  • action – A string representing the action to authorize
  • resource – A string representing resource for which the action applies
Returns:

True if the given attributes with the provided action and resource is accepted and authorized.

isAuthorized(subjectAttributes, action, resource, contextAttributes)
Arguments:
  • subjectAttributes – The current subjectAttributes
  • action – A string representing the action to authorize
  • resource – A string representing resource for which the action applies
  • contextAttributes – The current contextAttributes
Returns:

True if the given attributes with the provided action and resource is accepted and authorized.

Data Objects

delegation

A data structure describing the currently issued delegation that the procedure is working on. This object is only available in flows that operate on existing delegations. Such as the refresh token grant type on the oauth-token endpoint, or the exchange flow on the oauth-token-exchange endpoint.

id
Returns:the ID of this delegation, as a string.
clientId
Returns:the client ID, as a string.
data
Returns:the data stored in the delegation as a map.
Returns:the consent stored in the delegation as a map. If a consentor was used during the authorization flow, then this map has at least the following entries: consentorId with the consentor’s identifier string; consentorResultAttributes with the consentor result attributes map.
presentedToken

A data structure describing a token that was presented to the OAuth server before this procedure ran.

issuedAt
Returns:The epoch time in seconds when the token was issued
expiresAt
Returns:The epoch time in seconds when the token expires
active
Returns:A boolean value stating if the token is active or not
type
Returns:The type of token presented
subject
Returns:The subject the token was issued for, or null if not present
value

The token value is the exact token that was received on the endpoint. This is only present if the procedure is supposed to perform any operations using it. A good example is the refresh token procedure, that may need to re-issue the current token. If the client is configured to re-use tokens, then this property is present and not null. If the client is set to not re-use tokens, then the value property will be null.

Returns:The actual token (its value) that was received, or null if not available in the context
data

The data that is bound to this token. If it is a JWT the data comes from the token itself, and if it is a reference token (opaque) then this is the data found in the data-store holding the token data.

Returns:A map with the token data.
delegation
Returns:The delegation object that was used when issuing the token.
presentedIntrospectedToken

Extends presentedToken with the following properties:

expiredScopes
Returns:A collection of the scopes that has expired in the token. The scopes are given as strings.
presentedNonce

A data structure describing a note-more-than-once-token (typically the Authorization code) that was presented to the OAuth server before this procedure ran.

createdAt
Returns:The epoch time in seconds when the token was created
expiresAt
Returns:The epoch time in seconds when the token expires
data

The data that is bound to this nonce token.

Returns:A map containing the data that was stored with this token.
issuedToken

A data structure describing an issued access token. This is a smaller subset of the presentedToken and is only used in the assisted token flow.

value
Returns:The string value of the issued token. This can be used if the token should be re-used.
issuedAt
Returns:An epoch timestamp in seconds when the token was issued.
expiresAt
Returns:An epoch timestamp in seconds when the token expires.
scope
Returns:A space separated string of scopes issued for this token
subject
Returns:A string with the username that the token was issued for
data
Returns:A map holding the data that was stored with the token when it was issued.
subjectAttributes()
Returns:A map that represent the subject attributes that were established during authentication of the user.
contextAttributes()
Returns:A map that represent the context attributes that were established during authentication of the user.
subjectAttributesWithAuthorities()
Returns:A map that represent the subject attributes that were established during authentication of the user, in an extended format that includes attribute authority information. Each attribute is represented by an entry with key <attribute-full-name>@<attribute-authority>. If the attribute doesn’t have an authority, then the key is just <attribute-full-name>. There is an additional @authorities key, whose value is a map. Each entry in that inner map corresponds to an attribute name, and its value is a list of all authorities for attributes with that name.
contextAttributesWithAuthorities()
Returns:A map that represent the context attributes that were established during authentication of the user, in an extended format that includes attribute authority information.
scope

An object representing a scope. It contains the metadata about the scope as provided in the configuration.

name
Returns:The name of the scope, or prefix in case of prefix scopes.
description
Returns:The description of the scope
properties
Returns:A map with the key value properties that has been configured on the scope.
timeToLive
Returns:An integer describing how long in seconds this scope should be valid for once issued on a token
isPrefix
Returns:A boolean value indicating whether this is a prefix scope.
claimNames
Returns:A set containing the name of all claims associated with this scope.
client

An object representing a client. It contains the metadata about the client as provided in the configuration.

id
Returns:The Client ID (name) as a string
scopeMap
Returns:A ScopeMap object representing the scopes configured for this client.
properties
Returns:A map containing the properties of this client.
secret
Returns:The hashed client secret, if it exists, or null otherwise.
name
Returns:The name of this client.
description
Returns:The description of this client.
redirectUris
Returns:The redirect URIs allowed for this client.
requiresUserConsent()
Returns:whether this client requires consent of the resource owner.
allowConsentDeselection()
Returns:whether the user is allowed to deselect optional individual scopes or claims when asked for consent.
audiences
Returns:A set of strings with the audiences configured for this client
audiencesAsString
Returns:A space separated string of audiences configured for this client
delegationTimeToLive
Returns:The TTL in seconds that a delegation issued for this client is allowed to last.
accessTokenTimeToLive
Returns:The TTL in seconds that an access token issued for this client is allowed to last.
idTokenTimeToLive
Returns:The TTL in seconds that an id token issued for this client is allowed to last.
refreshTokenTimeToLive
Returns:The TTL in seconds that a refresh token issued for this client is allowed to last.
scopeNames
Returns:A set of strings with the names of the scopes configured for this client. Prefix scopes are not included.
scope
Returns:A space separated string of scopes that can be used with this client. This string can be placed directly in an access token. Prefix scopes are not included.

Deprecated since version 4.2: Use scopeNames and prefixScopes instead.

scopes
Returns:A map mapping scope names to scope objects as configured for this client. Prefix scopes are not included.
prefixScopes
Returns:A map mapping scope prefixes to scope objects as configured for this client.
claims
Returns:A map mapping claim names to claim objects as configured for this client.
claim

An object representing a claim. It contains the metadata about the claim as provided in the configuration.

properties
Returns:An map containing the properties of the claim.
name
Returns:The name of the claim.
description
Returns:The description of this client.
required
Returns:Whether this is a required claim.
consentable
Returns:Whether this is a consentable claim.
exposeInMetadata()
Returns:Whether this claim is exposed in the endpoint metadata.
claimsProviderId
Returns:The ID of the claims provider for this claim, or null if none.
scopeNames
Returns:a set of scope names associated with this claim.

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. In the following sections the flow-specific contexts are described.

tokenProcedureContext

The most basic token procedure context provides access to generic scripting methods and properties, as well as to actual token issuers. To facilitate issuance, the context provides a number of methods that return initialized maps with properties for issuing tokens for different purposes (AccessTokens, AuthorizationCode nonces, etc.) The default values of all properties are also exposed through attributes in the different Token Procedure Contexts.

Prepared token data

tokenProcedureContext.getDefaultDelegationData()

Properties that are included in the returned map are scope, owner, created, expires, clientId, redirectUri, status and authenticationAttributes.

returns:the map with initialized properties for issuing a delegation.
tokenProcedureContext.getDefaultAccessTokenData()

Properties that are included in the returned map are iat, exp, nbf, iss, sub, aud, scope and subject with SubjectAttributes and context with ContextAttributes.

returns:the map with initialized properties for issuing an AccessToken.

Token Issuers

tokenProcedureContext.getAccessTokenIssuer(id)

Returns the Access Token issuer

Arguments:
  • id – Optional id, if given, it must match a configured custom issuer. If not given, the default access token issuer is used.
Returns:

the delegationBasedTokenIssuer access token issuer

tokenProcedureContext.getAuthorizationCodeIssuer()

Returns the Authorization Code issuer

Returns:the tokenIssuer nonce token issuer
tokenProcedureContext.getRefreshTokenIssuer(id)

Returns the Refresh Token issuer

Arguments:
  • id – Optional id, if given, it must match a configured custom issuer. If not given, the default refresh token issuer is used.
Returns:

the delegationBasedTokenIssuer nonce token issuer

tokenProcedureContext.getIdTokenIssuer(id)

Returns the ID Token issuer

Arguments:
  • id – Optional id, if given, it must match a configured custom issuer. If not given, the default ID token issuer is used.
Returns:

the tokenIssuer ID token issuer

tokenProcedureContext.getDelegationIssuer()

Returns the delegation issuer

Returns:the delegationBasedTokenIssuer Delegation issuer

Utilities

tokenProcedureContext.request

Returns the httpRequest for the current transaction

Returns:httpRequest for the current transaction
tokenProcedureContext.response

Returns the httpResponse for the current transaction

Returns:httpResponse for the current transaction
tokenProcedureContext.getAttributeDataSource(dataSourceId)

Retrieves a configured AttributeDataAccessProvider with the provided ID if it exists, or null otherwise.

Arguments:
  • dataSourceId (string) – The ID of the data source.
Returns:

A dataSource with the requested ID, or null if it does not exist.

tokenProcedureContext.getAuthorizationManager()

Returns the configured authorization manager.

Returns:A authorizationManager
scopes

Returns a set of scopes that are authorized for this client. These are the scopes that may be issued in the access token issued by the procedure.

Returns:A collection of scope objects that has been authorized to issue
scopeNames
Returns:A collection of the scope names as strings for the scopes that has been authorized to be issued.
client
Returns:A client object that represents that client that made the request

Flow Specific Contexts

Each flow type has specific properties on the context that may be available. This section describes each flow type, what may exist on the context beyond what was described in the general section about Context.

Authorize Endpoint Authorization Code Flow

Procedures configured with the flow oauth-authorize-authorization-code will receive the following context:

authorizeCodeTokenProcedureContext

This context inherits all properties of the tokenProcedureContext and adds the following properties.

getDefaultAuthorizationCodeData()

Prepares an authorization code data object that can be modified or passed directly to the authorization code issuer. Properties that are included in the returned map are scope, owner, audience, clientId, redirectUri, redirectUriProvided, nonce, codeChallengeProvided, codeChallenge, codeChallengeMethod and authenticationAttributes.

Returns:A map with a prepared authorization code ready to be issued
getDefaultIdTokenData()

Only available when OpenID Connect is enabled

Prepares an id token data object that can be modified or passed directly to the id token issuer. Should only be used when the openid scope is presented together with the id_token response type. Properties that are included in the returned map are iat, exp, nbf, iss, sub, aud, auth_time and acr, as well as any user claims mapped from OpenID Connect scopes as described thoroughly in Token procedures - Userinfo. The property nonce is included when it was present in the original request. The properties amr and azp are added when they are available from the authentication’s ContextAttributes.

Returns:A map with a prepared id token ready to be issued
getProvidedState

Refers to the RFC 6749 state parameter on the Authorize Endpoint

Returns:The provided state that the client may have passed to the OAuth server when initializing the flow.
redirectUri

Refers to the RFC 6749 redirect_uri parameter on the Authorize Endpoint

Returns:The redirect URI that the system has determined should be used for the client when returning the data.

Authorize Endpoint Authorization Implicit Flow

Procedures configured with the flow oauth-authorize-implicit will receive the following context:

authorizeImplicitTokenProcedureContext
getDefaultIdTokenData()

Only available when OpenID Connect is enabled

Prepares an id token data object that can be modified or passed directly to the id token issuer. Should only be used when the openid scope is presented together with the id_token response type. Properties that are included in the returned map are iat, exp, nbf, iss, sub, aud, auth_time and acr, as well as any user claims mapped from OpenID Connect scopes as described thoroughly in Token procedures - Userinfo. The property nonce is included when it was present in the original request. The properties amr and azp are added when they are available from the authentication’s ContextAttributes.

Returns:A map with a prepared id token ready to be issued
getProvidedState

Refers to the RFC 6749 state parameter on the Authorize Endpoint

Returns:The provided state that the client may have passed to the OAuth server when initializing the flow.
redirectUri

Refers to the RFC 6749 redirect_uri parameter on the Authorize Endpoint

Returns:The redirect URI that the system has determined should be used for the client when returning the data.

Authorize Endpoint Hybrid Flow

Procedures configured with the flow openid-authorize-hybrid will receive the same context as procedures configured with Authorize Endpoint Authorization Code Flow, with the exception that default data for issuing an Access Token and default data for issuing an ID Token are only provided whenever this is requested through the appropriate response type of the request. For example, a request for code token will make the context’s getDefaultAccessTokenData() return the default data for issuing an Access Token, but when calling the context’s getDefaultIdTokenData() a null-value is returned. Please see Authorization Endpoint Hybrid Flow for an example.

Note that requesting the id_token token response type is handled by the Implicit Flow procedure (and not the Hybrid Flow procedure handler).

The responseType attribute is normalized, such that the values are alphabetically ordered (e.g. a response_type value of token code is normalized to code token).

Token Endpoint Authorization Code Flow

Procedures configured with the flow oauth-token-authorization-code will receive the following context:

tokenCodeFlowProcedureContext
getDefaultRefreshTokenData()

Properties that are included in the returned map are iat, exp, nbf, iss, sub, aud and scope. Note that a RefreshToken can not always be issued (e.g. in case of the authorize-procedure, no default RefreshTokenData is available).

Returns:the map with initialized properties for issuing a RefreshToken.
presentedNonce
Returns:A presentedNonce object with the data stored in the authorization code from the authorize endpoint.
getDefaultIdTokenData()

Only available when OpenID Connect is enabled

Prepares an id token data object that can be modified or passed directly to the id token issuer. Should only be used when the openid scope is presented together with the id_token response type. Properties that are included in the returned map are iat, exp, nbf, iss, sub, aud, auth_time and acr, as well as any user claims mapped from OpenID Connect scopes as described thoroughly in Token procedures - Userinfo. The property nonce is included when it was present in the original request. The properties amr and azp are added when they are available from the authentication’s ContextAttributes.

Returns:A map with a prepared id token ready to be issued

Token Endpoint Refresh Token Flow

Procedures configured with the flow oauth-token-refresh will receive the following context:

tokenRefreshFlowProcedureContext
getDefaultRefreshTokenData()

Properties that are included in the returned map are iat, exp, nbf, iss, sub, aud and scope. Note that a RefreshToken can not always be issued (e.g. in case of the authorize-procedure, no default RefreshTokenData is available).

Returns:the map with initialized properties for issuing a RefreshToken.
delegation
Returns:A delegation object representing the original delegation issued when the grant was given
presentedToken
Returns:The presented refresh token as a presentedToken that the client sent to the endpoint.

Token Endpoint Client Credentials Flow

Procedures configured with the flow oauth-token-client-credentials receive the standard tokenProcedureContext.

Token Endpoint Resource Owner Password Credentials Flow

Procedures configured with the flow oauth-token-resource-owner-password-credentials will receive the following context:

tokenPasswordFlowProcedureContext
getDefaultRefreshTokenData()

Properties that are included in the returned map are iat, exp, nbf, iss, sub, aud and scope. Note that a RefreshToken can not always be issued (e.g. in case of the authorize-procedure, no default RefreshTokenData is available).

Returns:the map with initialized properties for issuing a RefreshToken.

Token Endpoint Token Exchange Flow

Procedures configured with the flow oauth-token-token-exchange will receive the following context:

tokenExchangeFlowProcedureContext
delegation
Returns:A delegation object representing the original delegation issued when the grant was given
presentedToken
Returns:The presented refresh token as a presentedToken that the client sent to the endpoint.

Assisted Token Endpoint Flow

Procedures configured with the flow assisted-token-endpoint-identity will receive the following context:

assistedTokenFlowProcedureContext
issuedToken

This returns the currently issued access token if one is present. The assisted token endpoint keeps the access token in a cookie if configured to do so. This means that the procedure must re-use the token, if one is found rather than issuing a new one.

Returns:A issuedToken if present, or null otherwise

Note

It is not possible to use Custom issuers on the Assisted Token endpoint. Only default issuers are available.

Introspection Endpoint Flow

Procedures configured with the flow oauth-introspect or oauth-introspect-application-jwt will receive the following context:

introspectionFlowProcedureContext
delegation
Returns:A delegation object representing the original delegation issued when the grant was given
presentedToken
Returns:The presented refresh token as a presentedIntrospectedToken that the client sent to the endpoint.

Whether oauth-introspect or oauth-introspect-application-jwt is run is decided solely by the incoming Accept header, where either application/json or application/jwt mandates the output format (JSON output as described in the OAuth introspection spec or a “raw” JWT).

UserInfo Endpoint Flow

Procedures configured with the flow openid-userinfo will receive the following context:

userinfoFlowProcedureContext
accountAttributes
Returns:An accountAttributes object representing the account of the user that owns the token
presentedToken
Returns:The presented refresh token as a presentedToken that the client sent to the endpoint.
getDefaultResponseData()
Returns:A map with a prepared response for the userinfo request.