PingAM 7.5.0

Scope evaluation

This extension point retrieves and evaluates the scope information for an OAuth2 access token.

The default scopes implementation in AM treats scopes as profile attributes for the resource owner. When a resource server or other entity uses the access token to get token information from AM, AM populates the scopes with profile attribute values. For example, if one of the scopes is mail, AM sets mail to the resource owner’s email address in the token information returned.

The plugin lets you extend or modify this behavior by writing your own scope evaluator plugin to populate the scopes with custom values.

Default script

To view the default script, including the available script properties, refer to oauth2-evaluate-scope.js

To view or modify the default script in the AM admin UI, go to Realms > Realm Name > Scripts and select OAuth2 Evaluate Scope Script.

Java interface

org.forgerock.oauth2.core.plugins.ScopeEvaluator

Java sample
Show Sample Code
/*
 * Copyright 2021-2022 ForgeRock AS. All Rights Reserved
 *
 * Use of this code requires a commercial software license with ForgeRock AS.
 * or with one of its affiliates. All use shall be exclusively subject
 * to such license between the licensee and ForgeRock AS.
 */

package org.forgerock.openam.examples;

import java.util.HashMap;
import java.util.Map;
import java.util.Set;

import org.forgerock.oauth2.core.AccessToken;
import org.forgerock.oauth2.core.plugins.ScopeEvaluator;

/**
 * Custom implementation of the Scope Evaluator
 * plugin interface {@link org.forgerock.oauth2.core.plugins.ScopeEvaluator}
 *
 * <li>
 * The {@code evaluateScope} method populates scope values to return.
 * </li>
 *
 */
public class CustomScopeEvaluator implements ScopeEvaluator {

    @Override
    public Map<String, Object> evaluateScope(AccessToken token) {
        return mapScopes(token);
    }

    /**
     * Set read and write permissions according to scope.
     *
     * @param token The access token presented for validation.
     * @return The map of read and write permissions,
     *         with permissions set to {@code true} or {@code false},
     *         as appropriate.
     */
    private Map<String, Object> mapScopes(AccessToken token) {
        Set<String> scopes = token.getScope();
        Map<String, Object> map = new HashMap<String, Object>();
        final String[] permissions = {"read", "write"};

        for (String scope : permissions) {
            if (scopes.contains(scope)) {
                map.put(scope, true);
            } else {
                map.put(scope, false);
            }
        }
        return map;
    }
}

Example scope evaluator plugin

This example uses the Java sample provided by AM. Complete the following steps to implement a custom scope evaluator Java plugin that sets read and write values in the access token according to the scope information.

To configure AM to use a scripted scope evaluator plugin, refer to the steps in Configure AM to use a scripted OAuth 2.0 plugin.

Create and deploy the sample scope evaluator Java plugin

  1. Clone the sample code and build a JAR file by following the steps described in How do I access and build the sample code provided for PingAM? in the Knowledge Base.

    Files Included in the Sample
    pom.xml

    Apache Maven project file for the module.

    This file specifies how to build the sample, and specifies its dependencies on AM components.

    src/main/java/org/forgerock/openam/examples/CustomScopeEvaluator.java

    Sample class for the Scope Evaluator OAuth 2.0 plugin.

    After you successfully build the project, you find the openam-scope-sample-7.5.0.jar in the openam-samples/openam-scope-sample/target directory of the project.

  2. Copy the built JAR file to the /WEB-INF/lib folder where you deployed AM.

  3. Restart AM or the container in which it runs.

Configure AM to use the custom scope evaluator plugin

Perform this task to set up an OAuth 2.0 provider that uses the sample scope evaluator Java implementation.

  1. Log in to the AM admin UI as an administrator.

    For example, amAdmin.

  2. Configure the provider and ensure the following properties are set:

    • Scope Evaluation Plugin Type to JAVA.

    • Scope Evaluation Plugin Implementation Class to org.forgerock.openam.examples.CustomScopeEvaluator.

    By default, a new OAuth 2.0 provider uses the default Java implementation.

  3. Save your changes.

Create an OAuth2 client

Create an OAuth 2.0 client to use in the client credentials grant flow.

  1. In the AM admin UI, go to Realms > Realm Name > Applications > OAuth 2.0 > Clients, and click Add Client.

  2. Enter the following values:

    • Client ID: myClient

    • Client secret: forgerock

    • Redirection URIs: https://www.example.com:443/callback

    • Scope(s): read write

  3. Click Create.

  4. In Advanced > Grant Types, add Client Credentials.

  5. Save your changes.

AM is now configured for you to try the sample scope evaluator script.

Try the custom scope evaluator Java plugin

To try the custom scope evaluator plugin, use the Client credentials grant flow.

  1. Send a POST request to the /oauth2/access_token endpoint, specifying the grant type as client_credentials, scope as read, and your client details.

    For example:

    $ curl \
    --request POST \
    --data "grant_type=client_credentials" \
    --data "client_id=myClient" \
    --data "client_secret=forgerock" \
    --data "scope=read" \
    "https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/access_token"
    {
      "access_token": "M3M2Jb2SMjvgWhzNas2SVy2LALg",
      "scope": "read",
      "token_type": "Bearer",
      "expires_in": 3599
    }
  2. Call the oauth2/tokeninfo endpoint to inspect the custom scope values. Include the access token obtained in the previous request.

    For example:

    $ curl \
    "https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/tokeninfo\
    ?access_token=M3M2Jb2SMjvgWhzNas2SVy2LALg"
    {
      "access_token": "M3M2Jb2SMjvgWhzNas2SVy2LALg",
      "read": true,
      "grant_type": "client_credentials",
      "auditTrackingId": "f9a8395d-1bac-4cba-8b09-8cc336dc49e2-6810",
      "scope": ["read"],
      "realm": "/alpha",
      "token_type": "Bearer",
      "expires_in": 3583,
      "authGrantId": "l3355H89FDSWsfdKJmvWssGk_oE",
      "write": false,
      "client_id": "myClient"
    }

    As this example indicates, the requested scope read is authorized, but the write scope has not been authorized.

Scope evaluator plugin scripting API

The following properties are available to scope evaluator scripts.

Binding Description

accessToken

The OAuth 2.0 access token. For details, refer to AccessToken.

httpClient

An HTTP client for making external HTTP requests.

identity

Represents an identity that AM can access. For details, refer to AMIdentity.

The logger instance for the script.

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

Refer to Debug logging.

scriptName

The display name of the script.