Scopes enable fine-grained access control to API resources based on user roles. You define scopes to an API's resources. When a user invokes the API, his/her OAuth 2 bearer token cannot grant access to any API resource beyond its associated scopes.
How scopes work
To illustrate the functionality of scopes, assume you have the following scopes attached to resources of an API:
<ams:fault xmlns:ams="http://wso2.org/apimanager/security"> <ams:code>900910</ams:code> <ams:message>The access token does not allow you to access the requested resource</ams:message> <ams:description>Access failure for API: /orgnews, version: 1.0.0 with key: eb51eff0b4d85cda1eb1d312c5b6a3b8 </ams:description> </ams:fault>
Applying a scope
You apply scopes to an API resource at the time the API is created or modified. In the API Publisher, click the API -> Add menu (to add a new API) or the Edit link next to an existing API. Then, navigate to the Manage tab and scroll down to see the Add Scopes button under Resources. A screen such as the following appears:
Tip: When you generate access tokens to APIs protected by scope/s, a Select Scopes button is displayed in the My Subscriptions page for you to select the scope/s first and then generate the token to it.
A scope is not always used for controlling access to a resource. You can also use it to simply mark an access token. Such scopes do not have to have roles associated with them. Skipping role validation for scopes is called scope whitelisting.
To whitelist a scope, add it under the
APIKeyValidation element and restart the server. For example,
Next, invoke the Token API to get a token for the scope that you whitelisted. For example,
curl -k -d "grant_type=password&username=admin&password=admin&scope=some_random_scope" -H "Authorization: Basic WmRFUFBvZmZwYVFnR25ScG5iZldtcUtSS3IwYTpSaG5ocEVJYUVCMEN3T1FReWpiZTJwaDBzc1Vh, Content-Type: application/x-www-form-urlencoded" https://10.100.0.3:8243/token
Note that the issued token has the scope you requested:
An API template is its XML representation, which is saved in
<APIM_HOME>/repository/resources/api_templates/velocity_template.xml file. This file comes with the API Manager by default. You can edit this default template to change the synapse configuration of all APIs that are created.