Skip to content

External login providers (OpenID Connect) - #236

Merged
SteRiccio merged 4 commits into
masterfrom
external-login-providers
Nov 18, 2026
Merged

SteRiccio merged 4 commits into
masterfrom
external-login-providers

Conversation

@SteRiccio

@SteRiccio SteRiccio commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Description

Server side of external sign-in with OpenID Connect providers (Google, Microsoft, Keycloak, Okta, institutional SSO), alongside email/password login. Plan: docs/superpowers/plans/2026-11-17-oidc-authentication.md in openforis/arena#4748 (Tasks 1–3, see its "Implementation notes"). The Arena UI (login buttons, "Login providers" admin page, sign-in methods in the profile) comes in a follow-up Arena PR that uses this version.

  • Database

    Migration adding auth_provider (provider settings in props, encrypted client secret, uploaded icon) and user_external_identity (links a user to a provider account by (issuer, subject), cascade on user deletion).
  • Providers: AuthProviderService (ServerServiceType.authProvider)

    • Create, update, delete, reorder and icon upload, with validation.
    • Client secrets are encrypted with AES-256-GCM using AUTH_PROVIDER_SECRET_ENCRYPTION_KEY.
    • Providers can also be set read-only from AUTH_PROVIDERS_CONFIG, a JSON file or inline JSON, with the secrets in AUTH_PROVIDER_<ID>_CLIENT_SECRET.
    • The provider list is cached for 60 s, so changes reach every cluster instance within a minute.
    • Methods for the "Sign-in methods" section: getUserIdentities, and unlinkUserIdentity, which refuses to remove the user's last sign-in method.
  • OpenID Connect adapter

    • Uses openid-client v6: discovery, PKCE (S256), state and nonce, ID token validation.
    • Google and Microsoft are presets of the generic adapter. openid-client handles the Microsoft multi-tenant issuer.
    • An AuthProviderAdapter interface allows non-OIDC providers to be added later.
  • Matching provider accounts to Arena users

    • Login: matches an already-linked account, or else a verified email (or one from a provider trusted for emails). Matching ignores case and Gmail address variants; an email matching two users is refused. Allowed email domains are enforced. An invited user is accepted on first sign-in. There is no sign-up.
    • Invitation: accepts the invitation of the user behind the invitation link, even if the provider email differs. The user gets no password.
    • Link: a logged-in user links a provider account to their own account.
    • Test: a system admin runs a dry-run sign-in that writes nothing and reports the claims and the user that would match.
  • Routes

    • GET /auth/providers and /auth/providers/:id/icon: public.
    • GET /auth/oidc/:id: starts the sign-in.
    • GET /auth/oidc/:id/callback.
    • POST /auth/oidc/_2fa: Arena 2FA after the provider sign-in, when the provider requires it (the default) and the user has 2FA enabled. Uses the login rate limiters.
    • POST /auth/oidc/:id/ticket: short-lived ticket for the link and test modes, requested by the logged-in user.
    • GET /auth/oidc/_test-result: system admins only.
    • The sign-in state and the pending-2FA state are kept in short-lived, signed, httpOnly, SameSite=Lax cookies scoped to /auth/oidc.
    • Redirects back to the app use fixed paths, or a validated /app/... returnTo. Tokens and claims never go in URLs.
    • createSessionTokens was extracted from the password login, so both logins create the same tokens and refresh cookie.
  • Configuration

    ARENA_PUBLIC_URL (for the redirect URIs), AUTH_PROVIDER_SECRET_ENCRYPTION_KEY and AUTH_PROVIDERS_CONFIG, documented in .env.template.

Types of changes

  • Docs change
  • Refactoring
  • Dependency upgrade
  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)

New dependency openid-client; new dev dependency oauth2-mock-server.

How has this been tested

yarn test against PostgreSQL 16 + PostGIS: 19 suites, 122 tests passed. yarn tsc, yarn lint and yarn build are clean. New tests:

  • API tests that run complete sign-ins against oauth2-mock-server, started in a child process (it is ESM only):
    • provider list and reorder
    • unknown user, unverified email, disallowed domain
    • linking by verified email, and a linked account whose email changed at the provider
    • Gmail address variants
    • invitation acceptance with a different email, and an invalid invitation
    • missing flow cookie
    • link mode with a provider already linked
    • last sign-in method refused on unlink
    • Arena 2FA required, then a wrong code and a valid TOTP code
  • Unit tests: email normalization, provider defaults and validation, secret encryption, AUTH_PROVIDERS_CONFIG parsing.

The compiled package was also loaded with plain Node (outside Jest) to check require('openid-client').

Do you consider this PR needs further testing?

  • No
  • Yes

Still to try: a sign-in with real Google, Microsoft and Keycloak providers, in a deployment with ARENA_PUBLIC_URL set. This happens with the Arena PR that adds the UI.

Disclaimer

  • openid-client v6 is ESM only and this package compiles to CommonJS. It is loaded with require (supported by Node.js 22+) plus a type-only import with resolution-mode: 'import'. Jest transforms it, as it does otplib.
  • user_external_identity.provider_id has no foreign key to auth_provider, because providers from AUTH_PROVIDERS_CONFIG have no row there. Deleting a provider deletes its links in the same transaction.
  • The migration generator script (yarn dbmigrate:create) failed under ts-node in my environment, so the migration files were written from the existing template.

SteRiccio commented Nov 18, 2026 •

Copy link
Copy Markdown
Member Author

Fixed all 9 SonarCloud findings in 28d5743:

  • S7727 (the bug behind the C reliability rating): items.map(toProvider) now passes an explicit (item, index) callback.
  • S8786: ARENA_PUBLIC_URL trailing slashes and the Gmail +suffix are now removed without a regular expression.
  • S9382: provider reorder is a single UPDATE ... FROM unnest(...), so there is no await in a loop. A test now covers it.
  • S7776: gmailDomains and allowedIconMimes are now Sets.
  • S7780: the email normalization SQL uses String.raw.
  • S7503: handleTicket is no longer async.
  • S6551: the test cookie helper no longer stringifies an unknown value.

c7c117e restores 4 unrelated files that a Prettier run had reformatted in 28d5743. yarn test passes: 19 suites, 122 tests.


Generated by Claude Code

@sonarqubecloud

Copy link
Copy Markdown

@SteRiccio
SteRiccio merged commit 07053fa into master Nov 18, 2026
8 checks passed
@SteRiccio
SteRiccio deleted the external-login-providers branch November 18, 2026 12:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant