Guide to using the ForgeRock® Token Validation Microservice for new users and readers evaluating the product.

Preface

ForgeRock Identity Platform™ serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

Chapter 1. About the Token Validation Microservice

The Token Validation Microservice is delivered as part of the ForgeRock Identity Microservices to introspect and validate OAuth 2.0 access_tokens that adhere to either of the following IETF specifications:

The Token Validation Microservice uses the introspection endpoint defined in RFC-7662, OAuth 2.0 Token Introspection.

Use the Token Validation Microservice in service-to-service deployments to validate OAuth 2.0 access_tokens. The following figure illustrates a group of Secured Microservices in a container, representing a business service such as ordering, billing, or registration.

Example Deployment of the Token Resolution Microservice
Example architecture of the Token Validation Microservice

The request is processed in the following sequence:

  1. A client requests access to Secured Microservice A, providing a stateful OAuth 2.0 access_token as credentials.

  2. Secured Microservice A passes the access_token for validation to the Token Validation Microservice, using the /introspect endpoint.

  3. The Token Validation Microservice requests the Authorization Server to validate the token.

  4. The Authorization Server introspects the token, and sends the introspection result to the Token Validation Microservice.

  5. The Token Validation Microservice caches the introspection result, and sends it to Secured Microservice A.

  6. Secured Microservice A uses the introspection result to decide how to process the request. In this case it continues processing the request. Secured Microservice A asks for additional information from Secured Microservice B, providing the validated token as credentials.

  7. Secured Microservice B passes the access_token to the Token Validation Microservice for validation, using the /introspect endpoint.

  8. The Token Validation Microservice retrieves the introspection result from the cache, and sends it to Secured Microservice B.

  9. Secured Microservice B uses the introspection result to decide how to process the request. In this case it passes its response to Secured Microservice A.

  10. Secured Microservice A passes its response to the client.

The Token Validation Microservice can validate stateful and stateless OAuth 2.0 access_tokens. For information about setting up the Token Validation Microservice for each type of access_token, see "Introspecting Stateful Access_Tokens With the Token Validation Microservice" and "Introspecting Stateless Access_Tokens With the Token Validation Microservice".

Chapter 2. Downloading and Installing the Token Validation Microservice

The following sections describe how to download and install the Token Validation Microservice:

For information about starting and using the Token Validation Microservice, see "Introspecting Stateful Access_Tokens With the Token Validation Microservice" and "Introspecting Stateless Access_Tokens With the Token Validation Microservice".

2.1. Requirements

For detailed information about the requirements for running the Token Validation Microservice, see "Before You Install" in the Release Notes. The following software is required:

  • An OAuth 2.0 authentication server, such as ForgeRock Access Management.

    For information about downloading and using AM, see AM's Release Notes.

  • Oracle JDK 11 or later versions, or OpenJDK 11 or later versions.

2.2. Configuring the Network

Configure the network to route network traffic through the Token Validation Microservice. The examples used in the guide assume that:

  • The Token Validation Microservice is reachable on http://mstokval.example.com:9090

  • AM is reachable on http://openam.example.com:8088/openam

Before you try out the examples, configure the network to include the hosts.

To Configure the Network
  • Add the following additional entry to your /etc/hosts file on UNIX systems or %SystemRoot%\system32\drivers\etc\hosts on Windows:

    127.0.0.1  localhost mstokval.example.com openam.example.com

    For more information about host files, see the Wikipedia entry, Hosts (file).

2.3. Downloading the Token Validation Microservice

To Download the Token Validation Microservice Software
  1. Create a local installation directory for the Token Validation Microservice. The examples in this section use /path/to/microservices.

  2. Download MicroserviceTokenValidation-1.0.1.zip from the ForgeRock BackStage download site into your local installation directory.

  3. Unzip the file:

    $ unzip MicroserviceTokenValidation-1.0.1.zip

    The directory /path/to/microservices/token-validation is created for the configuration files and startup scripts. When you start the Token Validation Microservice, a log file is created in /path/to/microservices/token-validation/logs.

Chapter 3. Starting and Stopping the Token Validation Microservice

The following sections describe options for starting and stopping the Token Validation Microservice:

3.1. Starting the Token Validation Microservice With Default Settings

