Package org.forgerock.openig.assertion.handler

Class IdentityAssertionHandler

java.lang.Object
org.forgerock.openig.assertion.handler.IdentityAssertionHandler
All Implemented Interfaces:
Handler
public final class IdentityAssertionHandler extends Object implements Handler
Provides support to locally process a user and generate a JWT assertion that represents the user back to the calling party. Intended to be used in conjunction with an Identity Cloud authentication journey where it can redirect a user to IG to carry out local processing on its behalf and return the user to the journey, along with the assertion, once the local processing has been completed successfully. Local processing may include authentication and/or authorization.

Makes use of the IdentityRequestJwtContext provided by the IdentityRequestJwtValidationFilter once validation of the Identity Request JWT is completed. 

 {
      "type": "IdentityAssertionHandler",
      "config": {
          "identityAssertionPlugin"   : IdentityAssertionPlugin [REQUIRED]
          "selfIdentifier             : expression              [REQUIRED - a configuration time expression used to
                                                                            validate the AUD claim value in the
                                                                            Identity Request JWT and will be used as
                                                                            the ISS claim in the Identity Assertion
                                                                            JWT.]
          "peerIdentifier             : expression              [REQUIRED - a configuration time expression used to
                                                                            validate the ISS claim value in the
                                                                            Identity Request JWT and will be used as
                                                                            the AUD claim in the Identity Assertion
                                                                            JWT.]
          "encryptionSecretId"        : expression<secret-id>   [REQUIRED - a configuration time expression to define
                                                                            the secret ID of the Authenticated
                                                                            Encryption (symmetric) key, used to
                                                                            decrypt the Identity Request JWT and to
                                                                            encrypt the returned Identity Assertion
                                                                            JWT. The encryption method used when
                                                                            encrypting the Identity Assertion JWT will
                                                                            be the same as was used for the Identity
                                                                            Request JWT.]
          "secretsProvider"           : Secrets Provider        [REQUIRED - resolve the authenticated encryption key.]
          "expiry"                    : expression<duration>    [OPTIONAL - a configuration time expression used to
                                                                            set the additional duration from now on
                                                                            the Identity Assertion JWT expiry claim.
                                                                            Defaults to 30 seconds.]
          "skewAllowance"             : expression<duration>    [OPTIONAL - a configuration time expression to define
                                                                            the skew allowance duration of the
                                                                            Identity Request JWT issued at and expiry
                                                                            claims. Defaults to zero.]
          }
      }
 
 }
Example usage: 
 {
         "type": "IdentityAssertionHandler",
         "config": {
             "identityAssertionPlugin": "ScriptablePluginExample",
             "selfIdentifier": "identity-gateway",
             "peerIdentifier": "identity-cloud",
             "secretsProvider": "assertionSecrets",
             "encryptionSecretId": "encryption.key.id"
         }
     }
All JWTs contain the core claims of: 
     iss (Issuer)
     aud (Audience)
     iat (Issued At)
     exp (Expiration Time)
     nonce (a unique ID, generated by the Node and returned in the Identity Assertion JWT)
Additional claims in the Identity Request JWT: 
     redirect (URL to pass the Identity Assertion JWT back on)
     version (The version of the JWT, v1 is the only version currently supported)
     data (optional claim containing a map of claims items that might be required by a plugin)
Additional claims in the Identity Assertion JWT are either one of the following claim items: 
     principal (represents the principal of the local user)
     identity (a claim containing a map of any additional identity claim items returned by the plugin)
or in the case of an error during plugin processing 
     error (a claim containing the error message of the plugin processing failure)
Example Identity Request JWT: 
 {
     "iss": "issuer identifier",
     "aud": "audience identifier",
     "nonce": "unique random String",
     "redirect": "URL used to get the Identity Assertion JWT back to the Node",
     "iat": 1705618125,
     "exp": 1705618180,
     "version": "v1",
     "data": {
         "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:120.0) Gecko/20100101 Firefox/120.0"
     }
 }
Example Identity Assertion JWT with identity claims 
 {
     "iss": "Node identifier",
     "aud": "IG identifier",
     "nonce": "nonce from the Identity Request JWT",
     "iat": 1705618125,
     "exp": 1705618180,
     "principal": "iguser",
     "identity": {
         "auth": "Basic"
     }
 }
Example Identity Assertion JWT with error claim 
 {
     "iss": "IG identifier",
     "aud": "Node identifier",
     "nonce": "nonce from the Identity Request JWT",
     "iat": 1705618125,
     "exp": 1705618180,
     "error": "Invalid token"
 }

Cryptographic note: We chose to use on "A256GCM" encryption method to encrypt tokens exchanged with the Identity Cloud node module because:

  1. It can be easily generated in a PKCS12 or other keystore using Oracle's keytool (unlike "A256CBC_HS512")
  2. It can be used to create a symmetric key as an Octet JWK with the direct algorithm
  3. It is recommended by the Ping Cryptographic guidelines (v1_7 of 10/06/23)

  • Method Details

    • handle

      public Promise<Response,NeverThrowsException> handle(Context context, Request request)
      Description copied from interface: Handler
      Returns a Promise representing the asynchronous Response of the given request. If any (asynchronous) processing goes wrong, the promise still contains a Response (probably from the 4xx or 5xx status code family).

      A handler that doesn't hand-off the processing to another downstream handler is responsible for creating the response.

      The returned Promise contains the response returned from the server as-is. This is responsibility of the handler to produce the appropriate error response (404, 500, ...) in case of processing error.

      Note: As of Promise 2.0 implementation, it is not permitted to throw any runtime exception here. Doing so produce unexpected behaviour (most likely a server-side hang of the processing thread).

      Specified by:
      handle in interface Handler
      Parameters:
      context - The request context.
      request - The request.
      Returns:
      A Promise representing the response to be returned to the caller.