--- title: IdentityAssertionHandlerTechPreview description: Use in an PingOne Advanced Identity Cloud authentication journey with the Gateway Communication node. component: pinggateway version: 2024.11 page_id: pinggateway:reference:IdentityAssertionHandlerTechPreview canonical_url: https://docs.pingidentity.com/pinggateway/2024.11/reference/IdentityAssertionHandlerTechPreview.html revdate: 2025-06-03T09:07:28Z 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 PingOne Advanced Identity Cloud authentication journey with the [Gateway Communication node](https://docs.pingidentity.com/auth-node-ref/latest/cloud/auth-node-gateway-comm-node.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 PingOne Advanced Identity Cloud authentication journey does the following: * Redirects users to PingGateway for local authentication. * After local authentication, provides an identity assertion and redirects users back to the PingOne Advanced Identity Cloud authentication journey. The PingOne Advanced 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 PingOne Advanced 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](ScriptableIdentityAssertionPluginTechPreview.html). * `"selfIdentifier"`: *configuration expression<[string](preface.html#definition-string)>, required* An identifier to validate that this PingGateway instance is the right audience for the incoming JWT from PingOne Advanced Identity Cloud. The same identifier is used for the `iss` claim of the outgoing JWT sent to PingOne Advanced 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 to PingOne Advanced Identity Cloud. Can't be null. * `"expire"`: *[duration](preface.html#definition-duration), optional* The expiry time of the outgoing JWT sent to PingOne Advanced Identity Cloud. Default: 30 seconds * `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), required* The [SecretsProvider](SecretsProvider.html) to query for cryptographic keys. * `"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, PingGateway 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. 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 PingGateway clock. * A JWT with an `exp` 13:00 is expired after 13:02 on the PingGateway clock. Default: To support a zero-trust policy, the skew allowance is by 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 PingOne Advanced Identity Cloud authentication journey that uses a [Gateway Communication node](https://docs.pingidentity.com/auth-node-ref/latest/cloud/auth-node-gateway-comm-node.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).