PingAM 7.5.0

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.

Compatibility

Product Compatible?

PingOne Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Inputs

None.

Dependencies

A valid OIDC ID token provided in the HTTP request header.

Configuration

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 Label is used instead.

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

Client Secret Label

The secret label to which the OIDC client secret should be mapped.

Only required if the validation type is Client Secret.

You can specify an existing label or AM creates a new one dynamically.

The label can only contain alphanumeric characters a-z, A-Z, 0-9, and periods (.). It can’t start or end with a period.

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 Social Identity Provider Profile Transformation script that maps ID token attributes to local attributes.

For examples of transformation (normalization) scripts, refer to the Example or 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

Outputs

The node relies on the transformation script to set profile attributes required later in the journey.

Outcomes

  • True

  • False

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

Errors

The node logs the following warnings:

  • No OpenIdConnect ID Token referenced by header value: {}: if the node can’t read the ID token in the HTTP request header.

  • Error evaluating the script: if there is a problem with the transformation script.

The node logs an error if an AuthLoginException occurs during node processing.

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.

oidc idtoken validation example platform
oidc idtoken validation example

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;
}());

In a Ping Identity Platform deployment, a Scripted Decision node runs this script to find the username from lookupAttributes and store it in the shared node state:

  • Next-generation

  • Legacy

var attributes = nodeState.get("lookupAttributes");
var userName = attributes.get("uid");

// Add userName in objectAttributes to nodeState for use by Identify Existing User node.
nodeState.putShared("objectAttributes", attributes);

// Add username at the root level so that a session can be created
nodeState.putShared("username", userName);

action.goTo('true');
var attributes = nodeState.get("lookupAttributes");
var userName = attributes.get("uid").asString();

// Add userName in objectAttributes to nodeState for use by Identify Existing User node.
nodeState.putShared("objectAttributes", attributes);

// Add username at the root level so that a session can be created
nodeState.putShared("username", userName);

outcome = "true";

The Identify Existing User node then performs a lookup on IDM with the _id attribute using the username saved into shared state by the Scripted Decision node.

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://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate?authIndexType=service&authIndexValue=myJourney"
{
    "tokenId": "AQIC5w…​NTcy*",
    "successUrl": "/openam/console",
    "realm": "/alpha"
}

In a standalone AM deployment, a Scripted Decision node runs this script to find the user ID from lookupAttributes and store it in the shared node state:

  • Next-generation

  • Legacy

var attributeName = "uid";
var attributes = nodeState.get("lookupAttributes");
var uid = attributes.get(attributeName);

// get the identity for the sub claim (stored as uid)
var identity = idRepository.getIdentity(uid);

// verify the identity exists
var userName = identity.getAttributeValues(attributeName);

if (!userName.isEmpty()) {
    nodeState.putShared("username", userName[0]);
    action.goTo('true');
} else {
    action.goTo('false');
}
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 tree, 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"
}