Single Sign-On
Connect nano to your identity provider with OpenID Connect (OIDC) with nano Self-run.
Connect your identity provider with OpenID Connect (OIDC) so your team can sign in with corporate accounts. Register nano as an OIDC web application, then add the provider in nano.
Availability
| Edition | SSO |
|---|---|
| Self-run | Included. |
| Open core | Not available. The open-core build has no OIDC; users sign in with local credentials. |
This guide applies to nano Self-run. The open-core web build shows a placeholder instead of the SSO page.
Who can change providers
Viewing providers and making small edits needs the settings:system permission. Changes that decide who nano trusts need full administrator authority: every permission an administrator holds, not only settings:system. These are:
- creating a provider;
- enabling a provider;
- changing its Issuer URL, Client ID or Group claim;
- widening admission: turning on Create accounts for users in mapped groups, adding an Entra tenant ID, adding a verified domain, or setting a Google delegated administrator or service-account key.
Without that authority, the request fails with 403 and the error code admin_authority_required. Disabling a provider and removing a verified domain only need settings:system. Changing the issuer signs out and unlinks the accounts linked through the old issuer.
Group-gated sign-in
Map IdP groups before inviting the wider team. A first-time SSO user must belong to at least one group mapped on the provider. nano creates their local account with exactly the mapped grants. New SSO users receive no automatic Everyone or ReadOnly grant.
- Existing accounts (created locally or by invitation) can always sign in with SSO, even without a mapped group.
- Every sign-in syncs group access (how sync works). A mapped group the IdP no longer sends is removed, and the user's sessions are revoked. A group granted by hand in nano is kept, even when it matches a mapped group.
- Invitation-only providers. Turn off Create accounts for users in mapped groups and only existing accounts can sign in. Providers that existed before group admission and had no mappings start in this mode. New providers have it on by default.
- Unknown membership is refused. If nano can't determine membership (an unresolved Entra overage, a failed Graph or Directory lookup), it refuses the sign-in rather than guessing.
Verified email is required
nano only creates an account, or links SSO onto an existing account, when the identity provider marks the email verified. nano matches a first-time SSO identity to local accounts by email. An unverified address could otherwise take over someone else's account.
Once an identity is linked (by IdP issuer and subject), later sign-ins no longer depend on the email.
Where the verification comes from:
| Provider | Verified when |
|---|---|
| Okta and other generic OIDC | email_verified: true in the ID token or, from v2.0.11, in the userinfo response. Or the address is in one of the provider's verified domains. |
| Microsoft Entra ID | The ID token has xms_edov: true, or the provider pins a Directory (tenant) ID and the address is in its verified domains. See Entra email verification. |
email_verified: true in the ID token. Workspace accounts always send it. |
Email from userinfo (v2.0.11)
Some providers, such as an Okta custom authorization server, leave email and email_verified out of the ID token. From v2.0.11, nano then reads them from the provider's userinfo endpoint. This applies to generic OIDC providers only, not Google or Entra.
- nano calls userinfo only after the ID token passes its signature, issuer, audience and nonce checks.
- The userinfo endpoint must use
httpson the issuer's own host and port. Otherwise nano skips it. - The userinfo
submust match the ID tokensub, or the sign-in is refused. - Userinfo only fills claims the ID token left out. It never overrides them.
- If userinfo fails for any other reason, the sign-in goes on with the ID-token claims alone. The API logs
OIDC userinfo not usedwith the cause.
Before v2.0.11, Okta sign-in through a custom authorization server fails with "email not verified".
Verified domains
Verified domains is an optional field on Okta and other generic OIDC providers, available from v2.0.11. Only an administrator can add a domain.
By adding a domain, you assert: "this identity provider only gives addresses in this domain to the people who own them." nano then treats an address in that exact domain as verified when the provider sends no email_verified.
- An explicit
email_verified: falsealways wins. The domain never overrides it. - Domains match exactly. Subdomains are not included.
- Use it only when your directory controls the email attribute. Never list a domain for a provider that allows self-registration or lets users edit their own email.
- Free-mail domains (
gmail.com,outlook.com,yahoo.co.ukand so on) and public suffixes (co.uk,com.au,github.ioand so on) are refused. - On a Microsoft issuer, verified domains need a Directory (tenant) ID. A multi-tenant or B2C issuer would let anyone assert any address.
- Google doesn't use this field.
A verified domain only makes email linking safe. It doesn't admit anyone: first-time users still need a mapped group.
Sign-in URLs and origins
The IdP only needs your nano origin (scheme and host, no path):
| Value | |
|---|---|
| Origin | The URL your users open nano at, for example https://nano.example.com |
| Redirect URI | https://<your-nano-host>/auth/callback/<slug> |
Add a provider
Go to Settings → Single Sign-On (/settings/oidc) and add a provider. The fields are the same for every IdP:
| Field | What it is |
|---|---|
| Name | Display name shown on the sign-in screen, for example "Acme Okta". |
| Slug | Short identifier: lowercase letters, digits and hyphens. It is part of the redirect URI, and it can't be changed after the provider is created. |
| Issuer URL | The IdP's OIDC issuer. nano discovers its endpoints at <issuer>/.well-known/openid-configuration. |
| Client ID / Client secret | From the application you register in the IdP. When editing, leave them blank to keep the current values. |
| Scopes | Space-separated. openid email profile at minimum. |
| Group claim | Optional. The ID-token claim that carries group names or IDs (usually groups), used by group mappings. |
The access settings below these fields depend on the provider: Directory (tenant) ID and Verified domains for Entra, Verified domains for Okta and other generic providers, and Delegated administrator and Service account key for Google.
Configure and test mappings
In the provider form, leave Create accounts for users in mapped groups on. On the Group Mappings tab, map each exact IdP group identifier to one or more nano groups. Your permissions must cover the grants you map.
Test in a private window with an allowed user who has never been invited, then a user outside all mapped groups. The second user should see Your account is not in a group allowed to sign in. Confirm the first user has only the intended grants. Test removal and a separately assigned manual grant before expanding access.
Google ID tokens have no groups: configure a delegated service account for Workspace membership lookup, or keep invitation-only access.
For how sync, admission and removal work, with setup for each IdP, see SSO groups and roles.
To apply IdP changes between sign-ins, set up SCIM provisioning.
Signing out
Signing out of nano ends every session for that user, on every device, not only the current browser. It also invalidates every access token issued before the sign-out. A leftover session on another device would otherwise stay valid for up to 7 days.
Signing out of nano doesn't sign you out of your identity provider.
SSO-only sign-in
You can turn off password sign-in so that users must use SSO (PUT /api/settings/auth-methods with local_password_enabled: false).
- SSO-only needs at least one enabled provider. Without one the request returns
409(no_enabled_provider). - While SSO-only is on, you can't disable or delete the last enabled provider.
- Turning password sign-in back on is always allowed.
Provider guides
- SSO groups and roles
- SCIM provisioning: push deactivations and group changes from Okta or Entra ID
- Google Workspace
- Microsoft Entra ID
- Okta
Security notes
- nano validates every ID token's signature against the provider's published keys (JWKS), accepts RS256 only, and checks issuer, audience, expiry and a per-sign-in nonce.
- The authorization request uses PKCE.
- Issuer discovery, key fetches and userinfo calls are protected against server-side request forgery. Issuer URLs must resolve to a public host.
- Provider changes and SSO sign-ins are recorded in the platform audit log.
Denied sign-ins in the audit log
Each refused SSO sign-in is audited as sso_sign_in_denied. The row's details.reason says why. The person signing in sees only a short message.
reason | What it means | Fix |
|---|---|---|
email_unverified | nano would create or link an account, but the IdP didn't mark the email verified. | Make the IdP send email_verified: true. On Okta, upgrade to v2.0.11 or later. For Entra, add xms_edov or pin the tenant and its domains. Or add a verified domain. |
group_not_allowed | A first-time user is in no mapped group, or the provider is invitation-only. | Add the user to a mapped IdP group, map the group they're in, or invite them first. Check the group claim reaches the ID token. |
membership_unknown | nano couldn't determine group membership: an Entra overage it couldn't resolve, or a failed Graph or Directory lookup. | Fix the lookup: Graph consent on Entra, or the Google service account, delegation and delegated administrator. |
account_link_refused | The matching local account is disabled, or already linked to another SSO identity. | Re-enable the account, or unlink the other identity. |
sso_not_entitled | Your plan doesn't include SSO. | Use a plan with SSO, or sign in with a local account. |
userinfo_subject_mismatch | The IdP's userinfo named a different user than the ID token. | Check the issuer and userinfo endpoint belong to the same authorization server. Contact support if it persists. |
missing_email_claim | The IdP sent no email and no username. | Request the email scope, and make sure the user has an email in the IdP. |
Once the ID token is valid, the row also records idp_issuer, idp_subject and email_verified. A verified address is recorded as the actor. An unverified one is recorded only as asserted_email_unverified.
Each admitted sign-in is audited as sso_group_grants_synchronized.
Troubleshoot
Need help with these checks? Contact support with the request ID and time with timezone.
Saving a provider returns admin_authority_required
The change needs full administrator authority. See Who can change providers. Ask an administrator to make it.
SSO-only configuration returns no_enabled_provider
Enable at least one provider before turning off password sign-in. While SSO-only is enabled, nano prevents disabling or deleting the last enabled provider.
A user cannot sign in
Find the sso_sign_in_denied row in the platform audit log and look up its reason in Denied sign-ins.
The IdP rejects the redirect URI
Every IdP shows this differently (redirect_uri_mismatch, AADSTS50011, and so on). Compare the URI registered in the IdP with the table in Sign-in URLs and origins, character by character.
Issuer mismatch
nano checks the ID token's iss against the Issuer URL you saved, exactly. A trailing slash, http instead of https, or the wrong tenant or authorization server in the path all fail. Copy the issuer from the IdP's /.well-known/openid-configuration document.