Create or Edit an OAuth External Credential with the Browser Flow
With an OAuth 2.0 external credential that uses the Browser Flow, one or more users logs into the remote system via a web browser to trigger a callback that includes access tokens. The returned tokens authenticate calls to the endpoint defined in the named credential.
Required Editions
| Available in: both Salesforce Classic (not available in all orgs) and Lightning Experience |
| Available in: all editions |
| User Permissions Needed | |
|---|---|
| To view external credentials: | View Setup and Configuration |
| To create, edit, or delete external credentials: | Manage Named Credentials or Customize Applications |
This help content describes how to set up an OAuth external credential with the Browser Flow. For an end-to-end example implementation, see Named Credential Example: OAuth 2.0 Browser Flow with a Named Principal.
- From Setup, in the Quick Find box, enter Named Credentials, and then select Named Credentials.
- Click External Credentials.
- To create a new external credential, click New. To edit an existing external credential, click its link in the list of external credentials and then click Edit.
- Complete the fields.
Field Description Label A user-friendly name for the external credential that’s shown in the Salesforce user interface, such as in list views. Name A unique identifier that’s used to refer to this external credential from callout definitions and through the API.
The name can contain only underscores and alphanumeric characters. It must be unique, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.
Authentication Protocol Select OAuth 2.0. Authentication Flow Type Select Browser Flow. See Authentication Protocols for Named Credentials. Scope Optional. Specifies the scope of permissions to request for the access token. A scope declared here is a credential-level scope that applies to all callouts that use this credential. Your authentication provider determines the allowed values. See OAuth Tokens and Scopes and Use the Scope Parameter.
The Scope field accepts static values and formulas. For instance, use a static scope value that specifies that all callouts using this credential request have offline access. Or enter a formula to request access dynamically. This example uses the
session:rolescope to request credential-level access based on each user’s department.{!"session:role:" + $User.Department}When you create an external credential’s principal, you can also specify principal-level scopes, which apply only per principal. For example, create a principal-level scope to request access only for users that work in the Administration or Management departments.
When you set the credential’s scope, keep these considerations in mind.
- The value that you enter replaces the Default Scopes value that’s defined in the specified authentication provider.
- A scope can affect whether each OAuth flow prompts the user with a consent screen.
- We recommend that you request a refresh token or offline access. Otherwise, when the token expires, you lose access to the external system.
Identity Provider Select whether the external credential uses an Auth. Provider or an External Auth Identity Provider to obtain OAuth tokens. Then, specify the authentication provider for the external credential. See Authentication Providers and Create or Edit an External Auth Identity Provider. Additional Status Codes for Token Refresh Specify HTTP status codes that trigger Salesforce to refresh expired or invalid access tokens, in addition to the standard 401response. - Save the external credential.
Create Principals
After you create an external credential that uses OAuth authentication with the Browser Flow, create principals for it. You link an external credential to permission sets or user profiles through principals, and at run time, the platform ensures that the user has the permission set before accessing the remote system.
- On the Named Credentials page, click External Credential.
- Select the external credential that you created.
- Scroll to Principals.
- To create a principal for the external credential, click New or
select Edit from the Actions menu of an existing principal. When editing an existing principal, not all the fields listed here are modifiable.
- Enter the information for the principal.
Field Description Parameter Name Enter a name for the principal, such as Admin or Marketing Group. Sequence Number Assign a sequence number. A sequence number specifies the order of principals to apply when a user participates in more than one principal. For example, a user could be part of multiple permission sets that are applicable for a credential provider. Priority is from lower to higher numbers. Identity Type Choose either Named Principal or Per User Principal.
You can set up each external credential to use an org-wide named principal or per-user authentication. A named principal applies the same credential or authentication configuration for the entire org, while per-user authentication provides access control at the individual user level.
Scope Optional. Enter a principal-level scope.
This scope is in addition to the optional credential-level scope. You can use it to provide access parameters on a per-principal basis. For example, the credential-level scope can specify offline token access, while the principal-level scope can specify access for users with certain roles, such as Marketing or System Administrator.
Credential-level and principal-level scopes are concatenated together in callouts and sent as a space-separated list. These scopes overwrite an authentication provider’s default scopes, if the appended list is non-null.
This example uses a principal-level scope to link a group of authenticated users to roles on an external site. The scope is
session:role:<role>. If a user has Sales or Service in their department name, the scope is set assession:role:Salesorsession:role:Service.{!IF(OR(CONTAINS($User.Department, "Sales"), CONTAINS($User.Department, "Service")), "session:role:" + $User.Department, "")} - Save the principal.You can’t modify the Principal Name and Identity Type of an existing principal. To change these parameters, delete the principal and recreate it.
- Now that you created the external credential and its principal, it’s time to create the
connected name credential. See Create or Edit a Named Credential.For an overview of all of the steps required to configure a named credential, see Create Named Credentials and External Credentials.
After you configure the named credential and grant access via permission sets, you must authenticate the OAuth external credential to the external system.
When the principal’s identity type is set to Named Principal, in the external credential’s Principals section, select Authenticate from the principal’s Actions menu. Then, authenticate yourself to the external system. For example, enter a username and password. Return to Salesforce to confirm that you want to allow your Salesforce org to interact with the external system on your behalf.
When the principal’s Identity Type is set to Per User Principal, each user authenticates to the external system from the External Credentials page in their personal settings. In the tile of the external credential to authenticate, click Allow Access. Authenticate to the external system, and then return to Salesforce to confirm that you want to allow your Salesforce org to interact with the external system on your behalf. After the external credential is authenticated, its tile shows Configured. To revoke authentication on an external credential, click Revoke Access.
