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
- 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
-
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 AM? 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.3.0.jar
in theopenam-samples/openam-scope-sample/target
directory of the project. -
Copy the built JAR file to the
/WEB-INF/lib
folder where you deployed AM. -
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.
-
Log in to the AM admin UI as an administrator.
For example,
amAdmin
. -
Configure the provider to 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.
-
-
Save your changes.
Create an OAuth2 client
Create an OAuth 2.0 client to use in the client credentials grant flow.
-
In the AM admin UI, go to Realms > Realm Name > Applications > OAuth 2.0 > Clients, and click Add Client.
-
Enter the following values:
-
Client ID:
myClient
-
Client secret:
forgerock
-
Redirection URIs:
https://www.example.com:443/callback
-
Scope(s):
read
write
-
-
Click Create.
-
In Advanced > Grant Types, add
Client Credentials
. -
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.
-
Send a POST request to the /oauth2/access_token endpoint, specifying the grant type as
client_credentials
, scope asread
, 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 }
-
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 thewrite
scope has not been authorized.
Scope evaluator plugin scripting API
The following properties are available to scope evaluator scripts.
Binding | Description |
---|---|
|
The OAuth 2.0 access token. For details, refer to AccessToken. |
|
An HTTP client for making external HTTP requests. |
|
Represents an identity that AM can access. For details, refer to AMIdentity. |
The logger instance for the script. Logger names use the format Refer to Debug logging. |
|
|
The display name of the script. |