Loading
Salesforce now sends email only from verified domains. Read More
Identify Your Users and Manage Access
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
            Create a Custom External Authentication Provider

            You are here:

            1. Salesforce Help
            2. Docs
            3. Identify Your Users and Manage Access

            Create a Custom External Authentication Provider

            To configure single sign-on (SSO) from a third party that supports OAuth but not OpenID Connect, create a custom authentication provider. With a custom authentication provider, users can log in to your Salesforce org with third-party credentials.

            Required Editions

            Available in: Available in Enterprise, Performance, Unlimited, and Developer Editions

            Here’s the breakdown of each step to create a custom third-party authentication provider.

            1. Set up a registration handler.
            2. Set up an app with your chosen third party.
            3. Create your custom metadata types, and add the custom metadata fields that your third party requires.
            4. Build the matching Apex classes and methods for your chosen metadata types. Then use these classes to implement a custom authentication provider by extending the abstract class Auth.AuthProviderPluginClass.
            5. Configure your authentication provider by adding the third party’s metadata.
            6. Update your app so it uses the callback URL generated by Salesforce.
            7. Test the connection.
            8. Add the authentication provider to your login page.

            See Also

            Set Up a Registration Handler

            To use an authentication provider for single sign-on, you must create a registration handler. The registration handler creates users and updates existing users who access Salesforce via the identity provider. You can set up a registration handler with Apex or Flow Builder. For more information, see Create an Authentication Provider Registration Handler.

            Set Up a Third-Party App

            Before you configure the third-party authentication provider plug-in for your Salesforce org, set up an app in the third party.

            1. Go to your third party’s site, and create an app.
            2. Modify the app settings as needed. If the app has an Application Domain, set it to Salesforce.
            3. Note the information supplied by your third party. You add this information to custom metadata types in the next step. The following list provides a sample of the information a third party provides. Some third parties name these values differently, provide other values, or have other requirements.
              • App ID
              • App secret
              • Authorization endpoint URL
              • Token endpoint URL
              • Scope

            Create Custom Metadata Types in Salesforce

            After you create a third-party app, configure custom metadata types. In these types, add custom fields for the information provided by the third party, like the app ID and app secret. Later, when you set up the authentication provider, you enter the third party’s information in these custom fields.

            1. From Setup, in the Quick Find box, enter Metadata, and then select Custom Metadata Types.
            2. Click New Custom Metadata Type.
            3. Enter a label name and plural label name for your custom metadata, then save your work.
            4. Enter an object name for referencing the metadata object via the API.
            5. (Optional) Enter a description for your custom metadata type.
            6. Save your work.
            7. Under the Custom Fields section, click New, and select the data type that your third party requires to set up an authentication provider. When you configure your authentication provider, these custom fields are added to the Auth. Providers Setup page.
            8. Enter a label and name for the field, and provide details you want to specify for the custom field, such as a description and Help text.
            9. Select a page layout for the field.
            10. Save your work. Or, to add another custom field, click Save & New.
            Example
            Example If your third party has an app secret, create a custom Text field, and name it App Secret. When you configure the authentication provider, the App Secret field appears and you can enter the third party’s information.
            Note
            Note For more information about custom metadata types and fields, see Custom Metadata Types.

            Build Your Apex Classes and Methods

            After you have a custom metadata type, create an Apex class that extends the Auth.AuthProviderPluginClass abstract class. This new class stores the custom configuration for your authentication provider and handles its authentication protocols. The new Apex class also creates the name for your third-party authentication provider and displays this name in the list of available authentication providers.

            1. From Setup, in the Quick Find box, enter Apex Classes, and then select Apex Classes.
            2. Click New. In the field provided, create an Apex class that extends the Auth.AuthProviderPluginClass class. Use the methods in this class to build your authentication provider.
              • The getCustomMetadataType method returns the custom metadata type API name for your authentication provider.
              • The getUserInfo method returns user data that the registration handler can use.
              • The handleCallback method returns an OAuth access token and an OAuth secret or refresh token. It also returns the state of the authentication provider.
              • The initiatemethod returns the URL where the user goes for authentication.
              • The refreshmethod returns a new access token that updates the expired access token.
            Note
            Note Refer to the Apex guides for more information about creating this class. For information about the methods in this class, see AuthProviderPluginClass Class in the Apex Reference Guide. For sample classes, see Create a Custom Authentication Provider Plugin in the Apex Developer Guide.

            Configure Your Authentication Provider

            Set up your authentication provider in Salesforce.Note the generated authentication provider ID. You use it with the Auth.AuthToken Apex class.

            1. From Setup, in the Quick Find box, enter Auth., and then select Auth. Providers.
            2. ClickNew.
            3. For the provider type, select your custom authentication provider.
            4. Enter a name for the provider.
            5. Enter the URL suffix, which is used in the client configuration URL. For example, if your provider’s URL is MyAwesomeProvider, your SSO URL is similar to https://login.salesforce.com/auth/sso/00Dx00000000001/MyAwesomeProvider.
            6. Enter the third party’s information in the custom fields you created.
            7. To automatically enable the OAuth 2.0 Proof Key for Code Exchange (PKCE) extension, which improves security, select Use Proof Key for Code Exchange (PKCE) Extension. For more information on how this setting helps secure your provider, see Build the PKCE Extension into Your Implementations.
            8. To use an Apex registration handler, take these steps.
              1. For Registration Handler Type, select Apex.
              2. For Registration Handler, select an existing Apex class that implements the Auth.RegistrationHandler interface. Or, to create an template for the registration handler, click Automatically create a registration handler template. Edit this class later, and modify the default content before using it.
            9. To use a flow for your registration handler, take these steps.
              1. For Registration Handler Type, select Flow.
              2. For Registration Handler, select an existing flow of the Identity User Registration flow type.
              3. Select a default profile. A default profile is required to run the registration handler. If you don't specify a default profile here, set the default profile in the flow itself.

                If you use the Authentication Provider User Registration flow template, the profile that you set here is automatically stored in the defaultProfileId variable.

              4. Select a default account. If you use your authentication provider for Experience Cloud sites, this account stores new internal users.

                If you use the Authentication Provider User Registration flow template, the profile that you set here is automatically stored in the defaultAccountId variable.

            10. For Execute Registration As, select an execution user to run the Apex class or flow. The user must have the Manage Users permission.

              Execute Registration As provides the context in which the registration handler runs. In production, you typically create a system user for the Execute Registration As user. This way, operations performed by the handler are easily traced back to the registration process. For example, if a contact is created, the system user creates it.

            11. For Icon URL, add a path to an icon to display as a button on the login page for a site. This icon applies to an Experience Cloud site only. It doesn’t appear on your Salesforce login page or My Domain login URL. Users click the button to log in with the associated authentication provider for the site. Specify a path to your own image, or copy the URL for one of our sample icons into the field.
            12. To use the Salesforce multi-factor authentication (MFA) functionality instead of your identity provider’s MFA service, select Use Salesforce MFA for this SSO provider. This setting triggers MFA only for users who have MFA applied to them directly. For more information, see Use Salesforce MFA for SSO.
            13. Save your work.

            Add Request Parameters to Client Configuration URLs

            Several client configuration URLs are generated after defining the authentication provider:

            • Test-Only Initialization URL—Use this URL to test whether you set up the third party correctly. Open the URL, and log in to the third party. When logged in, you’re redirected back to your Salesforce org with a map of attributes.
            • Single Sign-On Initialization URL—Use this URL to direct users to perform SSO into your org from the third party. The user opens the URL and logs in to the third party. The third party creates or updates a user account, and then logs the user into Salesforce with that account.
            • Existing User Linking URL—Use this URL to link users in your org to an existing account in the third party. The user opens this URL, logs in to the third party, and logs in to Salesforce, creating a link between accounts.
            • OAuth-Only Initialization URL—Use this URL to obtain OAuth access tokens after the user authenticates. This flow doesn't provide for SSO.
            • Callback URL— For each of the other client configuration URLs, the authentication provider sends information back to the callback URL.

            Client configuration URLs support other request parameters that you can use to add functions to your authentication provider. For example, use request parameters to obtain permissions from a third party or direct users to a location after authenticating.

            Update Your Third-Party App

            After defining your authentication provider in your Salesforce org, go back to the third party’s site. Update your app to use the callback URL as your custom authentication provider’s website URL.

            Test the SSO Connection

            In a browser, open the Test-Only Initialization URL on the Auth. Provider Setup page. It redirects you to your third party’s site and asks you to log in. Then, it asks you to authorize your app. After you authorize access, you’re redirected back to Salesforce.

            Add the Authentication Provider to Your Login Page

            Configure your login page to show the authentication provider as a login option. Depending on whether you’re configuring SSO for an org or Experience Cloud site, this step is different.

             
            Loading
            Salesforce Help | Article