SSO setup

NexBasira supports both OpenID Connect (OIDC) and SAML 2.0 Web Browser SSO. Users in the configured email domains are signed in via your identity provider; first-time logins are just-in-time provisioned with the default role you choose.

Before you start

• You need an org_admin role on the NexBasira side.
• You need access to your IdP admin to register an application + configure attribute mapping.
• SSO is available on the Pro tier and above (see pricing).

OIDC walkthrough

1. Find your callback URL

In the NexBasira SPA: Admin → SSO → Protocol: OpenID Connect. The callback URL is shown at the top of the form:

https://app.nexbasira.com/api/v1/auth/sso/callback

Custom-domain customers (Pro+) see their own domain here. Copy this — your IdP needs it.

2. Register an application in your IdP

Each IdP has its own UI, but the shape is the same:

• Application type: Web (server-side, confidential client)
• Redirect URI: the callback URL from step 1
• Allowed grant types: Authorization Code (with PKCE)
• Scopes: openid + email + profile

The IdP gives you back a Client ID, a Client Secret, and the Issuer URL (the base URL for discovery — usually https://your-idp.example.com/realms/yourrealm or https://accounts.google.com).

3. Fill out the SSO config

Back in Admin → SSO, fill the form:

• Display name: shown on the "Continue with SSO" button. E.g. "Acme SSO".
• Issuer URL: from your IdP.
• Client ID + Client Secret from your IdP.
• Email domains: comma-separated list (acme.com, acme-eu.com). Users with emails in these domains are routed through SSO.
• Default role for new users: usually inspector. Org admins must be assigned the org_admin role manually after first login.
• Auto-provision new users on first sign-in: typically on.
• Enabled: off until you've tested.

4. Test discovery

Click Test discovery. It fetches your IdP's OpenID configuration ({issuer_url}/.well-known/openid-configuration) + parses the JWKS. Common errors:

• OK — N JWKS keys: you're done.
• Connection refused / DNS failure: issuer URL typo; verify it resolves in your browser.
• JSON parse error: the issuer URL points somewhere that isn't an OIDC provider.
• No JWKS keys: probe succeeded but the JWKS endpoint returned an empty set; check IdP-side key rotation.

5. Enable + smoke-test

Flip Enabled on, save. Sign out, then sign in with an email in one of the allowed domains. You should be redirected to your IdP's login screen, then back to the SPA dashboard.

SAML 2.0 walkthrough

1. Find your ACS URL

In Admin → SSO → Protocol: SAML 2.0, copy the Assertion Consumer Service URL:

https://app.nexbasira.com/api/v1/auth/saml/acs

2. Register a SAML app in your IdP

• ACS URL / Reply URL: the URL from step 1.
• Entity ID (audience): https://app.nexbasira.com/saml/sp (or your custom domain).
• NameID format: emailAddress.
• Attribute mapping: at least email; ideally givenName + surname too.
• Sign assertions: required.

The IdP gives you back an Entity ID, an SSO Service URL, and a signing certificate (PEM).

3. Fill out the SAML config

• IdP Entity ID — from your IdP.
• IdP SSO Service URL — from your IdP.
• IdP signing certificate (PEM) — paste the full -----BEGIN CERTIFICATE----- block.
• Email domains — same shape as OIDC.
• Default role + auto-provision — same as OIDC.

The Advanced — attribute mapping section lets you override the URNs we look for; defaults match Microsoft's WS-Federation convention which most IdPs honour out of the box.

4. Enable + smoke-test

Same flow as OIDC: flip Enabled, sign out, sign in with an allowed-domain email, expect a round-trip through your IdP.

Tested IdPs

NexBasira's OIDC + SAML support is generic; any spec-compliant IdP works. We've smoke-tested:

• Microsoft Entra ID (Azure AD) — OIDC + SAML
• Google Workspace — OIDC + SAML
• Okta — OIDC + SAML
• Keycloak — OIDC + SAML
• OneLogin — SAML

JIT provisioning rules

• First time a user with a matching domain signs in via SSO, a Membership is created with the configured default role.
• email is the unique key. A user changing their email at the IdP creates a new account.
• Role changes after first sign-in are managed in the SPA (Admin → Members), not at the IdP. For IdP-driven group → role mapping, see SCIM provisioning.

Disabling SSO

Either flip Enabled off (keeps the config; you can re-enable later) or click Remove SSO (deletes the config). With SSO disabled, all users fall back to password authentication; existing memberships are preserved.

Troubleshooting

What's next

• SCIM provisioning — IdP-driven create + deactivate of users
• API authentication — separate from SPA SSO