Single sign-on (SSO)
Let your team sign in to Neens with the identity provider (IdP) you already run — Okta, Azure AD / Microsoft Entra, Google Workspace, Auth0, or anything that speaks OIDC or SAML 2.0. SSO is per-tenant and bring-your-own-IdP: you add a connection for your company, point one or more of your email domains at it, and members with those domains get a Continue with SSO button on the sign-in page. There is no shared Neens identity provider to trust and nothing to install — Neens is the service provider, your IdP is the source of truth for who your people are.
At a glance
| Where | Settings → SSO (company admins only) |
| Protocols | OIDC (OpenID Connect) and SAML 2.0, one connection each or several |
| Routing | By email domain — an address’s domain decides which connection it uses |
| New users | Auto-provisioned on first SSO login (just-in-time) at a role and agent you choose |
| Second factor | Optional Also require Neens MFA after SSO per connection |
| Who can configure | Company admins. Members just sign in |
SSO federates into your existing Neens accounts — it does not replace them. A member’s role, org access, and agent scope are still governed by Neens exactly as with password sign-in; SSO only changes how they prove who they are. Password sign-in keeps working for anyone not routed to a connection.
Configure an OIDC connection
OIDC is the simplest path if your IdP supports it (most do). You will move four values from your IdP into Neens, and one value — the callback URL — from Neens into your IdP.
The fields Neens asks for
Open Settings → SSO → Add connection and choose Protocol: OIDC. The form asks for:
| Field | What it is | Where it comes from |
|---|---|---|
| Display name | A label for this connection (e.g. Acme Okta) | You pick it |
| Issuer URL | Your IdP’s OIDC issuer / discovery base — Neens reads its /.well-known/openid-configuration | Your IdP’s app / tenant settings |
| Client ID | The public identifier of the app you create in the IdP | The IdP app you create below |
| Client secret | The confidential secret for that app | The IdP app you create below |
| Scopes | What Neens requests — openid email profile covers everything Neens needs | Leave as the default unless your IdP needs more |
| Email domains | The domains routed to this connection (see Email-domain routing) | Your company’s email domains |
The callback URL you register in the IdP is always:
https://YOUR_NEENS_HOST/auth/sso/oidc/callbackThe client secret is write-only. After you save, the form shows A client secret is configured rather than the value — editing the connection later, leave the secret blank to keep it. Neens never displays a stored secret back to you.
Okta walkthrough (OIDC)
Create an OIDC web app in Okta
In the Okta Admin console, go to Applications → Create App Integration, choose OIDC - OpenID Connect and Web Application, and continue.
Set the redirect URI
Under Sign-in redirect URIs, add:
https://YOUR_NEENS_HOST/auth/sso/oidc/callbackAssign the app to the users or groups who should be able to sign in to Neens.
Copy the credentials
From the app’s General tab, copy the Client ID and Client secret. Your Issuer URL is
your Okta org URL (for example https://acme.okta.com, or a custom authorization-server issuer if
you use one) — Okta shows it under Security → API → Authorization Servers.
Create the connection in Neens
Back in Settings → SSO → Add connection, choose OIDC, paste the Issuer URL, Client
ID and Client secret, keep Scopes as openid email profile, add your Email domains,
tick Enabled, and save.
Azure AD / Microsoft Entra, Google Workspace, and Auth0 follow the exact same shape: create an
OIDC / OpenID Connect web app, register the same redirect URI
(https://YOUR_NEENS_HOST/auth/sso/oidc/callback), and copy the issuer, client ID, and client
secret into the Neens form. The issuer for Azure AD is
https://login.microsoftonline.com/<tenant-id>/v2.0; for Google it is https://accounts.google.com;
for Auth0 it is your tenant domain (https://acme.eu.auth0.com/).
Configure a SAML connection
Use SAML if your IdP standardizes on it. Here the exchange runs the other way for two values: you give the IdP two Neens service-provider (SP) URLs, and you copy three values back from the IdP.
The fields Neens asks for
Open Settings → SSO → Add connection and choose Protocol: SAML. The form asks for:
| Field | What it is |
|---|---|
| IdP entity ID | The issuer/entity ID of your IdP for this app |
| IdP sign-on URL | The IdP’s SAML SSO endpoint (where Neens sends the sign-in request) |
| IdP X.509 certificate | The IdP’s signing certificate, used to verify assertions |
| Email domains | The domains routed to this connection |
After you save, the connection’s Service provider details panel shows the two URLs to hand your IdP admin:
| Neens value | URL |
|---|---|
| SP metadata URL | https://YOUR_NEENS_HOST/auth/sso/saml/<connection-id>/metadata |
| Assertion consumer service (ACS) URL | https://YOUR_NEENS_HOST/auth/sso/saml/acs |
The metadata URL returns a standard SAML SP metadata document, so an IdP that can import metadata can configure itself from that one URL. The ACS URL is where the IdP posts its signed assertion.
Okta / Azure AD walkthrough (SAML)
Create a SAML app in the IdP
In Okta: Applications → Create App Integration → SAML 2.0. In Azure AD / Entra: Enterprise applications → New application → Create your own → non-gallery, then Single sign-on → SAML.
Enter the Neens SP URLs
Set the app’s Single sign-on URL / Reply URL (ACS) to
https://YOUR_NEENS_HOST/auth/sso/saml/acs, and its Audience / SP entity ID / metadata to the
Neens SP metadata URL shown on the connection. Configure the email address as the SAML
NameID / subject so Neens can match the user.
Copy the IdP values into Neens
From the IdP’s SAML settings, copy the IdP entity ID (issuer), the IdP sign-on / SSO URL, and the X.509 signing certificate. Paste all three into the Neens SAML form.
Assign users and enable
Assign the app to the right users or groups in the IdP, tick Enabled on the Neens connection, add your Email domains, and save.
Neens verifies every SAML assertion against the certificate you provide — signature, audience, and validity window. If sign-in fails right after setup, the mismatch is almost always the X.509 certificate (re-copy it, with no stray whitespace) or the ACS URL registered in the IdP.
Email-domain routing
A connection only does anything once you route email domains to it. In the connection’s Email
domains field, list the domains your members sign in with (for example acme.com,
acme.co.uk) — separate multiple domains with commas.
- When someone types a work email on the sign-in page, Neens looks up the domain and, if it maps to an enabled connection, shows a Continue with SSO button for it.
- A domain can belong to one connection across all of Neens. If a domain is already claimed elsewhere, saving is rejected rather than silently moving it.
- An address whose domain isn’t routed simply signs in with a password as before — SSO is additive, not a lockout.
New users are provisioned on first sign-in
The first time someone signs in through a connection and doesn’t yet have a Neens account, Neens creates one just-in-time — no invite needed. Two per-connection settings control what that new account looks like:
| Setting | Effect |
|---|---|
| Role for new users | The role a JIT-provisioned user gets — admin, member, or viewer. Workspace default uses the workspace’s default role |
| Default agent for new users | The agent a new user starts scoped to (optional) |
A JIT-provisioned account has no password — it exists to be signed into through your IdP. If an email already belongs to a Neens account in another company, the SSO login is rejected rather than moving the user across tenants; identity in Neens is one account per person.
Also require Neens MFA after SSO. By default a connection trusts the factor your IdP already enforced, so a successful IdP login signs the user straight in. Turn on Also require Neens MFA after SSO on a connection to additionally require the user’s Neens two-factor code after the IdP step — useful when you want a second factor Neens controls regardless of the IdP’s policy.
What the end-user experience looks like
For a member, SSO is three steps and no password:
Enter your work email
On the sign-in page, start typing your work email. If your domain is routed to a connection, a Continue with SSO button (labelled with your provider) appears beneath the password form.
Continue to your provider
Click it and Neens sends you to your IdP. Sign in there the way you always do — including whatever MFA your IdP enforces.
You’re signed in
Your IdP returns you to Neens, which signs you in (creating your account on the first visit). If the connection also requires a Neens second factor, you enter that code before you land in the app.
The password sign-in and its account-protection and reset flows stay exactly as they are for anyone not using SSO.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| No Continue with SSO button appears | The email’s domain isn’t routed, or the connection is disabled | Add the domain to the connection’s Email domains and tick Enabled |
| OIDC login returns to the sign-in page with an error | Redirect URI mismatch, or wrong issuer / client credentials | Confirm the IdP redirect URI is exactly https://YOUR_NEENS_HOST/auth/sso/oidc/callback and re-check the issuer, client ID and secret |
| SAML login is rejected | Certificate or ACS URL mismatch | Re-copy the IdP X.509 certificate; confirm the IdP’s ACS is https://YOUR_NEENS_HOST/auth/sso/saml/acs |
| Can’t save a domain | It’s already claimed by another connection | A domain maps to one connection only — remove it from the other first |
| Sign-in asks for a code after the IdP step | Also require Neens MFA after SSO is on for that connection | Enter your Neens authenticator code — this is expected |
Related
- Signing in & passwords — the password, invite, and reset flows SSO sits alongside.
- Members & roles — what the role a new SSO user is given can do.
- Your account — managing your own two-factor authentication.
- Connect Claude Code (MCP) — the browser sign-in a developer does to connect Claude Code runs through this same SSO when your domain is routed.