Expose journey session properties in the OIDC ID token

Description

Estimated time to complete: 20 minutes

In this use case, you create a PingOne Advanced Identity Cloud sign-on journey that collects end-user details and stores them as session properties on successful authentication. You then create an OIDC claims script that defines a custom claim. This script lets you retrieve a stored session property and include it in the ID token as a custom claim.

For testing purposes, the example uses a custom session property called mySessionProperty and an additional scope called myCustomScope, which adds the session property to the ID token.

Learn more about adding a session property claim to the profile scope in Add a session property claim to the profile scope.

Goals

After completing this use case, you will know how to do the following:

Make journey session properties available in the OIDC ID token.

Prerequisites

Before you start work on this use case, ensure you have these prerequisites:

A basic understanding of:
- Journeys and nodes
- OIDC
Access to your Advanced Identity Cloud development environment as a tenant administrator.
A test end user in the Alpha realm. Learn more about creating test users in Create test users and roles.

Tasks

Task 1: Create a sign-on journey

In this task, you create a journey that adds a custom property to the end user’s session on successful authentication.

Sign on to the Advanced Identity Cloud admin UI as a tenant administrator.
Select Journeys > + New Journey and set the following before clicking Save:

Field Value

Name

SetSessionProperties

Identity Object

managed/alpha_user
Drag the following nodes onto the journey editor canvas:
- Page node containing:
  - Platform Username node
  - Platform Password node
- Data Store Decision node
- Set Session Properties node
Connect the nodes, clicking Save from time to time to keep your work:
Click the Set Session Properties node and add a session property:
1. Click +, then Add + in the Properties modal.
2. Enter mySessionProperty in the Key field and customValue in the Value field.
3. Click Done.
4. Click Save.
Click Save to save the journey.

Field	Value
Name	`SetSessionProperties`
Identity Object	`managed/alpha_user`

Task 2: Allowlist the session property

In this task, you provide access to the mySessionProperty property to allow it to be output in the ID token.

Under Native Consoles > Access Management, select Realms > alpha > Services > Session Property Whitelist Service.
Add mySessionProperty to the Allowlisted Session Property Names field.
Save your changes.

Task 3: Create a custom claims script

In this task, you create a new OIDC claims script to map a session property claim.

In the Advanced Identity Cloud admin UI, go to Scripts > Auth Scripts > + New Script, and create a new OIDC Claims script.
Name the script Demo OIDC claims.

Edit the default JavaScript as follows:

In the utils.setScopeClaimsMap function call, add the mySessionProperty claim to a new scope named myCustomScope:

