Loading
Set Up and Maintain Your Salesforce Organization
Table of Contents
Filter by (0)Add
Select Filters

          No results
          No results
          Here are some search tips

          Check the spelling of your keywords.
          Use more general search terms.
          Select fewer filters to broaden your search.

            Search all of Salesforce Help
            Search all of Salesforce Help
            Named Credential Example: OAuth 2.0 Browser Flow with a Per User Principal

            You are here:

            1. Salesforce Help
            2. Docs
            3. Set Up and Maintain Your Salesforce Organization

            Named Credential Example: OAuth 2.0 Browser Flow with a Per User 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 Per User identity type, meaning that each user authenticates to GitHub.

            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 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, in the Quick Find box, enter Named Credentials, and then 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 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, in the Quick Find box, enter Named Credentials, and then 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.
              Scope Enter gist. This scope is a credential-level scope that applies to all callouts that use this credential and request access to gists in GitHub.
              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.
              FieldDescription
              Parameter Name Enter a name that references the external system, such as IndividualAccountAccess.
              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 Per User Principal.

              Per-user authentication provides access control at the individual user level.
            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, in the Quick Find box, enter Named Credentials, and then select Named Credentials.
            2. To create a named credential, click New.
            3. Complete the fields.
              FieldDescription
              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.

            Tip
            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, in the Quick Find box, enter Permission Sets, and then select Permission Sets.
            2. Click the permission set 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 IndividualAccountAccess, the name is GitHubOAuth - IndividualAccountAccess.
            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.

            Authenticate to GitHub

            After you grant access to the principal and user external credentials, authenticate the principal on the external credential.

            When the principal’s Identity Type is set to Per User Principal, each user must authenticate to GitHub following these steps.

            1. From your personal settings, in the Quick Find box, enter External Credentials, and then select External Credentials.
            2. In the tile of the GitHub external credential, click Allow Access.
            3. Authenticate to GitHub. For example, enter a username and password.
              After authenticating to GitHub, the user is redirected back to Salesforce. The external credential is authenticated, and its tile shows Configured. To revoke authentication on an external credential, users click Revoke Access.
            Tip
            Tip To make it easier for your users to authenticate to GitHub, you can also use Lightning Web Components (LWC) to build a custom button so they can more easily access the URL. See the Authenticate on a Per User Basis example in the Named Credentials Developer Guide.

            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 in the Named Credentials Developer Guide.

            See Also

             
            Loading
            Salesforce Help | Article