PingGateway 2024.9

JwtBuilderFilter

Collects data at runtime, packs it in a JSON Web Token (JWT), and places the resulting JWT into the JwtBuilderContext.

Configure JwtBuilderFilter to create a signed JWT, a signed then encrypted JWT, or an encrypted JTW:

  • Sign the JWT so that an application can validate the authenticity of the claims/data. The JWT can be signed with a shared secret or private key, and verified with a shared secret or corresponding public key.

  • Encrypt the JWT to reduce the risk of a data breach.

For a flexible way to pass identity or other runtime information to the protected application, use this filter with a HeaderFilter.

To enable downstream filters and handlers to verify signed and/or encrypted JWTs built by this filter, use this filter with a JwkSetHandler.

Usage

{
  "name": string,
  "type": "JwtBuilderFilter",
  "config": {
    "template": map or runtime expression<map>,
    "secretsProvider": SecretsProvider reference,
    "signature": object,
    "encryption": object
  }
}

Properties

"template": map or runtime expression<map>, required

A map of one or more data pairs with the format Map<String, Object>, where:

  • The key is the name of a data field

  • The value is a data object, or a runtime expression that evaluates to a data object

The following formats are allowed:

{
  "template": {
    "string": "runtime expression<object>",
    ...
  }
}
{
  "template": "runtime expression<map>"
}

In the following example, the property is a map whose values are runtime expressions that evaluate to objects in the context:

{
  "template": {
    "name": "${contexts.userProfile.commonName}",
    "email": "${contexts.userProfile.rawInfo.mail[0]}",
    "address": "${contexts.userProfile.rawInfo.postalAddress[0]}",
    "phone": "${contexts.userProfile.rawInfo.telephoneNumber[0]}"
  }
}

In the following example, the property is a runtime expression that evaluates to a map with the format Map<String, Object>:

{
  "template": "${contexts.attributes}"
}

Use the now dynamic binding to dynamically set the value of an attribute that represents time. For example, set the value of attributes to a defined time after the expressions are evaluated, as follows:

{
  "name": "JwtBuilderFilter-1",
  "type": "JwtBuilderFilter",
    "config": {
    "template": {
      "iat": "${now.epochSeconds}",
      "nbf": "${now.plusSeconds(10).epochSeconds}",
      "exp": "${now.plusSeconds(20).epochSeconds}"
    },
    "secretsProvider": "FileSystemSecretStore-1",
      "signature": {
        "secretId": "id.key.for.signing.jwt",
        "algorithm": "RS512"
    }
  }
}
"secretsProvider": SecretsProvider reference, required

The SecretsProvider to query for JWT signing or encryption keys.

"signature": object, "signature" and/or "encryption" is required

A JWT signature to allow the authenticity of the claims/data to be validated. A signed JWT can be encrypted.

JwtBuilderFilter.encryption takes precedence over this property.

{
  "signature": {
    "secretId": configuration expression<secret-id>,
    "includeKeyId": configuration expression<secret-id>,
    "algorithm": configuration expression<string>,
    "encryption": object
  }
}
"secretId": configuration expression<secret-id>, required if signature is used

The secret ID of the key to sign the JWT.

This secret ID must point to a CryptoKey.

"includeKeyId": configuration expression<boolean>, optional

When true, include the ID of the signature key in the JWT header.

Default: true

"algorithm": configuration expression<string>, optional

The algorithm to sign the JWT.

The following algorithms are supported but not necessarily tested in PingGateway:

"encryption": object, optional

Configuration to encrypt the JWT signature.

{
  "encryption": {
    "secretId": configuration expression<secret-id>,
    "algorithm": configuration expression<string>,
    "method": configuration expression<string>
  }
}
"secretId": configuration expression<secret-id>, optional

The secret ID of the key used to encrypt the JWT signature. The value is mapped to key aliases in KeyStoreSecretStore.

This secret ID must point to a CryptoKey.

"algorithm": configuration expression<string>, required

The algorithm used to encrypt the JWT signature.

For information about available algorithms, refer to RFC 7518: "alg" (Algorithm) Header Parameter Values for JWE.

"method": configuration expression<string>, required

The method used to encrypt the JWT signature.

For information about available methods, refer to RFC 7518: "enc" (Encryption Algorithm) Header Parameter Values for JWE.

"encryption": object, "signature" and/or "encryption" is required

Configuration to encrypt the JWT.

This property take precedence over JwtBuilderFilter.signature.

{
  "encryption": {
    "secretId": secret-id,
    "algorithm": configuration expression<string>,
    "method": configuration expression<enumeration>
  }
}
"secretId": secret-id, optional

The secret ID of the key used to encrypt the JWT. The value is mapped to key aliases in KeyStoreSecretStore.

This secret ID must point to a CryptoKey.

"algorithm": configuration expression<string>, required

The algorithm used to encrypt the JWT.

For information about available algorithms, refer to RFC 7518: "alg" (Algorithm) Header Parameter Values for JWE.

"method": configuration expression<enumeration>, required

The method used to encrypt the JWT.

For information about available methods, refer to RFC 7518: "enc" (Encryption Algorithm) Header Parameter Values for JWE.

Examples

For examples, refer to Pass data along the chain

More information

org.forgerock.openig.filter.JwtBuilderFilter

org.forgerock.openig.filter.JwtBuilderContext