This section describes how to start the Token Validation Microservice, specifying the configuration directory where the Token Validation Microservice looks for configuration files. An error is produced if a config.json is not available in the configuration directory.

The Token Validation Microservice starts up on the ports listed in admin.json, or by default on port 9090.

To Start the Token Validation Microservice With Default Settings
  1. Start the Token Validation Microservice, specifying the configuration directory as an argument. In the following example, the Token Validation Microservice looks for configuration files in the installation directory.

    $ /path/to/microservices/token-validation/bin/start.sh /path/to/microservices/token-validation
    ...
    ...Server listening on port 9090
    ...Token Validation Microservice started in 1106ms
  2. Make sure that the Token Validation Microservice is running:

    $ curl http://mstokval.example.com:9090/info
    {"name":"Microservice Token Validation","version":"...","revision":"...","branch":"...","timestamp":...}

3.2. Selecting Ports for the Token Validation Microservice

By default the Token Validation Microservice runs on a single port, 9090. To run the Token Validation Microservice on a different port, edit the configuration file /path/to/microservices/token-validation/config/admin.json. The following example runs the Token Validation Microservice on port 9091:

{
  "connectors": [
    {
      "port": 9091
    }
  ]
}

To run the Token Validation Microservice on multiple ports, add the ports to the array. In the following example, the Token Validation Microservice listens on ports 9091 and 9092

{
  "connectors": [
    {
      "port": 9091
    },
    {
      "port": 9092
    }
  ]
}

For information about the configuration of connectors, see "admin.json".

3.3. Starting the Token Validation Microservice With Custom Settings

When the Token Validation Microservice starts up, it searches for the file /path/to/microservices/token-validation/bin/env.sh to configure environment variables, JVM options, and other settings.

Configure /path/to/microservices/token-validation/bin/env.sh to customize the settings.

The following example specifies an environment variable for a secret, and an environment variable for JVM options:

# Specify a secret through an environment variable
export MY_SECRET_ID=foobar

# Specify JVM options through the JAVA_OPTS environment variable
export JAVA_OPTS="${JAVA_OPTS} -Xms256m -Xmx2048m"
To Start the Token Validation Microservice With Custom Settings
  1. Add a file /path/to/microservices/token-validation/bin/env.sh to define environment variables.

  2. Start the Token Validation Microservice, specifying the configuration directory as an argument. In the following example, the Token Validation Microservice looks for configuration files in the installation directory.

    $ /path/to/microservices/token-validation/bin/start.sh /path/to/microservices/token-validation
    ...
    ...Server listening on port 9090
    ...Token Validation Microservice started in 1106ms

3.4. Stopping the Token Validation Microservice

To Stop the Token Validation Microservice
  • In the terminal where the Token Validation Microservice is running, select CTRL-C to stop the service.

Chapter 4. Introspecting Stateful Access_Tokens With the Token Validation Microservice

This section describes how to set up the Token Validation Microservice to introspect stateful access_tokens, using AM as the authorization server. For information about the architecture, see "Example Deployment of the Token Resolution Microservice".

The following figure illustrates the flow of information when a client requests access to a protected microservice, providing a stateful access_token as credentials:

Validating Stateful OAuth 2.0 Tokens
Request flow when the Token Validation Microservice introspects a stateful access_token

The following sections describe how to set up the Token Validation Microservice to introspect stateful access_tokens:

4.1. Setting Up AM as An Authorization Server for Stateful Access_Tokens

Before you start, install and configure AM on http://openam.example.com:8088/openam, with the default configuration. If you use a different configuration, substitute in the tutorial accordingly.

For information about downloading and using AM, see AM's Release Notes. For more information about configuring AM as an OAuth 2.0 authorization service, see Configuring the OAuth 2.0 Provider Service in the AM OAuth 2.0 Guide.

