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) |
---|---|---|---|---|
|
Issuer |
|
|
|
|
Audience |
|
|
|
|
Issued at |
|
|
|
|
Expiration time |
|
|
|
|
Unique ID generated by the IdentityGatewayAssertionNode and returned in the identity assertion JWT |
|
|
|
|
URL on which to send the identity assertion JWT |
|
|
|
|
JWT version; only v1 is supported |
|
|
|
|
Map of claims items that can be required by a plugin |
Optional |
|
|
|
The user for whom the identity assertion JWT is issued |
|
|
|
|
Map of additional identity claims returned by the plugin |
|
|
|
|
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"
}
]
}
}
]
}