# Map identity claims to roles

> How role mappings turn identity provider claims into Buttons roles, and what happens on every sign-in, manual override or removed connection.

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 An SSO connection already configured: see Connect a generic OIDC provider or Connect LDAP or Active Directory . At least one Role already created: see Create roles and assign permissions . 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. Select Add mapping . Repeat for each mapping you need. Several claim values can grant the same role. One claim value can grant several roles. Select Test mappings , enter sample claims as a JSON object, and select Run test to preview the matching roles. Each sample value must be a string or an array of strings. For example: {"groups": ["operators"]} Include only the claims you want to test. A full decoded ID token can contain numbers, booleans, or objects that the test input does not accept. The test does not store the sample or perform a real sign-in. 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 For connections that support role mappings, role sync runs on every sign-in . Buttons adds or removes that connection's role contributions to match the current claims. A user loses a role only when no manual grant or other SSO contribution still grants it. What happens when a claim is missing vs. malformed A mapped claim is absent or no longer matches: Buttons removes that mapping's role contribution on this sign-in. The user keeps the role if a manual grant or another SSO contribution still grants it. A mapped claim has an unsupported value: Mapped claims must contain a string or an array of strings. A number, object, or other unsupported value causes Buttons to reject the sign-in before changing role assignments. Unsupported values in unrelated claims do not cause this rejection. Microsoft Entra ID reports group overage: Buttons rejects the sign-in because the token does not provide a complete group list. For either rejection, Buttons shows "Sign-in could not determine your access. Please contact your administrator." 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. Removing a role manually clears only its manual grant. If an SSO contribution still grants the role, the user keeps it immediately. Removing an SSO-only role manually has no effect. To remove SSO-granted access, change or remove the mapping, or change the user's matching claim at the provider. Provider claim changes take effect at the next sign-in. The user keeps the role if another grant still supports it. 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." Buttons removes that mapping's contributions immediately. Manual grants and other SSO contributions remain. Buttons also revokes active sessions authenticated through that connection for users who had a contribution from the deleted mapping. This happens even if another grant preserves their role. What happens when you disable or remove a connection Disabling or deleting an SSO connection takes effect immediately, not just for future logins: Buttons removes all role contributions from that connection. A user loses a role only if no manual grant or other SSO contribution remains. Buttons revokes every active session authenticated through that connection. Sessions authenticated locally or through another connection are not revoked by this operation. The user's account remains. Manual roles and roles from other connections remain. Disabling or deleting the connection does not create a local password or another sign-in method. What happens if a user is removed from the identity provider itself Buttons does not check the provider in the background for removed users. Removing a user at the provider does not automatically revoke their existing Buttons sessions or role assignments. Session refresh does not contact the provider or run role sync. It can extend access without another SSO sign-in, so session expiry is not a reliable deadline for removing access. At the next SSO sign-in, authentication depends on the provider's current response. To remove access promptly, revoke the user's active Buttons sessions rather than relying on provider removal alone. If you get stuck What you see What to try A user lost a role they used to have. Check the current claims and mappings. Sync removes unmatched contributions on every sign-in. The role disappears only when no manual grant or other SSO contribution remains. 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. SSO sync does not remove manual grants. Check whether another administrator or operation removed the manual assignment. You removed a role manually but the user still has it. An SSO contribution may still grant it. Change or remove the mapping, and check for other grants supporting the same role. 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. Provider removal does not revoke Buttons sessions, and refresh can extend them. Revoke the user's active Buttons sessions to remove that session access promptly. Where to go next Get started with SSO Create roles and assign permissions