OIDC ID Token Validator node

The OIDC ID Token Validator node lets AM rely on an OIDC provider (OP)'s ID token to authenticate an end user. The node evaluates whether the ID token is valid according to the OIDC specification.

To configure the node, first get an id_token from an OIDC client and examine the decoded JWT to view the required claims values.

This example uses an id_token from the OAuth 2.0 Playground:

{
    "iss": "https://accounts.google.com",
    "azp": "407408718192.apps.googleusercontent.com",
    "aud": "407408718192.apps.googleusercontent.com",
    "sub": "111730983950574648607",
    "at_hash": "kvQJZrGcnNMZqM4w68DFBA",
    "iat": 1677608448,
    "exp": 1677612048
}

The iss, azp, and aud claims provide the values for the node’s Token Issuer, Authorized parties and Audience name properties respectively.

To use the OIDC ID Token Validator node to authenticate a user, first configure the node to run a transformation script that maps the user attributes from the JWT to local attributes. You can then create a journey with a Scripted Decision node that stores the attributes in the shared node state so that you can authenticate the user with an ID token.

Outcomes

True
False

Evaluation continues along the True path if the ID token is valid; otherwise, evaluation continues along the False path.

Properties

Property Usage

Property	Usage
OpenID Connect Validation Type	To validate the ID token from the OP, the node requires either a URL to get the public keys for the provider, or the symmetric key for an ID token signed with an HMAC-based algorithm. Select one of the following options to determine how the node retrieves the required information: `Well Known URL` (default): Validate with the keys specified in the OP’s `/.well-known/openid-configuration` JSON document. `Client Secret`: Validate the ID token signature with the provided client secret. `JWK URL`: Validate with the keys retrieved from the URL to the OP’s JSON Web Key Set (JWKS).
OpenID Connect Validation Value	The well-known URL or URL to the JWK location, depending on the value of `OpenID Connect Validation Type`. If the validation type is `Client Secret`, this value is ignored and the `Client Secret Id` is used instead. For example: `https://accounts.google.com/.well-known/openid-configuration`
Client Secret Id	Specifies the ID of a client secret in the AM secret stores. Only required if the validation type is `Client Secret`.
ID Token Header Name	The name of the HTTP request header referencing the ID token. Default: `oidc_id_token`
Token Issuer	The issuer of the OIDC ID token, which is checked against the `iss` claim in the ID token. For example: `https://accounts.google.com`
Audience name	The case-sensitive name of the intended audience for this node, which is checked against the `aud` claim in the ID token.
Authorized parties	The authorized parties from which the node accepts ID tokens, which is checked against the `azp` claim in the ID token. The value can be either a case-sensitive string or a URI.
Transformation Script	Select a script that maps ID token attributes to local attributes. For examples of transformation (normalization) scripts, refer to the `*-profile-normalization.js` scripts in Sample scripts.
Script Inputs	A list of state inputs for the script. Default: `*`
Unreasonable Lifetime Limit	Specify the maximum permitted lifetime of the token in minutes. If the `iat` claim is present, the token must expire within the specified duration. Default: `60`

OpenID Connect Validation Type

To validate the ID token from the OP, the node requires either a URL to get the public keys for the provider, or the symmetric key for an ID token signed with an HMAC-based algorithm.

Select one of the following options to determine how the node retrieves the required information:

Well Known URL (default): Validate with the keys specified in the OP’s /.well-known/openid-configuration JSON document.
Client Secret: Validate the ID token signature with the provided client secret.
JWK URL: Validate with the keys retrieved from the URL to the OP’s JSON Web Key Set (JWKS).

OpenID Connect Validation Value

The well-known URL or URL to the JWK location, depending on the value of OpenID Connect Validation Type. If the validation type is Client Secret, this value is ignored and the Client Secret Id is used instead.

For example: https://accounts.google.com/.well-known/openid-configuration

Client Secret Id

Specifies the ID of a client secret in the AM secret stores. Only required if the validation type is Client Secret.

ID Token Header Name

The name of the HTTP request header referencing the ID token.

Default: oidc_id_token

Token Issuer

The issuer of the OIDC ID token, which is checked against the iss claim in the ID token.

For example: https://accounts.google.com

Audience name

The case-sensitive name of the intended audience for this node, which is checked against the aud claim in the ID token.

Authorized parties

The authorized parties from which the node accepts ID tokens, which is checked against the azp claim in the ID token.

The value can be either a case-sensitive string or a URI.

Transformation Script

Select a script that maps ID token attributes to local attributes.

For examples of transformation (normalization) scripts, refer to the *-profile-normalization.js scripts in Sample scripts.

Script Inputs

A list of state inputs for the script.

Default: *

Unreasonable Lifetime Limit

Specify the maximum permitted lifetime of the token in minutes. If the iat claim is present, the token must expire within the specified duration.

Default: 60

Example

This example demonstrates how to use the OIDC ID Token Validator node as part of a journey to validate an ID token and authenticate the user.

You can access all the provided JWT claims through the jwtClaims attribute. This JavaScript, configured as the node’s transformation script, retrieves the user ID from the JWT.

(function () {
    var fr = JavaImporter( org.forgerock.json.JsonValue);

    var identity = fr.JsonValue.json(fr.JsonValue.object());
    identity.put('uid', jwtClaims.get('sub'));

    return identity;
}());

A Scripted Decision node then runs this script to find the UID from lookupAttributes and store the user ID in the shared node state:

var attributeName = "uid"
var attributes = nodeState.get("lookupAttributes");
var userName = attributes.get(attributeName).asString();
var identity = idRepository.getAttribute(userName, attributeName);

if (!identity.isEmpty()) {
    nodeState.putShared("username", identity.iterator().next());
    outcome = "true";
} else {
    outcome = "false";
}

The following REST call authenticates the user with the example journey, providing the ID token in the header:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
--header "oidc_id_token: <id_token>" \
"https://openam.example.com:8443/openam/json/realms/root/authenticate?authIndexType=service&authIndexValue=myJourney"
{
    "tokenId": "AQIC5w…NTcy*",
    "successUrl": "/openam/console",
    "realm": "/alpha"
}

AM 7.3.1

OIDC ID Token Validator node

Outcomes

Properties

Example