Single sign-on with OpenID Connect and SAML 2.0

Single sign-on with OpenID Connect and SAML 2.0Sign people in through Okta, Auth0, Keycloak, Ping, OneLogin, Google, ADFS or any other OpenID Connect or SAML 2.0 identity provider — what is verified, how sessions work, and how to set it up. Besides Microsoft Entra ID, a server installation of ATX AnalyticsTable signs people in with any OpenID Connect (OIDC) provider and any SAML 2.0 identity provider. Roles, object-level access, data-access policies and the audit trail work the same whichever one a person used: the provider's groups and roles feed the same role map as Entra's app roles and groups. You can switch on more than one provider; the sign-in screen then offers one button for each.

Overview

Besides Microsoft Entra ID, a server installation of ATX AnalyticsTable signs people in with any OpenID Connect (OIDC) provider and any SAML 2.0 identity provider. Roles, object-level access, data-access policies and the audit trail work the same whichever one a person used: the provider's groups and roles feed the same role map as Entra's app roles and groups. You can switch on more than one provider; the sign-in screen then offers one button for each.
The desktop app is unaffected. A packaged desktop build listening on loopback treats its own user as the administrator, exactly as before.
Open Settings → Identity (Entra ID) → Single sign-on, provisioning and sessions: Settings → Settings → Set / Restore → Identity (Entra ID)

Which method to choose

Entra ID only — Entra ID sign-in, with a maximum token age — At the next silent token renewal — within the maximum token age you set, for example 5 minutes
Entra ID with provisioning — Entra ID sign-in plus SCIM (authoritative) — When Entra's provisioning cycle runs, or at once with Provision on demand
Okta, Auth0, Keycloak, Ping, OneLogin, Google — OpenID Connect, plus SCIM where the provider offers it — With SCIM: within seconds of the provider pushing the change. Without: at the next claims refresh (5 minutes by default)
ADFS, Shibboleth or another SAML-only provider — SAML 2.0, plus SCIM where available — With SCIM: at once. Without: when the claims reach their maximum age (60 minutes by default)
Any of them, right now — Revoke access in Settings → Identity (Entra ID) — At once

How an OIDC or SAML sign-in works

