Microsoft Entra ID
Connect Microsoft Entra ID (Azure AD) to nano with OIDC through an app registration.
Connect Microsoft Entra ID to let your team sign in to nano with OIDC. Register an application, create a client secret, and configure your tenant issuer in nano.
Prerequisites
- Access to the Microsoft Entra admin center (
entra.microsoft.com) with permission to create app registrations (for example Application Developer, or Application Administrator to grant consent). - A nano user with full administrator authority. Creating or enabling a provider needs it, not only
settings:system. See Who can change providers. - Your nano host, served over
https. Also a provider slug (this guide usesentra). - Existing IdP groups to map to nano grants, or existing invited members for invitation-only access.
App registration
| Deployment | Web redirect URI |
|---|---|
| Self-run | https://<your-nano-host>/auth/callback/entra (the provider form shows the exact value for your slug) |
Create the app registration. In the Entra admin center go to Identity → Applications → App registrations → New registration. Name it, for example nano, and choose the supported account types (choose Accounts in this organizational directory only, single tenant).
Set the redirect URI. Under Redirect URI, choose platform Web and enter the redirect URI above. Register the app.
Copy the IDs. On the app's Overview page, copy the Application (client) ID and the Directory (tenant) ID. You need the tenant ID for the issuer URL.
Create a client secret. Go to Certificates & secrets → New client secret. Copy the secret's Value (not the Secret ID) right away. It is shown only once.
Emit/lookup groups
Emit groups. For group mappings, go to Token configuration → Add groups claim, pick the group types to include, and save. This adds a groups claim to the ID token.
When the ID token indicates overage (hasgroups or _claim_names.groups), nano queries Microsoft Graph /me/transitiveMemberOf/microsoft.graph.group?$select=id with the user's access token and reads all pages before deciding. Configure delegated Microsoft Graph User.Read, the least privilege for the signed-in user’s memberships; an administrator must grant consent if your tenant requires it. A failed or incomplete lookup refuses sign-in. nano never follows token-supplied claim-source URLs.
Email verification
Add the email and xms_edov optional claims for the ID token under Token configuration → Add optional claim. If the portal does not list xms_edov, use the application's manifest optional-claims configuration:
{
"optionalClaims": {
"idToken": [
{ "name": "email", "essential": false },
{ "name": "xms_edov", "essential": false }
]
}
}Merge this into existing optional claims; preserve other configured claims. Confirm the signed ID token contains a real email and xms_edov: true for the test user. nano trusts this signal only for the exact directory-specific https://login.microsoftonline.com/<tenant-id>/v2.0 issuer with matching tid. A preferred_username alone does not prove a verified email.
Alternatively, set Directory (tenant) ID and an exact Verified domains list on this provider. Only an administrator can add them. The signed token's issuer and tid must match that pin, and its email domain must exactly match a configured domain. Add only domains your organization has verified. Other issuers still require email_verified: true; a domain list does not grant tenant access without the required group or existing invitation.
See Microsoft Graph transitive memberships.
nano provider form
In Settings → Single Sign-On → Add provider, enter:
| Field | Value |
|---|---|
| Name | Microsoft Entra ID |
| Slug | entra |
| Issuer URL | https://login.microsoftonline.com/<directory-tenant-id>/v2.0 |
| Client ID | (Application (client) ID) |
| Client secret | (client secret Value) |
| Scopes | openid email profile User.Read (Graph access for overage) |
| Group claim | groups |
Replace <directory-tenant-id> with your Directory (tenant) ID. To link existing accounts by email, also fill in Directory (tenant) ID and Verified domains (see Email verification). Save, and make sure Provider enabled is on.
Group mappings
Map Entra group object ID GUIDs, such as 22222222-2222-4222-8222-222222222222. Do not use display names.
Map to nano groups. Leave Create accounts for users in mapped groups on (the default). A new member receives exactly these grants; no default Everyone or ReadOnly grant is added. Turning it off, or leaving mappings empty, keeps access invitation-only.
Existing invited, active members can link using the same verified email and retain their manual grants. Membership and provider-owned grants re-sync on every sign-in; manual grants and grants owned by other providers survive. Client secrets are encrypted when saved and never returned by the provider API; blank secret fields on edit keep stored values.
Test
Use a private window and keep an administrator session open:
- Allowed new user: sign in with an account in a mapped IdP group. Confirm creation and exactly the mapped groups, without a default grant.
- Outsider: try a new account outside all mapped groups. Confirm sign-in is denied and no member is created.
- Invited member: sign in with an existing invited, active member whose email is verified by the IdP. Confirm linking and preserved manual access.
- Removal: remove the allowed user from the IdP group, then sign in again. Confirm provider-owned grants are removed; manual grants remain. A JIT member without any mapped group is denied.
- Lookup failure: in a disposable test configuration, revoke Graph consent for a user with a groups overage. Confirm sign-in is refused with the membership-verification error.
These steps apply to nano Self-run. SSO settings are hidden when the installation does not provide the SSO capability (the open-source edition).
Security notes
- Restrict to your directory. Register the app as single tenant so only accounts in your Entra tenant can sign in. In Enterprise applications → nano → Properties, set Assignment required to Yes and assign the users or groups who need access.
- First-time SSO members need a mapped IdP group and receive only its mapped grants. Existing invited, active members retain their manually assigned access.
- New SSO users receive no default Everyone or ReadOnly grant. SSO grants re-sync at sign-in; manual grants survive removal from an IdP group.
Troubleshooting
Need help with these checks? Contact support with the request ID and time with timezone.
Every refused sign-in has a reason in the platform audit log. See Denied sign-ins.
- Group membership could not be verified (
membership_unknown). Sign-in is denied when the Graph overage lookup fails or is incomplete, including for invited members. Check Graph consent and theUser.Readscope. No partial lookup grants access. - Account is not in an allowed group (
group_not_allowed). Check the mapped group object ID and the user's current membership. A new member needs at least one mapping; email-domain verification alone grants no access. - "Your identity provider didn't confirm your email address" (
email_unverified). Add thexms_edovoptional claim, or set the tenant ID and verified domains. AADSTS500117(redirect URI must use https). Register anhttpsredirect URI, or uselocalhostfor a local test.AADSTS50011(redirect mismatch). The Web redirect URI must exactly match the value in App registration.- Issuer errors. The issuer must be
https://login.microsoftonline.com/<directory-tenant-id>/v2.0. The/v2.0suffix matters, and the tenant must be the GUID, not the domain. - Issuer mismatch. Copy the issuer from
https://login.microsoftonline.com/<directory-tenant-id>/v2.0/.well-known/openid-configuration.commonororganizationsin place of the tenant ID won't match the token'siss. - Secret rejected. Check that you copied the secret Value, not its ID, and that it hasn't expired.
- A user can't sign in. Check mapped membership or an existing invitation, a real email claim, xms_edov or pinned-domain verification, and Graph consent for overage.