Identity Gateway 2024.3

IdentityAssertionHandlerTechPreview

The IdentityAssertionHandlerTechPreview, ScriptableIdentityAssertionPluginTechPreview, and IdentityAssertionPluginTechPreview are available in Technology preview. They aren’t yet supported, may be functionally incomplete, and are subject to change without notice.

Use in an Identity Cloud authentication journey with the Gateway Communication node. described in Identity Cloud’s Gateway Communication overview.

The IdentityAssertionHandlerTechPreview sets up an IdentityAssertionPluginTechPreview to manage local processing, such as authentication. The Handler then calls the plugin at runtime for each request.

An Identity Cloud authentication journey does the following:

  • Redirects users to IG for local authentication.

  • After local authentication, provides an identity assertion and redirects users back to the Identity Cloud authentication journey.

The Identity Cloud authentication journey provides:

  • A cryptographically-secure random value in a nonce to validate the identity assertion.

  • A returnUri to redirect the user back to Identity Cloud to continue the authentication journey.

Exceptions during local processing cause a redirect with an assertion JWT containing an assertionError claim. Exceptions that prevent the return of a valid assertion, such as an invalid incoming JWT or key error, cause an HTTP 500.

Usage

{
  "name": string,
  "type": "IdentityAssertionHandlerTechPreview",
  "config": {
    "identityAssertionPlugin": IdentityAssertionPluginTechPreview reference,
    "selfIdentifier": configuration expression<string>,
    "peerIdentifier": configuration expression<string>,
    "expire": configuration expression<duration>,
    "secretsProvider": Secrets Provider reference,
    "verificationSecretId": configuration expression<secret-id>,
    "decryptionSecretId": configuration expression<secret-id>,
    "skewAllowance": configuration expression<duration>,
    "signature": object
  }
}
"identityAssertionPlugin": configuration expression<string>, required

An implementation of org.forgerock.openig.handler.assertion.IdentityAssertionPluginTechPreview.

An out-of-the box implementation is available in ScriptableIdentityAssertionPluginTechPreview.

"selfIdentifier": configuration expression<string>, required

An identifier to validate that this IG instance is the right audience for the incoming JWT from Identity Cloud. The same identifier is used for the iss claim of the outgoing JWT sent to Identity Cloud.

Can’t be null.

"peerIdentifier": configuration expression<string>, required

An identifier to validate that the incoming JWT is from the expected peer. The same identifier is used for the aud claim in the outgoing JWT sent Identity Cloud.

Can’t be null.

"expire": duration, optional

The expiry time of the outgoing JWT sent to Identity Cloud.

Default: 30 seconds

"secretsProvider": SecretsProvider reference, required

The SecretsProvider to query for cryptographic keys.

"verificationSecretId": configuration expression<secret-id>, required

The secret ID for the secret to validate the signature of the incoming JWT. The secret ID must point to a CryptoKey.

"decryptionSecretId": configuration expression<secret-id>, optional

The secret ID for the secret to decrypt the incoming JWT. The secret ID must point to a CryptoKey.

When this property isn’t set, IG treats the incoming JWT as signed but not encrypted.

Default: Not set.

"skewAllowance": configuration expression<duration>, optional

The duration to add to the validity period of a JWT to allow for clock skew between different servers.

A skewAllowance of 2 minutes affects the validity period as follows:

  • A JWT with an iat of 12:00 is valid from 11:58 on the IG clock.

  • A JWT with an exp 13:00 is expired after 13:02 on the IG clock.

Default: To support a zero-trust policy, the skew allowance is by default zero.

"signature": object, required

A JWT signature to validate the authenticity of claims or data for the outgoing JWT.

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

The secret ID of the signing key. The secret ID must point to a CryptoKey.

"algorithm": configuration expression<string>, optional

The signing algorithm.

Default: RS256

"encryption": object, required

Configuration to encrypt the JWT.

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

The secret ID of the encryption key. The secret ID must point to a CryptoKey.

"algorithm": configuration expression<string>, required

The encryption algorithm. Use an algorithm from the List of JWS Algorithms.

"method": configuration expression<string>, required

The encryption method. Use a method from the List of JWE Algorithms.

Example

The following example route is for a Identity Cloud authentication journey that uses a Gateway Communication node.

For information about the identityAssertionPlugin object, refer to the example in ScriptableIdentityAssertionPluginTechPreview.

{
  "type": "IdentityAssertionHandlerTechPreview",
  "config": {
    "identityAssertionPlugin": "BasicAuthScriptablePlugin",
    "selfIdentifier": "identity-gateway",
    "peerIdentifier": "gateway-communication-node",
    "secretsProvider": [
      "IG-Decrypt",
      "Node-Verify",
      "IG-Sign",
      "Node-Encrypt"
    ],
    "verificationSecretId": "id.key.for.verifying.incoming.jwt",
    "decryptionSecretId": "id.key.for.decrypting.incoming.jwt",
    "signature": {
      "secretId": "id.key.for.signing.assertion.jwt",
      "algorithm": "RS256",
      "encryption": {
        "secretId": "id.key.for.encrypting.assertion.jwt",
        "algorithm": "RSA-OAEP-256",
        "method": "A256GCM"
      }
    }
  }
}

More information

org.forgerock.openig.handler.assertion.IdentityAssertionPluginTechPreview.