Use the Scope URL Parameter
When you set up single sign-on (SSO) with an authentication provider, use the scope parameter to customize data requests to a third party, like Facebook. For example, request access to the email address listed on a user’s Facebook profile. You can use this parameter with every authentication provider except Janrain.
| Required Editions |
|---|
| Available in: Lightning Experience and Salesforce Classic |
| Available in: Enterprise, Performance, Unlimited, and Developer Editions |
| User Permissions Needed | |
|---|---|
| To view the settings: | View Setup and Configuration |
| To edit the settings: | Customize Application AND Manage Auth. Providers |
In an authentication provider SSO flow, scopes define the type of data the relying party can request. After the user logs in, the relying party sends an authorization request. The third party validates the user and sends back the access token with scopes. If the user authorizes access to the data defined by the scopes, the relying party can access the requested third-party data.
For example, you set up a Google authentication provider to configure SSO with your Salesforce org as the relying party. You want to give users the ability to view their Google Drive in your Salesforce org. So you add the scope parameter to your SSO client configuration URL and implement an Auth.AuthToken method to retrieve the access token with the scopes you requested. A user logs in to your org, is redirected to authenticate with Google, and then approves Salesforce to access their Google Drive. Salesforce then displays the user’s Google Drive in Salesforce.
Some third parties require you to pre-register scopes before you can request them.
In addition to any scopes you specify, authentication providers provide default scopes. The default scopes vary depending on the third party, but they usually limit access to basic user information. For example, the Salesforce default scope is id, which gives you the user’s identity. To override default scopes, send scopes in a space-delimited string to the third party.
-
Add the scope parameter to a client configuration URL.
-
Use Apex
Auth.AuthTokenmethods to retrieve the access token. See AuthToken Class in the Apex Reference Guide for more information.
Here’s an example of a scope parameter requesting the Salesforce scopes api and webadded to the Single Sign-On Initialization URL. Salesforceapi scope allows the relying party to access Connect REST API resources, while the web scope allows the relying party to use the access token on the web.https://login.salesforce.com/services/auth/sso/{orgID}/{URLsuffix}?scope=id+api+web
- orgID is your Auth. Provider ID.
- URLsuffix is the value you specified when you defined the authentication provider.
Valid scopes vary depending on the third party, so refer to your third-party documentation.
| Value | Description |
|---|---|
Perform ANSI SQL queries on Customer Data Platform data (cdp_query_api) | Allows ANSI SQL queries of Data Cloud data on behalf of the user. |
Manage Pardot services (pardot_api) | Allows access to Marketing Cloud Account Engagement API services on behalf of the user. Manage the full extent of accessible services in Account Engagement. (Pardot is now Marketing Cloud Account Engagement.) |
Manage Customer Data Platform profile data (cdp_profile_api) | Allows access to Data Cloud REST API data. Use this scope to manage profile records. |
Access Connect REST API resources (chatter_api) | Allows access to Connect REST API resources on behalf of the user. |
Manage Customer Data Platform Ingestion API data (cdp_ingest_api) | Allows access to Data Cloud Ingestion API data. Use this scope to upload and maintain external datasets in Data Cloud. This scope is packaged in a JSON web token (JWT). |
Access Analytics REST API Charts Geodata resources (eclair_api) | Allows access to the Analytics REST API Charts Geodata resource. |
Access Analytics REST API resources (wave_api) | Allows access to the Analytics REST API resources. |
Manage user data via APIs (api) | Allows access to the current, logged-in user’s account using APIs, such as REST API and Bulk API 2.0. This scope also includes chatter_api, which allows access to Connect REST API resources. |
Access custom permissions (custom_permissions) | Allows access to the custom permissions in an org associated with the connected app. This scope also shows whether the current user has each permission enabled. |
Access the identity URL service (id, profile, email, address, phone) | Allows access to the identity URL service. You can request profile, email, address, or phone individually to get the same result as using id because they’re synonymous. |
Access Lightning applications (lightning) | Allows hybrid apps to directly obtain Lightning child sessions through the OAuth 2.0 hybrid app token flow and hybrid app refresh token flow. |
Access content resources (content) | Allows hybrid apps to directly obtain content child sessions through the OAuth 2.0 hybrid app token flow and hybrid app refresh token flow. |
Access unique user identifiers (openid) | Allows access to the current, logged in user’s unique identifier for OpenID Connect apps. In the OAuth 2.0 user-agent flow and the OAuth 2.0 web server flow, use the openid scope. In addition to the access token, this scope enables you to receive a signed ID token that conforms to the OpenID Connect specifications. |
Full access (full) | Allows access to all data accessible by the logged-in user, and encompasses all other scopes.full doesn’t return a refresh token. You must explicitly request the refresh_token scope to get a refresh token. |
Perform requests at any time (refresh_token, offline_access) | Allows a refresh token to be returned when the requesting client is eligible to receive one. With a refresh token, the app can interact with the user’s data while the user is offline. This token is synonymous with requesting offline_access. |
Access Visualforce applications (visualforce) | Allows access to customer-created Visualforce pages only. This scope doesn’t allow access to standard Salesforce UIs. To allow hybrid apps to directly obtain Visualforce child sessions, include this scope with the OAuth 2.0 hybrid app token flow or hybrid app refresh token flow. |
Manage user data via Web browsers (web) | Allows use of the access_token on the web. This scope also includes visualforce, allowing access to customer-created Visualforce pages. |
Access chatbot services (chatbot_api) | Allows access to Einstein Bot API services. |
| Access Headless Registration API (user_registration_api) | Allows access to the API for the Headless Registration Flow. If you set up your flow to require authentication, you must pass in an access token that includes this scope. |
Access Headless Forgot Password API (forgot_password) | Allows access to the API for the Headless Forgot Password Flow. If you set up your flow to require authentication, you must pass in an access token that includes this scope. |
Access all Data Cloud API resources (cdp_api) | Allows access to all Data Cloud API resources. |
Access the Salesforce API Platform (sfap_api) | Reserved for future use. |
| Access Interaction API resources (interaction_api) | Reserved for future use. |