Identity Cloud

Scope evaluator 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 evaluator 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 evaluator plugin

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

Prepare the sample scope evaluator 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. 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 evaluator plugin

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

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

  2. Configure the OAuth2 Provider:

    • If no provider exists for the current realm, create a new OAuth 2.0 provider:

      1. Go to Realms > Realm Name > Services and click Add a Service.

      2. Select OAuth2 Provider service from the drop-down list, leave the fields unchanged, and click Create.

    • Otherwise, go to Realms > Realm Name > Services > OAuth2 Provider.

      The OAuth2 provider configuration is displayed.

      For information on OAuth 2.0 provider properties, see OAuth2 Provider.

  3. Select the Plugins tab to edit the following settings:

    1. Set Scope Evaluation Plugin Type to SCRIPTED.

    2. Set Scope Evaluation Script to the name of the script you created.

  4. 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 (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 evaluator plugin scripting API

The following properties are available to scope evaluator 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.

Copyright © 2010-2022 ForgeRock, all rights reserved.