Okta
Connect Okta to nano with OIDC using a Web Application integration.
Connect Okta to let your team sign in to nano with OIDC. Create a Web Application integration, choose an authorization server, and configure its issuer in nano.
Prerequisites
- Access to the Okta Admin Console with permission to create app integrations and edit authorization servers (for example Super Administrator, or Application Administrator plus API Access Management Administrator).
- 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. Also a provider slug (this guide uses
okta). - Existing IdP groups to map to nano grants, or existing invited members for invitation-only access.
App registration
| Deployment | Sign-in redirect URI |
|---|---|
| Self-run | https://<your-nano-host>/auth/callback/okta (the provider form shows the exact value for your slug) |
Create the app integration. In the Okta Admin Console go to Applications → Applications → Create App Integration. Choose OIDC - OpenID Connect, then Web Application, and click Next.
Configure sign-in. Name it, for example nano. Under Grant type, keep Authorization Code. nano always uses PKCE. Set Sign-in redirect URIs to the redirect URI above.
Assign access. Under Assignments, assign the users or groups who should be able to sign in, then save.
Copy the credentials. On the app's General tab, copy the Client ID and Client secret.
Choose an authorization server
Use one of these two. The Issuer URL in nano must match the ID token's iss exactly. Check it at <issuer>/.well-known/openid-configuration.
| Authorization server | Issuer URL |
|---|---|
| Org authorization server | https://<your-org>.okta.com |
Custom authorization server, for example default | https://<your-org>.okta.com/oauth2/default |
Custom authorization server setup
A custom server (under Security → API → Authorization Servers) needs two things before nano can use it.
An access policy and rule. Add an access policy that covers the nano app. Add a rule that allows the Authorization Code grant and the openid, profile and email scopes. Without them, Okta refuses the sign-in before it reaches nano.
A groups claim. On the server's Claims tab, add a claim:
- Name:
groups - Include in token type: ID Token, either Always or Userinfo / id_token request. nano reads either.
- Value type: Groups
- Filter: a narrow filter, for example Starts with
nano-
Don't request a groups scope on default. That server has no groups scope, and Okta rejects the request.
Org authorization server setup
On the app's Sign On tab, edit OpenID Connect ID Token. Set Groups claim type to Filter, the claim name to groups, and a narrow filter such as Matches regex ^nano-.*$. Request the groups scope in nano.
See Okta groups claims.
Authentication policy
Check that the app's authentication policy uses factors your users actually have. Okta's default rule, "Any two factors", needs a device-bound factor such as Okta Verify, FastPass or a security key. Okta refuses users who only have a password and email.
On a new Integrator org, you may also need to set the Email authenticator to Authentication and recovery and allow enrollment.
nano provider form
In Settings → Single Sign-On → Add provider, enter:
| Field | Value |
|---|---|
| Name | Okta |
| Slug | okta |
| Issuer URL | The issuer from Choose an authorization server |
| Client ID | (from Okta) |
| Client secret | (from Okta) |
| Scopes | Custom server: openid email profile. Org server: openid email profile groups. |
| Group claim | groups |
Save, and make sure Provider enabled is on.
Email verification
nano only creates or links an account when Okta marks the email verified. Okta sends email_verified: true for users with a verified primary email.
With a custom authorization server, the ID token carries only base claims. From v2.0.11, nano reads email and email_verified from the authorization server's userinfo endpoint. See Email from userinfo.
If your Okta directory controls every address in a domain, an administrator can add it under Verified domains. See Verified domains for what that asserts and its limits.
Group mappings
On the Group Mappings tab, map the exact Okta group names that Okta sends, such as nano-analysts. Map each one to one or more nano groups.
Leave Create accounts for users in mapped groups on (the default). A new member receives exactly the mapped 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 with the same verified email and keep 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 the 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 Okta has verified. 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.
Security notes
- Restrict to assigned users. Only users and groups in the app's Assignments can complete the Okta sign-in. Keep Federation Broker Mode off if you want assignment enforced.
- First-time SSO members need a mapped IdP group and receive only its mapped grants. Existing invited, active members keep their manually assigned access.
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.
- "Email not verified" (
email_unverified). On a custom authorization server, upgrade to v2.0.11 or later. Then check the user's primary email is verified in Okta. - Okta refuses the sign-in before nano. On a custom authorization server, check the access policy and rule cover the nano app, the Authorization Code grant and the
openid profile emailscopes. Also check the authentication policy uses factors the user has. - Okta rejects the
groupsscope. Removegroupsfrom Scopes in nano when you usedefaultor another custom server. Use agroupsclaim instead. - Account is not in an allowed group (
group_not_allowed). Check the groups claim filter, the exact mapped name and the user's current Okta membership. redirect_urierror. The Sign-in redirect URI must exactly match the value in App registration.- Issuer mismatch. The Issuer URL in nano must equal the token's
issexactly, with no trailing slash. With a custom authorization server it is.../oauth2/<auth-server-id>, not the bare org URL. - User can't sign in. Confirm the user, or one of their groups, is assigned to the app in Assignments.