This documentation is for WSO2 API Manager 1.9.0. View documentation for the latest release.

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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.

You can 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. A screen such as the following appears:

Image Removed

Scope KeyA unique key for identifying the scope. Typically, it is prefixed by part of the API's name for uniqueness, but is not necessarily reader-friendly.
Scope NameA human-readable name for the scope. It typically says what the scope does.
Roles

The user role(s) that are allowed to obtain a token against this scope. E.g., manager, employee.

To illustrate the functionality of scopes, assume you have the following scopes attached to resources of an API: 

Image Removed

Assume that users named Tom and John are assigned the employee role and both the employee and manager roles respectively.

Tom requests a token through the Token API as To illustrate the functionality of scopes, assume you have the following scopes attached to resources of an API: 

Image Added

Assume that users named Tom and John are assigned the employee role and both the employee and manager roles respectively.

Tom requests a token through the Token API as grant_type=password&username=tom&password=xxxx&scope=news_read news_write. However, as Tom is not in the manager role, he will only be granted a token bearing the news_read scope. The response from the Token API will be similar to the following:

Code Block
"scope":"news_read","token_type":"bearer","expires_in":3299,
"refresh_token":"8579facb65d1d3eba74a395a2e78dd6",
"access_token":"eb51eff0b4d85cda1eb1d312c5b6a3b8"

Next, John requests a token as grant_type=password&username=tomjohn&password=xxxxjohn123&scope=news_read news_write. However, as Tom is not in the manager role, he will only be granted a token bearing the news_read scope. The response from the Token API As john has both roles assigned, the token will bear both the requested scopes and the response will be similar to the following:

Code Block
"scope":"news_read news_write", "token_type":"bearer", "expires_in":3299, "refresh_token":"8579facb65d1d3eba74a395a2e78dd64ca244fb321bd555bd3d555df39315",
"access_token":"eb51eff0b4d85cda1eb1d312c5b6a3b842a377a0101877d1d9e29c5f30857e"

Next, John requests a token as grant_type=password&username=john&password=john123&scope=news_read news_write. As john has both roles assigned, the token will bear both the requested scopes and the response will be similar to the following:

Code Block
"scope":"news_read news_write", "token_type":"bearer", "expires_in":3299, "refresh_token":"4ca244fb321bd555bd3d555df39315",
"access_token":"42a377a0101877d1d9e29c5f30857e"

This means that Tom can only access the GET operation of the API while John can access both as he is assigned to both the employee and manager roles. If Tom tries to access the POST operation, there will be an HTTP 403 Forbidden error as follows:

...

This means that Tom can only access the GET operation of the API while John can access both as he is assigned to both the employee and manager roles. If Tom tries to access the POST operation, there will be an HTTP 403 Forbidden error as follows:

Code Block
<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>

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:

Image Added

Scope KeyA unique key for identifying the scope. Typically, it is prefixed by part of the API's name for uniqueness, but is not necessarily reader-friendly.
Scope NameA human-readable name for the scope. It typically says what the scope does.
Roles

The user role(s) that are allowed to obtain a token against this scope. E.g., manager, employee.

Tip

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.


...