To Set Up AM as An Authorization Server for Stateful Access_Tokens
  1. Configure an OAuth 2.0 Authorization Server:

    1. In the top level realm, select Configure OAuth Provider > Configure OAuth 2.0.

    2. Accept all of the default values and select Create.

  2. Create an OAuth 2.0 client to request OAuth 2.0 access_tokens, using client credentials for authentication:

    1. Select Applications > OAuth 2.0.

    2. Add a client with the following values:

      • Client ID: microservice-client

      • Client secret: password

      • Scope(s): client-scope

    3. (From AM 6.5) On the Advanced tab, select the following option:

      • Grant Types: Client Credentials

  3. Create an OAuth 2.0 Client authorized to examine (introspect) tokens:

    1. In the top level realm, select Applications > OAuth 2.0.

    2. Add a client with the following values:

      • Client ID: token-validation

      • Client secret password

      • Scope(s): am-introspect-all-tokens

4.2. Setting Up the Token Validation Microservice for Stateful Access_Token Introspection

This section describes steps to set up the Token Validation Microservice to introspect stateful access_tokens, at the introspection endpoint.

Before you start, download and install the Token Validation Microservice as described in "Downloading and Installing the Token Validation Microservice".

To Set Up the Token Validation Microservice for Stateful Access_Token Introspection
  1. Prepare the Token Validation Microservice configuration and property files in /path/to/microservices/token-validation/config:

    1. Rename config-template-stateful-cache.json to config.json:

      {
        "properties": {
          "openAmOAuth2Endpoint": "http://openam.example.com:8088/openam/oauth2",
          "oauth2ClientId": "token-validation"
        },
        "introspectionConfig": {
          "accessTokenResolver": {
            "type": "CacheAccessTokenResolver",
            "config": {
              "maximumTimeToCache": "2 minutes",
              "delegate": {
                "type": "TokenIntrospectionAccessTokenResolver",
                "config": {
                  "endpoint": "&{openAmOAuth2Endpoint}/introspect",
                  "providerHandler": {
                    "type": "Chain",
                    "config": {
                      "filters": [
                        {
                          "type": "HttpBasicAuthenticationClientFilter",
                          "config": {
                            "urlEncodeCredentials": true,
                            "username": "${oauth2ClientId}",
                            "passwordSecretId": "oauth2.client.secret",
                            "secretsProvider": {
                              "type": "FileSystemSecretStore",
                              "config": {
                                "directory": "${environment.configDirectory}/secrets",
                                "format": "BASE64"
                              }
                            }
                          }
                        }
                      ],
                      "handler": "ForgeRockClientHandler"
                    }
                  }
                }
              }
            }
          }
        }
      }

      Notice the following features of the file:

      • The properties section declares values used in the AM configuration. If necessary, change these values to match your AM configuration.

      • The introspectionConfig object calls a CacheAccessTokenResolver to look in the cache for the presented access_token:

        • If the access_token is cached, the filter sends the introspection result back to the client microservice.

        • If the token is not cached, the filter delegates access_token introspection to the TokenIntrospectionAccessTokenResolver and then caches the result.

      • The TokenIntrospectionAccessTokenResolver uses the HttpBasicAuthenticationClientFilter to authenticate itself to AM as the OAuth 2.0 client token-validation.

        The password is provided by a FileSystemSecretStore. For more information, see FileSystemSecretStore, in the IG Configuration Reference

    2. In admin.json, make sure that the ports for the Token Validation Microservice are correct:

      {
        "connectors": [
          {
            "port": 9090
          }
        ]
      }
      
  2. Verify that the file /path/to/microservices/token-validation/config/secrets/oauth2.client.secret has the following content:

    cGFzc3dvcmQ=

    This file is called by the FileSystemSecretStore, and contains the base64-encoded password for the OAuth 2.0 client token-validation.

  3. Start the Token Validation Microservice, specifying the configuration directory as an argument. In the following example, the Token Validation Microservice looks for configuration files in the installation directory.

    $ /path/to/microservices/token-validation/bin/start.sh /path/to/microservices/token-validation
    ...
    ...Server listening on port 9090
    ...Token Validation Microservice started in 1106ms
  4. Make sure that the Token Validation Microservice is running:

    $ curl http://mstokval.example.com:9090/info
    {"name":"Microservice Token Validation","version":"...","revision":"...","branch":"...","timestamp":...}

4.3. Testing Stateful Access_Token Introspection

