Identity Cloud

Scope evaluation plugin

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 evaluation plugin to populate the scopes with custom values.

To view a sample script, including the available script properties, see oauth2-evaluate-scope.js

Example scope evaluation plugin

Complete the following steps to implement a custom scope evaluation plugin.

Prepare the sample scope evaluation script

This task decribes how to create a script to map a custom value.

  1. In the AM admin UI, go to Realms > Realm Name > Scripts, and click New Script.

  2. Enter a unique name for your script, select OAuth2 Evaluate Scope from the Script Type drop-down list, and click Create.

  3. If necessary, copy the oauth2-evaluate-scope.js script and paste in the Script field.

  4. Update the script by inserting a custom key/value pair preceding return map; on line 50:

    map.put("hello", "world");
  5. Save your changes.

Configure AM to use the custom scope evaluation plugin

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

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

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

    • Scope Evaluation Plugin Type to SCRIPTED.

    • Scope Evaluation Script to the name of the script you created.

  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 evaluation script.

Try the custom scope evaluation plugin

To try the custom scope evaluation 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 (Legacy) 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",
      "grant_type": "client_credentials",
      "auditTrackingId": "f9a8395d-1bac-4cba-8b09-8cc336dc49e2-6810",
      "scope": ["read"],
      "realm": "/alpha",
      "token_type": "Bearer",
      "expires_in": 3583,
      "authGrantId": "l3355H89FDSWsfdKJmvWssGk_oE",
      "hello": "world",
      "client_id": "myClient"
    }

    Verify that the response includes the custom key/value pair, "hello": "world".

OAuth 2.0 scope evaluation plugin scripting API

The following properties are available to scope evaluation scripts, in addition to the common OAuth 2.0 properties.

Show script properties
accessToken

The access token to be updated.

identity

Contains a representation of the identity of the resource owner.

For more details, see the com.sun.identity.idm.AMIdentity class in the AM Javadoc.

Copyright © 2010-2022 ForgeRock, all rights reserved.