utils.setScopeClaimsMap({
       profile: [
            'name',
            'family_name',
            'given_name',
            'zoneinfo',
            'locale'
        ],
        email: ['email'],
        address: ['address'],
        phone: ['phone_number'],
        myCustomScope: ['mySessionProperty']

In the utils.setClaimResolvers function call, insert mySessionProperty after the phone_number claim:

utils.setClaimResolvers({
        ...
        phone_number: utils.getUserProfileClaimResolver('telephonenumber'),
        mySessionProperty: function () {
            return session.getProperty('mySessionProperty');
        }

    });

Save your changes.

The new claims script is now ready to retrieve a session property claim for myCustomScope.

Task 4: Configure the OAuth 2.0 provider to return claims in the ID token

In this task, you configure the OAuth 2.0 provider to always return scope-derived claims in the ID token.

This option is disabled by default because of the security concerns of returning claims that may contain sensitive user information. Learn more in Request claims in ID tokens.

Under Native Consoles > Access Management, select Realms > alpha > Services > OAuth2 Provider > Advanced OpenID Connect.
Enable Always Return Claims in ID Tokens.
Save your changes.

Task 5: Create an OIDC relying party profile

In this task, you create an OIDC relying party (client) profile that overrides the OAuth 2.0 provider settings. The override lets you test the script you created in Task 3 without affecting ID and access tokens issued to other applications.

Learn more in Register a client application.

Create a confidential OAuth 2.0 client

In the Advanced Identity Cloud admin UI, go to Applications and click + Custom Application.
Select the sign-in method as OIDC - OpenId Connect and application type as Web.
Create the application, providing the following details:

Name

myClient

Owners

<resource-owner>

Client ID

myClient

Client Secret

mySecret
Switch to the Sign On tab and under General Settings, make the following changes:

Sign-in URLs

https://www.example.com:443/callback

Grant Types

Implicit

Scopes

openid myCustomScope
Click Show advanced settings, select the Access tab and make the following changes:

Response Types

token id_token
Select the Authentication tab and make the following changes:

Token Endpoint Authentication Method

None
Save your changes.

Override OAuth 2.0 provider settings for this client

Under Native Consoles > Access Management, select Realms > alpha > Applications > OAuth 2.0 > Clients > myClient, switch to the OAuth2 Provider Overrides tab and update the following settings:

Enable OAuth2 Provider Overrides

Enabled

OIDC Claims Plugin Type

SCRIPTED

OIDC Claims Script

Demo OIDC claims
Save your changes.

Check in

At this point, you:

Created a sign-on journey that captures a custom session property on successful authentication.

Allowlisted the custom session property.

Created an OIDC claims script to map the session property claim.

Configured the OAuth 2.0 provider to always return scope-derived claims in the ID token.

Created an OIDC relying party to override the default OAuth 2.0 provider settings.

Validation

You are now ready to validate the use case by authenticating to the Set session properties journey as a test end user, and then calling the /oauth2/idtokeninfo endpoint to inspect the session property claim values.

Steps

In an Incognito window, enter the following URL:

https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/authorize?client_id=myClient&response_type=id_token&scope=openid%20myCustomScope&redirect_uri=https://www.example.com:443/callback&service=SetSessionProperties&nonce=abc123&state=123abc (1)(2)(3)(4)

1	Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
2	`myClient` is the name of the client you created in Task 5.
3	`openid` and `myCustomScope` are the scopes configured in your client.
4	`SetSessionProperties` is the name of the journey you created in Task 1.

On the Sign in page, enter the username and password for your test end user and click Next.
Allow access to your account when prompted for consent.
After successful authentication, copy the value of the id_token in the URL. You’ll need this value in the next step.

Call the /oauth2/idtokeninfo endpoint to inspect the session property claim values, including the ID token obtained from the previous request:

$ curl \
--request POST \
--user myClient:mySecret \
--data 'id_token=<id-token>' \(1)
"https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/idtokeninfo" (2)

1	Replace <id_token> with the id_token copied in step 4.
2	Replace <tenant-env-fqdn> with the FQDN of your tenant environment.

Example output:

{
  "sub": "6bc9650a-05fa-400c-8529-98d4a701381d",
  "auditTrackingId": "7734d5b8-5ac5-4c21-a211-0a4dfc299dfd-624957",
  "subname": "6bc9650a-05fa-400c-8529-98d4a701381d",
  "iss": "https://<tenant-env-fqdn>:443/am/oauth2/realms/root/realms/alpha",
  "tokenName": "id_token",
  "nonce": "abc123",
  "sid": "5WoPI3klaBoa3K1MvjYpcKbe9/4Tm58dKX+gE501ZRw=",
  "aud": "myClient",
  "acr": "username-password",
  "org.forgerock.openidconnect.ops": "H-oyuSQJJCY46ObWRGM5ULmwF8I",
  "s_hash": "3RMKhJ17KeVUGwXS9_hqSg",
  "azp": "myClient",
  "auth_time": 1734864493,
  "mySessionProperty": "customValue", (1)
  "realm": "/alpha",
  "exp": 1734868156,
  "tokenType": "JWTToken",
  "iat": 1734864556
}

1	`mySessionProperty` is the custom session property you defined in the journey.

If you use PingGateway to consume the resulting ID token, the session property might be null. This can happen when the ID token is issued successfully with the custom claim containing your session property. Subsequently, PingGateway makes a call to /userinfo, which causes the OIDC claims script to be invoked again, but this time there is no session, which leads to a null session property.

If you experience this issue, modify the OIDC claims script to ensure it only adds claims when a session exists.

Explore further

Reference material

Reference	Description
Journeys	Conceptual information on journeys and their purpose in Advanced Identity Cloud.
Nodes for journeys	Learn about the configurable nodes Advanced Identity Cloud offers for use in journeys.
Claims	Learn about OIDC claims and ID tokens in Advanced Identity Cloud.
OpenID Connect 1.0 (OIDC) claims	Learn about modifying and overriding claims in an ID token in Advanced Identity Cloud.

Reference

Description

Journeys

Conceptual information on journeys and their purpose in Advanced Identity Cloud.

Nodes for journeys

Learn about the configurable nodes Advanced Identity Cloud offers for use in journeys.

Claims

Learn about OIDC claims and ID tokens in Advanced Identity Cloud.

OpenID Connect 1.0 (OIDC) claims

Learn about modifying and overriding claims in an ID token in Advanced Identity Cloud.

Nodes used

The following nodes are listed in the order they appear in the journey.

Page node containing:
- Platform Username node
- Platform Password node
Data Store Decision node
Set Session Properties node