Role mapping

Four sources can grant a role. They are unioned, then filtered to Seylo’s four roles.

Source	When it applies
The role claim or attribute	Each value is looked up in your role map
Default roles	Only when the claim yielded nothing at all
Base roles	To every authenticated member of your organisation
Explicit user roles	To one named subject or email address

The rule that prevents accidents

A value with no entry in your role map grants nothing. It is never passed through.

This matters more than it sounds. If your directory happens to contain a group literally called admin — created years ago, for something unrelated — it must not become Seylo admin because the names happen to match. Mapping is explicit, always.

Claim shapes

For a role claim, all of these work:

an array — ["releaser", "approver"]
a space- or comma-delimited string — "releaser approver"
a single scalar — "admin"

Nested paths are supported: realm_access.roles, resource_access.my-client.roles. An exact top-level key match wins over path splitting — which is what makes an Auth0 namespaced claim like https://seylo/roles work despite containing dots.

Empty is a legitimate outcome

A user with no mapped roles is authenticated and authorised for nothing. Every action returns 403.

Test login reports this explicitly rather than leaving it to be discovered, because the alternative — a user who signs in successfully and then finds every button greyed out — is a support ticket.

Base roles vs default roles

These are easy to confuse and behave differently:

	Applies
Default roles	Only when the claim produced nothing. A safety net for users your directory has no grant for
Base roles	To everyone, always, in addition to whatever the claim produced. A floor

Use base roles when everyone who can sign in should at minimum be able to look — the standard Google Workspace setup. Use default roles when you want an unmapped user to land somewhere specific rather than nowhere.

Explicit user roles

Granted to one named subject or email address. Two properties make them safe:

They are additive — they never remove anything.
They cannot let anyone in. They are applied only after the token has been validated and your organisation resolved, so your directory remains the sole authority on who can sign in.

Verifying a mapping

Do not verify by asking someone to try signing in. Use test login: it shows the contribution of each of the four sources and the final role set, per value, with the reason anything did not map.