Skip to content

External login providers (OpenID Connect): plan and implementation - #4748

Merged
SteRiccio merged 33 commits into
masterfrom
ccr-f0461556-tzz9x8
Nov 18, 2026
Merged

SteRiccio merged 33 commits into
masterfrom
ccr-f0461556-tzz9x8

Conversation

@SteRiccio

@SteRiccio SteRiccio commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Description

Sign-in with external identity providers (Google, Microsoft, any OpenID Connect provider such as Keycloak, Okta or an institutional SSO), alongside email/password login. The server side is in arena-server 2.8.17 (openforis/arena-server#236).

  • Plan and mockup

    docs/superpowers/plans/2026-11-17-oidc-authentication.md (design, access rules, security checklist, implementation notes and follow-ups) and the clickable admin UI mockup in docs/superpowers/mockups/2026-11-18-login-providers/.
  • Login and invitation pages

    • One button per provider under the login form: the official logo for Google and Microsoft, an uploaded or generic icon for the others.
    • The Arena 2FA step after an external sign-in, when the provider requires it (the default).
    • Translated error messages: unknown user, email not verified, email domain not allowed, and so on.
    • The invitation page offers "Continue with ..." instead of choosing a password.
  • System administration > Login providers (system admins only)

    • List: order, enable/disable, linked users count.
    • Add a Google, Microsoft or OpenID Connect provider (google / microsoft suggested as identifier for the presets).
    • Edit form: redirect URI to register at the provider, setup steps for the provider type with a link to its detailed guide, client secret (write-only, never filled in by the browser), allowed email domains (all, or only specific domains entered as chips), Arena 2FA, trust provider emails, show on login page, icon upload.
    • Test connection; test sign-in (shows the claims and the matching Arena user, logs nobody in).
    • Delete, emailing the users left without any sign-in method.
    • Providers defined in AUTH_PROVIDERS_CONFIG are read-only.
  • Sign-in methods in the profile and user edit view

    • Shows the password status and the linked providers.
    • Link a provider (own profile) and unlink one, with an email notification. The last sign-in method can only be removed by a system admin, after confirmation.
    • A user without a password can set one without entering an old one.
  • Server

    • server/modules/authProvider/: admin API and sign-in methods API over the arena-server AuthProviderService.
    • Errors from arena-server services are returned as { key, params } with their status.
    • Two new emails: provider unlinked, provider deleted.
  • Other changes

    • Translations: login/invitation buttons, errors and sign-in methods in all 8 languages. Admin page in English, French and Spanish (the others fall back to English).
    • Docs: authentication section in docs/architecture.md, external login setup in docs/server-requirements.md and .env.template, setup guides for Google, Microsoft, Keycloak and other OpenID Connect providers in docs/login-providers/ (linked from the provider form).
    • Jest: openid-client, oauth4webapi and jose are transformed, as other ESM-only dependencies already are.
    • CI: throwaway AUTH_PROVIDER_SECRET_ENCRYPTION_KEY for the e2e tests.

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)

@openforis/arena-server 2.8.17 (@openforis/arena-core still resolves to a single version); new dev dependency oauth2-mock-server.

How has this been tested

  • yarn typecheck and ESLint (no errors) on the changed files.
  • yarn test:unit on Node 24.22.3: 2279 tests passed.
  • New e2e spec test/e2e/specs/externalLogin.spec.ts against a mock OpenID Connect provider (oauth2-mock-server): provider listed in the admin page, existing user signs in with the provider, unknown user refused, linked provider shown in the profile. It passes locally, together with login.spec.ts.
  • Manually, on a production build with a mock provider: added a provider through the admin page, tested the connection, signed in with it from the login page (account linked by email), checked the profile sign-in methods and the error shown for an unknown user; allowed email domains as chips (required when "only specific domains" is selected).

Do you consider this PR needs further testing?

  • No
  • Yes

Sign-in with real Google, Microsoft and Keycloak clients in a deployment with ARENA_PUBLIC_URL and AUTH_PROVIDER_SECRET_ENCRYPTION_KEY set.

UI changes

New login buttons, invitation page buttons, System administration > Login providers page and Sign-in methods section; screenshots are in the manual sections below.

  • User manual (docs/user-manual/, English, French and Spanish) updated, or not needed

