--- schema_version: "1" id: afc20e3f2f271f7912eaae83ac192f00c598bc955d2d39bf05f530017d01b77c title: OAuth Custom Scopes collection: admin version: current locale: en-us portal_url: https://docs.salesforce.com/admin/current/en-us/xcloud/264-0-0/remoteaccess_oauth_customscopes.md canonical_url: https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_customscopes.htm&release=264.0.0&type=5 source_site: help.salesforce.com content_type: documentation content_hash: 3051a24136b8365142261acbe33925e684f469b99ed3aa5551c34ffb661145fe description: 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. products: - Security - Cross Cloud release: "264" --- # 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](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_jwt_flow.htm&release=264.0.0&type=5 "Sometimes you want to authorize servers to access data without interactively logging in each time the servers exchange information. For these cases, you can use the OAuth 2.0 JSON Web Token (JWT) bearer flow. This flow uses a certificate to sign the JWT request and doesn’t require explicit user interaction. However, this flow does require prior approval of the client app."). ![Note](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-xcloud-identity-264-0-0-production-enus/699dab6f-8f1a-4662-b24f-6521d5b747f7/images/icon_note.png) 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](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-xcloud-identity-264-0-0-production-enus/699dab6f-8f1a-4662-b24f-6521d5b747f7/images/icon_example.png) 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](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_customscopes_create.htm&release=264.0.0&type=5)** 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](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_customscopes_assign.htm&release=264.0.0&type=5)** 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](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_customscopes_edit.htm&release=264.0.0&type=5)** 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 - [Connected App Use Cases](https://help.salesforce.com/s/articleView?id=xcloud.connected_app_about.htm&release=264.0.0&type=5 "There are four main use cases for which your org can implement connected apps. You can use a connected app to integrate external applications with the Salesforce API, such as a web-based app that pulls in order status data from your Salesforce org. You can also use connected apps to integrate service providers with your Salesforce org, and to set security policies to control what data a third-party app can access from your org. And you can configure a connected app to provide authorization for external API gateways, such as API gateways hosted on MuleSoft’s Anypoint Platform.") - [Create a Connected App](https://help.salesforce.com/s/articleView?id=xcloud.connected_app_create.htm&release=264.0.0&type=5 "When you create a connected app, make sure that you understand how it’s going to be used so you can configure the appropriate settings. For example, if you’re creating a connected app to integrate an external application with your Salesforce API, configure the connected app with OAuth authorization settings. Or if you’re creating a connected app to act as a service provider in a SAML single sign-on (SSO) flow, configure SAML settings.") - [Manage Access to a Connected App](https://help.salesforce.com/s/articleView?id=xcloud.connected_app_manage.htm&release=264.0.0&type=5 "After a connected app is installed in your org, you can manage access to it. Configure permissions and policies for the app, explicitly defining who can use the connected app and where they can access the app from. These permissions and policies, which include user-access, IP range restrictions, and multi-factor authentication (MFA), provide extra security for your org.") - [Edit a Connected App](https://help.salesforce.com/s/articleView?id=xcloud.connected_app_edit_parent.htm&release=264.0.0&type=5 "After you create a connected app, you can make changes to it’s configuration. The actions that you can perform depend on the type of connected app. Use the App Manager to get a list of apps available in your org, including connected apps. From here, you can edit, reconfigure, or delete the connected app.") - [_Metadata API Developer Guide:_ OauthCustomScope](https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_objects_oauthcustomscope.htm) - [_SOAP API Developer Guide:_ OauthCustomScope](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_oauthcustomscope.htm)