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.
Required Editions
| Available in: Lightning Experience and Salesforce Classic |
| Available in: Enterprise, Performance, Unlimited, and Developer Editions |
Before You Start: Get Familiar with Flows
If you're new to flows, use these resources to get up to speed.
- Trailhead resources:
- Salesforce Help resources
View the Flow
To view the template, from Setup, enter Flows in the Quick Find box, and then select Flows. Click New Flow and select the Authentication Provider User Registration template.
The flow consists of many different elements, including decision, action, and assignment elements. To see details for a specific element, click the element. We recommend that you click through each element as you follow this document.
We also recommend that you familiarize yourself with the variables that are included in this flow. To view all variables, open the Toolbox. To learn more about a specific variable, such as its properties and where it's used in the flow, click the variable name.
How the Flow Launches
The flow begins with a Start element. For this flow type, if the flow is
configured as the registration handler in the authentication provider definition, the flow
is automatically launched during SSO. After the identity provider authenticates the user, it
returns user information to Salesforce. Salesforce uses this information to create an
Auth.UserData object. At this point, the flow starts.
Get Information from the Identity Provider
The flow starts by getting information from the identity provider. When Salesforce creates
the Auth.UserData object, it exposes the identity provider's user info
response and ID token, if returned. To retrieve specific information from these responses,
you can use the Get User Data from JSON String action.
The action takes two input parameters. The first input parameter is the JSON Object String.
In this parameter, specify the user info response or ID token. To specify the user info
response or ID token, reference fields on the Auth.UserData object.
- The full user info response is stored in the
userInfoJSONStringfield. - The decoded JSON Web Token (JWT) payload of the ID token is stored in the
idTokenJSONStringfield.
The template contains an Apex-defined variable, authUserData, to store the
Auth.UserData object. Use this variable to reference the
userInfoJSONString or idTokenJSONString fields from
authUserData as an input parameter, such as
{!authUserData.userInfoJSONString}.
The second input parameter is the JSON Attribute Key. In this parameter, specify the JSON variable path for a specific attribute that you want to retrieve. For example, consider a JSON string with nested attributes.
{"location": [ { "type": "office", "city": "San Francisco"}, {"type": "home", "city":"New York"}]}To retrieve the value of the type attribute for the first location, use
this JSON variable path: $.location[0].type.
The action returns the value of the attribute and stores the value in an instance of the
JsonValueOutput Apex class. To easily use it later in the flow, manually
assign it to a variable. For example, in the template, the action retrieves a user ID value
and stores it in the federationIdentifier variable. If you go to the
Toolbox and click federationIdentifier, you can see that this
Apex-defined variable uses the JsonValueOutput class.
Here's a summary of how this action works.
| Task | Flow Element | Flow Element Name in Template | How it Works |
|---|---|---|---|
| Get user information from the ID token or user info response returned by the identity provider. | Get User Data from JSON String invocable action | Get User Data from JSON String | This action takes two input parameters:
The action returns the value of the attribute specified in the JSON Attribute
Key. Each action returns an instance of the |
Decide Whether to Create or Update a User
After the flow retrieves user information, it's time to make the first decision in the flow: whether to create a user or update an existing user. To make this multi-part decision, it's important to understand how Salesforce links users to the identity provider.
When a user logs in to Salesforce via an identity provider using the authentication provider framework, Salesforce creates a ThirdPartyAccountLink record. You can use this record in your flow to determine whether a given user has previously authenticated with this identity provider.
To make this process easier, Salesforce includes an existingUserIdFromTpal variable in the flow. This variable is marked as available for input, meaning that the value comes from outside the flow. In the template, Salesforce automatically sets this value when the flow runs. To set the value, Salesforce uses the third-party identifier from the identity provider to look for a ThirdPartyAccountLink with a matching remoteIdentifier value. If Salesforce finds a ThirdPartyAccountLink, it stores the value of its UserId in the existingUserIdFromTpal variable.
If the user has previously authenticated with the identity provider, the user exists in Salesforce and the flow can proceed with updating the user. In the template, we refer to a user who has a ThirdPartyAccountLink as a linked user.
If the user hasn't authenticated with the identity provider, you don't know whether the
user exists in Salesforce. It's possible that the user exists in Salesforce but hasn't used
this identity provider before. To determine whether the user exists, the flow uses the
information from the identity provider returned in the Auth.UserData
object. It looks for a user record with attribute values that match values in the
Auth.UserData object.
If the flow finds a matching user, it updates the user information from the identity provider. In the template, we refer to a user who exists but who doesn't have a ThirdPartyAccountLink as an existing user. If the flow doesn't find a matching user, it's time to create a user.
Here's how the template completes these tasks.
| Task | Flow Element Type | Flow Element Name in Template | How It Works |
|---|---|---|---|
| Decide whether you can update the user immediately or must continue looking for a user based on whether the user has previously authenticated with this identity provider | Decision | Is Third-Party Account Linked? | Checks whether there is a ThirdPartyAccountLink by looking for a value for the existingUserIdFromTpal variable. If existingUserIdFromTpal is null, the outcome is No and the flow proceeds to the Find Existing User element. If there is a value for existingUserIdFromTpal, the outcome is Yes and the flow proceeds to update the linked user. |
If the user hasn't previously authenticated with the identity provider, look
for an existing user record that matches information from the
Auth.UserData object. |
Get Records | Find Existing User | Looks for a user record with attributes, such as email address, that match
attributes from the Apex In the template,
the element filters for user records where the value of the
Email field on the user record matches the value of the
|
| Decide whether to update or create a user | Decision | Was Existing User Found? | Determines whether to create a user or update an existing user by checking if the Find Existing User element returned a user record. If the Find Existing user action returned a user ID, the outcome is Yes and the flow proceeds to update the existing user. If there's no matching user, the outcome is No and the flow proceeds to create a user. |
Generate User Data
If you determine that 1) the user hasn't logged in previously and 2) there's no matching user information in Salesforce, it's time to create a user. A prerequisite for creating a user is having enough user data to create a complete user record. In some cases, the identity provider doesn't return enough information to create a complete user record in Salesforce. If that's the case, use the Generate User Data invocable action to generate placeholder values for the missing user data. You can update the values later.
This action doesn't take any input parameters. Its output is a set of placeholder values for these fields. Here are the fields and default values.
| User Field | Generated Placeholder Value |
|---|---|
alias |
alias |
email |
placeholder-email@example.com |
emailEncodingKey |
A default value based on the user context. |
firstName |
placeholder-first-name |
languageLocaleKey |
A default value based on the user context. |
lastName |
placeholder-last-name |
localeSidKey |
A default value based on the user context. |
timeZoneSidKey |
A default value based on the user context. |
username |
placeholder-username<uniqueNumber>@example.com For example, placeholder-username17300000000000@example.com. The unique number is 14 digits long. |
The generated user data is stored in an instance of the GeneratedUserData
Apex class. Later, when the flow creates a user, it sets the values of fields on the User
object by using the outputs of this action. Here's a summary of this action.
| Task | Flow Element Type | Flow Element Name in Template | How It Works |
|---|---|---|---|
| Generate placeholder values for user data that isn't supplied by the identity provider | Generate User Data invocable action | Generate User Data | Generates placeholder values for the fields that are required to create a user, including a unique placeholder username. Reference the values later when you create a user. For example, set the Alias field on the User object to {!GenerateUserData.generatedUserData.alias}. |
Decide What Type of User to Create
If you use your flow for both Salesforce orgs and Experience Cloud sites, include a way to decide whether to create an internal user, such as an employee or contractor, or an external user, such as a customer or partner. There are different requirements for each user type. Both internal and external users require a profile, but external users also require an account and contact.
To help decide what type of user to create, the template includes an IsUserExternal boolean variable that's used as an input for the flow. Salesforce automatically sets the value of this variable based on whether the user is logging in to a Salesforce org or an Experience Cloud site.
| Task | Flow Element Type | Flow Element Name in Template | How It Works |
|---|---|---|---|
| Determine whether to create an internal or external user | Decision | Is User External? | In the template, this decision checks whether the value of the isExternalUser boolean value is true or false. If the user is an internal user, the outcome is No and the flow proceeds to assign a profile and create the user. If the user is an external user, the outcome is Yes and the flow proceeds to assign an account and contact to the user. |
Handle Profile Assignments for New Users
To create an internal or external user, you must assign a profile. Salesforce supports these ways to specify the default profile.
- Specify a default profile when you define your authentication provider. The defaultProfileId variable in the template automatically stores this value.
- Specify a default profile in your flow.
If you specify a default profile in both the authentication provider definition and the flow, Salesforce uses the value specified in the flow.
The template shows you both ways to set a profile. For external users, the template uses the profile specified in the authentication provider, and there are no extra steps in the flow to set a profile.
For internal users, the template specifies a default profile in the flow by using a Get Records element.
| Task | Flow Element Type | Flow Element Name in Template | How it Works |
|---|---|---|---|
| Set a default profile for new users. | Get Records | Get User Profile | Finds a specific profile and then updates the defaultProfileId variable to store this value. The template filters by profile name to find the Standard User profile. The action is configured to store the ID of the matching profile in the defaultProfileId variable. |
Handle Account and Contact Assignment for New External Users
To create an external user, you must assign them to an account and create a contact that associates the user with the account. Salesforce supports different ways to assign the default account for new external users.
- Specify a default account when you define your authentication provider. The defaultAccountId variable in the template automatically stores this value.
- Create a default account in your flow.
If you specify a default account in both the authentication provider definition and in the flow, Salesforce uses the value specified in the flow.
Here's how the template approaches these steps.
| Task | Flow Element Type | Flow Element Name in Template | How it Works |
|---|---|---|---|
| Decide whether to create a default account by checking whether a default account is specified in the authentication provider definition. | Decision | Is Default Account Defined? | In the template, this decision checks whether there is a value in the defaultAccountId variable. Salesforce automatically sets the value of this variable based on the default account specified in the authentication provider definition. If Yes, the flow uses the value of the defaultAccountId variable for the new user. If No, the flow creates an account. |
| If no default account is specified in the authentication provider definition, create a default account for new users. | Create Records | Create Account | Creates an account named Social Sign-On and assigns it as the defaultAccountId. To create only one account the first time the flow runs, we recommend that you configure this element to prevent duplicate records. If an account named Social Sign-On exists, the flow doesn't create an account. |
| Create a contact for the new user | Create Records | Create Contact | Creates a contact with information from the Auth.UserData
object and associates the contact with the default account by setting the
Account ID field to the value of the
defaultAccountId variable. |
Create a User and Manage Permission Sets
After the flow handles profile, account, and contact assignments for new users, it finally creates the user record and assigns permission sets. For this section of the flow, it's important to complete these steps in this order.
- (1) Create the user record.
- (2) Assign the new user ID to the userIdOutput variable. Behind the scenes, Salesforce uses this variable to complete permission set assignments.
- (3) Assign permission sets to the created user.
After the third step, the user creation process is complete. When a user logs in and the flow determines that they don't exist in Salesforce, the flow creates a user record. The login process also creates a ThirdPartyAccountLink. The next time the user logs in, the flow treats them as a linked user.
| Task | Flow Element Type | Flow Element Name in Template | How It Works |
|---|---|---|---|
| Create the user. | Create Records | Create User | Creates a user record by using information from the
Auth.UserData object for some fields, such as the first name. For
other fields, it uses the placeholder values generated by the Generate User Data
action, such as {!GenerateUserData.generatedUserData.alias}. Other
values, such as language, are set directly in the flow. The contact is set as the
contact ID from the Create Contact element. |
| Assign the user ID for the new user to an output variable so that the Salesforce runtime can complete additional assignments, such as assigning permission sets. This step is required when you create a user. | Assignment | Assign Created User ID to Output Variables | Assigns the user ID for the created user to the userIdOutput variable. |
| Control user access by adding permission sets | Assignment | Manage Permission Sets for Created User | Adds permission sets to the updated, existing user based on the desired level of access. The flow template uses the permissionSetsToAdd variable to store the permission set API names. You can't remove permission sets from a created user. If you include permissionSetsToRemove in this assignment, the flow fails with an execution error. |
Update an Existing User
Now that we reviewed the steps to create a user, let's look at the processes for updating users. In the template, go back to the Was Existing User Found? decision. If the outcome of this decision is Yes, it means that 1) the user who logged in doesn't have a ThirdPartyAccountLink and 2) the user exists in Salesforce. We refer to a user who meets these criteria as an existing user.
To update the existing user with information from the identity provider, use an Update
Records element to pull information from the Auth.UserData object into the
user record. Optionally, you can decide to add or remove permission sets depending on the
level of access you want the user to have.
When a user logs in and the flow determines that they exist in Salesforce but don't have a ThirdPartyAccountLink, the flow updates the user. The login process also creates a ThirdPartyAccountLink. The next time this user logs in, the flow treats them as a linked user.
Here's how the template accomplishes these steps.
| Task | Flow Element Type | Flow Element Name in Template | How It Works |
|---|---|---|---|
| Update the existing user with information from the identity provider | Update Records | Update Existing User | Updates the existing user record with information from the
Auth.UserData object. To specify the user record, it filters for
records where the user ID matches the user ID returned by the Find Existing User
element ({!FindExistingUser.Id}). |
| Assign the user ID for the updated, existing user to an output variable so that the Salesforce runtime can complete additional assignments, such as assigning permission sets. This step is required when you create a user, but it isn't required to update an existing user. You can include it for consistency or opt to remove it entirely. | Assignment | Assign Updated User ID to Output Variable | Updates the value of the userIdOutput variable to the existing user ID. |
| Control user access by adding or removing permission sets | Assignment | Manage Permission Sets for Updated User | Adds or removes permission sets from the updated, existing user based on the desired level of access. The flow template uses the permissionSetsToAdd and permissionSetsToRemove variables to store the permission set API names. |
Update a Linked User
In the template, go back to the Is Third-Party Account Linked? decision. If the outcome of this decision is Yes, it means that the user who logged in has a ThirdPartyAccountLink and therefore exists in Salesforce. We refer to a user with a ThirdPartyAccountLink as a linked user. The flow can proceed to update the linked user based on information from the identity provider. These steps are similar to the steps for updating an existing user.
| Task | Flow Element Type | Flow Element Name in Template | How It Works |
|---|---|---|---|
| Update the linked user with information from the identity provider | Update Records | Update Linked User | Updates the linked user record with information from the
Auth.UserData object as well as the identifier returned from the
Get User Data from JSON String action (stored in the
federationIdentifier variable). To specify the user record,
it filters for records where the user ID matches the value of the
existingUserIdFromTpal variable. |
| Assign the user ID for the updated, existing user to an output variable so that the Salesforce runtime can complete additional assignments, such as assigning permission sets. This step is required when you create a user, but it isn't required to update a linked user. You can include it for consistency or opt to remove it entirely. | Assignment | Assign Linked User ID to Output Variable | Updates the value of the userIdOutput variable to the linked user ID. |
| Control user access by adding or removing permission sets | Assignment | Manage Permission Sets for Linked User | Adds or removes permission sets from the updated, linked user based on the desired level of access. The flow template uses the permissionSetsToAdd and permissionSetsToRemove variables to store the permission set API names. |
Next Steps
When you understand how each part of the template works, customize the template for your use case. Add your flow when you define the authentication provider.
Make sure that you understand how to test, deploy, and monitor your flow. For more information, see these resources.