New sections 3.5 Signing in with Google, Microsoft or your organization's account and 14.4 Login providers, with screenshots, in the three languages.

Disclaimer

Follow-ups (listed in the plan): a recent-login check before a user sets their first password, a Sign-in method filter and column in the users list, identity links in the users backup export/import, and translations of the admin page into the other five languages.

@mergify

mergify Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

This pull request is merged.

@SteRiccio SteRiccio changed the title Plan: generic OpenID Connect (OIDC) login Plan: external login providers (OpenID Connect) Nov 18, 2026

Copy link
Copy Markdown
Member Author

The 88 SonarCloud issues were all in the login providers mockup HTML (73 Web:ImgWithoutAltCheck, 15 Web:S6853). Fixed in 56b0337: decorative SVG icons are now aria-hidden, icon-only buttons have an aria-label, and the mockup's field labels are plain text, since the mockup has no real form controls.


Generated by Claude Code

mergify Bot and others added 8 commits November 18, 2026 11:53
…ign-in methods in the profile

- arena-server 2.8.17 (OpenID Connect sign-in)
- admin API (system admins) over the arena-server provider service; user sign-in methods API with unlink
- login page and invitation page buttons, 2FA step and errors after an external sign-in
- Login providers system admin page (list, add, edit, test connection, test sign-in, delete)
- Sign-in methods section in the user profile and edit view; password can be set when the user has none
- e2e tests with a mock OpenID Connect provider
- user manual: 3.5 Signing in with Google, Microsoft or your organization's account; 14.4 Login providers
- architecture and server requirements docs, .env.template
- plan: implementation notes of the Arena side and follow-ups
@SteRiccio SteRiccio changed the title Plan: external login providers (OpenID Connect) External login providers (OpenID Connect): plan and implementation Nov 18, 2026

SteRiccio commented Nov 18, 2026 •

Copy link
Copy Markdown
Member Author

Fixed the 6 SonarCloud issues in 18ce1ee:

  • S9382: the emails to the users left without a sign-in method, when a provider is deleted, are now sent with Promise.all, so there is no await in a loop.
  • S4624 (×2): the provider icon URL and the external login start URL no longer use nested template literals.
  • S6767: isNew is now only in the props of the sections that use it.
  • S6551: the field error keys are typed as strings, so String(...) is no longer needed.
  • S6819: the test sign-in success message uses <output> instead of role="status".

yarn typecheck and ESLint are clean.

mergify Bot and others added 3 commits November 18, 2026 16:55
…sets, clearer setup steps

- client secret uses autocomplete new-password and the identifier field is no longer named id, so browsers don't fill the login email and password
- Google and Microsoft presets suggest google / microsoft as identifier
- per-type setup steps that name the fields to fill in (Connection section) and Save
- redirect URI of a new provider is built by the server (public URL) instead of the browser origin
SteRiccio and others added 9 commits November 18, 2026 18:12
…ic (chips)

- docs/login-providers: setup guides for Google, Microsoft, Keycloak and other OpenID Connect providers, linked from the provider form
- Allowed email domains: radio buttons (all / only specific domains); specific domains are entered as chips and at least one is required
- user manual (EN/FR/ES): allowed email domains, guide link and form screenshot updated
… link of hidden providers

- the Preview login page button opened the login page, which redirects logged-in users to the app (the edit form already has a preview of the button)
- a provider not shown on the login page is used with the sign-in start link (<public URL>/auth/oidc/<id>): the info of Show on the login page named a /guest/login?provider= link that doesn't exist
- user manual (EN/FR/ES): login providers list and edit form screenshots updated
…er and direct link of hidden providers

- What's new item for system admins (EN/FR/ES), with screenshots of the login page and of the Login providers page
- changelog entry for the next release (2.14.0, not released yet: to be dated, or renumbered, at release)
- user manual (EN/FR/ES): google / microsoft suggested as identifier, direct link of the providers not shown on the login page
@sonarqubecloud

Copy link
Copy Markdown

@SteRiccio
SteRiccio merged commit ab868c1 into master Nov 18, 2026
14 checks passed
@SteRiccio
SteRiccio deleted the ccr-f0461556-tzz9x8 branch November 18, 2026 22:37
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