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 PingOne Advanced Identity Cloud authentication journey with the Gateway Communication node. described in PingOne Advanced 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 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
returnUrito 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
{
"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 PingGateway instance is the right audience for the incoming JWT from PingOne Advanced Identity Cloud. The same identifier is used for the
issclaim of the outgoing JWT sent to PingOne Advanced 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
audclaim in the outgoing JWT sent to PingOne Advanced Identity Cloud.Can’t be null.
"expire": duration, optional-
The expiry time of the outgoing JWT sent to PingOne Advanced 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, PingGateway 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
skewAllowanceof 2 minutes affects the validity period as follows:-
A JWT with an
iatof 12:00 is valid from 11:58 on the PingGateway clock. -
A JWT with an
exp13: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, 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 PingOne Advanced 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"
}
}
}
}