Configure Token Issuance Authorizers

This tutorial shows how to configure a Token Issuance Authorizer (TIA) in the Curity Identity Server. The authorizer ensures that the Curity Identity Server only issues a scope if the incoming request meets certain requirements. These requirements may be complex but for the purpose of this tutorial, the rule is simple: Authorize the scope only if the user authenticated within the last five minutes.

What is a Token Issuance Authorizer?

Token Issuance Authorizers basically are rules assigned to a scope. The Curity Identity Server invokes them when it evaluates the requested scopes of an authorization or token request. This means, it evaluates the rules before it issues the scope to the access token.

Why do you need a Token Issuance Authorizer?

When you need fine-grained authorization, static client configuration is often not enough. Sometimes, you need control over not only which scopes a client may request but also when and under which conditions the authorization server should issue a scope to a client's access token. Just because a client is allowed to request a scope doesn't mean it should receive that scope in an access token. Token Issuance Authorizers let you evaluate runtime conditions before issuing a token with a certain scope, so you can enforce stronger, more dynamic and fine-grained policy decisions through the Curity Identity Server.

In this tutorial you learn how to use a script to define the rules for a Token Issuance Authorizer and how to assign the Token Issuance Authorizer to a scope.

Prerequisites

Before starting, ensure you have the following prerequisites in place.

• A running Curity Identity Server environment
• Admin UI access with permission to update a Token Service profile
• An OAuth client you can use for testing
• Expert view enabled in Admin UI

If you miss some of the prerequisites, check out the Getting Started guides to get up and running with the Curity Identity Server. These guides give you a working setup for this tutorial. Make sure to enable the Expert View before continuing.

If you need a client to easily test OAuth flows, you can use OAuth Tools for that.

Step 1: Define the Scope Policy

Write down the policy rules for the scopes before changing configuration. This gives you a good overview of what you need to configure to avoid mistakes. The rules for this tutorial are as follows:

• Allow the test client to read data (read scope).
• Allow the test client to write data (write scope) only if the user authenticated in the last 5 minutes.

You can represent these rules in a table to make review easier.

Step 2: Create Scopes

For the purpose of this tutorial, create two scopes, read and write.

1. Navigate to Profiles → Token Service → Scopes.
2. Click on the + New button next to "Scopes".
3. Enter read as the name of the new scope in the dialog.
4. Click Create.
5. Repeat the steps for the write scope.
6. In the Changes menu, click Commit to commit the changes.

Step 3: Assign Scopes to Client

The test client is expected to request read scope and write scope. Therefore, configure the client with both scopes. Follow these steps in the Admin UI.

1. Navigate to Profiles → Token Service → Clients.
2. Open your test client.
3. On the General tab, scroll down to the Scopes and Claims section and click Add Scopes.
4. Add the read scope to the test client.
5. Add the write scope to the test client.
6. Commit the changes.

Step 4: Create a Token Issuance Authorizer

The Token Issuance Authorizer enables you to evaluate policies based on a requested scope and dynamically restrict what access clients can receive at runtime. In this tutorial, the policy only allows the write scope, if the user authenticated in the last 5 minutes.

Follow these steps to configure the Token Issuance Authorizer in the Admin UI.

1. Navigate to Profiles → Token Service → Scopes → Token Authorization.
2. Create a new Token Issuance Authorizers by clicking on +New.
3. Enter a name, e.g. allow-write-for-fresh-auth-only.
4. Select Script as the type for the Token Issuance Authorizer.
5. Click Create.

6. Add the following script for the policy.

/**
 * @param {se.curity.identityserver.procedures.tokenissuanceauthorizer.TokenIssuanceAuthorizerProcedureContext} context
 */
function result(context) {
  var authTime = context.authenticationAttributes.authTime;

  var allowScope = authTime >= Math.floor(Date.now() / 1000) - 300; // 5 minutes

  if (allowScope) {
    return context.newResultBuilder()
      .allow("write")
      .build();
  } else {
    return context.newResultBuilder()
      .build();
  }
}

