Create an OAuth Named Credential

This example shows how to create an OAuth named credential in Apex to connect to GitHub. The general steps are:

  1. If needed, create an external auth identity provider.
  2. Create an external credential. Assign it an authentication protocol, create principals for authorization, and set other parameters.
  3. Create a named credential, and link it to the external credential.
  4. Check the status of the external credential.
  5. Create permissions for the external credential.
  6. Authenticate a user external credential.
  7. Authenticate to an external system.
  8. Use the named credential in a callout.

In this example, you create an external auth identity provider instead of a standard Salesforce authentication provider. Unlike standard authentication providers, you can package Apex code to create an external auth identity provider. The external auth identity provider object also offers additional configuration options so it’s easier to interact with an identity provider without writing custom Apex code.

You use two separate Apex transactions to create the external auth identity provider metadata and its credentials. Separate transactions prevent mixed DML errors.

First, create a method with the Future annotation that creates credentials asynchronously after you create external auth identity provider metadata.

In a separate transaction, create an external auth identity provider record and call the Future method that you created to populate its credentials.

An external credential contains the authentication and authorization information for the callout. When you create the external credential, you link it to the external auth identity provider. Later, you link the external credential to a named credential.

After you create an external credential, create a named credential, set the callout endpoint (URL), set callout options, and link the named credential to the external credential.

Here are examples of how to create and add permissions for these types of users.

  • A profile for a customer, using the System Administrator profile
  • Another customer profile, using the Standard User profile
  • A profile for an ISV, using permission sets

Sometimes an ISV wants to use a permission set for authorization.

A user external credential stores encrypted tokens used by named credentials. For most permission sets and profiles, Salesforce grants access to the user external credentials object by default.

This example updates a permission set. In the rare case that you want to allow guest users to perform authenticated callouts, you must grant Read access to the User External Credentials object manually on the guest user profile. See Configure the Guest User Profile in Salesforce Help.

Here are examples for authenticating by named principal and on a per-user basis.

If you’re working programmatically, it can be useful to check the status of a credential to determine if users must authenticate. The external credential has an initial status of Not Configured.

Depending on whether you’re in a per-user scenario or using a named principal, you approach programmatic authentication differently. Named principals can be authenticated easily in the setup UI, though you can use code shown in Example: Authenticate Using a Named Principal to access the URL needed for authentication.

This code returns the URL an administrator would visit to authenticate a named principal on behalf of all users in the org.

Use code like this when building a custom UI to help users visit the URL required to authenticate against the external system. Again, in a per-user scenario, each user must visit this URL on their own before the integration can work.

Congratulations. You have a working named credential. For tips on managing named and external credentials, such as deleting or changing them, see Managing an OAuth Named Credential.

For examples of how to use a named credential in your code, see Use the Named Credential in a Callout.