Configure a Salesforce Authentication Provider

Set Up a Registration Handler

Create an App in the Identity Provider Org

Define the Salesforce Authentication Provider in the Relying Party Org

1. In the relying party org, from Setup, enter Auth. Providers in the Quick Find box, and then select Auth. Providers | New.
2. For the provider type, select Salesforce.
3. Enter a name for the provider.
4. Enter the URL suffix, which is used in the client configuration URLs. For example, if the URL suffix of your provider is MySFDCProvider, your SSO URL is similar to https://mydomain_url or site_url /services/auth/sso/MySFDCProvider.
5. Paste the consumer key value from the external client app definition into the Consumer Key field.
6. Paste the consumer secret value from the external client app definition into the Consumer Secret field.
7. Optionally, set the following fields.
   • For Authorize Endpoint URL, specify an OAuth authorization URL.

     For Authorize Endpoint URL, we recommend that you use the org's My Domain login URL, which you can find on the My Domain page in Setup. The URL must end in .salesforce.com, and the path must end in /services/oauth2/authorize. For example, https://MyDomainName.my.salesforce.com/services/oauth2/authorize.

   • For Token Endpoint URL, specify an OAuth token URL.

     For Token Endpoint URL, the host name can include a sandbox or custom domain name. The URL must end in .salesforce.com, and the path must end in /services/oauth2/token. For example, https://login.salesforce.com/services/oauth2/token.

   • 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 Proof Key for Code Exchange (PKCE) Extension.
   • For Default Scopes, enter the scopes to send along with the request to the authorization endpoint. Otherwise, the hard-coded default is used.

     For more information, see Customize Relying Party Data Requests.

   • If the authentication provider was created after the Winter ’15 release, the Include identity organization’s organization ID for third-party account linkage option no longer appears. Before Winter ’15, the destination org couldn’t differentiate between users with the same user ID on different orgs. For example, two users with the same user ID in different orgs were seen as the same user. As of Winter ’15, user identities contain the org ID, so this option isn’t needed. For older authentication providers, enable this option to keep identities separate in the destination org. When you enable this option, your users must reapprove all third-party links. The links are listed in the Third-Party Account Links section of a user’s detail page.
   • If you enter a consumer key and consumer secret, the consumer secret is included in SOAP API responses by default. To hide the secret in SOAP API responses, deselect Include Consumer Secret in SOAP API Responses. Starting in November 2022, the secret is always replaced in Metadata API responses with a placeholder value. On deployment, replace the placeholder with your consumer secret as plain text, or modify the value later through the UI.
   • For Custom Error URL, enter the URL for the provider to use to report any errors.
   • For Custom Logout URL, enter a URL to provide a specific destination for users after they log out, if they authenticated using the SSO flow. Use this field to direct users to a branded logout page or destination other than the default Salesforce logout page. The URL must be fully qualified with an http or https prefix, such as https://acme.my.salesforce.com.
   

   Tip Configure single logout (SLO) to automatically log out a user from Salesforce and the identity provider. As the relying party, Salesforce supports OpenID Connect SLO when the user logs out from the identity provider or Salesforce.
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. To use a portal with your provider, select the portal from the Portal dropdown list.
12. 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.
13. 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.
14. Click Save.
    Note the value of the Client Configuration URLs. You need the callback URL to complete the last step. Use the Test-Only initialization URL to check your configuration. Also note the Auth. Provider ID value because you use it with the Auth.AuthToken Apex class.
15. In the identity provider org, return to the external client app definition that you created earlier from Setup. Paste the callback URL value from the authentication provider into the Callback URL field.

Test the SSO Connection

Add the Authentication Provider to Your Login Page