This documentation is for WSO2 API Manager 1.10.0 View documentation for the latest release.
Page Comparison - Extending Scope Validation (v.27 vs v.33) - API Manager 1.10.0 - WSO2 Documentation

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Linked to definition on scope whitelisting

OAuth Scopes scopes, which were introduced from the WSO2 API Manager release version 1.7.0 onwards, allow you to have fine grained access control to API resources based on the user roles. It allows you to define scopes per API and associate defined scopes with API Resourcesresources. OAuth 2.0 bearer tokens will be are obtained for a set of requested scopes and the token obtained will is not be allowed to access any API Resources resources beyond the associated scopes. Refer For more information, see OAuth Scopes for more information.

API manager uses scopes as a way of defining permissions for a resource. If a resource is assigned a scope, then the token accessing the resource should be generated with that scope. By associating a scope with a role, we you can control which users are permitted to have tokens under certain scopes.  So in that sense In this instance, associating a role to a scope seems legitimate.

Validating the role of a requester would does not make much sense in some scenarios like where . For instance, when the scope is used as a way means of making generating an access token . Scope is not used as a means of securing  resource sometimes. and not for securing a resource (e.g. openId scope). In such situations to work correctly, scope validation can be extended to skip role validation for certain scopes.



role validation for



When scopes which cannot be associated to roles are requested, the the token should be issues issued without validating the scope. By providing a white-listed scopes through configuration, In WSO2 API Manager has provided this facility, you do this by whitelisting the scope through configuration. Patterns of the white-listed scopes can be provided whitelisted scopes are specified via a config configuration under the APIKeyValidator section element in the <APIM_HOME>/repository/conf/api-manager.xml file. When we specify the pattern of the scope in the white-list, scopes Scopes that match the pattern won’t be tested for roles. Simply, anyone requesting a white-listed scope will be given that.

Following example shows a demonstration.

Skipping role validation for certain scopes in API Manager 


are not validated by role and are available to anyone requesting it.

The following steps show a demonstration:

  1. Start the API Manager server and log into the API Store.
  2. Create an application and click on the generate button to generate keys. On the My Subscriptions tab for your application, click Generate Keys.
  3. Get the consumer key and consumer secret and create a command to call the token API.


    You can simply get this by clicking on cURL button on  My Subscription page.


    Image Removed


    click the cURL button and select the relevant grant type.

    Image Added

  4. Get the token by calling the token API.


    Make sure you include some a random scope in the request.

    Code Block
    curl -k -d "grant_type=password&username=admin&password=admin&scope=some_random_scope" -H "Authorization: Basic WmRFUFBvZmZwYVFnR25ScG5iZldtcUtSS3IwYTpSaG5ocEVJYUVCMEN3T1FReWpiZTJwaDBzc1Vh," -H "Content-Type: application/x-www-form-urlencoded"

    You will get following like Along with the token, you receive a response from the server with similar to the tokenone below.

    Code Block

    You may not see the scope you requested for in this response as it has not been whitelisted yet.

  5. Shut down the server.

  6. Add To whitelist the scope, add the following section inside under the <APIKeyValidator> element of  api-manager.xml located in the <APIM_HOME>/repository/conf directory and /api-manager.xml file and restart the server.

    Code Block
  7. Call the token API using the same request used in step 4. You will get the following like responsereceive a response similar to the one below.

    Code Block

    You can see a successful response along with the whitelisted scope for which you requested for in this response which is white-listed so that validated.