Invoking Callouts Using Named Credentials

Salesforce developers use apex callout to invoke an external web service or to send HTTP request to external web service and get the response. Common use case for apex callout is a requirement where you need to fetch data from third-party application. Authentication details (for example. endpoint or credentials) of target system are required to send in a callout definition for successfully setting up connection to external system. Named credentials gives a way to securely store this data in salesforce and allows to provide the physical endpoint at deployment time and manage user credentials in the organisations encrypted credential store. Hence, you do not need to specify the endpoint url into apex code callout definition.

Pros of Using Named Credentials:

• No need to specify callout endpoint into remote site settings.
• Salesforce manages all the authentication for Apex callouts.
• If any of the authentication details (for. example endpoint) has changed, you do not need to change the callout definition in apex code, instead changing named credential will suffice.

Parts of Named Credential:

Named Credentials consist of following,

1. Named credentials:

• Named Credentials specify callout endpoint and HTTP Transport protocol.

2. External Credentials:

• External Credentials specify authentication protocol as well as permission set or profile to use when authenticating to an external system.
• Authentication protocol available in external credential are as follows,
  -OAuth 2.0
  -AWS Signature Version 4
  -Custom

Following is the named credential setup with respect to authentication protocols:

OAuth 2.0:

The OAuth 2.0 is authorization protocol which grants users with access to external system’s protected resources without revealing credentials. To connect to external systems where OAuth 2.0 is being used, you need to create auth. provider in salesforce which will have authorization details such as consumer key, consumer secret etc. This Auth. Provider then will be used in external credentials to reference in named credential so that it can be sent in callout definition. Follow below steps to configure named credentials in case of OAuth 2.0 authentication with target/external system,

Step 1:Create Auth Provider:

1. Go to setup-> Auth. Providers->click New
2. Enter details as below:
   Provider type: Select the provider type depending on the API documentation.

• Provider type: Select the provider type depending on the API documentation.
• Name: Enter Name of the auth. provider. for ex. ‘Demo Auth Provider’
• Consumer Key: Enter client key/consumer key. (Provided by external system to access the API)
• Consumer Secret: Enter client Secret/consumer secret.(Provided by external system to access the API)
• Authorization Endpoint URL: This URL will be found in API documentation.
• Token Endpoint URL:This URL will be found in API documentation.

3. Click ‘Save’

4. Copy ‘Callback URL’ and ‘OAuth-Only Initialization URL’ and provide it to third-party application where the API is hosted. This URL needs to be configured at external system for successful Authentication.

Step 2:Create External Credentials

1. Go to Setup->Named credentials->External Credentials->click New
2. Enter details as shown in the screenshot and select auth provider you created i.e ‘Demo Auth Provider’ and
3. Select ‘Browser flow’ as ‘Authentication flow type’.
   If you select ‘JWT Bearer Token’ then enter ‘Identity Provider Url’ and upload ‘Signing Certificate’. This signing certificate can be provided by external system which them needs to be imported in to certificate and key management in salesforce.
4. Click Save.

Step 5:Create Named Credentials:

1. Go to setup->Named credentials->Click New
2. Enter details as below:

• Label: Enter the label. for ex. Demo Named Credentials
• Name: Enter the name. for ex. Demo_Named_Credentials
• URL: Enter callout endpoint.
• External Credentials: Select external credential ‘Demo External credential’ which you created above.
• Enable ‘Enabled for Callouts’
• Enable ‘Generate Authorization Header’. This will generate authorization header and apply it to callout definition.
• Click ‘Save’.

AWS Signature Version 4:
Select this authentication protocol to authenticate callouts to resources in Amazon Web Services over HTTP. The identity type must be Named Principal.

To configure the named credentials for AWS signature Version 4, enter service and region of the resource.

Check out below link for more information:

https://help.salesforce.com/s/articleView?id=sf.nc_auth_protocols.htm&type=5

https://help.salesforce.com/s/articleViewid=sf.nc_create_edit_awssig4_ext_cred.htm&type=5

Custom:

