When someone logs in through SSO, your identity provider sends CheckHub a short description of that user. This article explains what we need in it, and how to configure it in your provider.
This applies whichever identity provider you use, so read it alongside your provider's setup article.
The user attributes
CheckHub builds each user's profile from these attributes. The names must match exactly, capital letters included.
Attribute | Required | What it holds |
email | Yes | The user's email address — this is how we recognize the user |
firstName | Yes | Given name |
lastName | Yes | Surname |
phone | No | Mobile or contact number |
language | No | Interface language: en, fr, nl, de or it |
language is only applied when the account is created at the user's very first login. After that the user chooses their own language in CheckHub and your provider won't overwrite it. If you don't send it, new users get your company's default language.
In Microsoft Entra ID, go to Single sign-on > Attributes & Claims > Edit and map user.mail to email, user.givenname to firstName, user.surname to lastName and user.mobilephone to phone. Clear the Namespace field on each one — the claim must be named email, not http://schemas.xmlsoap.org/.../emailaddress.
Use user.mail, not user.userprincipalname. In many tenants the User Principal Name isn't the user's real email address — it can look like jdoe@example.onmicrosoft.com — and CheckHub recognizes people by their email. Only use the UPN if you've checked that it matches the email address for everyone.
In Google Workspace, on the Attribute mapping screen, use the Attributes section at the top. Map Basic Information > Primary email to email, First name to firstName, Last name to lastName and Phone > Phone number to phone. Use ADD MAPPING to add a row.
The groups claim
Groups decide what a user can do inside CheckHub. Your provider must send a claim named groups containing the user's groups, and we apply a simple rule:
- If at least one group matches a CheckHub group, the user logs in and joins every group that matched.
- If nothing matches, the user is refused and sent back to the login page.
Group membership is synchronized at every login, not just added to. If you remove someone from a group in your directory, they are removed from the matching CheckHub group the next time they log in. Your directory stays the single source of truth.
This means group mapping isn't optional. Someone with a perfectly valid account and no matching group simply can't log in.
Getting your groups to match
You don't need us for this. Your groups belong to your company, so you can set this up yourself.
In CheckHub, go to Settings > Groups, open a group, and look at the Group settings tab. Two fields are used for matching:
- External ID — a free text field, described as External identifier for SSO integration. This is the one built for the job.
- Name — the group's name in CheckHub.
A group matches if either field is identical to a value in the groups claim. We recommend using External ID: it accepts whatever your provider happens to send, so you can keep your CheckHub group names readable for your team.
In your SAML app, go to Attributes & Claims > Add a group claim, choose Groups assigned to the application, and name the claim groups.
With this option Entra sends only the groups assigned to the application. If you assigned individual users instead, the claim arrives empty and nobody can log in — with no error message on screen. Open Users and groups in the application and assign the groups themselves.
Entra ID sends group Object IDs by default, not names — you'll see 8f4a1c2e-... rather than Recruiters. So:
- In Entra ID, go to Groups > All groups and copy the Object Id of each group you're sending. This is the value CheckHub expects.
- In CheckHub, open the group it corresponds to and paste that value into External ID.
If you'd rather send names, set Source attribute on the group claim to the cloud group display names (or sAMAccountName for groups synced from on-premises Active Directory), and put that name in External ID instead.
On the same Attribute mapping screen, scroll to the Group membership (optional) section below. Add the groups to send under Google groups, and set the App attribute to groups.
Google sends group names — there are no group IDs to use here. Put the Google group name in the External ID field of the matching CheckHub group.
Keeping it up to date
If you rename a group in your directory, or start sending a different set of groups, update the External ID of the matching CheckHub group at the same time. A group that no longer matches will lock its members out at their next login.