Identity Cloud

Scope evaluation

Use this extension point to change how AM evaluates and retrieves scopes for OAuth 2.0 access token introspection.

This page demonstrates the sample scope evaluation script. The script treats scopes as profile attributes for the resource owner. AM populates the scopes with profile attribute values in response to a token introspection request.

Prepare the demonstration

Start by preparing the demonstration:

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.

  1. In the AM admin UI, select Realms > alpha > Scripts > + New Script.

    Name

    Demo scope evaluation extension

    Script Type

    OAuth2 Evaluate Scope

  2. In the new script window, select Language: JavaScript and save the following script:

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

OAuth 2.0 client

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

  1. Create a confidential OAuth 2.0 client account.

    In the Identity Cloud admin UI, select Applications > + Add Application, and create a new Web client with the following settings:

    Client ID

    myClient

    Client Secret

    forgerock

  2. Add the following settings in the client profile and save your work:

    Sign-in URLs

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

    Scopes

    mail

  3. Override OAuth 2.0 provider settings for this client.

    In the AM admin UI, 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

Resource owner

An OAuth 2.0 client requests the access token on behalf of a resource owner.

  1. Create the OAuth 2.0 resource owner account.

    In the Identity Cloud admin UI, select Identities > Manage > Alpha Realm - Users > + New Alpha Realm - User and fill the required fields.

    Record the username and password.

  2. Update the following settings in the new user profile and save your work:

    Email Address

    user@example.com

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 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 introspects the access token.

Follow these steps:

  1. 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"}
  2. 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…​
    …​
  3. 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": "Q71RvkqBOJelmiS1pM0OEcsous4",
      "refresh_token": "tsf54TPeobg9yNu0Q6ouiNVkiUc",
      "scope": "mail",
      "token_type": "Bearer",
      "expires_in": 3599
    }
  4. Introspect the access token as the client acting as a resource server:

    curl \
    --request POST \
    --user 'myClient:forgerock' \
    --data 'token=Q71RvkqBOJelmiS1pM0OEcsous4' \
    'https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/introspect'
    {
      "active": true,
      "scope": "mail",
      "realm": "/alpha",
      "client_id": "myClient",
      "user_id": "1dff18dc-ac57-4388-8127-dff309f80002",
      "username": "1dff18dc-ac57-4388-8127-dff309f80002",
      "token_type": "Bearer",
      "exp": 1670244749,
      "sub": "1dff18dc-ac57-4388-8127-dff309f80002",
      "subname": "1dff18dc-ac57-4388-8127-dff309f80002",
      "iss": "https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha",
      "auth_level": 0,
      "authGrantId": "yklvnvUdC4HOsN-7BoxQBXYEOgI",
      "auditTrackingId": "b187bfdc-c0ff-4942-b4be-34a8c7134c40-1709794",
      "mail": ["user@example.com"]
    }

    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.

  1. In the AM admin UI, add the script to the target realm if you have not done so.

  2. 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

AM injects the following objects into the execution context of an OAuth 2.0 scope evaluation script:

Binding Information

accessToken

The OAuth 2.0 access token.

For details, refer to AccessToken.

httpClient

An HTTP client for making external HTTP requests.

identity

A platform identity AM can access.

For details, refer to AMIdentity.

logger

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

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

The logger identifier takes the form scripts.script-type.script-id.

For details, refer to Debug.

scriptName

The display name of the script.

Copyright © 2010-2023 ForgeRock, all rights reserved.