Login role mapping automatically assigns an EvTrack access role to a person as they log in through single sign-on, based on what their identity provider asserts about them - typically their group or app-role membership. It removes the need to manually keep EvTrack roles in sync with an identity provider’s directory: add someone to the right group in your identity provider, and their EvTrack role follows on their next login.
Before you start: you need single sign-on configured (see the Keycloak, Azure Entra ID and AD FS SAML configuration guides) and user administration rights. Login role mapping is configured from User Management > Settings > Single Sign On, with one panel per configured identity provider.
Claim sources
A claim source names which attribute in the identity provider’s assertion carries the values you want to map - groups, app roles, or anything else your identity provider sends. Each source has a label, a preset that pre-fills the attribute name for common identity providers (Microsoft Entra ID groups or app roles, AD FS Group or Role, Keycloak groups or roles, Okta/Google Workspace groups), or a custom attribute name of your own, and can be enabled or disabled independently of the rules built on it.
Rules
A rule maps one exact value from a claim source to one EvTrack access role: “if the source’s value equals this, grant this role.” Values match exactly, case-insensitively. A rule can be enabled or disabled without deleting it - disabling stops it granting the role on future logins, but never revokes a role a user already holds: a matching rule always applies its role, and a login matching no rule always leaves an existing user’s current role alone (see Unmatched-user policy, below).
A rule that grants an administrator role, or a role carrying sensitive permissions (such as viewing every visitor), needs one extra step: after saving, a confirmation page opens asking you to type the role’s name before the rule takes effect. This is the same deliberate pause used when granting an administrator role to a user directly - it ensures handing out powerful access through a rule is always something you chose, not something a directory change slipped through silently.
Example: mapping Microsoft Entra ID app roles
A common setup drives EvTrack roles from Entra app roles (rather than group object IDs, which Entra caps at 150 per login). Create one app role in Entra per EvTrack role you want to grant, assign people to them, then add a single claim source (preset Microsoft Entra ID - app roles) and one rule per app-role value:
| App-role value Entra sends | EvTrack access role |
|---|---|
evtrack-admin | Administrators |
evtrack-power-user | Power Users |
evtrack-receptionist | Receptionists |
evtrack-guard | Guards |
evtrack-host | Hosts |
The value on the left is a label you choose in Entra; only the exact string has to match the rule. With this set and an unmatched-user policy of Assign the default role, a new person who carries none of these app roles is created with the system default role, while anyone carrying evtrack-admin becomes an administrator (after the one-time name-confirmation step described above). The step-by-step Entra side is in the Azure Entra ID SAML configuration guide.
Unmatched-user policy
For each identity provider, decide what happens when a login matches none of the configured rules. This setting governs new-account creation only:
- Assign the default role - the default setting, matching legacy behaviour. A brand-new person logging in for the first time with no matching rule has their account created with the system default role.
- Keep their current role - the stricter option. A brand-new person logging in for the first time with no matching rule is not provisioned at all; nothing is created.
An existing user’s login that matches no rule always keeps their current role, regardless of this setting - the policy never resets or demotes anyone who already has an account. Disabling or deleting a rule works the same way: it stops the rule granting its role on a future login, but never revokes a role a user already holds.
Dry-run
Before relying on a rule set, use Dry-run to test it without saving anything:
- Pasted values - paste sample attribute values (one per line) and see which rules match and which role would result, for both an existing user’s login and a brand-new one.
- A user’s last login - look up what a specific user’s most recently stored login would resolve to under the current rules, using the attributes actually received the last time they logged in.
The result shows the winning role, which rules matched, any values that were ignored, and in Microsoft Entra ID’s case whether the identity provider omitted the groups claim because the user belongs to more than 150 groups (the “group overage” case - EvTrack leaves the role unchanged rather than guessing when this happens).
The user page panel
Once a person has logged in via single sign-on at least once, their user record’s Profile tab shows a read-only Single sign-on panel: the identity provider and time of their last login, the outcome (a rule matched, no rule matched, or the account was created at first login), the resolved role, the linked login, which rules matched, and the raw attributes the identity provider sent. A banner on the panel notes when the role is managed by login mapping, so a manual role change from the user’s edit page is not mistaken for permanent - it is replaced again on the user’s next login whenever a rule matches. See Edit a User for the panel in context.
Notes
- Roles managed by a rule show a read-only Login mapping panel on the role’s own edit page, listing every rule that currently grants it - see Roles.
- Configuring the identity provider side of this - which attribute carries groups or roles, and how to send it - is covered per identity provider in the Azure Entra ID and AD FS SAML configuration guides, and in the Keycloak SAML configuration guide for a Keycloak broker in front of any of these.
- If you register more than one identity provider, note that an unlinked user’s account can be linked by whichever registered identity provider first asserts a matching email address.