Select this option if you need to provide custom authentication or user-created authentication. For example. API has been setup with client id enforcement policy where you need to send credentials in body or header.

Configure custom authentication as below:

Step 1:Create External Credentials

1. Go to Setup->Named credentials->External Credentials->click New
2. Enter Label and Name.
3. Select ‘Custom’ In Authentication protocol.
4. Click Save.
5. Go to ‘Principals’ section in External Credentials and click ‘New’
6. Enter name ‘Demo External principal’ and select Identity type as ‘Named Principle’
7. Click save.
8. Go to ‘Custom Header’ section.
9. Click ‘New’
10. Enter Name of the parameter. for. ex ‘client-id’.
11. Enter Value and sequence.
12. Click save.
13. Add all other parameters such as content type, client secret etc by following step 9 to 12.

Step 2:Provide access of Named Credentials through profiles/permission set:

1. Go to profile or permission set
2. go to ‘Enable External Credential Principal Access’
3. Select the named principle ‘Demo Named Principle’ and move it into next box.
4. Save

Step 3:Create Named Credentials:

1. Go to setup->Named credentials->Click New
2. Enter details as below:

• Label: Enter the label. for ex. Demo Named Credentials
• Name: Enter the name. for ex. Demo_Named_Credentials
• URL: Enter callout endpoint.
• External Credentials: Select external credential ‘Demo External credential’ which you created above.
• Enable ‘Enabled for Callouts’
• Enable ‘Allow Formulas in HTTP Header’. The values of custom header evaluate as formulae. hence, enabling this option allows formulas in HTTP header.
• Click ‘Save’.

Configure Basic Authentications as below:

Basic authentication uses username and password to connect to external system. Basic authentication can be configured in named credential by creating external credential and adding username and password in authentication details of named principle.

follow below steps to configure the basic authentication:

Step 1:Create External Credentials

1. Go to Setup->Named credentials->External Credentials->click New
2. Enter Label and Name.
3. Select ‘Custom’ In Authentication protocol.
4. Click Save.
5. Go to ‘Principals’ section in External Credentials and click ‘New’
6. Enter name ‘Demo External principal’ and select Identity type as ‘Named Principle’
7. Under Authentication Parameters, click Add to add a parameter, for example Username and password. Set the values to the parameters you use for the web service provider.
8. Click save.
9. Go to ‘Custom Header’ section.
10. Click ‘New’
11. Enter Name of the parameter as ‘Authorization’.
12. Enter below formula as value to encoded Basic username-password combination:
    {!'Basic ' & BASE64ENCODE(BLOB($Credential.externalCredentialName.Username & ':' & $Credential.externalCredentialName.Password))}
13. Click save.

Step 2:Provide access of Named Credentials through profiles/permission set:

1. Go to profile or permission set
2. go to ‘Enable External Credential Principal Access’
3. Select the named principle ‘Demo Named Principle’ and move it into next box.
4. Save

Step 3:Create Named Credentials:

1. Go to setup->Named credentials->Click New
2. Enter details as below:

• Label: Enter the label. for ex. Demo Named Credentials
• Name: Enter the name. for ex. Demo_Named_Credentials
• URL: Enter callout endpoint.
• External Credentials: Select external credential ‘Demo External credential’ which you created above.
• Enable ‘Enabled for Callouts’
• Enable ‘Allow Formulas in HTTP Header’. The values of custom header evaluate as formulae. hence, enabling this option allows formulas in HTTP header.
• Disable Generate Authorization Header in the named credential. Disabling this option ensures that the named credential uses the custom Authorization header that you created.
• Click ‘Save’.

Using named Credential in Apex code:

HttpRequest req = new HttpRequest();
req.setEndpoint('callout:Demo_Named_Credentials/ + <path>');
req.setMethod('GET');
Http http = new Http();
HTTPResponse res = http.send(req);
System.debug(res.getBody());

References:

https://help.salesforce.com/s/articleView?id=sf.nc_create_edit_custom_auth_ext_cred.htm&type=5

https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_callouts_named_credentials.htm