Salesforce Docs Portal

OAuth Custom Scopes

An external client app can use the OAuth authorization protocol to access protected resources. As part of the protocol, OAuth default scopes fine-tune the app’s permissions to access protected resources in Salesforce. However, these default scopes are insufficient when an external entity hosts the protected resource. In this scenario, Salesforce plays the role of OAuth authentication and authorization provider, but it has little knowledge about the resource it’s protecting. To define an external client app’s permissions to access protected resources hosted by an external entity, create an OAuth custom scope. The custom scope tells the external entity which information the external client app is authorized to access.

Required Editions

Available in: both Salesforce Classic and Lightning Experience

External client apps can be created in: Group, Essentials, Professional, Enterprise, Performance, Unlimited, and Developer Editions

External client apps can be installed in: All editions

Typically, to receive custom scopes that are assigned to an external client app, you must include the scope parameter in the authorization request. With the OAuth 2.0 JWT bearer flow, for external client apps that are pre-authorized, custom scopes are automatically returned with an access token. For more information, see OAuth 2.0 JWT Bearer Flow for Server-to-Server Integration.

Note
Note OAuth custom scopes aren’t included when you refresh a sandbox. After refreshing a sandbox, reassign custom scopes to your external client app.
Example
Example You want to build a Customer Order Status web app that pulls the status of customer orders from your order system’s API. The order system API can reveal all sorts of information about the customer, such as billing, but the custom app only needs access to order status information. To protect the other data in the order system API, your Salesforce org’s admin and the API provider admin take the following steps.

Salesforce Org Admin Steps

  1. Create an order_status OAuth custom scope, and describe the protected data that the scope allows access to (customer order status).
  2. Assign the order_status OAuth custom scope to the external client app associated with the Customer Order Status web app.

API Provider Admin Step

  1. In the API Management solution, apply a policy that requires an order_status scope to access a customer’s order status in the order system’s API.

Custom Scope Flow

After configuring the OAuth custom scope in the API Management solution and your Salesforce org, the Customer Order Status web app can successfully access a customer’s order status. Here’s how it plays out.

  1. The Customer Order Status web app posts a request to the order system API endpoint. The request includes the client ID, client secret, and scope parameter.
  2. The API gateway, which fronts the order system API, intercepts the call and queries Salesforce for the access token based on the OAuth grant type associated with the call.
  3. Salesforce validates that the web app’s client ID and client secret are valid and sends the access token to the API gateway endpoint. The order_status OAuth custom scope is included with the access token.
  4. The API gateway receives the access token and verifies the following.
    • The access token is valid.
    • The access token has the order_status OAuth custom scope associated with it.
  5. On successful validation, the API gateway lets the Customer Order Status web app access the customer’s order status information.
  • Create an OAuth Custom Scope
    To define permissions about the data that an external client app can access from an external entity, create an OAuth custom scope in Salesforce. The custom scope tells the external entity which information the external client app is authorized to access.
  • Assign an OAuth Custom Scope to a Connected App
    After you create an OAuth custom scope in your Salesforce org, you can assign it to an external client app to set data-access permissions for the app. For example, an external client app with an order_status custom scope has the correct permission set to access order status data from the external entity.
  • Edit an OAuth Custom Scope
    You can change the name and description of a custom scope, and update your selection to include the custom scope in the OpenID Connect discovery endpoint.

See Also