nano SIEM
SettingsSingle Sign-On

Okta

Supported in:Self-hosted

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

DeploymentSign-in redirect URI
Self-runhttps://<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 serverIssuer URL
Org authorization serverhttps://<your-org>.okta.com
Custom authorization server, for example defaulthttps://<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:

FieldValue
NameOkta
Slugokta
Issuer URLThe issuer from Choose an authorization server
Client ID(from Okta)
Client secret(from Okta)
ScopesCustom server: openid email profile. Org server: openid email profile groups.
Group claimgroups

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:

  1. Allowed new user: sign in with an account in a mapped IdP group. Confirm creation and exactly the mapped groups, without a default grant.
  2. Outsider: try a new account outside all mapped groups. Confirm sign-in is denied and no member is created.
  3. Invited member: sign in with an existing invited, active member whose email Okta has verified. Confirm linking and preserved manual access.
  4. 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 email scopes. Also check the authentication policy uses factors the user has.
  • Okta rejects the groups scope. Remove groups from Scopes in nano when you use default or another custom server. Use a groups claim 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_uri error. 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 iss exactly, 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.

What's next

On this page