1. The person clicks the provider's button on the sign-in screen. The server sets a one-time, HttpOnly cookie in that browser and sends it to the provider — for OIDC with an Authorization Code request using PKCE (S256), a state and a nonce; for SAML with an AuthnRequest over the HTTP-Redirect binding.
2. The person signs in at the provider, with whatever the provider requires: password, MFA, a smart card, Windows integrated sign-in.
3. The provider sends the browser back — for OIDC to /sso/oidc/callback with a code, for SAML by an automatic form POST of the signed Response to /sso/saml/acs.
4. The server verifies what came back (see the table below), checks it against revocations and, if SCIM is authoritative, against the directory, and creates a session.
5. The browser lands on the page it started from with a one-time hand-off code in the address fragment. The app redeems the code — which only works in the browser holding the cookie from step 1 — and from then on every request carries the session.
The hand-off code lives 60 seconds, can be used once, and travels in the URL fragment, which browsers never send to a server or put in a Referer header. Binding it to the cookie stops login cross-site request forgery: a link carrying somebody else's finished sign-in is useless in any other browser.
The shared API token is still required on every /api request, exactly as before; a sign-in adds who is asking, it does not replace the transport guard. The /sso/* paths sit outside /api because a browser navigation and an identity provider's form post cannot carry that header — each of them is authenticated by what it validates instead.

What is verified

Signature — Keys from the provider's published key set (JWKS, found by discovery). Asymmetric algorithms only — none and HS256 are refused. — XML signature verified by the @node-saml library. The assertion itself must be signed by one of the configured IdP certificates; signing the Response as well can be required.
Issuer — The token's iss must equal the configured issuer exactly, and so must the issuer in the discovery document. — When an IdP entity ID is configured, the Issuer must equal it.
Audience — The ID token must be for this client (and name it as azp when it names several audiences). — The assertion's audience must be this server's entity ID.
Freshness — exp and nbf, with 60 seconds' tolerance. — NotBefore and NotOnOrAfter with 60 seconds' tolerance; the assertion may be at most 10 minutes old.
Binding to this sign-in — state used once, the PKCE verifier, and the nonce the server sent. — InResponseTo must answer a request this server issued, which is then spent; each assertion ID is accepted once.
Unsolicited sign-in — Not applicable. — Refused. An IdP-initiated Response has no request to answer; point the portal tile at /sso/saml/login instead.
If the provider or its key set cannot be reached, sign-in fails closed. A discovery document that was fetched successfully keeps being used through an outage of up to a day.

Sessions

After an OIDC or SAML sign-in the server issues its own session token, an opaque random value sent in the x-analytics-user-token header like an Entra token. The server stores only its SHA-256 digest, so a backup of the profile folder holds no live credentials. Signing out deletes the session on the server, so a copied token stops working too.
ANALYTICS_AUTH_SESSION_HOURS — A session ends this long after sign-in, however busy — 12
ANALYTICS_AUTH_IDLE_MINUTES — A session ends after this long without a request — 60
ANALYTICS_AUTH_CLAIMS_REFRESH_MINUTES — How often roles and groups are refreshed from an OIDC provider, using its refresh token — 5
ANALYTICS_AUTH_CLAIMS_MAX_AGE_MINUTES — Past this without a successful refresh, the person must sign in again — 60
If the provider answers a refresh with invalid_grant — the person was disabled, or consent was withdrawn — the session ends at once. Refresh tokens are held in memory only: after a server restart a session runs on its last claims until they reach their maximum age, and then asks for a new sign-in, which the provider's own session usually turns into a redirect without a password prompt. SAML has no refresh, so a SAML session's roles are as fresh as its sign-in until the maximum age. When SCIM is authoritative none of these clocks matter, because the directory supplies the roles on every request.
Sessions are kept on the server that issued them. A deployment with several replicas needs sticky sessions until the shared state backend arrives.

Set up OpenID Connect

1. At the provider, register a web application (a confidential client). Redirect URI: https://<your server>/sso/oidc/callback — Settings → Identity (Entra ID) shows the exact string. Grant type: Authorization Code; add Refresh Token if you want roles refreshed without a new sign-in (Okta, Auth0 and Keycloak need the offline_access scope for that).
2. Make the provider send roles or groups as a claim — Okta: a groups claim with a filter; Keycloak: realm_access.roles; Auth0: a namespaced claim added by an Action.
3. In ATX AnalyticsTable, open Settings → Identity (Entra ID) → OpenID Connect. Tick Enabled, enter the Issuer exactly as the provider publishes it (trailing slash included), the Client ID and the Client secret, and the Roles claim and Groups claim if they are not roles and groups.
4. Click Test discovery. It shows the issuer the provider reported and confirms that its endpoints were found.
5. Click Save sign-in settings. The client secret is written to the credential vault on the server; it is never shown again and no endpoint returns it.
6. Sign out and use the new button on the sign-in screen.
ANALYTICS_OIDC_ISSUER — The issuer, exactly as published — —
ANALYTICS_OIDC_CLIENT_ID — The client id — —
ANALYTICS_OIDC_CLIENT_SECRET — The client secret. Without one the server acts as a public client with PKCE only — from the vault (oidc-identity)
ANALYTICS_OIDC_SCOPES — Scopes, separated by spaces or commas — openid profile email
ANALYTICS_OIDC_USERNAME_CLAIM — Where the sign-in name is — preferred_username, then upn, then email, then sub
ANALYTICS_OIDC_ROLES_CLAIM, ANALYTICS_OIDC_GROUPS_CLAIM — Dot paths such as realm_access.roles; a namespaced claim is read whole — roles, groups
ANALYTICS_OIDC_AUDIENCE — Accepted audiences for bearer tokens — the client id
ANALYTICS_OIDC_ACCEPT_BEARER — 0 stops scripts and other apps sending the provider's own access tokens — on
ANALYTICS_OIDC_REQUIRE_SIGN_IN — Refuse /api requests without a signed-in person — off
ANALYTICS_OIDC_LABEL — Text of the sign-in button — Single sign-on
ANALYTICS_PUBLIC_URL — This server's public address. Set it behind a reverse proxy — otherwise the redirect URI is built from the Host header — WEB_ORIGIN, then the request
Environment variables win as a whole: when ANALYTICS_OIDC_ISSUER and ANALYTICS_OIDC_CLIENT_ID are set, the OIDC fields in Settings are read-only and say so. An issuer over plain http is refused except on the local machine.

Set up SAML 2.0

1. At the identity provider, add a relying party / service provider by importing https://<your server>/sso/saml/metadata, or enter it by hand: ACS (reply) URL https://<your server>/sso/saml/acs, HTTP-POST binding; entity ID https://<your server>/sso/saml/metadata (or your own, see ANALYTICS_SAML_SP_ENTITY_ID).
2. Sign the assertion with SHA-256. Signing the Response as well is fine. Do not encrypt the assertion.
3. Send a groups or roles attribute. These are recognised without configuration: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups, http://schemas.xmlsoap.org/claims/Group, groups, memberOf, and for roles …/identity/claims/role, roles and role.
4. In ATX AnalyticsTable, open Settings → Identity (Entra ID) → SAML 2.0. Tick Enabled and enter the IdP sign-in URL, the IdP entity ID and the IdP signing certificate (PEM; paste more than one during a certificate rollover).
5. Click Save sign-in settings, sign out and use the new button.
ANALYTICS_SAML_ENTRY_POINT — The IdP's single sign-on URL (HTTP-Redirect binding)
ANALYTICS_SAML_IDP_CERT or ANALYTICS_SAML_IDP_CERT_FILE — The IdP signing certificate(s), PEM or bare base64
ANALYTICS_SAML_IDP_ISSUER — The IdP entity ID. Recommended: the Issuer must then match
ANALYTICS_SAML_SP_ENTITY_ID — This server's entity ID, when the IdP wants a URN rather than the metadata URL
ANALYTICS_SAML_USERNAME_ATTRIBUTE, _EMAIL_ATTRIBUTE, _DISPLAY_NAME_ATTRIBUTE — Override the defaults (UPN, then e-mail, then the NameID)
ANALYTICS_SAML_GROUPS_ATTRIBUTE, ANALYTICS_SAML_ROLES_ATTRIBUTE — Attribute names, comma-separated
ANALYTICS_SAML_WANT_RESPONSE_SIGNED — 1 requires the Response envelope to be signed as well
ANALYTICS_SAML_REQUIRE_SIGN_IN, ANALYTICS_SAML_LABEL — As for OpenID Connect
A transient NameID changes at every sign-in, so it is not used as the person's identity; the sign-in name is used instead. SAML Single Logout is not implemented: signing out ends the session on this server, and the provider's own session ends when the provider ends it.

Roles from your provider

Groups and roles from the provider are matched against the role map like Entra's: the built-in values AT.Admin, AT.Analyst and AT.Viewer work with no configuration, and ANALYTICS_RBAC_ROLE_MAP maps any group or role name you already have. The highest matching role wins. See Sign-in and roles.

Common problems

Test discovery: "names issuer … not the configured …" — The issuer was typed differently from how the provider publishes it — often a missing or extra trailing slash. — Copy the issuer from the provider's /.well-known/openid-configuration.
"This sign-in was started in a different browser" — The callback arrived without the cookie set at the start — a bookmarked callback URL, or a browser that blocks the cookie. — Start again from the app's sign-in button.
The provider reports a redirect-URI mismatch — The registered URI differs from the one the server sends, usually behind a reverse proxy. — Set ANALYTICS_PUBLIC_URL to the address users open, and register <that address>/sso/oidc/callback.
SAML: "This sign-in was not started from the app" — The IdP sent an unsolicited Response (a portal tile, or a refresh of the ACS page). — Point the tile at https://<your server>/sso/saml/login.
SAML sign-in fails and the server log says Invalid signature — The configured certificate is not the one the IdP signs with, or only the Response is signed. — Paste the IdP's current signing certificate; make the IdP sign the assertion.
Signed in, but everybody is a Viewer — The provider sends no groups or roles, or sends names the role map does not contain. — Add the groups claim or attribute at the provider, or map the names in ANALYTICS_RBAC_ROLE_MAP.

ATX Institute on LinkedIn

This site needs JavaScript for the full experience. Every page above is reachable without it.