7. Close the modal window.
8. Commit the changes.

Step 5: Assign the Token Issuance Authorizer to the Scope

The Token Issuance Authorizer should get triggered when the client requests the write scope. Follow these steps in the Admin UI to assign the Token Issuance Authorizer to the scope.

1. Navigate to Profiles → Token Service → Scopes.
2. In the list of scopes, search for and mark write to select the scope.
3. In the right panel, at the top select allow-write-for-fresh-auth-only from the dropdown menu to apply the Token Issuance Authorizer to the scope.
4. Commit the changes.

Step 6: Verify With Positive and Negative Tests

Use your test client to run a flow and request the read and write scope. For example, the following is an authorization request for the OAuth Tools app that will start a new OAuth flow.

http://localhost:8443/oauth/v2/oauth-authorize?client_id=oauth-tools&response_type=code&redirect_uri=oauth.tools%3a%2f%2fapp%2fcallback%2fcode&state=1770905431829-vEZ&scope=read+write&code_challenge=vMWrcur5O5tYARZGK6XtqcG23qIdHH6YbYi-OMAMkXg&code_challenge_method=S256

If required, create an account and log in. When redeeming the authorization code for an access token, study the response from the Curity Identity Server. You should see that it issued both the read and write scopes, as you have just logged in to the server.

{
  "token_type": "bearer",
  "access_token": "_0XBPWQQ_cfb9c428-cc7c-4cc6-a6f9-5398875caa7e",
  "refresh_token": "_1XBPWQQ_0cc90e54-6357-4e31-b721-7f9baf266248",
  "scope": "read write",
  "expires_in": 299
}

Run the same flow after some time. You won't have to log in, as the SSO session kicks in. The access token should only have the read scope.

{
  "token_type": "bearer",
  "access_token": "_0XBPWQQ_02ce23ce-71d0-4277-b319-6c516feeb5bd",
  "refresh_token": "_1XBPWQQ_32d54f65-4edd-4ad8-9b4b-c5776f42324a",
  "scope": "read",
  "expires_in": 300
}

Passing Attributes To Token Procedures

You might find it useful to pass attributes computed by a TIA script to a token procedure. It allows you to make additional decisions during token issuance using data obtained during issuance authorization. You can pass such attributes from the TIA script using the response builder's method:

return context.newResultBuilder()
      .allow("write")
      .addParameter('writeScopeAllowed', true)
      .build();

Token procedures can then access such parameters from their context with context.tokenIssuanceAuthorizerAttributes().

Types of Token Issuance Authorizer

This tutorial used a script to run custom rules on a scope. The script TIA can use an HTTP client that collects runtime client and user attributes, then sends them to an external HTTP service. If you need to implement complex logic, you can use the Java SDK to implement TIA plugins.

You can also configure two global Token Issuance Authorizers:

• One that runs for all scopes before the Curity Identity Server triggers the rules for individual scopes.
• One that runs after all claim values have been determined.

If you use a script TIA for the latter option, the procedure will have access to all the claims prepared for the token. See the TIA script plugin documentation for details.

The script TIA is just one of multiple built-in types of Token Issuance Authorizer you can use. Examples for other types are as follows.

• Authentication Freshness TIA
• Authentication ACR TIA
• AuthnZen TIA
• Composite TIA

Conclusion

The Curity Identity Server has two main rules that govern what scopes a client may receive in an access token:

• The client configuration that defines which scopes a client is allowed to request.
• Token Issuance Authorizers that define when to issue such a scope to an access token.

Token Issuance Authorizers enable the Curity Identity Server to restrict under which conditions it issues a scope to an access token. The tutorial showed an example with a simple script that allows a scope only under certain circumstances. For a complete description of what Token Issuance Authorizers (TIAs) can do, refer to the product documentation.