Create an Authentication Provider Registration Handler
To set up single sign-on (SSO) with an authentication provider, you must set up a registration handler. The registration handler creates and updates Salesforce users after they authenticate with the identity provider. To set up a registration handler, you can use Flow Builder or Apex.
Required Editions
| Available in: Lightning Experience and Salesforce Classic |
| Available in: Enterprise, Performance, Unlimited, and Developer Editions |
What Does a Registration Handler Do?
To understand the role of a registration handler during SSO, here's a simplified overview of how SSO works with the authentication provider framework.
- (1) The end user goes to Salesforce and clicks a button to log in with an identity provider, such as Google.
- (2) Salesforce redirects the user's browser to the identity provider's login page.
- (3) On the identity provider's login page, the user enters their credentials.
- (4) The identity provider authenticates the user and returns tokens to Salesforce, including an ID token.
- (5) If the identity provider supports a user info endpoint, Salesforce uses the tokens to request a user info response.
- (6) If supported, the identity provider returns a user info response.
- (7) Using information returned from the identity provider, Salesforce builds an Apex
Auth.UserDataobject to represent the user. - (8) In Salesforce, the registration handler takes the information from the identity
provider and completes these actions.
- The registration handler looks for a Salesforce user with information that matches the information returned by the identity provider.
- If there isn't a matching user, the registration handler creates a user record.
- If there is a matching user, the registration handler updates the user record with information from the identity provider.
- (9) The created or updated user is logged in to Salesforce and can access their Salesforce data.
Choose a Registration Handler Type
Before you choose a registration handler type, consider the basic design of your registration handler. When you have an idea of its design, it's easier to determine whether flow or Apex is better for your use case. At minimum, your registration handler must accomplish these tasks.
- Take information from the identity provider and look for a matching user record in Salesforce. Depending on your identity provider, this step can require parsing complex JSON structures.
- Decide whether to create a user or update an existing user.
- Create a complete user record based on information from the identity provider.
- Update an existing user with information from the identity provider.
There's no hard rule for what type of registration handler to use. When you review these considerations, think about what you want the registration handler to do and what resources you have available.
| Consideration | Flow | Apex |
|---|---|---|
| Performance and scale for complex use cases | Supports most use cases, but isn't always ideal for very complex use cases | Supports more complex use cases |
| Accessibility and maintainability | Can be configured and maintained entirely with clicks instead of code. No developer knowledge is necessary. | Requires an Apex-trained developer to develop and maintain |
| User access | Provides built-in way to control user access by adding and removing permission sets in a single transaction, which helps you avoid mixed DML errors that are common with Apex | Can be more complex to manage permission sets while avoiding mixed DML errors |
| Parsing information from the identity provider | Provides invocable action to retrieve a specific attribute value from complex, nested JSON structures. If the identity provider returns a user info response and ID token, this action makes it easier to retrieve information. | To retrieve information from the user info response or ID token, you must build a method to retrieve specific attribute values from the identity provider. |
- Develop an Apex Registration Handler
To set up single sign-on (SSO) with an authentication provider, you must build a registration handler. During SSO, the handler creates and updates users based on information from the identity provider. For high-scale, high-performance use cases, develop a registration handler with Apex. - Design an Authentication Provider User Registration Flow
Before you set up an authentication provider registration handler with Flow Builder, understand registration handler requirements. - Example: Authentication Provider Registration Handler Flow
To create a registration handler flow for single sign-on (SSO), customize the Authentication Provider User Registration Flow template. The template creates and updates both internal and external users. It shows you how to use the Get User Data from JSON String and Generate User Data invocable actions. It also shows you how to manage permission set assignments. - Troubleshoot an Authentication Provider User Registration Flow
When you use a flow for authentication provider user registration, there are some errors that are revealed only when you run the flow. Learn how to update your flow based on execution errors.
Did this article solve your issue?
Let us know so we can improve!
