IdentityAssertionHandler

Use in an PingOne Advanced Identity Cloud authentication journey with the IdentityAssertionNode node. The node is available in PingOne Advanced Identity Cloud and from AM 7.5. Learn more from PingOne Advanced Identity Cloud’s Identity Assertion node and AM’s Identity Assertion node.

This handler replaces IdentityAssertionHandlerTechPreview designed for the Gateway Communication node.

The following image shows the flow of information when an Identity Assertion node authenticates internal accesses:

As part of an PingOne Advanced Identity Cloud journey, the IdentityAssertionHandler uses an identityAssertionPlugin to manage local authentication as follows:

The PingOne Advanced Identity Cloud authentication journey redirects a user to PingGateway for local authentication, providing an identity request JWT.
PingGateway validates the identity request JWT.
The identityAssertionPlugin accesses the IdentityRequestJwtContext generated from the identity request JWT. It then performs local processing and returns the principal and identity claims in an identity assertion JWT.
PingGateway redirects the user back to PingOne Advanced Identity Cloud authentication journey, providing the identity assertion JWT. If an exception prevents PingGateway from returning a valid identity assertion JWT, PingGateway returns an HTTP 500.

The following table lists the claims contained in identity request JWT and identity assertion JWT:

Claim Description Identity request JWT Identity assertion JWT
(succesful plugin processing) Identity assertion JWT
(plugin processing error)

iss

Issuer

aud

Audience

iat

Issued at

exp

Expiration time

nonce

Unique ID generated by the IdentityGatewayAssertionNode and returned in the identity assertion JWT

redirect

URL on which to send the identity assertion JWT

version

JWT version; only v1 is supported

data

Map of claims items that can be required by a plugin

Optional

principal

The user for whom the identity assertion JWT is issued

identity

Map of additional identity claims returned by the plugin

error

Error message of the plugin processing failure

Usage

{
  "name": string,
  "type": "IdentityAssertionHandler",
  "config": {
    "identityAssertionPlugin": IdentityAssertionPlugin reference,
    "selfIdentifier": configuration expression<string>,
    "peerIdentifier": configuration expression<string>,
    "encryptionSecretId": configuration expression<secret-id>,
    "secretsProvider": Secrets Provider reference,
    "expiry": configuration expression<duration>,
    "skewAllowance": configuration expression<duration>
  }
}

"identityAssertionPlugin": configuration expression<string>, required

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

This plugin is called after the IdentityAssertionHandler validates the identity request JWT from PingOne Advanced Identity Cloud. The handler then passes the IdentityRequestJwtContext in the context chain to the plugin.

For an out-of-the-box plugin to support use-cases that aren’t already provisioned by a PingGateway plugin, refer to ScriptableIdentityAssertionPlugin.

"selfIdentifier": configuration expression<string>, required

An identifier to validate that this PingGateway instance is the correct audience for the identity request from PingOne Advanced Identity Cloud.

This identifier is the value of:

aud claim in the identity request JWT
iss claim in the identity assertion JWT

Can’t be null.

"peerIdentifier": configuration expression<string>, required

An identifier to validate that the expected PingOne Advanced Identity Cloud tenant issued the identity request.

This identifier is the value of the:

iss claim in the identity request JWT
aud claim in the identity assertion JWT

Can’t be null.

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

The secret ID for the secret to decrypt the identity request JWT and encrypt the returned identity assertion JWT. The secret ID must point to a CryptoKey. Decryption and encryption is with AES GCM using a 256-bit key.

"secretsProvider": SecretsProvider reference, required

The SecretsProvider to resolve encrytion and decryption keys.

"expiry": _configuration expression<duration>, optional

The expiry time of the identity assertion JWT.

Default: 30 seconds

"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.

Example

The following route is an Identity Assertion service route for use with the IdentityAssertionNode.

Learn about how to set up the example in PingOne Advanced Identity Cloud’s Identity Assertion node and AM’s Identity Assertion node.

{
  "name": "IdentityAssertion",
  "condition": "${find(request.uri.path, '^/idassert')}",
  "properties": {
    "amIdcPeer": "myTenant.forgeblocks.com"
  },
  "handler": "IdentityAssertionHandler-1",
  "heap": [
    {
      "name": "IdentityAssertionHandler-1",
      "type": "IdentityAssertionHandler",
      "config": {
        "identityAssertionPlugin": "BasicAuthScriptablePlugin",
        "selfIdentifier": "https://ig.ext.com:8443",
        "peerIdentifier": "&{amIdcPeer}",
        "secretsProvider": [
          "secrets-pem"
        ],
        "encryptionSecretId": "idassert"
      }
    },
    {
      "name": "BasicAuthScriptablePlugin",
      "type": "ScriptableIdentityAssertionPlugin",
      "config": {
        "type": "application/x-groovy",
        "source": [
          "import org.forgerock.openig.assertion.IdentityAssertionClaims",
          "import org.forgerock.openig.assertion.plugin.IdentityAssertionPluginException",
          "logger.info('Running ScriptableIdentityAssertionPlugin')",
          "return new IdentityAssertionClaims('demo')"
        ]
      }
    },
    {
      "name": "pemPropertyFormat",
      "type": "PemPropertyFormat"
    },
    {
      "name": "secrets-pem",
      "type": "FileSystemSecretStore",
      "config": {
        "directory": "&{ig.instance.dir}/secrets/igfs",
        "suffix": ".pem",
        "format": "pemPropertyFormat",
        "mappings": [
          {
            "secretId": "idassert",
            "format": "pemPropertyFormat"
          }
        ]
      }
    }
  ]
}

More information

org.forgerock.openig.assertion.plugin.IdentityAssertionPlugin

PingGateway 2024.9

IdentityAssertionHandler

Usage

Example

More information