Once a connection exists, Role mappings decide which Buttons roles a person gets when they sign in through it: based on claims their identity provider actually sends, re-evaluated every time they sign in.
Before you begin#
Add a mapping#
- Open the connection and find Role mappings: "Map ID-token claims to local roles. Changes save immediately."
- Enter a Claim name (for example,
groups), a Claim value matching what your provider actually sends, and the Local role to grant when it matches. - Add as many mappings as you need: several claim values can point at the same role, and one claim value can be reused across several mappings pointing at different roles.
Use Test mappings to paste a sample of decoded ID-token claims and see which roles it would grant, without needing a real sign-in to check your work.
Note
GitHub doesn't offer role mappings at all: it uses its own Required Organization setting instead. Google, Microsoft Entra ID, Okta, and LDAP each show their own short caveat about how their group claims actually behave; read it before assuming your claim name is right.
Understand when sync actually runs#
Role sync isn't a one-time provisioning step: it runs on every sign-in, comparing what the current login's claims justify against the SSO-granted roles the person already has, and adds or removes roles to match. A role this connection previously granted can be taken away on a later login if the claim that justified it is no longer present.
These are genuinely different outcomes:
- A claim is simply absent from a login's claims (the person's group membership changed, for example): the role tied to that specific mapping is removed on this login, same as any other reconciliation. They are not able to keep their last-known access.
- A claim's shape is malformed or ambiguous: for example, a value your mapping expected as a string arrives as a number or object, or Microsoft Entra ID sends a group "overage" claim because there are too many groups to list: the entire sign-in is rejected outright, with the message "Sign-in could not determine your access. Please contact your administrator." Buttons refuses to guess at partial or unreliable data rather than granting or revoking access on it.
Override a role manually#
An admin can still grant a role to an SSO-authenticated user by hand, the same way as any other user. A manually granted role survives every future sync, even if the identity provider's claims never grant it: Buttons tracks manual grants separately and never removes them through reconciliation.
The reverse isn't quite symmetric: if a role is still being actively granted by a live claim mapping, removing it from the user manually won't make it stick: the next sign-in re-grants it via that mapping. To durably take a role away from someone whose claims currently justify it, change or remove the mapping itself rather than just unassigning the role.
Delete a mapping#
Deleting a mapping shows an explicit warning: "Delete the mapping {claim}={value}? SSO role assignments granted by this mapping will be removed immediately. Manual role assignments are not affected." Manually granted roles are never touched by deleting a mapping.
What happens when you disable or remove a connection#
Disabling or deleting an SSO connection takes effect immediately, not just for future logins:
- Every role contribution from that connection is removed at once, and any role left with no other reason to exist (not manually granted, no other mapping still justifying it) is dropped.
- Every active session signed in through that connection is signed out immediately.
- The user's account itself isn't deleted: it persists as a local account with no SSO-derived roles, effectively an orphan until it's given local access some other way.
What happens if a user is removed from the identity provider itself#
Buttons has no way to know this happened: there's no background check or scheduled sync against your provider. An already-active session for that person keeps working until it naturally expires or an admin kicks it manually. Nothing changes on the Buttons side until they try to sign in again, at which point the failure happens on your identity provider's end, outside Buttons' control.
If you get stuck#
What you see | What to try |
|---|
A user lost a role they used to have. | Check whether the claim that justified it is still present in their current login: sync runs every sign-in and removes roles that no longer match. |
A sign-in fails with "Sign-in could not determine your access." | A claim arrived in an unexpected shape (or, for Microsoft Entra ID, a group-overage claim): check your provider's claim configuration, not just the mapping itself. |
You manually assigned a role but it keeps disappearing. | A live claim mapping may not be granting it, and something else is removing it: check for a mapping actively removing that role, not just add one back manually. |
You removed a role from a user but it came right back. | A claim mapping is still actively granting it: adjust or remove the mapping itself rather than the user's role assignment. |
You disabled a connection and users got signed out unexpectedly. | That's expected: disabling a connection immediately revokes its role contributions and kicks every session it authenticated. |
Someone was removed from the identity provider but still has an active Buttons session. | |
Where to go next#
