REST Scopes Defined
Rest Scopes are an additional layer of surface control over the REST API. They limit what actual endpoints an oauth client, user interface or API key are allowed to call.
Security and Scope
While it is a fact that scopes restrict access to certain APIs you should not consider it the same as security. A scope simply states that a caller can access a specific resource, not that the resource has permission to see or modify the content within that resource. All security permissions still apply as it relates to access to content regardless of scope. This means a user can have a token or key with a granted scope that allows access to the create forum thread endpoint, but the user themself does not have the appropriate permission to create new threads, resulting in a security failure.
It is also important to remember scopes apply to an endpoint itself, not the data it consumes or returns. Many REST APIs will contain information that crosses application boundaries, such as a thread containing information about a forum or information about its author. Even without granting user or forum related scopes, this information is still visible in the response for a thread.
Scopes in the Community
A scope identifier is divided into three parts, the scope group, the scope entity and the access modifier, separated by periods (.).
group.entity.accessmodifer
The group is generally the governing application, so in the case of forums, the group is just blogs. The entity is usually a child object inside the group, so for a scope group of forums you could have threads, replies, etc. Finally the access modifier is either readonly or modify. Entities that detect a registered endpoint with a method of HTTP GET fall under the readonly modifier. For endpoints using HTTP GET,PUT,POST or DELETE, they will fall under modify.
Here are a some examples:
- forums.threads.readonly - This scope belongs to the forums scope group, is acting on the threads entity, and allows for viewing(GET) requests only.
- blogs.posts.modify - This scope belongs to the blogs scope group, is acting on the posts entity, and allows for creating/editing and deleting of posts (PUT|POST|DELETE).
Endpoints Without Scope
Your community’s platform REST Apis all have scopes defined, with the exception of the batch endpoint which will be discussed later. You may however have written or installed third party REST endpoints that have not been updated to use scopes. These endpoints are shown at the bottom of the OAuth scope selection tab, site API Key configuration and individual API Key scope selection tab(assuming these were allowed at the site level). They are referred to as “Uncategorized Read Endpoints” and “Uncategorized Modify Endpoints” and show all the Urls for REST endpoints that are considered uncategorized. You can choose to allow these endpoints by selecting the corresponding checkbox for the appropriate uncategorized group. You can only allow ALL Read or ALL modify, or ALL of both, you cannot choose individual Urls. If you have uncategorized endpoints, it’s best to notify the endpoint vendor they need to update their endpoints.
BATCH Requests
The BATCH REST endpoint is the only endpoint that specifically has no scope. This is because by nature, it is a bunch of REST requests sent simultaneously. Its scope is governed by the requests it contains, meaning that the token or API key being utilized must have access to the scopes governing the individual requests in the batch.
OAuth Scopes
Scopes in OAuth work a few different ways, but it always starts at the client level. To define what scopes an OAuth client has access to you navigate to Administration, Integration, then OAuth Clients. You can only set scopes once the client has been created so create a client and save, or edit an existing client, then click on the Allowed Scopes tab. Check the scopes you wish to grant access to. You can select individual scopes, or the group itself to allow all scopes in that group. You can also hover over the check box for specific scope information.
There are a few important considerations when using scopes with OAuth:
- You must always allow at least one scope on an OAuth client.
- When requesting a token or access code, if no scopes are requested, it will utilize the client’s scopes.
- Authorization codes can request fewer scopes than the client, but never scopes not allowed by the client.
- Tokens can request fewer scopes than the client, but never scopes not allowed by the client. The same applies to tokens via the authorization code flow, the token can request less scopes than the authorization code has been granted, but not more.
When passing scopes during OAuth, you must include and format them in a specific way. For more information on scopes and requests, see <Making REST Requests>
API Key Scopes
Scopes at the API Key level work at two levels, individual API keys and a site wide setting.
Site Level API Key Scopes
You can modify what scopes will be available to API Keys when user’s generate them, assuming they have access to do so. This ONLY applies to API keys and not OAuth or the user interface. In Administration, Integration and API Key scopes, you will find all possible scopes. Select either the individual scope or group to allow that group or scope to be used by individual API Keys. You can also hover over a scope checkbox to get a description and the actual scope identifier.
Individual API Key Scopes
As a user who has permissions to do so, navigate to the user settings, scroll to the bottom and select Manage Api Keys to present the API Key management panel. You can only set scopes on an existing API key, so if you have none, create one, then edit it. Notice since we limited the site level API Key availability, we only have a limited set to choose from. You can also hover over the check box for specific scope information.
There is no change in how you call the REST API using an API Key. The requests will simply be accepted or rejected based on the site and API key level scope settings.
User Interface Scopes
There are many cases where you wish to make REST calls from a widget. By default widgets and any associated API calls made within them DO NOT have access to any REST endpoint until the widget has been granted the appropriate scope.
To grant scopes to a widget, first know what API calls you plan on making and what scope(s) they belong to. Then in Widget Studio, edit the widget and set the Accessible Rest Scopes field using the type ahead box provided. In this example we are granting access to read user profile information only. You can grant multiple scopes, however ensure you only allow what is necessary.
Legacy Scope Options for the User Interface
If you are upgrading to 12.1, the interface will continue to function as it did before in regards to REST scopes because "Enable all REST scopes for the user interface" is enabled in Administration -> Interface->Legacy Options. This setting is meant to allow you time to make any adjustments to custom widgets that need to have scopes defined. If you have no custom widgets, or have completed updating your widgets, this options should be turned off. For new installs, this legacy option is not on by default.