Skip to content

Add trusted-assertion authentication provider (signed JWT from an authenticating reverse proxy) - #2595

Open
robireton wants to merge 2 commits into
OHDSI:masterfrom
Center-for-Health-Informatics:trusted-assertion
Open

robireton wants to merge 2 commits into
OHDSI:masterfrom
Center-for-Health-Informatics:trusted-assertion

Conversation

@robireton

Copy link
Copy Markdown

Why

Many sites already put WebAPI and Atlas behind an authenticating reverse proxy (nginx auth_request, oauth2-proxy, Apache mod_auth_openidc, or an institutional SSO gateway). Today WebAPI can't use that sign-in directly. The options are a second login (DB/LDAP/OIDC) or trusting a plain REMOTE_USER-style header, which anyone who reaches WebAPI directly can forge.

This provider accepts a signed, short-lived JWT that the proxy adds to each request. WebAPI verifies it against the proxy's JWKS. Nothing is trusted just because of the network path.

What it does

  • GET /user/login/assertion verifies the assertion header and logs in through LoginService like every other provider. The user gets UserOrigin.ASSERTION; origin is stored as a string, so no migration is needed. It is listed in /auth/providers as an ajax provider, so Atlas needs no changes.

  • Per-request binding (enforce-on-every-request, default on). A filter that runs after Spring Security requires a valid assertion for the same user on every request made with a WebAPI session token. Two effects:

    • A leaked WebAPI token is useless without a live proxy session.
    • Signing out at the proxy takes effect within the assertion's lifetime.

    API-key and anonymous requests are not affected.

  • Auto-provisioning (default on) creates the user on first login. When it is off, unknown users get 403. Assertions carry no roles; roles stay managed in WebAPI.

Security properties

  • Algorithm allow-list, ES256 by default. HS* and none are rejected at config time and at verification.
  • iss must match exactly and aud must contain the configured value. exp is required: Spring's JwtTimestampValidator alone would accept a token with no exp.
  • JWKS fetches have connect and read timeouts. An unreachable JWKS returns 503, not 401, so an IdP outage doesn't look like everyone being signed out.
  • A mismatch between the token user and the assertion user is logged as SECURITY_AUDIT.
  • The provider is off by default, and enabling it without jwk-set-uri, issuer and audience fails at startup.

Configuration and docs

Disabled by default. Enable with security.auth.assertion.enabled: true plus jwk-set-uri, issuer and audience. The full property reference, the claims the assertion must contain, an nginx auth_request example, the endpoint's error responses and the security considerations are in the new articles/TrustedAssertion_HOWTO.md.

Changes

  • New package org.ohdsi.webapi.security.authc.assertion: AssertionAuthConfig, AssertionAuthProperties, AssertionVerifier, AssertionLoginController, AssertionBindingFilter.
  • AuthProviderService: lists the provider when it is enabled.
  • UserOrigin: adds ASSERTION.
  • application.yaml: a documented security.auth.assertion block, disabled by default.
  • Docs: new articles/TrustedAssertion_HOWTO.md; the provider is added to the README's auth-provider list and to articles/LoginPipeline.md (flow and UserOrigin).
  • No new dependencies. It uses the existing spring-boot-starter-oauth2-resource-server.

Tests

AssertionVerifierTest, AssertionLoginControllerTest and AssertionBindingFilterTest run against a real local JWKS server, so the production decoder, including its key fetch, is exercised. They cover:

  • valid, expired and missing-exp tokens;
  • wrong or missing aud, wrong iss, no sub;
  • a foreign signing key, an unknown kid, HS256, alg: none, garbage input;
  • JWKS unavailable;
  • user binding, and API-key and anonymous pass-through.

This is running in production at the University of Cincinnati Center for Health Informatics, in front of WebAPI 3 / Atlas3, behind nginx auth_request and our SSO service. It is early days: only a handful of users have signed in through it so far.

🤖 Generated with Claude Code

robireton and others added 2 commits November 16, 2026 11:41
Authenticates users from a short-lived signed JWT that an authenticating
reverse proxy adds to each request (e.g. nginx auth_request in front of
an SSO service), configured under security.auth.assertion.*.

- GET /user/login/assertion verifies the header against a JWKS (ES256
  by default; HS* and none refused), pins iss and aud, requires exp, and
  logs in through LoginService like every other provider. Listed in
  /auth/providers as an ajax provider, so Atlas needs no changes.
- With enforce-on-every-request (default), a filter after Spring
  Security requires a valid assertion for the same user on every request
  made with a WebAPI session token. A leaked WebAPI token is useless
  without a live proxy session, and proxy sign-out takes effect within
  the assertion's lifetime. API-key requests are not affected.
- An unreachable JWKS answers 503, not 401, so an outage doesn't read as
  everyone being signed out. JWKS fetches have a timeout.
- auto-provision (default true) creates the user on first login;
  otherwise unknown users get 403.

New UserOrigin.ASSERTION; origin is stored as a string, so no migration.

Tests use a real local JWKS server so the production decoder, including
its key fetch, is exercised: valid, expired, no exp, wrong/missing aud,
wrong iss, no sub, foreign key, unknown kid, HS256, alg none, garbage,
JWKS down, user binding, API-key and anonymous pass-through.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
New articles/TrustedAssertion_HOWTO.md: when to use it, the login and
per-request binding flow, property reference (including the optional
claim and timeout settings), required claims, roles, proxy setup with an
nginx auth_request example, endpoint responses and security notes.

README lists security.auth.assertion.enabled with the other providers;
LoginPipeline.md gains the flow entry and UserOrigin.ASSERTION.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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