Create or Edit an OAuth External Credential with the Client Credentials with Client Secret Flow
An OAuth 2.0 external credential that uses the Client Credentials with Client Secret Flow exchanges a client identifier and a client secret for an access token. The returned tokens authenticate calls to the endpoint defined in the named credential. Use the Client Credentials with Client Secret Flow when Salesforce is a client application of another external system that has its own login credentials. Instead of managing access to the external system on a per-user basis, you can set up service-level access for your Salesforce org.
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 |
Before you create an OAuth 2.0 external credential that uses the Client Credentials with Client Secret Flow, register Salesforce as a client application in an external system. Generate and save the client credentials—client ID and client secret—on your local machine. You need the copied values when you set up the external credential and principal in Salesforce.
- 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 Client Credentials with Client Secret Flow. For information on the OAuth 2.0 variants, see Authentication Protocols for Named Credentials. Scope Optional. Specifies the scope of permissions to request for the access token. This scope 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. This example uses the
session:rolescope to request access based on each user’s department.{!"session:role:" + $User.Department}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.
Identity Provider URL The URL of the identity provider to send the client credentials to in exchange for an access token. Pass client credentials in request body Optional. Sends the client ID and client secret in the callout’s request body instead of its header.
By default, client credentials are sent in the callout’s authorization header, as with Basic authentication. With this format, the client_id is appended to the client_secret in the format
client_id:client_secret, and the resulting value is Base64-encoded.Sending client credentials in the authorization header aligns with section 2.3.1 Client Password in The OAuth 2.0 Authorization Framework from the Internet Engineering Task Force. If the external system requires that you pass client credentials in the request body instead, use this option.
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 the OAuth Client Credentials with Client Secret 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.
Principals that authenticate with Client Credentials with Client Secret use the Named Principal identity type automatically because the authentication configuration is applied at the service level.
- 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. Client ID Enter the unique identifier that is used to authenticate the client. Client Secret Enter the secret for your client. 
Tip Client secrets often contain special characters. If your client ID or client secret contains special characters, you must URL-encode it before you save it in your principal. - 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.