To Test Stateful Access_Token Introspection
  1. Get an access_token from AM:

    $ mytoken=$(curl \
      --request POST \
      --url http://openam.example.com:8088/openam/oauth2/access_token \
      --user microservice-client:password \
      --data grant_type=client_credentials \
      --data scope=client-scope --silent | jq -r .access_token)
  2. View the access_token:

    $ echo $mytoken
    Abc...xyz
  3. Call the Token Validation Microservice to introspect the access_token:

    $ curl --data "token=${mytoken}" http://mstokval.example.com:9090/introspect
    {
      "active": true,
      "scope": "client-scope",
      "client_id": "microservice-client",
      "user_id": "microservice-client",
      "token_type": "Bearer",
      "exp": 155...587,
      "sub": "microservice-client",
      "iss": "http://openam.example.com:8088/openam/oauth2"
    }

4.4. Capturing Calls to AM to Introspect Access_Tokens

When an access_token is cached, IG can reuse the token information without repeatedly asking the authorization server to verify the access_token. The following procedure gives an example of how to capture the call to AM to introspect the access_token.

To Capture Calls to AM to Introspect Access_Tokens
  1. Set up AM and the Token Validation Microservice as described in this chapter, and then change the ForgeRockClientHandler in config.json from:

    "handler": "ForgeRockClientHandler"

    to

    "handler": {
      "type": "Delegate",
      "config": {
        "delegate": "ForgeRockClientHandler"
      },
      "capture": "all"
    }

    The capture logs the call to AM to introspect the access_token.

  2. Restart the Token Validation Microservice, and then introspect an access_token as described in "Testing Stateful Access_Token Introspection".

  3. In /path/to/microservices/token-validation/logs/token-validation.log, note the call to AM to validate the access_token:

    POST http://openam.example.com:8088/openam/oauth2/introspect HTTP/1.1
  4. Within the duration set by maximumTimeToCache, call the Token Validation Microservice to introspect the access_token again.

    Note that this time, because the access_token is cached, the log does not include a call to AM.

Chapter 5. Introspecting Stateless Access_Tokens With the Token Validation Microservice

This section describes how to set up the Token Validation Microservice to introspect stateless access_tokens locally, without referring to an authorization server. For information about the architecture, see "Example Deployment of the Token Resolution Microservice".

The following figure illustrates the flow of information when a client requests access to a protected microservice, providing a stateless access_token as credentials:

Request Flow When Introspecting Stateless Access_Tokens
Request flow when the Token Validation Microservice introspects a stateless access_token

The following sections describe how to set up the Token Validation Microservice to introspect stateless access_tokens:

5.1. Setting Up AM as An Authorization Server for Stateless Access_Tokens

Before you start, install and configure AM on http://openam.example.com:8088/openam, with the default configuration. If you use a different configuration, substitute in the tutorial accordingly.

For information about downloading and using AM, see AM's Release Notes. For more information about configuring AM as an OAuth 2.0 authorization service, see Configuring the OAuth 2.0 Provider Service in the AM OAuth 2.0 Guide.

To Set Up AM as An Authorization Server for Stateless Access_Tokens
  1. Configure an OAuth 2.0 Authorization Provider to provide signed stateless access_tokens:

    1. Select Configure OAuth Provider > Configure OAuth 2.0, accept the default values, and select Create.

    2. Select Services > OAuth2 Provider.

    3. On the Core tab, select the following option:

      • (From AM 6.5) Use Client-Based Access & Refresh Tokens: on

      • (From AM 6) Use Stateless Access & Refresh Tokens: on

      Save the configuration.

    4. On the Advanced tab, select the following option:

      • OAuth2 Token Signing Algorithm: RS256

  2. Create an OAuth 2.0 client to request OAuth 2.0 access_tokens, using client credentials for authentication:

    1. Select Applications > OAuth 2.0.

    2. Add a client with the following values:

      • Client ID: microservice-client

      • Client secret: password

      • Scope(s): client-scope

    3. (From AM 6.5) On the Advanced tab, select the following option:

      • Grant Types: Client Credentials

5.2. Setting Up the Token Validation Microservice for Stateless Access_Token Introspection

This section describes steps to set up Token Validation Microservice to introspect stateless access_tokens, at the introspection endpoint.

Before you start, download and install the Token Validation Microservice as described in "Downloading and Installing the Token Validation Microservice".

