Signed tokens with KeyStoreSecretStore

This page shows how to validate signed access tokens with the StatelessAccessTokenResolver using a KeyStoreSecretStore.

Set up signing keys

Locate the following directories for keys, keystores, and certificates, and in a terminal create variables for them:
- Directory where the keystore is created: keystore_directory
- AM keystore directory: am_keystore_directory
- PingGateway keystore directory: ig_keystore_directory

Set up the keystore for signing keys:

Generate a private key called signature-key, and a corresponding public certificate called x509certificate.pem:

$ openssl req -x509 \
-newkey rsa:2048 \
-nodes \
-subj "/CN=ig.example.com/OU=example/O=com/L=fr/ST=fr/C=fr" \
-keyout $keystore_directory/signature-key.key \
-out $keystore_directory/x509certificate.pem \
-days 365

...
writing new private key to '$keystore_directory/signature-key.key'

Convert the private key and certificate files into a PKCS#12 file, called signature-key, and store them in a keystore named keystore.p12:

$ openssl pkcs12 \
-export \
-in $keystore_directory/x509certificate.pem \
-inkey $keystore_directory/signature-key.key \
-out $keystore_directory/keystore.p12 \
-passout pass:password \
-name signature-key

List the keys in keystore.p12:

$ keytool -list \
-v \
-keystore "$keystore_directory/keystore.p12" \
-storepass "password" \
-storetype PKCS12

...
Your keystore contains 1 entry
Alias name: signature-key

Set up keys for AM:
1. Copy the signing key keystore.p12 to AM:
  $ cp $keystore_directory/keystore.p12 $am_keystore_directory/AM_keystore.p12
2. List the keys in the AM keystore:
  $ keytool -list \ -v \ -keystore "$am_keystore_directory/AM_keystore.p12" \ -storepass "password" \ -storetype PKCS12 ... Your keystore contains 1 entry Alias name: signature-key
3. Add a file called keystore.pass, containing the store password password:
  $ cd $am_keystore_directory $ echo -n 'password' > keystore.pass
  Make sure the password file contains only the password, with no trailing spaces or carriage returns.
  
  The filename corresponds to the secret ID of the store password and entry password for the KeyStoreSecretStore.
4. Restart AM.

Set up keys for PingGateway:

Import the public certificate to the IG keystore, with the alias verification-key:

$ keytool -import \
-trustcacerts \
-rfc \
-alias verification-key \
-file "$keystore_directory/x509certificate.pem" \
-keystore "$ig_keystore_directory/IG_keystore.p12" \
-storetype PKCS12 \
-storepass "password"

...
Trust this certificate? [no]:  yes
Certificate was added to keystore

List the keys in the PingGateway keystore:

$ keytool -list \
-v \
-keystore "$ig_keystore_directory/IG_keystore.p12" \
-storepass "password" \
-storetype PKCS12

...
Your keystore contains 1 entry
Alias name: verification-key

In the PingGateway configuration, set an environment variable for the keystore password:
```
$ export KEYSTORE_SECRET_ID='cGFzc3dvcmQ='
```
Restart PingGateway.

Validate tokens

This procedure uses the Resource Owner Password Credentials grant type. As suggested in The OAuth 2.0 Authorization Framework, use other grant types whenever possible.

Set up AM:
1. Create a KeyStoreSecretStore to manage the new AM keystore:
  1. In AM, select Secret Stores, and then add a secret store with the following values:
    
    Secret Store ID : keystoresecretstore
    
    Store Type : Keystore
    
    File : am_keystore_directory/AM_keystore.p12
    
    Keystore type : PKCS12
    
    Store password secret label : keystore.pass
    
    Entry password secret label : keystore.pass
  2. Select the Mappings tab, and add a mapping with the following values:
    
    Secret Label : am.services.oauth2.stateless.signing.RSA
    
    Aliases : signature-key
    
    The mapping sets signature-key as the active alias to use for signature generation.
2. Create a FileSystemSecretStore to manage secrets for the KeyStoreSecretStore:
  1. Select Secret Stores, and then create a secret store with the following configuration:
    
    Secret Store ID : filesystemsecretstore
    
    Store Type : File System Secret Volumes
    
    Directory : am_keystore_directory
    
    File format : Plain text
3. Configure an OAuth 2.0 Authorization Provider:
  1. Select Services, and add an OAuth 2.0 Provider.
  2. Accept all of the default values, and select Create. The service is added to the Services list.
  3. On the Core tab, select the following option:
    
    Use Client-Based Access & Refresh Tokens : on
  4. On the Advanced tab, select the following options:
    
    Client Registration Scope Allowlist : myscope
    
    OAuth2 Token Signing Algorithm : RS256
    
    Encrypt Client-Based Tokens : Deselected
4. Create an OAuth2 Client to request OAuth 2.0 access tokens:
  1. Select Applications > OAuth 2.0 > Clients, and add a client with the following values:
    
    Client ID : client-application
    
    Client secret : password
    
    Scope(s) : myscope
  2. (Optional) On the Core tab, switch to using a client secret associated with a secret label by setting a Secret Label Identifier and mapping the label to a secret.
    
    To learn more, read Create a client profile and Map and rotate secrets in the AM documentation.
  3. On the Advanced tab, select the following values:
    
    Grant Types : Resource Owner Password Credentials
    
    Response Types : code token
  4. On the Signing and Encryption tab, include the following setting:
    
    ID Token Signing Algorithm : RS256

Set up PingGateway:

Set up PingGateway for HTTPS, as described in Configure PingGateway for TLS (server-side).

Add the following route to PingGateway, replacing ig_keystore_directory:

Linux
Windows

$HOME/.openig/config/routes/rs-stateless-signed-ksss.json

%appdata%\OpenIG\config\routes\rs-stateless-signed-ksss.json

{
  "name": "rs-stateless-signed-ksss",
  "condition" : "${find(request.uri.path, '/rs-stateless-signed-ksss')}",
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "KeyStoreSecretStore-1",
      "type": "KeyStoreSecretStore",
      "config": {
        "file": "<ig_keystore_directory>/IG_keystore.p12",
        "storeType": "PKCS12",
        "storePasswordSecretId": "keystore.secret.id",
        "entryPasswordSecretId": "keystore.secret.id",
        "secretsProvider": "SystemAndEnvSecretStore-1",
        "mappings": [
          {
            "secretId": "stateless.access.token.verification.key",
            "aliases": [ "verification-key" ]
          }
        ]
      }
    }
  ],
  "handler" : {
    "type" : "Chain",
    "capture" : "all",
    "config" : {
      "filters" : [ {
        "name" : "OAuth2ResourceServerFilter-1",
        "type" : "OAuth2ResourceServerFilter",
        "config" : {
          "scopes" : [ "myscope" ],
          "requireHttps" : false,
          "accessTokenResolver": {
            "type": "StatelessAccessTokenResolver",
            "config": {
              "secretsProvider": "KeyStoreSecretStore-1",
              "issuer": "http://am.example.com:8088/openam/oauth2",
              "verificationSecretId": "stateless.access.token.verification.key"
            }
          }
        }
      } ],
      "handler": {
        "type": "StaticResponseHandler",
        "config": {
          "status": 200,
          "headers": {
            "Content-Type": [ "text/html; charset=UTF-8" ]
          },
          "entity": "<html><body><h2>Decoded access_token: ${contexts.oauth2.accessToken.info}</h2></body></html>"
        }
      }
    }
  }
}

Notice the following features of the route:

The route matches requests to /rs-stateless-signed-ksss.
The keystore password is provided by the SystemAndEnvSecretStore in the heap.
The OAuth2ResourceServerFilter expects an OAuth 2.0 access token in the header of the incoming authorization request, with the scope myscope.
The accessTokenResolver uses a StatelessAccessTokenResolver to resolve and verify the authenticity of the access token. The secret is provided by the KeyStoreSecretStore in the heap.
After the OAuth2ResourceServerFilter validates the access token, it creates the OAuth2Context context. For more information, refer to OAuth2Context.
If there is no access token in a request, or if the token validation does not complete successfully, the filter returns an HTTP error status to the user agent, and PingGateway stops processing the request, as specified in the RFC, The OAuth 2.0 Authorization Framework: Bearer Token Usage.
The StaticResponseHandler returns the content of the access token from the context.

Test the setup for a signed access token:

Get an access token for the demo user, using the scope myscope:

$ mytoken=$(curl -s \
--user "client-application:password" \
--data "grant_type=password&username=demo&password=Ch4ng31t&scope=myscope" \
http://am.example.com:8088/openam/oauth2/access_token | jq -r ".access_token")

Display the token:
```
$ echo ${mytoken}
```

Access the route by providing the token returned in the previous step:

$ curl -v \
--cacert /path/to/secrets/ig.example.com-certificate.pem \
--header "Authorization: Bearer ${mytoken}" \
https://ig.example.com:8443/rs-stateless-signed-ksss

...
Decoded access_token: {
sub=(usr!demo),
cts=OAUTH2_STATELESS_GRANT,
...

PingGateway 2024.9

Signed tokens with KeyStoreSecretStore

Set up signing keys

Validate tokens