Single sign-on

Single sign-on (SSO) lets a trusted external identity provider sign users in to your self-hosted Nodaro. You describe each provider in the EXTERNAL_SSO_PROVIDERS variable, and the login page shows an SSO button. The account a user ends up in is an ordinary user of your install: SSO is only a way to start a session. This page covers the operator's side; the protocol is in Single sign-on for developers.

Which kind of provider to use

SSO is off by default. With EXTERNAL_SSO_PROVIDERS unset, the login page shows no SSO button, GET /v1/sso/providers returns an empty list, and every provider route answers 404 unknown_provider.

Configure the providers

Set EXTERNAL_SSO_PROVIDERS to a JSON array, inline or as @/path/to/providers.json to read a file.

[
  {
    "id": "librechat",
    "label": "LibreChat",
    "kind": "assertion",
    "secret": "a-dedicated-32+char-hmac-key-not-the-idp-session-secret",
    "audience": "nodaro",
    "claimMap": { "email": "email", "emailVerified": "email_verified", "subject": "sub" },
    "initiateUrl": "https://chat.example.com/oauth/nodaro",
    "maxLifetimeSeconds": 300
  },
  {
    "id": "keycloak",
    "label": "Acme (Keycloak)",
    "kind": "oidc",
    "supabaseProvider": "keycloak"
  }
]

A malformed value stops the boot. A typo in an entry that holds a secret must never drop a provider silently, which would look like SSO failing with 404, or half-configure sign-in.

On the compose stack, add EXTERNAL_SSO_PROVIDERS and EXTERNAL_SSO_LINK_EXISTING under environment: of the nodaro service, because the compose file does not pass them from .env. To use a file, mount it into the container and give its path inside the container.

Provider fields

Only id, label and kind are ever published, by GET /v1/sso/providers. The secret never leaves the server.

What Nodaro checks in an assertion

An assertion provider's identity server signs a JWT and sends the browser to GET /v1/sso/<id>?assertion=<jwt>. Nodaro accepts it only when all of these hold:

• It is signed with HS256 and the provider's secret.
• aud equals the provider's audience.
• exp is present and not past, with 5 seconds of tolerance, and the lifetime is within maxLifetimeSeconds.
• jti is present and has never been used. Each assertion works once.
• The email claim is present. The verified claim must be true to create or link an account.

A failed check answers 401. The route allows 20 requests per 60 seconds from one IP address, then answers 429. The full contract, the error codes and the redirect flow are in Single sign-on for developers.

How accounts are linked

When an assertion passes, Nodaro finds or creates the matching user. The rules make sure that an assertion can never take over an existing account only because it has the same email address.

EXTERNAL_SSO_LINK_EXISTING defaults to false, which is safe against takeovers. Only true or 1, in any letter case, enables it. Enable it only when you trust your providers' verified-email claims enough to attach them to existing accounts.

account_exists and email_unverified use the same wording for every account, so the login form cannot be used to probe which addresses exist. The server log records which account was targeted.

The login button

The login page shows an SSO button when at least one provider is configured.

• One provider: the button reads Single sign-on, or the surface profile's auth.ssoLabel.
• Several providers: each button shows its provider's label, unless the surface profile sets auth.ssoLabel.

After sign-in, the user lands on /projects. The provider can send a different page by adding &next=<path> when it redirects back. Nodaro honors it only when it is a relative path on the same origin, starting with / but not //. Anything else goes to /projects. On the hosts listed in CORS_ORIGIN, the landing redirect stays relative, on the host the user arrived on.

Allow sign-in through SSO only

On the Business edition, the surface profile can remove the other sign-in methods:

NODARO_SURFACE_PROFILE={"auth":{"methods":["sso"],"ssoLabel":"Sign in with Acme"}}

A list that names only sso also enables a rule on the server: every signed-in account must have been created or linked through SSO. Any other session is refused on its first API call with 403 sso_required, so an account registered directly on the sign-in service cannot use the install. Adding email to the list disables the rule. See Editions and surface profiles.

Security summary

• A dedicated secret per provider, distinct from the provider's own session secret.
• Single-use assertions, with a short, server-enforced lifetime.
• Same-origin redirects only after sign-in.
• No secret leaves the server. Assertions and one-time tokens are removed from request logs.
• Rate limits on the exchange route, per IP address.
• Ordinary sessions. After the exchange, the user is a normal user with no special credential.