To Set Up the Token Validation Microservice for Stateless Access_Token Introspection
  1. Prepare the Token Validation Microservice configuration and property files in /path/to/microservices/token-validation/config:

    1. Rename config-template-stateless.json to config.json:

      {
        "properties": {
          "openAmOAuth2Endpoint": "http://openam.example.com:8088/openam/oauth2"
        },
        "introspectionConfig": {
          "accessTokenResolver": {
            "type": "StatelessAccessTokenResolver",
            "config": {
              "issuer": "&{openAmOAuth2Endpoint}",
              "secretsProvider": {
                "type": "JwkSetSecretStore",
                "config": {
                  "jwkUrl": "&{openAmOAuth2Endpoint}/connect/jwk_uri"
                }
              },
              "verificationSecretId": "stateless.access.token.verification.key"
            }
          }
        }
      }

      Notice the following features of the file:

      • The properties section declares values used in the AM configuration.

      • The introspectionConfig object delegates access_token introspection to the StatelessAccessTokenResolver.

      • The StatelessAccessTokenResolver uses a JwkSetSecretStore, which specifies the URL to a JWK set on AM that contains signing keys identified by a kid.

        For information and an example of how JwkSetSecretStore manages secrets for a StatelessAccessTokenResolver, see "Example".

        The value of verificationSecretId must be specified, but it is not used unless the signed access_token doesn't contain a kid, or the JWK set doesn't contain a matching key.

    2. In admin.json, make sure that the ports for the Token Validation Microservice are correct:

      {
        "connectors": [
          {
            "port": 9090
          }
        ]
      }
      
  2. Start the Token Validation Microservice, specifying the configuration directory as an argument. In the following example, the Token Validation Microservice looks for configuration files in the installation directory.

    $ /path/to/microservices/token-validation/bin/start.sh /path/to/microservices/token-validation
    ...
    ...Server listening on port 9090
    ...Token Validation Microservice started in 1106ms
  3. Make sure that the Token Validation Microservice is running:

    $ curl http://mstokval.example.com:9090/info
    {"name":"Microservice Token Validation","version":"...","revision":"...","branch":"...","timestamp":...}

5.3. Testing Stateless Access_Token Introspection

To Test Stateless Access_Token Introspection
  1. Get an access_token from AM:

    $ mytoken=$(curl \
      --request POST \
      --url http://openam.example.com:8088/openam/oauth2/access_token \
      --user microservice-client:password \
      --data grant_type=client_credentials \
      --data scope=client-scope --silent | jq -r .access_token)
  2. View the access_token:

    $ echo $mytoken
    eyJ...FPg

    Note that the token has the structure of a stateless access_token.

  3. Call the Token Validation Microservice to introspect the access_token:

    $ curl --data "token=${mytoken}" http://mstokval.example.com:9090/introspect
    {
     "active": true,
     "sub": "microservice-client",
     "cts": "OAUTH2_STATELESS_GRANT",
     "auditTrackingId": "3b5...083",
     "iss": "http://openam.example.com:8088/openam/oauth2",
     "tokenName": "access_token",
     "token_type": "Bearer",
     "authGrantId": "26V..._oc",
     "aud": "microservice-client",
     "nbf": 1559895523,
     "grant_type": "client_credentials",
     "scope": ["client-scope"],
     "auth_time": 155...523,
     "realm": "/",
     "exp": 155...123,
     "iat": 155...523,
     "expires_in": 3600,
     "jti": "cXQ...Lko"
    }

Chapter 6. Monitoring the Token Validation Microservice

All ForgeRock products expose monitoring endpoints where metrics are exposed. When the Token Validation Microservice is running, metrics are exposed at the Prometheus Scrape Endpoint and Common REST Monitoring Endpoint. By default, no authentication is required to access the monitoring endpoints.

The following procedures describe how to monitor the Token Validation Microservice, and protect the monitoring endpoints:

