This article describes how to pass additional user-profile data when connecting users via single sign-on (SSO). Let's walk through how to set it up.
Create a field
1. Access the Dashboard.
2. Navigate to the Settings > Membership > User Profile page.
3. Click Add Field and set the following:
- Type - Select the type of field you require: Single Textbox, Multi-line Textbox, Single Checkbox, Single-select Dropdown, Multi-select Dropdown, Date Picker, Numeric Input, Numeric Dropdown.
- API Label - This is a machine-readable key that will be used to store and access this data. For this reason, it cannot be changed once set or the data will be “orphaned.” The API label cannot contain white-spaces, slashes, or periods, so a Label like "Player Level" must be "playerLevel."
- Label - Enter a human-readable label. This is the label that users will see on registration or edit forms, or on their profile page. The Label can have spaces and special characters (even emojis). This can be changed after you have saved it because it's just a visual interface in a form. Enter, for example, “Player Level”.
Complete the remaining fields as desired: Description, Visibility, Editing, Registration Options.
- 4. Click Save to create your custom field.
To learn about the other fields that you can set, see:
Pass the User Profile data
Pass the User Profile data from your identity provider to Vanilla as a user attribute. The key of the profile field being sent must be the API Label.
🛑 IMPORTANT: The field must be an exact match to the API Label. Below is an example of a JSON object returned in an OAuth2 User Info Request, but the same principle applies in a OIDC IDToken or a SAML user attribute.
{
"Email": "ian@example.com",
"Photo": "https://cdn.ouravatars.com/avatar/1fa90f330a58f5d.png",
"Name": "Ian",
"FullName": "Ian Devloper",
"UniqueID": "fa0e81fa65e8",
"PlayerLevel": "Novice",
"TopRatetodate": "11",
"email_verified": true,
"Provider": "oauth2"
}
Remember, it's an exact match so it’s case-sensitive. If you send "playerlevel" instead of “playerLevel”, it will not throw an error but it will be ignored, and it will not pass the Player Level to the user's profile.
User Profile Fields and the Connection Workflow
Now that your User Profile Fields are set up and you're passing user data over SSO, what will the user experience be during the first connection and subsequent logins?
“User connection” refers to the first time a user connects to your Vanilla application over SSO. This could mean that the user already exists in your Vanilla application (for example they were migrated from another platform), or they are joining for the first time, and a new user is being created.
Creating a new user
During the connection workflow of a new user, if there are any user profile fields configured with:
- visibility of private or public (i.e., not ‘internal’), and
- Registration Option of either optional or required (i.e., not ‘hidden’),
the connection workflow will stop and present these fields to the user. Any data passed from the Identity Provider will populate these fields. Fields that do not have data being sent from the Identity Provider will be empty. The user will be able to add or change the data in these fields at this time. If a field is required, the user will be forced to fill in the required field to complete the connection process.
Any profile fields with a Visibility of ‘internal’ or a Registration Option of ‘hidden’ will receive and store user profile data passed from the Identity Provider without the connecting user seeing it.
📝 NOTE: Even if a field’s editing option is configured to block (meaning they cannot edit this field on their User Profile page), they can edit it during the connection process.
Connecting to an existing user
This section pertains to users connecting to your Vanilla application for the first time using SSO when they already have a user record on the Vanilla application (either because the record was migrated from another platform when the Vanilla instance was set up or the user had previously signed up using Vanilla’s native registration form).
During the connection workflow for existing users, no matter what configuration you have for user profile fields:
- visibility of either private, public, or internal or
- registration option of either optional, required, or hidden,
the connection workflow will not be interrupted to present the user with these fields, even if the data being passed from the Identity Provider is empty and the field is required. If data is passed from the Identity Provider, it will overwrite any existing User Profile data.
