IdentityAssertionHandler

Use in an Identity Cloud authentication journey with the IdentityAssertionNode node. The node is available from AM 7.5 and when announced in Identity Cloud’s Release notes.

This handler replaces IdentityAssertionHandlerTechPreview designed for the Gateway Communication node described in Identity Cloud’s Gateway Communication overview.

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

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

The Identity Cloud authentication journey redirects a user to IG for local authentication, providing an identity request JWT.
IG 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.
IG redirects the user back to Identity Cloud authentication journey, providing the identity assertion JWT. If an exception prevents IG from returning a valid identity assertion JWT, IG 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 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 an IG plugin, refer to ScriptableIdentityAssertionPlugin.

"selfIdentifier": configuration expression<string>, required

An identifier to validate that this IG instance is the correct audience for the identity request from 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 Identity Cloud instance 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 IG clock.
A JWT with an exp 13:00 is expired after 13:02 on the IG 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.

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

IG 2024.3

IdentityAssertionHandler

Usage

Example

More information