Identity Cloud

Scope validator plugin

Use this plugin to configure the OAuth2 provider to validate the set of requested scopes against the allowed scopes and, optionally, to modify the list of valid scopes.

The plugin comprises four functions that let you customize the validation of scopes at the following endpoints:

Function / Method Endpoint

validateAuthorizationScope

/authorize

validateAccessTokenScope

/authorize and /access_token

validateRefreshTokenScope

/refresh

validateBackChannelAuthorizationScope

/bc_authorize

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

Example scope validator plugin

Complete the following steps to implement a scope validator script that modifies the list of valid scopes.

Prepare the scope validator script

This task decribes how to create a script to add an extra scope 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 Validate Scope from the Script Type drop-down list, and click Create.

  3. Copy the oauth2-validate-scope.js script and paste in the Script field.

    • Update the script by inserting the following line of code preceding return scopes; on line 69:

       scopes.add("customscope");
  4. Save your changes.

The scope validator script is now amended to add customscope to the requested scopes.

Configure AM to use the custom scope validator script

Perform this task to set up the OAuth2 provider to use the scope validator script.

  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 Validator Plugin Type to SCRIPTED.

    2. Set Scope Validator 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 console, 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): access

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

  4. Click Create.

  5. Save your changes.

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

Try the custom scope validator plugin script

To try your custom script, 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 access, and your client details.

    For example:

    $ curl \
    --request POST \
    --data "grant_type=client_credentials" \
    --data "client_id=myClient" \
    --data "client_secret=forgerock" \
    --data "scope=access" \
    "https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/access_token"
    {
      "access_token": "M3M2Jb2SMjvgWhzNas2SVy2LALg",
      "scope": "access",
      "token_type": "Bearer",
      "expires_in": 3599
    }
  2. Call the /oauth2/tokeninfo (Legacy) endpoint to inspect the custom scope values. Include the access token value 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",
      "access": "",
      "grant_type": "client_credentials",
      "auditTrackingId": "f9a8395d-1bac-4cba-8b09-8cc336dc49e2-6810",
      "scope": ["access", "customscope"],
      "realm": "/alpha",
      "token_type": "Bearer",
      "expires_in": 3583,
      "authGrantId": "l3355H89FDSWsfdKJmvWssGk_oE",
      "customscope": "",
      "client_id": "myClient"
    }

    Verify that the response contains both the requested scope and the additional scope, customscope.

OAuth 2.0 scope validator scripting API

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

Show script properties
requestedScopes

The set of requested scopes.

defaultScopes

The set of default scopes.

allowedScopes

The set of allowed scopes.

Copyright © 2010-2022 ForgeRock, all rights reserved.