Setting up Named Credentials in Salesforce

Named Credentials in Salesforce are a great way of decoupling the API endpoint setup from the code. The named credential holds the endpoint, authentication and access information, giving the user the flexibility to change the endpoint details without requiring any code changes. Obviously, this should be tested to ensure that the new setup works as should all changes made to a Production environment.

Before named credentials, the endpoint would have been coded into the apex class and added to Remote Site Settings to enable callouts to that api endpoint. With named credentials, this step can be skipped. Named credentials can be thought of as a variable or container for the callout endpoint. This makes the code cleaner as you will see in the example below.

The legacy Named Credential is quite straightforward to set up but I cannot say the same about the new Named/External Credentials. However, an understanding of the legacy setup helped with me understand how to go about setting up the new Named Credentials.

In this article, I will look at both the legacy and the new Named Credentials.

Let’s start with the legacy Named Credential…

Creating a Legacy Named Credential

The steps are as follows
1. Create a Connected App
2. Create an Auth. Provider
3. Create a Named Credential

STEP 1 — Creating a Connected App
Navigate to Setup -> Apps -> App Manager and click on New Connected App.

Connected App

Steps
1. Provide a name and an API name for the connected app.
2. Provide a contact email.
3. Check the Enable OAuth Settings option under API(Enable OAuth Settings).
4. Provide a dummy URL for the Callback URL at this stage. This will be updated after the next step.
5. Select the relevant OAuth Scopes.
6. Save

STEP 2 — Create an Auth. Provider
Navigate to Setup -> Identity -> Auth. Providers and click on New.

Select a Provider type. In my case, I am choosing Salesforce to allow me to call Salesforce Rest APIs without using the current sessionID.

Select a Provider Type

Complete the setup by filling in the form below

Setting up an Auth. Provider

Provide a Name and URL suffix.
Note that the Customer Key and Customer Secret are created in the previous step and are part of the Connected App.
Click on Manage Consumer Details as shown below and this will prompt the user to enter a verification code sent to their email address.

Click on Manage Consumer Details to see the Customer Key/Secret

The customer key and secret can be copied over to the Auth. Provider. Accept the default for the remaining fields and click Save.
This step generates a number of URLs including the Callback URL.

Create an Auth. Provider

Update the Callback URL in the Connected App with this value.

Update the Connected App

STEP 3 — Create the Named Credential
Navigate to Setup -> Security -> Named Credentials and click on the dropdown next to New and select New Legacy.

Create a Legacy Named Credential

Populate the fields as shown below.
Note that the URL is the My Domain url (navigate to My Domain and copy the My Current Domain URL).

Create the Legacy Named Credential

For the Scope, I entered refresh_token full. This ensures that the process returns a refresh_token, otherwise the access will expire.
On Save, the authentication process will kick off and redirect the user to a login page. Note that the Authentication Status will be updated after this authentication process.

Creating a Named/External Credential

Based on my learnings through the creation of a legacy Named Credential, I can see that Salesforce has further decoupled the access provision from the Named Credential into an External Credential.

The External Credential now holds the Authentication provision as well as the access provision. Rather than all access running under the authenticated user (see the last step in the Legacy Named Credential creation above), Salesforce now provides the flexibility to grant access through the creation of Named Principals. This can be done by creating Permission Sets or granting access through profiles rather than through named individuals.

With this approach, the Named Credential becomes just a variable holding the callout endpoint URL and protocol.

So, let’s create a Named Credential in the new way…

Step 1 — Create a Connected App (as above)

Step 2 — Create an Auth. Provider (as above)

Step 3 — Create an External Credential

Create an External Credential

Step 4 — Create a Named Credential as follows

Create a Named Credential

Step 4 — Create a Named Principal

Create a named principal as shown below.

Creating a Named Principal

Once saved, click on the actions as shown below and select Authenticate.

Configure the Named Principal

Step 5 — Grant access through Permission sets

Create a permission set and edit the External Credential Principal Access to grant access to the Named Principal created in the step above.

Granting access to the Named Principal

Save and assign this Permission Set to the relevant users.

Let’s test this out…
I executed the following code as a test in the Developer Console and I got a 200 status code back.

  String searchEndpoint = 'callout:MyNewNamedCred/services/data/v58.0/search?q=FIND+%7Brach%7D';
    
  HttpRequest request = new HttpRequest();
  request.setEndpoint(searchEndpoint);
  request.setMethod('GET');

  HttpResponse res = new Http().send(request);
  system.debug(res.getStatusCode());

Successful callout to salesforce