Scope evaluation

Use this extension point to change how Advanced Identity Cloud evaluates and retrieves scopes for an OAuth 2.0 access token.

This page demonstrates the sample scope evaluation script. The script treats scopes as profile attributes for the resource owner. Advanced Identity Cloud populates the scopes with profile attribute values when token information is returned using the /oauth2/idtokeninfo endpoint.

Prepare the demonstration

Start by preparing the demonstration:

Create a sample script.
Create a resource owner account.
Create an OAuth 2.0 client.

Sample script

The sample script populates scopes with attributes from the resource owner’s user profile. It uses methods of the accessToken, identity, and logger bindings.

In the Advanced Identity Cloud admin UI, select Scripts > Auth Scripts > + New Script, and create a new OAuth2 Evaluate Scope script.
Name the script Demo scope evaluation extension.

Edit the default JavaScript as follows:

(function () {
    var map = new java.util.HashMap();
    if (identity) {
        var scopes = accessToken.getScope().toArray();
        scopes.forEach(function (scope) {
            var attributes = identity.getAttribute(scope).toArray();
            map.put(scope, attributes.join(","));
        });
    } else {
        logger.error('identity is null');
    }
    return map;
}());

Save your changes.

Resource owner

Create a resource owner profile and record the username and password.

In this example, the resource owner also plays the role of application owner for the OAuth 2.0 client.
Update the following setting in the new user profile and save your work:

Email Address

user@example.com

OAuth 2.0 client

The OAuth 2.0 client profile in this example overrides the Advanced Identity Cloud OAuth 2.0 provider settings. This lets you test the script without affecting access tokens issued to other clients.

Register a client application.
1. In the Advanced Identity Cloud admin UI, go to Applications and select + Custom Application.
2. Select the sign-in method as OIDC - OpenId Connect and application type as Web.
3. Create the application, providing the following details:
  
  Name
  
  myClient
  
  Owners
  
  <resource-owner>
  
  Client ID
  
  myClient
  
  Client Secret
  
  forgerock
Add the following settings in the client profile under Sign On > General Settings and save your work:

Sign-in URLs

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

Scopes

mail
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, update the following settings and save your work:

Enable OAuth2 Provider Overrides

Enabled

Scope Evaluation Plugin Type

SCRIPTED

Scope Evaluation Script

Demo scope evaluation extension

Test the demonstration

After preparing the demonstration, test your work using HTTP calls to REST endpoints.

The demonstration uses the Authorization code grant flow:

The resource owner authenticates to obtain an SSO token.
The client relies on Implied Consent being enabled (default) in the Advanced Identity Cloud admin UI under Applications > Client ID > Advanced settings > Authentication. It assumes the resource owner grants the client access.
The client requests the authorization code and exchanges it for an access token your script modified.
The client uses the legacy /oauth2/tokeninfo endpoint to inspect the access token.

Follow these steps:

Authenticate as the resource owner:

curl \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-OpenAM-Username: <resource-owner-username>' \
--header 'X-OpenAM-Password: <resource-owner-password>' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
{"tokenId":"<resource-owner-tokenId>","successUrl":"/enduser/?realm=/alpha","realm":"/alpha"}

Request the authorization code as the client:

curl \
--dump-header - \
--request POST \
--cookie '<session-cookie-name>=<resource-owner-tokenId>' \
--data 'scope=mail' \
--data 'response_type=code' \
--data 'client_id=myClient' \
--data 'csrf=<resource-owner-tokenId>' \
--data 'redirect_uri=https://www.example.com:443/callback' \
--data 'state=abc123' \
--data 'decision=allow' \
'https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/authorize'
...
location: https://www.example.com:443/callback?code=<authorization-code>&iss=https%3A%2F%2F...
...

Exchange the authorization code for an access token as the client:

curl \
--request POST \
--user 'myClient:forgerock' \
--data 'grant_type=authorization_code' \
--data 'code=<authorization-code>' \
--data 'redirect_uri=https://www.example.com:443/callback' \
'https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/access_token'
{
  "access_token": "<access-token>",
  "refresh_token": "<refresh-token>",
  "scope": "mail",
  "token_type": "Bearer",
  "expires_in": 3599
}

Get information about the access token as the client acting as a resource server:

curl \
--request GET \
--header 'Authorization: Bearer <access-token>' \
'https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/tokeninfo'
{
  "access_token": "<access-token>",
  "mail": "user@example.com",
  "grant_type": "authorization_code",
  "auth_level": 0,
  "auditTrackingId": "<audit-tracking-id>",
  "scope": ["mail"],
  "realm": "/alpha",
  "token_type": "Bearer",
  "expires_in": 3497,
  "authGrantId": "<auth-grant-id>",
  "client_id": "myClient"
}

The script added "mail": "user@example.com".

Use a validated script

Test your scope evaluation scripts as you did for the demonstration. After validating your script with OAuth 2.0 provider overrides in your test client, you can update the OAuth 2.0 provider configuration to use the script.

Under Native Consoles > Access Management, add the script to the target realm if you haven’t done so.
Select Realms > Realm Name > Services > OAuth2 Provider, switch to the Plugins tab, and edit these settings before saving your work:
- Scope Evaluation Plugin Type
- Scope Evaluation Script

Available objects

Advanced Identity Cloud injects the following objects into the execution context of an OAuth 2.0 scope evaluation script:

Binding Information

Binding	Information
`accessToken`	The OAuth 2.0 access token. Learn more in AccessToken.
`httpClient`	An HTTP client for making external HTTP requests.
`identity`	An identity Advanced Identity Cloud can access. Learn more in AMIdentity.
`logger`	Write a message to the debug log. Always present in all extension scripts. In Advanced Identity Cloud, this corresponds to the `am-core` log source. Logger names use the format `scripts.OAUTH2_EVALUATE_SCOPE.<script UUID>.(<script name>)`. You can find details about debug logs in Get audit and debug logs.
`scriptName`	The display name of the script.

accessToken

The OAuth 2.0 access token.

Learn more in AccessToken.

httpClient

An HTTP client for making external HTTP requests.

identity

An identity Advanced Identity Cloud can access.

Learn more in AMIdentity.

logger

Write a message to the debug log. Always present in all extension scripts.

In Advanced Identity Cloud, this corresponds to the am-core log source.

Logger names use the format scripts.OAUTH2_EVALUATE_SCOPE.<script UUID>.(<script name>).

You can find details about debug logs in Get audit and debug logs.

scriptName

The display name of the script.

PingOne Advanced Identity Cloud