Token Issuance Authorizers

Token Issuance Process#

When a request is made to issue a token, the scopes to be granted are determined based on what is requested, what is allowed by configuration, and with Token Issuance Authorizers, it is also based on what is authorized by the applicable TIA plugins. The following diagram illustrates the role of TIA plugins in the token issuance process.

The grant types that support Token Issuance Authorization are

• Authorization Code Flow
• Client Credentials Flow
• Refresh Token Flow
• Resource Owner Password Credentials Flow
• Device Flow
• CIBA
• Token Exchange Flow
• OAuth Token Exchange Flow
• Implicit flow
• JWT Assertion Flow
• Assisted Token Flow
• Pre-Authorization Flow

TIA Plugin Operation#

When a token is being issued, the scopes to be issued together with the context in which the request is made, are provided to the applicable TIA plugins for authorization. This results in an authorization decision for each scope. An authorization decision can be

• Allow (the scope can be issued)
• Deny (the scope cannot be issued)
• Conditional

If a plugin authorizes the issuance of a scope with conditions, then those conditions must be met for the scope to be issued.

The conditions that the TIA plugin can return, are

• Require User Consent
• Set Scope Time To Live

Condition: Require User Consent#

The Require User Consent condition allows a TIA plugin to indicate that it is ok to issue the scope, but the user must first give their consent to the release of the scope. This is useful for cases where a scope is considered to be more sensitive and requires an explicit user action to allow it to be released in a token.

Example: Require user consent with code-flow and refresh-flow#

For example, when a client requests an access token by starting the code flow. The user authenticates and the TIA plugins determine that the requested scope messages:read can be issued when user consent is given. The user is prompted for consent and issuance of the scope depends on the user decision.

Continuing the example, the access token expires and the client is using a refresh token to get a new access token. The TIA plugins determine (again) that for the requested scope messages:read, user consent is required. However, since the delegation already exists (implying that conditions for initial token issuance have been met), user consent was implicitly given at the time of the initial token issuance, and the new access token’s scope will include the messages:read scope without actual user-interactive consent.

Example: Require user consent with JWT Assertion flow#

Another example is when a client requests an access token by starting the JWT Assertion flow. A resulting token will be based on a new delegation. When the TIA plugins indicate that user consent is required for the requested scope messages:read, the scope will not be issued since the user can not be asked for consent to include the scope.

Condition: Set Scope Time To Live#

The Set Scope Time To Live condition allows a TIA plugin to indicate that it is ok to issue the scope, but it must be issued with the specified time to live value. The result is similar to how a lifetime on a scope can be configured , however in the case of it being the result of TIA plugin authorization, the lifetime is determined at the time of token issuance and can be dynamic based on the context of the request.

For example, a TIA plugin could set a shorter lifetime for a scope if the user authentication freshness has passed a certain age.

Global Token Issuance Authorizer#

In addition to scope-bound TIAs, an OAuth profile can configure an optional Global Token Issuance Authorizer. The Global TIA runs once, before any scope-bound TIAs are evaluated, and receives the full set of requested-and-allowed scopes — including the empty default scope when no scopes were explicitly requested. This gives the Global TIA a say in every scope that may be issued, plus the ability to authorize (or refuse) the default-scope path.

Decisions made by the Global TIA fold into the same Allow / Deny / Set Scope Time To Live / Require User Consent semantics as scope-bound TIAs. A scope denied by the Global TIA is removed from the issuance set before scope-bound TIAs are consulted, so scope-bound TIAs are never invoked for scopes the Global TIA has already denied. The collapse rules (Deny wins, smallest TTL wins, Require User Consent accumulates) apply across the Global and scope-bound passes.

Configuration#

The Global TIA is an optional leaf inside the token-issuance-authorizers configuration that references one of the TIAs defined in the same container by id:

<token-issuance-authorizers xmlns="https://curity.se/ns/conf/profile/oauth/authorization-server">
    <global-token-issuance-authorizer>my-global-tia</global-token-issuance-authorizer>
    <token-issuance-authorizer>
        <id>my-global-tia</id>
        <!-- one of the provided TIA plugins, e.g. script, composite, authzen, ... -->
    </token-issuance-authorizer>
</token-issuance-authorizers>

The referenced id must match an existing token-issuance-authorizer entry; this is enforced as a referential integrity constraint at configuration time. The same TIA plugin instance can be used as both the Global TIA and a scope-bound TIA on individual scopes if desired.

The Global TIA can be set in the Admin UI by navigating to the Token Issuance Authorizers section of the Token Profile and selecting the Global Authorizer button on the top right. This opens a dialog where you can select one of the configured TIA plugins to be used as the Global TIA.

Default Scope Authorization#

When a client requests a token without supplying a scope parameter, an internal “default scope” (an empty-named scope) is used. Scope-bound TIAs cannot bind to the default scope, so before the Global TIA was introduced there was no way to authorize or deny the default-scope path through the TIA mechanism. The Global TIA closes that gap: it receives the empty default scope in its input set and can Allow or Deny it like any other scope.

Behavior when Everything is Denied#

When all TIAs (Global and scope-bound combined) deny every requested scope and no individually-requested claim survives, the token endpoint refuses the request with an OAuth access_denied error rather than issuing a token with empty scope and empty claims. This applies regardless of whether the denial came from the Global TIA, a scope-bound TIA, or both.

If individually-requested claims (via the OAuth claims request parameter) survive the scope denial — i.e. they are still allowed to be issued because they were not exclusively tied to a denied scope — the token is issued with those claims, even when no scopes survive.

Configuring Token Issuance Authorizers#

Token Issuance Authorizer plugins are configured in the Token Issuance Authorizers section of the Token Profile. Each plugin has its own configuration options. A configured TIA plugin can be assigned to a scope to create configurable authorization logic to control the release of scopes when issuing tokens.

To create a new TIA plugin, navigate to the Token Authorization section of the Scopes menu and click the +New button.

Assigning Token Issuance Authorizers To Scopes#

To assign a TIA plugin to a scope, navigate to the Scopes section of the Token Profile and click on the scope you want to edit to see Scope details in the right column. A Token Issuance Authorizers section appears where you can select one of the configured TIA plugins that will be applied when that scope is considered to be issued.

Provided TIA Plugins#

The following TIA plugins are provided out of the box: