IG 2023.2

JwkSetHandler

Expose cryptographic keys as a JWK set. Use this handler so that a downstream application can reuse the exposed keys for their assigned purpose.

Consider the following limitations:

  • When the public key is not available, the corresponding private key cannot be exposed. Note, however, that it is not recommended to expose private keys as JWK.

  • Keys in secure storage, such as a Hardware Security Module (HSM) or remote server, cannot be exposed.

For a description of how secrets are managed, see Secrets.

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

Usage

{
  "name": string,
  "type": "JwkSetHandler",
  "config": {
    "secretsProvider": SecretsProvider reference,
    "purposes": [ object, ... ]
  }
}
"secretsProvider": SecretsProvider reference, required

The SecretsProvider to use to resolve the secret. Provide either the name of a SecretsProvider object defined in the heap, or specify a SecretsProvider object inline.

"purposes": array of objects, required

One or more purposes for the secret.

{
  "purposes": [
    {
      "secretId": configuration expression<secret-id>,
      "keyUsage": configuration expression<enumeration>
    },
    ...
  ]
}
"secretId": configuration expression<secret-id>, required

The secret ID of the key to be exposed in the JwkSet.

This secret ID must point to a CryptoKey.

"keyUsage": configuration expression<enumeration>, required

The allowed use of the key:

  • AGREE_KEY: Export the private key used in the key agreement protocol, for example, Diffie-Hellman.

  • ENCRYPT: Export the public key used to encrypt data.

  • DECRYPT: Export the private key used to decrypt data.

  • SIGN: Export the private key used to sign data.

  • VERIFY: Export the public key used to verify signature data.

  • WRAP_KEY: Export the public key used to encrypt (wrap) other keys.

  • UNWRAP_KEY: Export the private key used to decrypt (unwrap) other keys.

Examples

This example uses a JwkSetHandler to expose a signing key used by the JwtBuilderFilter:

  1. Set an environment variable for the base64-encoded secret to sign the JWT:

    $ export SIGNING_KEY_SECRET_ID='cGFzc3dvcmQ='
  2. Add the following route to IG:

    • Linux

    • Windows

    $HOME/.openig/config/routes/jwksethandler.json
    appdata\OpenIG\config\routes\jwksethandler.json
    {
      "name": "jwksethandler",
      "condition": "${find(request.uri.path, '/jwksethandler')}",
      "heap": [
        {
          "name": "SecretKeyPropertyFormat-1",
          "type": "SecretKeyPropertyFormat",
          "config": {
            "format": "BASE64",
            "algorithm": "AES"
          }
        },
        {
          "name": "SystemAndEnvSecretStore-1",
          "type": "SystemAndEnvSecretStore",
          "config": {
            "mappings": [{
              "secretId": "signing.key.secret.id",
              "format": "SecretKeyPropertyFormat-1"
            }]
          }
        }
      ],
      "handler": {
        "type": "Chain",
        "config": {
          "filters": [
            {
              "name": "JwtBuilderFilter-1",
              "type": "JwtBuilderFilter",
              "config": {
                "template": {
                  "name": "${contexts.userProfile.commonName}",
                  "email": "${contexts.userProfile.rawInfo.mail[0]}"
                },
                "secretsProvider": "SystemAndEnvSecretStore-1",
                "signature": {
                  "secretId": "signing.key.secret.id",
                  "algorithm": "HS256"
                }
              }
            }
          ],
          "handler": {
            "type": "JwkSetHandler",
            "config": {
              "secretsProvider": "SystemAndEnvSecretStore-1",
              "purposes": [{
                "secretId": "signing.key.secret.id",
                "keyUsage": "SIGN"
              }]
            }
          }
        }
      }
    }

    Notice the following features of the route:

    • The route matches requests to /jwksethandler.

    • The JWT signing key is managed by the SysEnvStoreSecretStore in the heap, which refers to the SecretKeyPropertyFormat for the secret’s format.

    • The JwtBuilderFilter signature property refers to the JWT signing key in the SysEnvStoreSecretStore.

    • The JwkSetHandler refers to the JWT signing key.

  3. Go to http://ig.example.com:8080/jwksethandler.

    The signing key is displayed as an array, as follows:

    {
      "keys": [
        {
          "k": "cGFzc3dvcmQ",
          "kid": "signing.key.secret.id",
          "kty": "oct",
          "use": "sig"
        }
      ]
    }

    The JWK set secret is ULR base64-encoded. Although the secret is set with the value cGFzc3dvcmQ=, the value cGFzc3dvcmQ is exposed.

Copyright © 2010-2023 ForgeRock, all rights reserved.