Identity Gateway

JwkSetHandler

Expose cryptographic keys cryptographic keys as 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 used by the JwtBuilderFilter to sign or encrypt the JWT.

"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.

More information

org.forgerock.openig.handler.JwkSetHandler