To Query the Monitoring Endpoints
  1. Set up the the Token Validation Microservice as described in "Introspecting Stateful Access_Tokens With the Token Validation Microservice" or "Introspecting Stateless Access_Tokens With the Token Validation Microservice".

  2. Query the Prometheus Scrape Endpoint, and note that monitoring information is returned:

    $ curl "http://mstokval.example.com:9090/metrics/prometheus"
    # HELP tv_request_active Generated from Dropwizard metric import (metric=request.active, type=gauge)
    # TYPE tv_request_active gauge
    tv_request_active 0.0
    # HELP tv_request_total Generated from Dropwizard metric import (metric=request, type=counter)
    # TYPE tv_request_total counter
    tv_request_total 1.0
    ...
  3. Query the Common REST Monitoring Endpoint, and note that monitoring information is returned:

    $ curl "http://mstokval.example.com:9090/metrics/api?_prettyPrint=true&_sortKeys=_id&_queryFilter=true"
    {
      "result" : [ {
        "_id" : "request",
        "count" : 1,
        "_type" : "counter"
      }, {
        "_id" : "request.active",
        "value" : 0.0,
        "_type" : "gauge"
      },
    ...
To Protect the Monitoring Endpoints
  1. Add the following script to the Token Validation Microservice configuration as /path/to/microservices/token-validation/scripts/groovy/BasicAuthResourceServerFilter.groovy

    /**
     * This scripts is a simple implementation of HTTP Basic Authentication on
     * server side.
     *
     * It expects the following arguments:
     *  - realm: the realm to display when the user-agent prompts for
     *    username and password if none were provided.
     *  - username: the expected username
     *  - password: the expected password
     */
    
    import static org.forgerock.util.promise.Promises.newResultPromise;
    
    import java.nio.charset.Charset;
    import org.forgerock.util.encode.Base64;
    
    String authorizationHeader = request.getHeaders().getFirst("Authorization");
    if (authorizationHeader == null) {
        // No credentials provided, reply that they are needed.
        Response response = new Response(Status.UNAUTHORIZED);
        response.getHeaders().put("WWW-Authenticate", "Basic realm=\"" + realm + "\"");
        return newResultPromise(response);
    }
    
    String expectedAuthorization = "Basic " + Base64.encode((username + ":" + password).getBytes(Charset.defaultCharset()))
    if (!expectedAuthorization.equals(authorizationHeader)) {
        return newResultPromise(new Response(Status.FORBIDDEN));
    }
    // Credentials are as expected, let's continue
    return next.handle(context, request);

    The script is a simple implementation of the HTTP Basic Authentication mechanism.

    For information about scripting filters and handlers, see Extending IG, in the IG Gateway Guide.

  2. Add the following heap object to /path/to/microservices/token-validation/config/config.json:

    "heap": [{
      "name": "MetricsProtectionFilter",
      "type": "ScriptableFilter",
      "config": {
        "type": "application/x-groovy",
        "file": "BasicAuthResourceServerFilter.groovy",
        "args": {
          "realm": "/",
          "username": "metric",
          "password": "password"
        }
      }
    }]
  3. Restart the Token Validation Microservice to reload the configuration.

  4. Query the monitoring endpoints again, as described in "To Query the Monitoring Endpoints", and note that access is denied:

    $ curl "http://mstokval.example.com:9090/metrics/prometheus" -v
    ...
    HTTP/1.1 401 Unauthorized
    ...
    $ curl "http://mstokval.example.com:9090/metrics/api?_prettyPrint=true&_sortKeys=_id&_queryFilter=true" -v
    ...
    HTTP/1.1 401 Unauthorized
    ...
  5. Query the monitoring endpoints again, providing the credentials required in the ScriptableFilter, and note that the monitoring information is returned:

    $ curl "http://mstokval.example.com:9090/metrics/prometheus" --user metric:password
    $ curl "http://mstokval.example.com:9090/metrics/api?_prettyPrint=true&_sortKeys=_id&_queryFilter=true" --user metric:password

Chapter 7. Querying and Disabling the Information Endpoint

When the Token Validation Microservice is running, version information is exposed at the information endpoint. The following sections describe how to query and disable the information endpoint:

To Query the Version Information Endpoint
  • Query the version information endpoint, and note that the following information is returned:

    $ curl "http://mstokval.example.com:9090/info"
    {"version":"...","revision":"...","branch":"...","timestamp":...}
    ...
To Disable the Version Information Endpoint
  1. Add the following attribute to the admin.json file:

    "infoEndpointEnabled": false

    For example:

    {
      "connectors": [
        {
          "port": 9090
        }
      ],
      "infoEndpointEnabled": false
    }

    For more information, see "admin.json".

  2. Restart the Token Validation Microservice to reload the configuration, and then query the version information endpoint again. Note this time that no information is returned.

Appendix A. Reference

This section describes configuration options for the Token Validation Microservice. For information about objects referred to in the example configurations but not described in this appendix, see the Identity Gateway Configuration Reference.

A.1. admin.json

The admin.json file is loaded from a JSON-encoded configuration file, expected by default at /path/to/microservices/token-validation/config. For information about the properties of the file, see AdminHttpApplication, in the Identity Gateway Configuration Reference. This section describes additional properties specific to the Token Validation Microservice.

A.1.1. Usage

{
   "connectors": [ configuration expression<number>, ... ],
   "infoEndpointEnabled": boolean,
}

A.1.2. Properties

"connectors": array of numbers, required

One or more ports on which the Token Validation Microservice listens. When more than one port is defined, the Token Validation Microservice listens on each port.

"infoEndpointEnabled": boolean, optional

Whether the version information endpoint /info is exposed.

Default: true

A.1.3. Default Configuration

The following configuration is provided by default.

{
  "connectors": [
    {
      "port": 9090
    }
  ]
}

A.2. config.json

The config.json file is loaded from a JSON-encoded configuration file, expected by default at /path/to/microservices/token-validation/config.

A.2.1. Usage

{
  "introspectionConfig": {
    "accessTokenResolver": "AccessTokenResolver reference"
  }
}

A.2.2. Properties

"accessTokenResolver": AccessTokenResolver reference, required

An access_token resolver to resolve an access_token against an authorization server. Configure a resolver defined in Access Token Resolvers, in the Identity Gateway Configuration Reference.

A.3. CacheAccessTokenResolver

Enable and configure caching of OAuth 2.0 access_tokens, based on Caffeine. For more information, see the GitHub entry, Caffeine.

This resolver configures caching of access_tokens, and delegates their resolution to another AccessTokenResolver.

A.3.1. Usage

{
  "name": string,
  "type": "CacheAccessTokenResolver",
  "config": {
    "delegate": AccessTokenResolver reference,
    "enabled": configuration expression<boolean>,
    "defaultTimeout": configuration expression<duration>,
    "executor": ScheduledExecutorService reference,
    "maximumSize": configuration expression<number>,
    "maximumTimeToCache": configuration expression<duration>
  }
}

A.3.2. Properties

"delegate": AccessTokenResolver reference, required

Delegate access_token resolution to one of the following access_token resolvers:

enabled: configuration expression<boolean>, optional

Enable caching.

When an access_token is cached, IG can reuse the token information without repeatedly asking the authorization server to verify the access_token. When caching is disabled, IG must ask the authorization server to validate the access_token for each request.

Default: true

defaultTimeout: configuration expression<duration>, optional

The duration for which to cache an OAuth 2.0 access_token when it doesn't provide a valid expiry value or maximumTimeToCache.

If the defaultTimeout is longer than the maximumTimeToCache, then the maximumTimeToCache takes precedence.

Default: 1 minute

"executor": ScheduledExecutorService reference, optional

An executor service to schedule the execution of tasks, such as the eviction of entries from the cache.

Default: ForkJoinPool.commonPool()

"maximumSize": configuration expression<number>, optional

The maximum number of entries the cache can contain.

Default: Unlimited/unbound

"maximumTimeToCache": configuration expression<duration>, optional

The maximum duration for which to cache access_tokens.

Cached access_tokens are expired according to their expiry time and maximumTimeToCache, as follows:

  • If the expiry time is before the current time plus the maximumTimeToCache, the cached token is expired when the expiry time is reached.

  • If the expiry time is after the current time plus the maximumTimeToCache, the cached token is expired when the maximumTimeToCache is reached

The duration cannot be zero or unlimited.

Default: The token expiry time or defaultTimeout

A.3.3. Example

For an example that uses the cache, see "Introspecting Stateful Access_Tokens With the Token Validation Microservice".

A.3.4. More Information

OAuth2ResourceServerFilter, in the IG Configuration Reference

A.4. HttpBasicAuthenticationClientFilter

A.4.1. Description

Authenticate clients according to HTTP Basic Authentication protocol, using the client's credentials.

Use this filter in a service-to-service context, where services need to access resources protected by HTTP Basic Authentication.

A.4.2. Usage

{
  "type": "HttpBasicAuthenticationClientFilter",
  "config": {
    "username": configuration expression<string>,
    "passwordSecretId": configuration expression<secret-id>,
    "secretsProvider": SecretsProvider reference,
    "urlEncodeCredentials": configuration expression<boolean>
  }
}

A.4.3. Properties

"username": configuration expression<string>, required

The username of the client to authenticate.

"passwordSecretId": configuration expression<string>, required

The secret ID required to obtain the client password.

"secretsProvider": SecretsProvider reference, required

The SecretsProvider object to use to obtain the client password. Provide either the name of a SecretsProvider object defined in the heap, or specify a SecretsProvider object inline.

For more information, see SecretsProvider, in the IG Configuration Reference.

"urlEncodeCredentials": configuration expression<boolean>, optional

Set to true to URL-encoded credentials before base64-encoding them.

Default: false

A.4.4. Examples

For an example that uses HttpBasicAuthenticationClientFilter, see "Introspecting Stateful Access_Tokens With the Token Validation Microservice".

A.5. JwkSetSecretStore

Manages a secret store for JSON Web Keys (JWK) from a local or remote JWK Set.

For information about JWKs and JWK Sets, see RFC-7517, JSON Web Key (JWK).

A.5.1. Usage

{
  "name": string,
  "type": "JwkSetSecretStore",
  "config": {
    "jwkUrl": configuration expression<url>,
    "handler": Handler reference or inline handler declaration,
    "cacheTimeout": configuration expression<duration>,
    "cacheMissCacheTime": configuration expression<duration>
  }
}

A.5.2. Properties

"jwkUrl": configuration expression<url>, required

A URL that contains the client's public keys in JWK format.

"handler": Handler reference, optional

An HTTP client handler to communicate with the jwkUrl.

Usually set this property to the name of a ClientHandler configured in the heap, or a chain that ends in a ClientHandler.

Default: ClientHandler

"cacheTimeout": configuration expression<duration>, optional

Delay before the cache is reloaded. The cache contains the jwkUrl.

Default: 2 minutes

"cacheMissCacheTime": configuration expression<duration>, optional

If the jwkUrl is looked up in the cache and is not found, this is the delay before the cache is reloaded.

Default: 2 minutes

A.5.3. Example

In the following example, a JWK set on AM contains signing keys identified by a kid, and the SecretProvider uses a JwkSetSecretStore to verify a signed access_token:

"accessTokenResolver": {
  "type": "StatelessAccessTokenResolver",
  "config": {
    "secretsProvider": {
      "type": "JwkSetSecretStore",
      "config": {
        "jwkUrl": "http://openam.example.com:8088/openam/oauth2/connect/jwk_uri"
      },
      "issuer": "http://openam.example.com:8088/openam/oauth2",
      "verificationSecretId": "verification.secret.id"
    }
  }
}

A JWT signature is validated as follows:

  • The StatelessAccessTokenResolver tries to verify the signature through named secret resolution:

    • If the JWT contains a kid, the StatelessAccessTokenResolver queries the JwkSetSecretStore to find a named secret, whose ID matches the value of a kid in the JwkSetSecretStore.

    • If a named secret is returned, the StatelessAccessTokenResolver tries to validate the signature with it.

    • Note that the property verificationSecretId must be configured but is not used in named secret resolution.

  • If named secret resolution fails, the StatelessAccessTokenResolver tries to verify the signature through valid secret resolution:

    • The StatelessAccessTokenResolver queries the JwkSetSecretStore for a list of valid secrets, whose purpose matches verification.secret.id.

    • The JwkSetSecretStore returns all secrets in the JWK set whose purpose is signature verification. For example, signature verification keys can have the following JWK parameters:

      {
        "use": "sig"
      }

      {
        "key_opts": [ "verify" ]
      }

    • Secrets are returned in the order that they are listed in the JWK set. The StatelessAccessTokenResolver tries to validate the signature with each secret sequentially, starting with the first, and stopping when it succeeds.

  • If the list of valid secrets is empty, or none of the valid secrets can verify the signature, the token is considered as invalid.

A.5.4. More Information

RFC-7517, JSON Web Key (JWK)

Read a different version of :