Single sign-on

With single sign-on (SSO), your team signs in to NuRoute with your company's identity provider instead of a NuRoute password. It works with any provider that supports OpenID Connect, including Microsoft Entra ID (Azure AD), Okta, Google Workspace, Keycloak and Auth0. It is part of the Enterprise plan, on self-hosted installs and on NuRoute Cloud.

How it works

1. On the login page, someone enters their work email and chooses Sign in with SSO.
2. NuRoute recognises your company from the email's domain and sends them to your identity provider, where they sign in as they do everywhere else (with MFA, if you require it there).
3. The first time, NuRoute creates their account with the role you chose (Member by default). Owners and admins change roles later on Members, as for anyone else.

Accounts that already exist with the same email (people invited before SSO) are connected to their identity provider account at their first SSO sign-in. Emails outside your domains, or belonging to another NuRoute organization, are always refused.

Set it up

You need to be an owner or admin of your NuRoute organization, and an administrator of your identity provider. It takes about 10 minutes.

In NuRoute, open Settings → Single sign-on. Step 1 on that page shows your redirect URI: https://<your domain>/auth/sso/callback. You need it at the identity provider.

At your identity provider, create an application for NuRoute (steps for each provider below), then copy three values back into NuRoute:

NuRoute field	What it is
Issuer URL	Your provider's OpenID Connect issuer (shown for each provider below). NuRoute reads its configuration from <issuer>/.well-known/openid-configuration
Client ID	The application's ID
Client secret	The application's secret. Stored encrypted; never shown again (leave the field empty when you change other settings)
Email domains	Your company's email domains, e.g. acme.com, acme.de. People whose email ends in one of them sign in through your provider. A domain can belong to one NuRoute organization only
Role for people signing in for the first time	Member (default), Viewer or Admin. Never Owner

Select Save. NuRoute checks it can read your provider's configuration and tells you if not. Then try it: open a private browser window, go to https://<your domain>/app/login, enter your work email and choose Sign in with SSO.

Microsoft Entra ID (Azure AD)

1. In the Entra admin center, open Identity → Applications → App registrations → New registration.
2. Name: NuRoute. Supported account types: Accounts in this organizational directory only. Redirect URI: platform Web, your NuRoute redirect URI. Select Register.
3. On the app's Overview, copy the Application (client) ID (NuRoute's Client ID) and the Directory (tenant) ID.
4. Certificates & secrets → New client secret, then copy its Value (not the Secret ID) into NuRoute's Client secret. Note when it expires, and replace it in NuRoute before then.
5. Issuer URL: https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0.
6. Optional, to choose who may sign in: Enterprise applications → NuRoute → Properties → Assignment required? → Yes, then add users or groups under Users and groups.

NuRoute uses the email claim, or preferred_username when Entra sends no email, so accounts without a mailbox work too.

Okta

1. In the Okta Admin Console, Applications → Applications → Create App Integration.
2. Sign-in method OIDC - OpenID Connect, application type Web Application. Next.
3. Name NuRoute; grant type Authorization Code; Sign-in redirect URIs: your NuRoute redirect URI. Under Assignments, choose who may use it. Save.
4. Copy the Client ID and the Client secret from the app's General tab.
5. Issuer URL: your Okta domain, e.g. https://acme.okta.com.

Google Workspace

1. In the Google Cloud console, choose (or create) a project for your company.
2. APIs & Services → OAuth consent screen: user type Internal (only your Workspace's users can sign in), app name NuRoute. Save.
3. APIs & Services → Credentials → Create credentials → OAuth client ID: application type Web application, Authorized redirect URIs: your NuRoute redirect URI. Create.
4. Copy the Client ID and Client secret.
5. Issuer URL: https://accounts.google.com.

Keycloak

1. In your realm, Clients → Create client: type OpenID Connect, Client ID nuroute.
2. Client authentication: On, Standard flow: On (others off). Next.
3. Valid redirect URIs: your NuRoute redirect URI. Save.
4. Copy the secret from the client's Credentials tab.
5. Issuer URL: https://<your Keycloak>/realms/<realm>.

Auth0

1. Applications → Applications → Create Application: name NuRoute, type Regular Web Applications.
2. On Settings, set Allowed Callback URLs to your NuRoute redirect URI. Save.
3. Copy the Client ID and Client Secret from the same page.
4. Issuer URL: https://<your tenant>.<region>.auth0.com/ (your Auth0 Domain with https:// in front).

Any other OpenID Connect provider

Create a web (confidential) application with the authorization code flow, your NuRoute redirect URI, and the scopes openid email profile. The issuer URL is the address its /.well-known/openid-configuration lives under.

Single sign-on only

With Single sign-on only switched on, passwords stop working for everyone except owners: access then follows your identity provider, so someone who leaves loses NuRoute access when you disable them there. Owners keep their password so they can still sign in, and fix the settings, if the identity provider is down or misconfigured. Keep at least one owner whose password is stored somewhere safe.

API keys are not affected: they keep working until an admin deletes them on API Keys. When someone leaves, delete the API keys they created.

Changing or removing it

• Switch it off for a while: turn off Single sign-on on and save. Settings are kept; everyone signs in with a password again (people created by SSO have none yet; see below).
• Remove it: Remove single sign-on on the same page.
• People created by SSO have no NuRoute password. If SSO is off and they need to sign in, they use Forgot password? on the login page (with your mail server connected), or someone with access to the server runs ./reset-password.sh <their email>.

When sign-in fails

The login page explains what went wrong:

Message	What to do
"Single sign-on is not set up for this email domain…"	The email's domain is not in Email domains. Check for typos in the email, or add the domain
"Your identity provider signed you in with an email address this organization does not accept."	The provider sent an email outside your domains, e.g. a guest account. Sign in with a company account, or add that domain
"This email address already belongs to another NuRoute organization."	On NuRoute Cloud, that email is registered elsewhere. Contact support
"Your identity provider did not sign you in. You may not be assigned to NuRoute there."	Assign the person to the NuRoute application at your provider (Entra: Users and groups; Okta: Assignments)
"Your identity provider did not send an email address…"	Make sure the application gets the email scope (and, in Entra, an email or user principal name in the email format)
"The answer from your identity provider could not be verified…"	Often a wrong client secret or an expired one (Entra secrets expire). Enter the current secret under Settings → Single sign-on
"The sign-in took too long or was already used."	Start again from the login page (sign-ins expire after 10 minutes)
"Your organization signs in with single sign-on. Use Sign in with SSO." (password login)	Single sign-on only is on: use Sign in with SSO. Owners can still use their password

On a self-hosted install, docker compose logs auth-service | grep sso shows the reason for each refused sign-in.