--- title: IdentityAssertionHandlerTechPreview description: Use in an Identity Cloud authentication journey with a Gateway Communication node. For more information, refer to Identity Cloud's Gateway Communication overview. component: pinggateway version: 2023.11 page_id: pinggateway:reference:IdentityAssertionHandlerTechPreview canonical_url: https://docs.pingidentity.com/pinggateway/2024.11/reference/IdentityAssertionHandlerTechPreview.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2025-06-03T11:21:31Z superseded_by: https://docs.pingidentity.com/pinggateway/2024.11/reference/IdentityAssertionHandlerTechPreview.html section_ids: IdentityAssertionHandlerTechPreview-usage: Usage IdentityAssertionHandlerTechPreview-example: Example IdentityAssertionHandlerTechPreview-moreinfo: More information --- # IdentityAssertionHandlerTechPreview | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The IdentityAssertionHandlerTechPreview, ScriptableIdentityAssertionPluginTechPreview, and IdentityAssertionPluginTechPreview are available in [Technology preview](https://docs.pingidentity.com/pinggateway/release-notes/stability.html#interface-stability). They aren't yet supported, may be functionally incomplete, and are subject to change without notice. | Use in an Identity Cloud authentication journey with a Gateway Communication node. For more information, refer to Identity Cloud's [Gateway Communication overview](https://docs.pingidentity.com/auth-node-ref/latest/cloud/auth-node-gateway-comm.html). 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 and 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 ```json { "name": string, "type": "IdentityAssertionHandlerTechPreview", "config": { "identityAssertionPlugin": IdentityAssertionPluginTechPreview reference, "selfIdentifier": configuration expression, "peerIdentifier": configuration expression, "expire": configuration expression, "secretsProvider": Secrets Provider reference, "verificationSecretId": configuration expression, "decryptionSecretId": configuration expression, "skewAllowance": configuration expression, "signature": object } } ``` * `"identityAssertionPlugin"`: *configuration expression<[string](preface.html#definition-string)>, required* An implementation of [org.forgerock.openig.handler.assertion.IdentityAssertionPluginTechPreview](../_attachments/apidocs/org/forgerock/openig/handler/assertion/IdentityAssertionPluginTechPreview.html). An out-of-the box implementation is available in [ScriptableIdentityAssertionPluginTechPreview](MiscellaneousConfigurationObjects.html#ScriptableIdentityAssertionPluginTechPreview). * `"selfIdentifier"`: *configuration expression<[string](preface.html#definition-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](preface.html#definition-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](preface.html#definition-duration), optional* The expiry time of the outgoing JWT sent to Identity Cloud. Default: 30 seconds * `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), optional* The [SecretsProvider](secrets.html#SecretsProvider) to resolve queried cryptographic keys. Default: The route's default secret service. For more information, refer to [Default secrets object](secrets.html#default-secrets-object). * `"verificationSecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, required* The secret ID for the secret to validate the signature of the incoming JWT. The secret ID must point to a [CryptoKey](../security-guide/keys.html#secret-types). * `"decryptionSecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, optional* The secret ID for the secret to decrypt the incoming JWT. The secret ID must point to a [CryptoKey](../security-guide/keys.html#secret-types). When this property isn't set, IG treats the incoming JWT as signed but not encrypted. Default: Not set. - `"skewAllowance"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* The duration to add to the validity period of a JWT to allow for clock skew between different servers. To support a zero-trust policy, the skew allowance is by default zero. 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: `zero` - `"signature"`: *[object](preface.html#definition-object), required* A JWT signature to validate the authenticity of claims or data for the outgoing JWT. ```json { "signature": { "secretId": configuration expression, "algorithm": configuration expression, "encryption": object } } ``` * `"secretId"`: *[secret-id](preface.html#definition-secretid), required* The secret ID of the signing key. The secret ID must point to a [CryptoKey](../security-guide/keys.html#secret-types). * `"algorithm"`: *configuration expression<[string](preface.html#definition-string)>, optional* The signing algorithm. Default: `RS256` * `"encryption"`: *[object](preface.html#definition-object), required* Configuration to encrypt the JWT. ```json { "encryption": { "secretId": configuration expression, "algorithm": configuration expression, "method": configuration expression } } ``` * `"secretId"`: *[secret-id](preface.html#definition-secretid), required* The secret ID of the encryption key. The secret ID must point to a [CryptoKey](../security-guide/keys.html#secret-types). * `"algorithm"`: *configuration expression<[string](preface.html#definition-string)>, required* The encryption algorithm. Use an algorithm from the [List of JWS Algorithms](https://tools.ietf.org/html/rfc7518#section-3). * `"method"`: *configuration expression<[string](preface.html#definition-string)>, required* The encryption method. Use a method from the [List of JWE Algorithms](https://tools.ietf.org/html/rfc7518#section-4.1). ## Example The following example route is for a Identity Cloud authentication journey that uses a [Gateway Communication node](https://docs.pingidentity.com/auth-node-ref/latest/cloud/auth-node-gateway-comm.html). For information about the `identityAssertionPlugin` object, refer to the example in [ScriptableIdentityAssertionPluginTechPreview](ScriptableIdentityAssertionPluginTechPreview.html). ```json { "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](../_attachments/apidocs/org/forgerock/openig/handler/assertion/IdentityAssertionPluginTechPreview.html).