Map OIDC Claims and Profile Fields
Configure email, name, and custom field claims for an OIDC provider.
Use this guide after the OIDC provider connection exists and before pilot testing. Built LMS requires a stable email claim for profile matching.
Before you begin
You need:
- A saved OIDC provider in Built LMS.
- Access to the IdP app's claim or token configuration.
- A pilot user assigned to the IdP app.
- Any Built LMS custom user fields you want to map already created.
Do not map a claim unless the IdP is the right source of truth for that value.
Confirm claim mapping
Built LMS reads these standard OIDC claims:
| Built LMS user field | OIDC claim | Required |
|---|---|---|
email | Yes | |
| Display name | name | No |
| First name | given_name | No |
| Last name | family_name | No |
The email claim must be stable and present for the pilot user. If the IdP
sends a different email than the user's Built LMS profile, the sign-in can
create or match the wrong identity.
If the IdP requires explicit claim configuration, configure the app to include:
subemailemail_verifiedwhen availablenamegiven_namefamily_name
Map custom user fields
Use custom field mappings only for claims that should update on each SSO login.
- In the OIDC provider form, find Custom field mappings.
- Select Add mapping.
- Enter the OIDC claim name.
- Select the Built LMS custom user field.
- Repeat for each field.
The mapping list is available only when active custom user fields exist in the organization.
Good candidates:
departmentemployeeTypemanagermanagerEmailcostCenter
Claim names must match exactly. If the IdP nests claims or uses namespaced claims, copy the exact claim name your IdP emits.
Verify success
Claim mapping is ready for pilot testing when:
- The IdP app sends
emailfor the pilot user. profileandemailscopes are requested when name and email claims are expected.- Optional name claims appear when your team expects them.
- Custom claim names match exactly.
- Active Built LMS custom user fields exist for every mapped field.
Troubleshooting
Check that the email scope is requested, the IdP app includes the email
claim, the pilot user has an email value in the IdP, and the email claim is
included in the ID token or UserInfo response.
Built LMS requires email for profile matching.
Check that the profile scope is requested, the IdP sends name,
given_name, and family_name, and the pilot user has those profile fields
populated in the IdP.
Name fields are optional, but they improve the user profile.
Check that the Built LMS custom user field is active, the claim name in the mapping matches exactly, the IdP sends the claim for the pilot user, and the claim is available to Built LMS through the ID token or UserInfo response.