--- schema_version: "1" id: a6070972784faf06471ccac9c736ddff0f0678f18a93373e5455acefda4e93e1 title: "Named Credential Example: OAuth 2.0 Browser Flow with a Named Principal" collection: admin version: current locale: en-us portal_url: https://docs.salesforce.com/admin/current/en-us/xcloud/264-0-0/nc_example_oauth_github.md canonical_url: https://help.salesforce.com/s/articleView?id=xcloud.nc_example_oauth_github.htm&release=264.0.0&type=5 source_site: help.salesforce.com content_type: documentation content_hash: 847a77892f349b75c2b7b6bdac9271084f8a55c30495bf4ed987a1688f9357a8 description: In this example, configure a named credential with the OAuth 2.0 Browser Flow to make authenticated callouts to GitHub. This example uses the Named Principal identity type, meaning that a Salesforce admin authenticates to GitHub on behalf of all users in the org. products: - Security release: "264" --- # Named Credential Example: OAuth 2.0 Browser Flow with a Named Principal In this example, configure a named credential with the OAuth 2.0 Browser Flow to make authenticated callouts to GitHub. This example uses the Named Principal identity type, meaning that a Salesforce admin authenticates to GitHub on behalf of all users in the org. ### Required Editions
Available in: Salesforce Classic (not available in all orgs) and Lightning Experience
Available in: all editions
Permission sets available in: Contact Manager, Group, Professional, Enterprise, Performance, Unlimited, Developer, and Database.com Editions
User Permissions Needed
To view named credentials: View Setup and Configuration
To create, edit, or delete named credentials: Manage Named Credentials or Customize Applications
To edit permission sets and user profiles: Manage Profiles and Permission Sets
This is the process for integrating Salesforce and GitHub. 1. In Salesforce, configure an external auth identity provider and copy its callback URL for the OAuth flow. 2. In GitHub, create an OAuth application for the connection to Salesforce. 3. In Salesforce, update the external auth identity provider that you created with the client ID and client secret from the GitHub application. 4. In Salesforce, add Accept headers: one for the token request and one for the refresh request. 5. In Salesforce, create an external credential that uses the external auth identity provider that you configured. 6. In Salesforce, create a named credential that uses the external credential that you configured. 7. In Salesforce, grant access to the external credential principal and the user external credential. To use Apex to create an OAuth named credential to connect to GitHub, see [Create an OAuth Named Credential](https://developer.salesforce.com/docs/platform/named-credentials/guide/nc-create-oauth-cred.html) in the Named Credentials Developer Guide. ## Configure an External Auth Identity Provider in Salesforce Create an external auth identity provider in Salesforce. 1. From [Setup](https://help.salesforce.com/s/articleView?id=xcloud.basics_nav_setup.htm&type=5&language=en_US), use the Quick Find box to find and select **Named Credentials**. 2. Click the **External Auth Identity Providers** tab, and then click **New**. 3. Give the external auth identity provider a name such as GitHubIdp, and enter placeholder values in other required fields. You update these fields after you create the OAuth application in GitHub. 4. Keep the Authentication Protocol default value of **OAuth 2.0** and the Authentication Flow Type default value of **Authorization Code (Browser Flow)**. 5. Next, on the external auth identity provider detail page, copy the callback URL that Salesforce generated. When you create the application in GitHub, you enter this callback URL so that you or other Salesforce admins are redirected back to Salesforce after authenticating in GitHub. ## Create an OAuth App in GitHub Create an OAuth application in GitHub to enable access to GitHub’s API. 1. In GitHub, give the application a name such as Salesforce, and use the callback URL that you copied from the external auth identity provider in Salesforce as the value for the Authorization callback URL. See [Creating an OAuth app](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) in the GitHub documentation. 2. After you create the GitHub application, retrieve and save the client ID and client secret from the application’s settings. When you update the external auth identity provider that you created in Salesforce, you add these values. ## Update the External Auth Identity Provider in Salesforce In Salesforce, update the external auth identity provider that you created with the values from the GitHub application and standard GitHub URLs. 1. On the external auth identity provider detail page, enter these values from GitHub. | Salesforce external auth identity provider Field | GitHub Value | | --- | --- | | Client ID | Client ID | | Client Secret | Client secret | | Authorize Endpoint URL | https://github.com/login/oauth/authorize | | Token Endpoint URL | https://github.com/login/oauth/access\_token | 2. Save your changes. ## Add Custom Request Parameters to the External Auth Identity Provider In Salesforce, add an Accept HTTP header to specify the content type that the client can accept. You create one request parameter for the token request and one for the refresh request. 1. In the Custom Request Parameters section of the external auth identity provider, click **New**, and complete these fields. | Field | DESCRIPTION | | --- | --- | | Name | Enter Accept. | | Value | Enter application/json. | | Request Type | Select **Token Request**. | | Parameter Location | Select **HTTP Header**. | 2. Save your changes. 3. In the Custom Request Parameters section, click **New**, and complete these fields. | Field | DESCRIPTION | | --- | --- | | Name | Enter Accept. | | Value | Enter application/json. | | Request Type | Select **Refresh Request**. | | Parameter Location | Select **HTTP Header**. | 4. Save your changes. ## Create an External Credential Create an external credential in Salesforce. The external credential holds the details of how Salesforce authenticates to a remote system. Use the OAuth 2.0 Browser Flow with the external auth identity provider that you created for the GitHub account. 1. From [Setup](https://help.salesforce.com/s/articleView?id=xcloud.basics_nav_setup.htm&type=5&language=en_US), use the Quick Find box to find and select **Named Credentials**. 2. Click **External Credentials**, and then click **New**. 3. Complete the fields.
Field Description
Label

Enter GitHub OAuth.

This label is a user-friendly name for the external credential that’s displayed in the Salesforce user interface, such as in list views.
Name

Enter GitHubOAuth.

The name is a unique identifier that’s used to refer to this external credential from callout definitions to GitHub.
Authentication Protocol Select OAuth 2.0.
Authentication Flow Type Select Browser Flow.
Identity Provider Select External Auth Identity Provider, and then select the external auth identity provider that you created to access GitHub.
4. Save the external credential. ## Create an External Credential Principal Create the external credential principal. The principal maps the external credential to user permissions to authorize users to make callouts to the remote system. 1. In the external credential’s details, scroll to the Principals section. 2. To create a principal, click **New**. 3. Enter the information for the principal.
Field Description
Parameter Name Enter a name that references the external system, such as SharedServiceAccount.
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 can be part of multiple permission sets that are applicable for a credential provider. Priority is from lower to higher numbers.
Identity Type

Select Named Principal.

With the Named Principal identity type, your organization uses only one login account to access the GitHub external system.
4. Save the principal. ## Create a Named Credential The named credential specifies the callout endpoint and uses the authentication configuration that you defined in the GitHub external credential. 1. From [Setup](https://help.salesforce.com/s/articleView?id=xcloud.basics_nav_setup.htm&type=5&language=en_US), use the Quick Find box to find and select **Named Credentials**. 2. To create a named credential, click **New**. 3. Complete the fields.
Field Description
Label

Enter GitHub API.

This label is a user-friendly name for the named credential that’s displayed in the Salesforce user interface, such as in list views.
Name

Enter GithubAPI.

This name is a unique identifier that’s used to refer to this named credential from a callout definition.
URL Enter https://api.github.com.
External Credential Select the GitHub OAuth external credential that you created.
Generate Authorization Header Leave this checkbox selected so that Salesforce generates an authorization header and applies it to each callout to GitHub that references this named credential.
4. Save your changes. ## Create a Permission Set and Grant Principal Access Use permission sets to grant access to the GitHub external credential’s principal so that users can make authenticated callouts to the GitHub API. If you don’t already have a permission set that allows users to access external systems, create one first. See [Create Permission Sets](https://help.salesforce.com/s/articleView?id=platform.perm_sets_create.htm&type=5&language=en_US). ![Tip](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-xcloud-security-264-0-0-production-enus/8cecd769-ab2d-4e07-addf-c4f2927925e1/images/icon_tip.png) Tip To apply credential permissions to the largest number of users, link a principal to a permission set and then add the permission set to a permission set group. 1. From [Setup](https://help.salesforce.com/s/articleView?id=xcloud.basics_nav_setup.htm&type=5&language=en_US), use the Quick Find box to find and select **Permission Sets**. 2. Click the permission set that you created for accessing external systems. 3. In the Apps section, click **External Credential Principal Access**. 4. Click **Edit**. 5. Under the available external credential principals, select the principal for the GitHub external credential and move it to the enabled principals column. The principal’s name is concatenated from the external credential’s name and the parameter name of the external credential’s principal. In this example, for the external credential named `GitHubOAuth` with a parameter called `SharedServiceAccount`, the name is `GitHubOAuth - SharedServiceAccount`. 6. Save your changes. Most standard permission sets and profiles have access to the User External Credentials object by default. If you use these permission sets and profiles, enabling external credential principals is the last step to create a named credential. For the guest user profile, and for some custom permission sets and profiles, you must assign User External Credentials object permissions manually so these users can make authenticated callouts to GitHub. See [Enable User External Credentials](https://help.salesforce.com/s/articleView?id=xcloud.nc_user_external_credentials.htm&release=264.0.0&type=5 "Tokens for named credential callouts are encrypted and stored in the User External Credential object. Any user performing an authenticated callout needs profile- or permission set-based access to user external credentials. Most standard permission sets and profiles have access to the User External Credentials object by default. For the guest user profile, and for some custom permission sets and profiles, you must assign User External Credentials object permissions manually."). ## Authenticate to GitHub After you grant access to the principal and user external credentials, authenticate the principal on the external credential. When the principal uses the Named Principal identity type, you, the Salesforce admin, authenticate to GitHub one time on behalf of all users in your org. 1. From [Setup](https://help.salesforce.com/s/articleView?id=xcloud.basics_nav_setup.htm&type=5&language=en_US), use the Quick Find box to find and select **Named Credentials**. 2. On the Named Credentials page, click **External Credential**. 3. Select the external credential that you created, and then scroll to the Principals section. 4. From the actions menu of the principal, select **Authenticate**. You’re taken to GitHub to authenticate, and then redirected back to Salesforce. Congratulations, you have a working named credential that you and your users can use to make authenticated callouts to GitHub. See [Use the Named Credential in a Callout](https://developer.salesforce.com/docs/platform/named-credentials/guide/nc-use-oauth-cred-in-callout.html) in the Named Credentials Developer Guide. #### See Also - [Named Credentials](https://help.salesforce.com/s/articleView?id=xcloud.named_credentials_about.htm&release=264.0.0&type=5 "Intended to secure and simplify authenticated API callouts to external systems, a named credential specifies the URL of a callout endpoint and its required authentication parameters in one definition. To streamline your Apex code and simplify the setup of authenticated callouts, specify a named credential as the callout endpoint.")