SSO groups and roles
Map identity provider groups to nano groups, and keep access in sync at every SSO sign-in.
Manage nano access in your identity provider (IdP). Map IdP groups, such as siem-admins or siem-analysts, to nano groups. A nano group carries roles, so membership in the IdP group decides what the user can do in nano.
How it works
- You define roles on nano groups in Settings → Access Control → Groups. See Access control.
- On the SSO provider, you map each IdP group to one or more nano groups.
- When a user signs in with SSO, nano reads their IdP groups and adds or removes them from the mapped nano groups to match.
With SCIM provisioning, Okta and Entra ID can also push group changes and deactivations between sign-ins, using the same mappings.
Matching is exact and case-sensitive. siem-admins does not match SIEM-Admins or siem-admins with a trailing space.
How sync works
nano reconciles a user's groups on every SSO sign-in, in one step with the sign-in itself:
- SSO-managed groups follow the IdP. nano adds the user to every nano group their IdP groups map to, and removes them from mapped groups the IdP no longer sends.
- Manual grants are never touched. If an administrator added the user to a group by hand in nano, that membership stays, even when it is the same group a mapping grants.
- Lost access ends sessions. If the sign-in removes any group, nano signs the user out of every other session and invalidates their earlier access tokens. The new session has the new access.
- API keys follow their owner. An API key runs with at most the permissions its owner holds right now. When a user loses a group, their keys lose those permissions on the next request.
nano tracks where each membership came from. That is how it knows which memberships it may remove: only the ones a mapping created.
Example
Alex is in siem-analysts in Okta, mapped to the nano group SOC Analysts. An administrator also added Alex to Detection Engineering by hand in nano.
| What happens | Alex's nano groups after the next SSO sign-in |
|---|---|
| Starting point | SOC Analysts (SSO), Detection Engineering (manual) |
Okta admin moves Alex from siem-analysts to siem-admins, mapped to Admins. Alex signs in. | Admins (SSO), Detection Engineering (manual). Alex's other sessions are signed out. |
Okta admin removes Alex from siem-admins. Alex signs in. | Detection Engineering (manual), if Alex's account was invited. If nano created it through SSO, the sign-in is refused. See Who can sign in. |
When you change a mapping
Saving the mappings takes effect straight away for removals:
- A removed or changed mapping removes the memberships it granted, for every affected user, before the save completes. Those users are signed out everywhere, and their API keys lose the permissions at once.
- A new mapping is granted at each user's next SSO sign-in.
Manual memberships are kept in both cases.
Who can sign in
Each provider has one admission setting: Create accounts for users in mapped groups, in the provider's Access section.
| Setting | First-time users | Existing accounts |
|---|---|---|
| On (mapped groups only). The default for new providers. | nano creates the account only if the IdP says the user is in at least one mapped group. The account gets exactly the mapped groups, with no Everyone or ReadOnly default. | Can sign in. |
| Off (invitation-only) | Refused. | Only accounts created in nano or by invitation can sign in. |
"Existing accounts" means accounts created in nano: by an administrator, by invitation or at setup. These can always sign in with SSO, even with no mapped group. They still get their mapped groups synced.
Accounts that nano created through SSO are different. They need a mapped group at every sign-in. If they no longer have one, or you turn the provider to invitation-only, the sign-in is refused and their SSO-managed groups are removed.
A refused user sees:
Your account is not in a group allowed to sign in. Ask your administrator for access.
The message is the same for "not in a mapped group" and "provider is invitation-only", so it doesn't reveal which. The audit log records the reason.
Linking and account creation also need an email address the IdP has verified. See Verified email is required.
Set up group mappings
Okta
Okta sends group names. Add a groups claim to the ID token, then map the names exactly as Okta sends them.
Custom authorization server (for example default, issuer https://<your-org>.okta.com/oauth2/default):
- Go to Security → API → Authorization Servers, open the server, then the Claims tab.
- Add a claim named
groups. Set Include in token type to ID Token, Value type to Groups, and a narrow Filter, for example Starts withsiem-. - In nano, leave
groupsout of Scopes. Thedefaultserver has nogroupsscope, and Okta rejects the request.
Org authorization server (issuer https://<your-org>.okta.com):
- Go to Applications → Applications, open the nano app, then the Sign On tab.
- Edit OpenID Connect ID Token. Set Groups claim type to Filter, the claim name to
groups, and a filter such as Matches regex^siem-.*$. - In nano, add
groupsto Scopes:openid email profile groups.
For both:
- Assign the IdP groups to the app under Assignments. Okta refuses sign-in for users who aren't assigned, before the request reaches nano.
- Set Group claim to
groupson the nano provider.
The full Okta walkthrough is in Okta.
Microsoft Entra ID
Entra sends groups as object IDs (GUIDs), not display names. Map the object ID.
- In the Entra admin center, open your app registration, then Token configuration → Add groups claim. Pick the group types to include and save. This adds a
groupsclaim to the ID token. - Find each group's object ID: Groups → All groups, open the group, and copy Object ID from its Overview page.
- Map that object ID in nano, for example
22222222-2222-4222-8222-222222222222.
The issuer must be your tenant's own issuer, https://login.microsoftonline.com/<directory-tenant-id>/v2.0. nano reads the groups claim for this issuer whatever the Group claim field says.
Users in many groups. When a user is in too many groups for the token, Entra leaves the list out and marks the token with a groups overage instead. nano then reads the user's group IDs, including nested groups, from Microsoft Graph with the user's own access token. This needs the Graph permission and scopes in Entra: emit and look up groups. If the Graph lookup fails or is incomplete, nano refuses the sign-in.
Linking existing accounts by email on Entra needs the Directory (tenant) ID and Verified domains, or the xms_edov claim. See Entra email verification.
Google Workspace
Google ID tokens carry no groups. nano asks the Admin SDK Directory API whether the user is a member of each mapped group, using a service account with domain-wide delegation. It uses the read-only admin.directory.group.member.readonly scope and checks only the groups you map.
- In the Google Cloud project, enable Admin SDK API.
- Create a service account, enable domain-wide delegation, and download one JSON key.
- A Workspace super administrator adds the service account's client ID under Security → Access and data control → API controls → Manage Domain Wide Delegation, with the scope
https://www.googleapis.com/auth/admin.directory.group.member.readonly. - On the nano provider, enter a Workspace administrator's email in Delegated administrator, and paste the JSON key into Service account key.
- Map each group by its email address, for example
siem-analysts@example.com, or its Directory group ID.
Without both the key and the delegated administrator, nano can't see Google membership, so first-time Google users are refused. A Google provider can have at most 64 mapped groups; more than that refuses sign-in.
The full Google walkthrough is in Google Workspace.
In nano
- Define the roles on your nano groups in Settings → Access Control → Groups.
- Go to Settings → Single Sign-On and open the provider. The Group Mappings tab appears once the provider is saved.
- On Group Mappings, under Add mapping, enter the OIDC group (the exact IdP name or ID), pick the Local group, and click Add mapping (+). Map one IdP group to several nano groups by adding a row for each.
- Click Save mappings.
- On the Configuration tab, check Create accounts for users in mapped groups is set the way you want, and click Save changes.
After users have signed in, Groups seen in login tokens lists the IdP group values nano received. Click one to fill in the OIDC group field. This is the quickest way to get Entra object IDs right.
A provider can have up to 256 mappings.
Test
Use a private window and keep an administrator session open:
- Sign in as a new user in a mapped IdP group. Check they have exactly the mapped groups.
- Sign in as a new user outside every mapped group. Check they are refused.
- Remove the first user from the IdP group, then sign in again. Check the mapped group is gone and any manual group remains.
Removing access
Without SCIM, changes in the IdP take effect at the user's next SSO sign-in. nano doesn't hear about them before then.
With SCIM provisioning (Okta and Entra ID), the IdP pushes deactivations and group changes to nano as they happen. Deactivating a user in the IdP disables their nano account and revokes their sessions, tokens and API keys within seconds. This is the automated way to offboard.
Removing a mapping in nano is different: it takes effect immediately for every affected user. See When you change a mapping.
Audit events
SSO sign-ins and mapping changes are recorded in the platform audit log. Open Settings → Audit Log and filter by action, or search them:
metadata.log_source=audit api.service.name=oidcAction (api.operation) | When |
|---|---|
oidc_user_provisioned | nano created a new account on a first SSO sign-in. |
sso_group_grants_synchronized | An admitted SSO sign-in reconciled the user's groups. details.idp_groups lists the IdP groups received (up to 64). |
sso_sign_in_denied | An SSO sign-in was refused. details.reason says why. See Denied sign-ins. |
oidc_group_mappings_updated | Someone saved a provider's group mappings. |
oidc_login | An SSO sign-in completed (subsystem auth). |
oidc_provider_created, oidc_provider_updated, oidc_provider_enabled, oidc_provider_disabled, oidc_provider_deleted | Provider configuration changed. |
Troubleshoot
Start with the user's sso_sign_in_denied row in the audit log. Its details.reason narrows the cause.
The user is refused with "not in a group allowed to sign in"
The reason is group_not_allowed. Check, in order:
- The user is in an IdP group that is mapped on this provider.
- The mapping matches exactly what the IdP sends, including case. Compare it with Groups seen in login tokens.
- The groups claim reaches the ID token. If Groups seen in login tokens is empty after users have signed in, the IdP isn't sending groups. Check the claim setup for your IdP above, and that Group claim is
groups(Okta and generic OIDC). - The provider isn't invitation-only. With Create accounts for users in mapped groups off, accounts nano created through SSO are refused too.
Entra sends IDs instead of group names
This is expected. Entra's groups claim carries object IDs. Map the object ID from the group's Overview page, not its display name.
"Group membership could not be verified"
The reason is membership_unknown. nano couldn't read the user's groups: an Entra overage it couldn't resolve through Graph, or a failed Google Directory lookup. nano refuses rather than guess. Check Graph consent on Entra, or the Admin SDK API, delegation, key and delegated administrator on Google.
The Okta groups filter sends the wrong groups
Okta applies the filter before nano sees the token. A group the filter excludes never reaches nano, even if it's mapped. Check the filter matches every mapped name. Matches regex must match the whole group name, so use ^siem-.*$ rather than siem-.
The user's email isn't verified
The reason is email_unverified. See Verified email is required.
A group change in the IdP isn't reflected
- Ask the user to sign out of nano and sign in again with SSO. nano only reads groups at sign-in.
- Check
sso_group_grants_synchronizedfor that sign-in. Its details show the IdP groups nano received. - On Entra, a membership change can take a while to appear in new tokens. If the old groups still arrive, wait and sign in again.