Configure an Authentication Provider Using OpenID Connect

To configure single sign-on (SSO) with Salesforce as the relying party for a third-party OpenID provider, set up an authentication provider that implements OpenID Connect. With this configuration, your users can log in to Salesforce from the OpenID provider and authorize Salesforce to access protected data.

Required Editions
Available in: Lightning Experience and Salesforce Classic
Available in: Enterprise, Performance, Unlimited, and Developer Editions
User Permissions Needed
To view the settings:View Setup and Configuration
To edit the settings:Customize Application AND Manage Auth. Providers

You can configure an authentication provider for any third party that implements the server side of the OpenID Connect protocol. Here are some common OpenID providers.

To configure Salesforce as the relying party for your OpenID provider, complete these steps.

  1. Register your app, making Salesforce the app domain.
  2. Define an OpenID Connect authentication provider in Salesforce.
  3. Update your app to use the callback URL generated by Salesforce.
  4. Test the connection.
  5. Add the authentication provider to your login page.

Before you can define your authentication provider in Salesforce, you must register a web app with your OpenID provider. The process varies depending on the OpenID provider. For example, to register a Google app, Create an OAuth 2.0 Client ID.

  1. Register your app on your OpenID provider’s website.
  2. Modify the app settings and set the app domain, or Home Page URL, to Salesforce.
  3. From the OpenID provider’s documentation, get these configuration values.
    • Client ID
    • Client Secret
    • Authorization Endpoint URL
    • Token Endpoint URL
    • User Info Endpoint URL

Be sure to note the generated Auth. Provider ID value. Use it with the Auth.AuthToken Apex class.

  1. From Setup, in the Quick Find box, enter Auth, and then select Auth. Providers.

  2. Click New.

  3. For the provider type, select OpenID Connect.

  4. Enter a name for the provider.

  5. Enter the URL suffix, which is used in the client configuration URLs. For example, if the URL suffix of your authentication provider is MyOpenIDConnectProvider, your SSO URL is similar to https://_mydomain_url or site_url_ /services/auth/sso/OpenIDConnectProvider.

  6. For Consumer Key, use the client ID from your OpenID provider.

  7. For Consumer Secret, use the client secret from your OpenID provider.

  8. For Authorize Endpoint URL, enter the base URL from your OpenID provider.

    You can add query string parameters to the base URL, if necessary. For example, to get a refresh token from Google for offline access, use https://accounts.google.com/o/oauth2/auth?access_type=offline&approval_prompt=force. You need the approval_prompt parameter to ask the user to accept the refresh action so that Google continues to provide refresh tokens after the first one.

  9. Enter the token endpoint URL from your OpenID provider.

  10. Enter the User Info Endpoint URL from your OpenID provider.

    If you want to integrate the provider with your API using OAuth, a User Info endpoint isn’t required.

  11. 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.

  12. Optionally, set these fields.

    • The Token Issuer field identifies the source of the authentication token in the form https://URL.

      • For an OAuth 2.0 web server authentication flow, the provider must include an ID token in the response from the token endpoint. Optionally, the provider can include an ID token in the response for a refresh token flow.
      • The ID token is validated against the Token Issuer value and information in the UserInfo endpoint. The signature of the ID token isn’t validated.
      • The audience for the ID token is the consumer key registered with your authentication provider. Don’t include any other audience values.

    • For Default Scopes, enter the scopes to send along with the request to the authorization endpoint. Otherwise, the hard-coded defaults for the authentication provider type are used. See the OpenID Connect developer documentation for these defaults.

      For more information, see Use the Scope URL Parameter.

    • 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.

  13. Optionally, to have the token sent in a header instead of a query string, select Send access token in header.

  14. Optionally, to send the consumer key and secret in a Basic header instead of in the request body, select Send client credentials in header.

  15. Optionally, set these fields.

    • 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.

      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.

    • Select an existing Apex class as the Registration Handler class. Or to create an Apex class template for the registration handler, click Automatically create a registration handler template. Edit this class later, and modify the default content before using it.

      A Registration Handler class is required for Salesforce to generate the SSO initialization URL.

    • For Execute Registration As, select the user that runs the Apex handler class. The user must have the Manage Users permission.

      Execute Registration As provides the context in which the registration handler runs. Select a user regardless of whether you’re specifying an existing registration handler class or creating one from the template. 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.

    • To use a portal with your provider, select the portal from the Portal dropdown list.

    • 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.

  16. 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.

  17. Save the settings.

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

Client configuration URLs support additional request parameters that enable you to direct users to log in to specific sites, obtain customized permissions from the third party, or go to a specific location after authenticating.

After defining the authentication provider in Salesforce, go back to your OpenID provider and update your app’s callback URL. For Google apps, the callback URL is called the Authorized Redirect URI. For PayPal, it’s called the Return URL.

In a browser, open the Test-Only Initialization URL on the Auth. Provider Setup page. It redirects you to your OpenID provider and asks you to sign in. You’re then asked to authorize your app. After you authorize, you’re redirected to Salesforce.

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.