PingGateway 2024.9

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.

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

{
  "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
"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 iss claim 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 aud claim 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 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, 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"
      }
    }
  }
}
Copyright © 2010-2024 ForgeRock, all rights reserved.