Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-28T22:26:20Z

Jweisz: /* Tests (74 total) */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Provider configuration is validated at boot via config/initializers/oidc.rb. In production, a provider with any missing required key raises OidcConfig::InvalidConfiguration, which prevents the application from starting with a misconfigured OIDC provider. In all other environments (development, test), the invalid provider is skipped with a warning logged so that local development and CI are not blocked when OIDC credentials are not configured.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Login ===
At one point it was suggested that OIDC completely replace password login if configured. We considered this idea, however, given this feature must support multiple institutions, some of which may want OIDC and others which may not and there is no institution context pre-login at this time, we felt that probably falls under account management and is beyond the scope of this assignment.

=== Logout ===
Logout will not be impacted. The OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is required and must be true.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each identity provider is defined as a YAML configuration block with its own credentials, issuer, and scopes. <code>OidcRequest.authorization_uri_for!</code> and <code>OidcLoginController#callback</code> operate on whatever provider key is passed in, with no <code>if provider == "google"</code> branching. Adding a new institution's SSO requires only a new YAML entry and environment variables, no code changes anywhere.
** [https://github.com/johnmweisz/reimplementation-back-end/blob/9bc24c3ca0a13188899b3b72ec3208afcdd8a21b/app/controllers/oidc_login_controller.rb#L34 Source]

* '''Singleton''' — <code>OidcConfig</code> is effectively a singleton: provider configuration is memoized as class-level state and cleared via <code>reload!</code>, ensuring YAML is parsed once per process. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing additional safety since necessary methods are not available to a new instance anyway. AI recommended we keep it this way.

* '''Probabilistic Garbage Collection''' — Stale <code>oidc_requests</code> rows are cleaned up on a small percentage (10%) of new request creations rather than scheduled. This amortizes cleanup cost across normal usage and avoids adding a scheduler dependency to the application.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== New Dependencies ==

=== openid_connect ===

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>oidc_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

=== rack-attack ===

The <code>rack-attack</code> gem ([https://github.com/rack/rack-attack github.com/rack/rack-attack]) was added to provide rate limiting on the OIDC endpoints. Without it, an attacker could spam <code>POST /auth/client-select</code> to fill the <code>oidc_requests</code> table or repeatedly probe <code>POST /auth/callback</code> to attempt token guessing.

* '''Throttle abuse before it reaches the application:''' Rack-level middleware rejects abusive clients before any controller code runs, protecting both the database and the IdP discovery endpoints from being hammered.
* '''Per-IP throttling on OIDC endpoints:''' <code>POST /auth/client-select</code> is rate-limited to prevent table-fill attacks and discovery spam (each request creates a row and triggers an IdP discovery call). <code>POST /auth/callback</code> is rate-limited to slow brute-force state guessing — even though the state values have 256 bits of entropy and won't realistically be guessed, throttling prevents wasted work and log noise.
* '''Lightweight and well-established:''' Single gem, no external dependencies (uses Rails cache for storage), maintained by the Rack team, used by tens of thousands of production Rails apps.
* '''Configuration in code:''' Rules live in <code>config/initializers/rack_attack.rb</code> and are version-controlled alongside the rest of the auth configuration, rather than living in a gateway or load balancer config.

The tradeoff is that rate limiting at the application layer is best-effort — a sufficiently distributed attack can still overwhelm the app. For production deployment, a gateway-level rate limit (e.g. nginx, Cloudflare) should be added in front of <code>rack-attack</code> as defense in depth. <code>rack-attack</code> is documented as the application-layer baseline, not the only line of defense.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests (74 total) ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

Validates the full OIDC flow on the model: that state values are atomically consumed (preventing replay), that stale rows are cleaned up, that authorization URLs include the right parameters, that ID tokens are properly verified (signature, nonce, email_verified), and that user matching is case-insensitive and whitespace-tolerant. The IdP is fully stubbed so tests run without network access.

* '''.consume_recent_by_state!''' — Verifies the matching row is destroyed on consumption, expired or missing rows raise <code>RecordNotFound</code>, and replay attempts fail because the row has already been deleted.
* '''.delete_stale''' — Confirms rows older than the validity window are deleted while fresh rows are preserved.
* '''Probabilistic cleanup on create''' — Confirms <code>CleanupStaleOidcRequestsJob</code> is enqueued only when <code>rand</code> falls under the configured threshold.
* '''.authorization_uri_for!''' — Creates an <code>oidc_requests</code> row with the username, returns a properly-formed authorization URI, falls back to default scopes when none are configured, and rejects duplicate state values via the unique index.
* '''#verified_email_from_code!''' — Returns the email when <code>email_verified</code> is true, raises <code>AuthenticationError</code> when the claim is absent or false, and raises <code>InvalidToken</code> when the nonce doesn't match.
* '''#authenticate_user!''' — Matches users by username and email with case-insensitive, whitespace-tolerant comparison; raises <code>AuthenticationError</code> when either field doesn't match or the email is blank.
* '''.new_client''' — Builds an <code>OpenIDConnect::Client</code> with the correct credentials and discovery endpoints.

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

Covers YAML loading and validation of the provider config. Verifies ERB env var interpolation, memoization with explicit reload, defensive parsing of malformed inputs, the production-vs-non-production validation behavior (raise vs. warn), scope normalization, and that secrets never leak through <code>public_list</code>.

* '''.providers''' — Loads providers from YAML with ERB interpolation, memoizes results until <code>reload!</code>, and gracefully handles malformed input (empty file, null providers, non-Hash structures, YAML aliases) by returning an empty hash. Skips invalid providers with a warning.
* '''Production behavior''' — Raises <code>InvalidConfiguration</code> in production (rather than skipping with a warning) when providers are missing required keys or the YAML structure is invalid.
* '''.find''' — Returns the provider config by key, raises <code>ProviderNotFound</code> for unknown keys.
* '''.public_list''' — Returns only id and name per provider, never secrets or endpoints.
* '''.scopes_for''' — Parses whitespace-, comma-, and mixed-delimited scope strings; falls back to default scopes when missing or nil.

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

Verifies the shared session token method used by both password and OIDC login: that the JWT contains the expected user attributes, has the correct expiry, and that signature tampering is detected on decode.

* '''#generate_jwt''' — Encodes the expected user attributes (id, name, full_name, role, institution_id, exp), defaults to a 24-hour expiry, and rejects tampered tokens on decode.

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

End-to-end request specs covering the three OIDC endpoints. Validates the happy path, all documented error responses (400/401/404/502), the generic 401 policy that hides which specific check failed, and Rack::Attack rate limiting on the write endpoints.

* '''GET /auth/providers''' — Returns the provider list with id and name only, with no secrets leaked.
* '''POST /auth/client-select''' — Returns an authorization URL on the happy path; returns 400 for missing params, 404 for unknown providers, and 502 when discovery fails.
* '''POST /auth/callback — happy path''' — Exchanges a valid code and state for a session JWT.
* '''POST /auth/callback — generic 401 "Authentication failed"''' — Returns the same generic 401 for all failure modes (no matching user, username/email mismatch, invalid or expired state, token verification failure, deleted provider) to avoid information leakage.
* '''POST /auth/callback — other errors''' — Returns 400 for missing params and 502 when discovery fails.
* '''Rate limiting (Rack::Attack)''' — Confirms requests succeed within the configured limit on each endpoint, return 429 with a <code>Retry-After</code> header when exceeded, and that throttling is per-IP (one IP hitting the limit does not affect others).

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

Verifies the SSO modal behavior: that the SSO button only appears when providers are configured, the modal opens with the username input and provider dropdown, the form gates submission until both fields are filled, and that successful submits redirect to the IdP's authorization URL. Axios is mocked to keep tests offline.

* '''OidcModal Component''' — Renders nothing when the providers response is empty or fails; renders the SSO button and opens a modal with the provider dropdown when providers are returned; disables submit until both username and provider are filled; posts the provider id and username to <code>/auth/client-select</code> and redirects the browser to the returned authorization URL on success (no redirect on failure).

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

Verifies the callback page that handles the redirect back from the identity provider: that it posts the code and state to the backend on mount, processes the success response (storing the JWT, dispatching auth state, navigating to the dashboard), and degrades gracefully on missing params, IdP errors, or backend failures.

* '''OidcCallback Component''' — Posts code and state to <code>/auth/callback</code> on mount, stores the JWT and dispatches auth state on success, redirects to the dashboard, displays an error alert and redirects to login on failure, handles the IdP <code>error</code> query parameter without calling the backend, redirects to login when params are missing, and shows a "Completing login..." message while in flight.

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

=== Story 15: Backend — Rate Limiting on OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints rate-limited at the application layer, '''so that''' abusive clients cannot fill the <code>oidc_requests</code> table, hammer the IdP discovery endpoint, or brute-force callback state values.

'''Acceptance Criteria:'''
* Add the <code>rack-attack</code> gem to the Gemfile.
* Configure throttles in <code>config/initializers/rack_attack.rb</code>:
** <code>POST /auth/client-select</code>: throttled per IP (e.g. 10 requests per minute) to prevent table-fill and discovery-spam attacks.
** <code>POST /auth/callback</code>: throttled per IP (e.g. 20 requests per minute) to slow brute-force state guessing.
* Throttled requests return HTTP 429 with a JSON body matching the existing error response shape (<code>{ error: "Too many requests" }</code>).
* Use the Rails cache (<code>Rails.cache</code>) as the backing store so no additional infrastructure is required.
* Document the rationale in the initializer with a brief comment, including the note that gateway-level rate limiting (nginx, Cloudflare) should be added in front for defense in depth in production.
* Add request specs verifying:
** A burst of requests above the threshold returns 429.
** Requests under the threshold succeed normally.
** Different IPs are throttled independently.
* Verify existing endpoints (login, etc.) are not affected by the new rules.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://youtu.be/ES6VWZxkj_w| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-28T22:20:02Z

Jweisz: /* Tests (74 total) */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Provider configuration is validated at boot via config/initializers/oidc.rb. In production, a provider with any missing required key raises OidcConfig::InvalidConfiguration, which prevents the application from starting with a misconfigured OIDC provider. In all other environments (development, test), the invalid provider is skipped with a warning logged so that local development and CI are not blocked when OIDC credentials are not configured.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Login ===
At one point it was suggested that OIDC completely replace password login if configured. We considered this idea, however, given this feature must support multiple institutions, some of which may want OIDC and others which may not and there is no institution context pre-login at this time, we felt that probably falls under account management and is beyond the scope of this assignment.

=== Logout ===
Logout will not be impacted. The OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is required and must be true.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each identity provider is defined as a YAML configuration block with its own credentials, issuer, and scopes. <code>OidcRequest.authorization_uri_for!</code> and <code>OidcLoginController#callback</code> operate on whatever provider key is passed in, with no <code>if provider == "google"</code> branching. Adding a new institution's SSO requires only a new YAML entry and environment variables, no code changes anywhere.
** [https://github.com/johnmweisz/reimplementation-back-end/blob/9bc24c3ca0a13188899b3b72ec3208afcdd8a21b/app/controllers/oidc_login_controller.rb#L34 Source]

* '''Singleton''' — <code>OidcConfig</code> is effectively a singleton: provider configuration is memoized as class-level state and cleared via <code>reload!</code>, ensuring YAML is parsed once per process. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing additional safety since necessary methods are not available to a new instance anyway. AI recommended we keep it this way.

* '''Probabilistic Garbage Collection''' — Stale <code>oidc_requests</code> rows are cleaned up on a small percentage (10%) of new request creations rather than scheduled. This amortizes cleanup cost across normal usage and avoids adding a scheduler dependency to the application.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== New Dependencies ==

=== openid_connect ===

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>oidc_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

=== rack-attack ===

The <code>rack-attack</code> gem ([https://github.com/rack/rack-attack github.com/rack/rack-attack]) was added to provide rate limiting on the OIDC endpoints. Without it, an attacker could spam <code>POST /auth/client-select</code> to fill the <code>oidc_requests</code> table or repeatedly probe <code>POST /auth/callback</code> to attempt token guessing.

* '''Throttle abuse before it reaches the application:''' Rack-level middleware rejects abusive clients before any controller code runs, protecting both the database and the IdP discovery endpoints from being hammered.
* '''Per-IP throttling on OIDC endpoints:''' <code>POST /auth/client-select</code> is rate-limited to prevent table-fill attacks and discovery spam (each request creates a row and triggers an IdP discovery call). <code>POST /auth/callback</code> is rate-limited to slow brute-force state guessing — even though the state values have 256 bits of entropy and won't realistically be guessed, throttling prevents wasted work and log noise.
* '''Lightweight and well-established:''' Single gem, no external dependencies (uses Rails cache for storage), maintained by the Rack team, used by tens of thousands of production Rails apps.
* '''Configuration in code:''' Rules live in <code>config/initializers/rack_attack.rb</code> and are version-controlled alongside the rest of the auth configuration, rather than living in a gateway or load balancer config.

The tradeoff is that rate limiting at the application layer is best-effort — a sufficiently distributed attack can still overwhelm the app. For production deployment, a gateway-level rate limit (e.g. nginx, Cloudflare) should be added in front of <code>rack-attack</code> as defense in depth. <code>rack-attack</code> is documented as the application-layer baseline, not the only line of defense.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests (74 total) ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

Validates the full OIDC flow on the model: that state values are atomically consumed (preventing replay), that stale rows are cleaned up, that authorization URLs include the right parameters, that ID tokens are properly verified (signature, nonce, email_verified), and that user matching is case-insensitive and whitespace-tolerant. The IdP is fully stubbed so tests run without network access.

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing
* Raises a uniqueness error when two rows have the same state

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false
* Raises InvalidToken when the token's nonce doesn't match (tampered/replayed token)

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

Covers YAML loading and validation of the provider config. Verifies ERB env var interpolation, memoization with explicit reload, defensive parsing of malformed inputs, the production-vs-non-production validation behavior (raise vs. warn), scope normalization, and that secrets never leak through <code>public_list</code>.

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

Verifies the shared session token method used by both password and OIDC login: that the JWT contains the expected user attributes, has the correct expiry, and that signature tampering is detected on decode.

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

End-to-end request specs covering the three OIDC endpoints. Validates the happy path, all documented error responses (400/401/404/502), the generic 401 policy that hides which specific check failed, and Rack::Attack rate limiting on the write endpoints.

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

'''Rate limiting (Rack::Attack)'''
* <code>POST /auth/client-select</code>: 5 requests from one IP all succeed (within limit)
* <code>POST /auth/client-select</code>: 6th request from same IP gets 429 with "Rate limit exceeded"
* <code>POST /auth/client-select</code>: throttled response includes a Retry-After header
* <code>POST /auth/client-select</code>: hitting the limit on one IP does not affect a different IP
* <code>POST /auth/callback</code>: 10 requests from one IP all succeed (within limit)
* <code>POST /auth/callback</code>: 11th request from same IP gets 429 with "Rate limit exceeded"
* <code>POST /auth/callback</code>: throttled response includes a Retry-After header

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

Verifies the SSO modal behavior: that the SSO button only appears when providers are configured, the modal opens with the username input and provider dropdown, the form gates submission until both fields are filled, and that successful submits redirect to the IdP's authorization URL. Axios is mocked to keep tests offline.

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

Verifies the callback page that handles the redirect back from the identity provider: that it posts the code and state to the backend on mount, processes the success response (storing the JWT, dispatching auth state, navigating to the dashboard), and degrades gracefully on missing params, IdP errors, or backend failures.

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

=== Story 15: Backend — Rate Limiting on OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints rate-limited at the application layer, '''so that''' abusive clients cannot fill the <code>oidc_requests</code> table, hammer the IdP discovery endpoint, or brute-force callback state values.

'''Acceptance Criteria:'''
* Add the <code>rack-attack</code> gem to the Gemfile.
* Configure throttles in <code>config/initializers/rack_attack.rb</code>:
** <code>POST /auth/client-select</code>: throttled per IP (e.g. 10 requests per minute) to prevent table-fill and discovery-spam attacks.
** <code>POST /auth/callback</code>: throttled per IP (e.g. 20 requests per minute) to slow brute-force state guessing.
* Throttled requests return HTTP 429 with a JSON body matching the existing error response shape (<code>{ error: "Too many requests" }</code>).
* Use the Rails cache (<code>Rails.cache</code>) as the backing store so no additional infrastructure is required.
* Document the rationale in the initializer with a brief comment, including the note that gateway-level rate limiting (nginx, Cloudflare) should be added in front for defense in depth in production.
* Add request specs verifying:
** A burst of requests above the threshold returns 429.
** Requests under the threshold succeed normally.
** Different IPs are throttled independently.
* Verify existing endpoints (login, etc.) are not affected by the new rules.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://youtu.be/ES6VWZxkj_w| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-27T14:17:21Z

Jweisz: /* Design Patterns */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Provider configuration is validated at boot via config/initializers/oidc.rb. In production, a provider with any missing required key raises OidcConfig::InvalidConfiguration, which prevents the application from starting with a misconfigured OIDC provider. In all other environments (development, test), the invalid provider is skipped with a warning logged so that local development and CI are not blocked when OIDC credentials are not configured.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Login ===
At one point it was suggested that OIDC completely replace password login if configured. We considered this idea, however, given this feature must support multiple institutions, some of which may want OIDC and others which may not and there is no institution context pre-login at this time, we felt that probably falls under account management and is beyond the scope of this assignment.

=== Logout ===
Logout will not be impacted. The OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is required and must be true.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each identity provider is defined as a YAML configuration block with its own credentials, issuer, and scopes. <code>OidcRequest.authorization_uri_for!</code> and <code>OidcLoginController#callback</code> operate on whatever provider key is passed in, with no <code>if provider == "google"</code> branching. Adding a new institution's SSO requires only a new YAML entry and environment variables, no code changes anywhere.

* '''Singleton''' — <code>OidcConfig</code> is effectively a singleton: provider configuration is memoized as class-level state and cleared via <code>reload!</code>, ensuring YAML is parsed once per process. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing additional safety since necessary methods are not available to a new instance anyway. AI recommended we keep it this way.

* '''Probabilistic Garbage Collection''' — Stale <code>oidc_requests</code> rows are cleaned up on a small percentage (10%) of new request creations rather than scheduled. This amortizes cleanup cost across normal usage and avoids adding a scheduler dependency to the application.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== New Dependencies ==

=== openid_connect ===

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>oidc_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

=== rack-attack ===

The <code>rack-attack</code> gem ([https://github.com/rack/rack-attack github.com/rack/rack-attack]) was added to provide rate limiting on the OIDC endpoints. Without it, an attacker could spam <code>POST /auth/client-select</code> to fill the <code>oidc_requests</code> table or repeatedly probe <code>POST /auth/callback</code> to attempt token guessing.

* '''Throttle abuse before it reaches the application:''' Rack-level middleware rejects abusive clients before any controller code runs, protecting both the database and the IdP discovery endpoints from being hammered.
* '''Per-IP throttling on OIDC endpoints:''' <code>POST /auth/client-select</code> is rate-limited to prevent table-fill attacks and discovery spam (each request creates a row and triggers an IdP discovery call). <code>POST /auth/callback</code> is rate-limited to slow brute-force state guessing — even though the state values have 256 bits of entropy and won't realistically be guessed, throttling prevents wasted work and log noise.
* '''Lightweight and well-established:''' Single gem, no external dependencies (uses Rails cache for storage), maintained by the Rack team, used by tens of thousands of production Rails apps.
* '''Configuration in code:''' Rules live in <code>config/initializers/rack_attack.rb</code> and are version-controlled alongside the rest of the auth configuration, rather than living in a gateway or load balancer config.

The tradeoff is that rate limiting at the application layer is best-effort — a sufficiently distributed attack can still overwhelm the app. For production deployment, a gateway-level rate limit (e.g. nginx, Cloudflare) should be added in front of <code>rack-attack</code> as defense in depth. <code>rack-attack</code> is documented as the application-layer baseline, not the only line of defense.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests (74 total) ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing
* .authorization_uri_for! Raises a uniqueness error when two rows have the same state

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false
* #verified_email_from_code! Raises InvalidToken when the token's nonce doesn't match (tampered/replayed token)

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

'''Rate limiting (Rack::Attack)'''
* <code>POST /auth/client-select</code>: 5 requests from one IP all succeed (within limit)
* <code>POST /auth/client-select</code>: 6th request from same IP gets 429 with "Rate limit exceeded"
* <code>POST /auth/client-select</code>: throttled response includes a Retry-After header
* <code>POST /auth/client-select</code>: hitting the limit on one IP does not affect a different IP
* <code>POST /auth/callback</code>: 10 requests from one IP all succeed (within limit)
* <code>POST /auth/callback</code>: 11th request from same IP gets 429 with "Rate limit exceeded"
* <code>POST /auth/callback</code>: throttled response includes a Retry-After header

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

=== Story 15: Backend — Rate Limiting on OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints rate-limited at the application layer, '''so that''' abusive clients cannot fill the <code>oidc_requests</code> table, hammer the IdP discovery endpoint, or brute-force callback state values.

'''Acceptance Criteria:'''
* Add the <code>rack-attack</code> gem to the Gemfile.
* Configure throttles in <code>config/initializers/rack_attack.rb</code>:
** <code>POST /auth/client-select</code>: throttled per IP (e.g. 10 requests per minute) to prevent table-fill and discovery-spam attacks.
** <code>POST /auth/callback</code>: throttled per IP (e.g. 20 requests per minute) to slow brute-force state guessing.
* Throttled requests return HTTP 429 with a JSON body matching the existing error response shape (<code>{ error: "Too many requests" }</code>).
* Use the Rails cache (<code>Rails.cache</code>) as the backing store so no additional infrastructure is required.
* Document the rationale in the initializer with a brief comment, including the note that gateway-level rate limiting (nginx, Cloudflare) should be added in front for defense in depth in production.
* Add request specs verifying:
** A burst of requests above the threshold returns 429.
** Requests under the threshold succeed normally.
** Different IPs are throttled independently.
* Verify existing endpoints (login, etc.) are not affected by the new rules.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://youtu.be/ES6VWZxkj_w| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-27T14:16:31Z

Jweisz: /* Design Patterns */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Provider configuration is validated at boot via config/initializers/oidc.rb. In production, a provider with any missing required key raises OidcConfig::InvalidConfiguration, which prevents the application from starting with a misconfigured OIDC provider. In all other environments (development, test), the invalid provider is skipped with a warning logged so that local development and CI are not blocked when OIDC credentials are not configured.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Login ===
At one point it was suggested that OIDC completely replace password login if configured. We considered this idea, however, given this feature must support multiple institutions, some of which may want OIDC and others which may not and there is no institution context pre-login at this time, we felt that probably falls under account management and is beyond the scope of this assignment.

=== Logout ===
Logout will not be impacted. The OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is required and must be true.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each identity provider is defined as a YAML configuration block with its own credentials, issuer, and scopes. <code>OidcRequest.authorization_uri_for!</code> and <code>OidcLoginController#callback</code> operate on whatever provider key is passed in, with no <code>if provider == "google"</code> branching. Adding a new institution's SSO requires only a new YAML entry and environment variables, no code changes anywhere.

* '''Singleton''' — <code>OidcConfig</code> is effectively a singleton: provider configuration is memoized as class-level state and cleared via <code>reload!</code>, ensuring YAML is parsed once per process. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing additional safety (since necessary methods are not available to a new instance.

* '''Probabilistic Garbage Collection''' — Stale <code>oidc_requests</code> rows are cleaned up on a small percentage (10%) of new request creations rather than scheduled. This amortizes cleanup cost across normal usage and avoids adding a scheduler dependency to the application.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== New Dependencies ==

=== openid_connect ===

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>oidc_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

=== rack-attack ===

The <code>rack-attack</code> gem ([https://github.com/rack/rack-attack github.com/rack/rack-attack]) was added to provide rate limiting on the OIDC endpoints. Without it, an attacker could spam <code>POST /auth/client-select</code> to fill the <code>oidc_requests</code> table or repeatedly probe <code>POST /auth/callback</code> to attempt token guessing.

* '''Throttle abuse before it reaches the application:''' Rack-level middleware rejects abusive clients before any controller code runs, protecting both the database and the IdP discovery endpoints from being hammered.
* '''Per-IP throttling on OIDC endpoints:''' <code>POST /auth/client-select</code> is rate-limited to prevent table-fill attacks and discovery spam (each request creates a row and triggers an IdP discovery call). <code>POST /auth/callback</code> is rate-limited to slow brute-force state guessing — even though the state values have 256 bits of entropy and won't realistically be guessed, throttling prevents wasted work and log noise.
* '''Lightweight and well-established:''' Single gem, no external dependencies (uses Rails cache for storage), maintained by the Rack team, used by tens of thousands of production Rails apps.
* '''Configuration in code:''' Rules live in <code>config/initializers/rack_attack.rb</code> and are version-controlled alongside the rest of the auth configuration, rather than living in a gateway or load balancer config.

The tradeoff is that rate limiting at the application layer is best-effort — a sufficiently distributed attack can still overwhelm the app. For production deployment, a gateway-level rate limit (e.g. nginx, Cloudflare) should be added in front of <code>rack-attack</code> as defense in depth. <code>rack-attack</code> is documented as the application-layer baseline, not the only line of defense.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests (74 total) ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing
* .authorization_uri_for! Raises a uniqueness error when two rows have the same state

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false
* #verified_email_from_code! Raises InvalidToken when the token's nonce doesn't match (tampered/replayed token)

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

'''Rate limiting (Rack::Attack)'''
* <code>POST /auth/client-select</code>: 5 requests from one IP all succeed (within limit)
* <code>POST /auth/client-select</code>: 6th request from same IP gets 429 with "Rate limit exceeded"
* <code>POST /auth/client-select</code>: throttled response includes a Retry-After header
* <code>POST /auth/client-select</code>: hitting the limit on one IP does not affect a different IP
* <code>POST /auth/callback</code>: 10 requests from one IP all succeed (within limit)
* <code>POST /auth/callback</code>: 11th request from same IP gets 429 with "Rate limit exceeded"
* <code>POST /auth/callback</code>: throttled response includes a Retry-After header

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

=== Story 15: Backend — Rate Limiting on OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints rate-limited at the application layer, '''so that''' abusive clients cannot fill the <code>oidc_requests</code> table, hammer the IdP discovery endpoint, or brute-force callback state values.

'''Acceptance Criteria:'''
* Add the <code>rack-attack</code> gem to the Gemfile.
* Configure throttles in <code>config/initializers/rack_attack.rb</code>:
** <code>POST /auth/client-select</code>: throttled per IP (e.g. 10 requests per minute) to prevent table-fill and discovery-spam attacks.
** <code>POST /auth/callback</code>: throttled per IP (e.g. 20 requests per minute) to slow brute-force state guessing.
* Throttled requests return HTTP 429 with a JSON body matching the existing error response shape (<code>{ error: "Too many requests" }</code>).
* Use the Rails cache (<code>Rails.cache</code>) as the backing store so no additional infrastructure is required.
* Document the rationale in the initializer with a brief comment, including the note that gateway-level rate limiting (nginx, Cloudflare) should be added in front for defense in depth in production.
* Add request specs verifying:
** A burst of requests above the threshold returns 429.
** Requests under the threshold succeed normally.
** Different IPs are throttled independently.
* Verify existing endpoints (login, etc.) are not affected by the new rules.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://youtu.be/ES6VWZxkj_w| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-26T17:11:28Z

Jweisz: /* Design Patterns */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Provider configuration is validated at boot via config/initializers/oidc.rb. In production, a provider with any missing required key raises OidcConfig::InvalidConfiguration, which prevents the application from starting with a misconfigured OIDC provider. In all other environments (development, test), the invalid provider is skipped with a warning logged so that local development and CI are not blocked when OIDC credentials are not configured.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Login ===
At one point it was suggested that OIDC completely replace password login if configured. We considered this idea, however, given this feature must support multiple institutions, some of which may want OIDC and others which may not and there is no institution context pre-login at this time, we felt that probably falls under account management and is beyond the scope of this assignment.

=== Logout ===
Logout will not be impacted. The OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is required and must be true.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each identity provider is defined as a YAML configuration block with its own credentials, issuer, and scopes. <code>OidcRequest.authorization_uri_for!</code> and <code>OidcLoginController#callback</code> operate on whatever provider key is passed in, with no <code>if provider == "google"</code> branching. Adding a new institution's SSO requires only a new YAML entry and environment variables, no code changes anywhere.

* '''Singleton''' — <code>OidcConfig</code> is effectively a singleton: provider configuration is memoized as class-level state and cleared via <code>reload!</code>, ensuring YAML is parsed once per process. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing additional safety.

* '''Probabilistic Garbage Collection''' — Stale <code>oidc_requests</code> rows are cleaned up on a small percentage (10%) of new request creations rather than scheduled. This amortizes cleanup cost across normal usage and avoids adding a scheduler dependency to the application.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== New Dependencies ==

=== openid_connect ===

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>oidc_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

=== rack-attack ===

The <code>rack-attack</code> gem ([https://github.com/rack/rack-attack github.com/rack/rack-attack]) was added to provide rate limiting on the OIDC endpoints. Without it, an attacker could spam <code>POST /auth/client-select</code> to fill the <code>oidc_requests</code> table or repeatedly probe <code>POST /auth/callback</code> to attempt token guessing.

* '''Throttle abuse before it reaches the application:''' Rack-level middleware rejects abusive clients before any controller code runs, protecting both the database and the IdP discovery endpoints from being hammered.
* '''Per-IP throttling on OIDC endpoints:''' <code>POST /auth/client-select</code> is rate-limited to prevent table-fill attacks and discovery spam (each request creates a row and triggers an IdP discovery call). <code>POST /auth/callback</code> is rate-limited to slow brute-force state guessing — even though the state values have 256 bits of entropy and won't realistically be guessed, throttling prevents wasted work and log noise.
* '''Lightweight and well-established:''' Single gem, no external dependencies (uses Rails cache for storage), maintained by the Rack team, used by tens of thousands of production Rails apps.
* '''Configuration in code:''' Rules live in <code>config/initializers/rack_attack.rb</code> and are version-controlled alongside the rest of the auth configuration, rather than living in a gateway or load balancer config.

The tradeoff is that rate limiting at the application layer is best-effort — a sufficiently distributed attack can still overwhelm the app. For production deployment, a gateway-level rate limit (e.g. nginx, Cloudflare) should be added in front of <code>rack-attack</code> as defense in depth. <code>rack-attack</code> is documented as the application-layer baseline, not the only line of defense.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests (74 total) ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing
* .authorization_uri_for! Raises a uniqueness error when two rows have the same state

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false
* #verified_email_from_code! Raises InvalidToken when the token's nonce doesn't match (tampered/replayed token)

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

'''Rate limiting (Rack::Attack)'''
* <code>POST /auth/client-select</code>: 5 requests from one IP all succeed (within limit)
* <code>POST /auth/client-select</code>: 6th request from same IP gets 429 with "Rate limit exceeded"
* <code>POST /auth/client-select</code>: throttled response includes a Retry-After header
* <code>POST /auth/client-select</code>: hitting the limit on one IP does not affect a different IP
* <code>POST /auth/callback</code>: 10 requests from one IP all succeed (within limit)
* <code>POST /auth/callback</code>: 11th request from same IP gets 429 with "Rate limit exceeded"
* <code>POST /auth/callback</code>: throttled response includes a Retry-After header

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

=== Story 15: Backend — Rate Limiting on OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints rate-limited at the application layer, '''so that''' abusive clients cannot fill the <code>oidc_requests</code> table, hammer the IdP discovery endpoint, or brute-force callback state values.

'''Acceptance Criteria:'''
* Add the <code>rack-attack</code> gem to the Gemfile.
* Configure throttles in <code>config/initializers/rack_attack.rb</code>:
** <code>POST /auth/client-select</code>: throttled per IP (e.g. 10 requests per minute) to prevent table-fill and discovery-spam attacks.
** <code>POST /auth/callback</code>: throttled per IP (e.g. 20 requests per minute) to slow brute-force state guessing.
* Throttled requests return HTTP 429 with a JSON body matching the existing error response shape (<code>{ error: "Too many requests" }</code>).
* Use the Rails cache (<code>Rails.cache</code>) as the backing store so no additional infrastructure is required.
* Document the rationale in the initializer with a brief comment, including the note that gateway-level rate limiting (nginx, Cloudflare) should be added in front for defense in depth in production.
* Add request specs verifying:
** A burst of requests above the threshold returns 429.
** Requests under the threshold succeed normally.
** Different IPs are throttled independently.
* Verify existing endpoints (login, etc.) are not affected by the new rules.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://youtu.be/ES6VWZxkj_w| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-26T17:09:34Z

Jweisz: /* Design Patterns */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Provider configuration is validated at boot via config/initializers/oidc.rb. In production, a provider with any missing required key raises OidcConfig::InvalidConfiguration, which prevents the application from starting with a misconfigured OIDC provider. In all other environments (development, test), the invalid provider is skipped with a warning logged so that local development and CI are not blocked when OIDC credentials are not configured.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Login ===
At one point it was suggested that OIDC completely replace password login if configured. We considered this idea, however, given this feature must support multiple institutions, some of which may want OIDC and others which may not and there is no institution context pre-login at this time, we felt that probably falls under account management and is beyond the scope of this assignment.

=== Logout ===
Logout will not be impacted. The OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is required and must be true.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each identity provider is defined as a YAML configuration block with its own credentials, issuer, and scopes. <code>OidcRequest.authorization_uri_for!</code> and <code>OidcLoginController#callback</code> operate on whatever provider key is passed in, with no <code>if provider == "google"</code> branching. Adding a new institution's SSO requires only a new YAML entry and environment variables — no code changes anywhere.

* '''Singleton''' — <code>OidcConfig</code> is effectively a singleton: provider configuration is memoized as class-level state and cleared via <code>reload!</code>, ensuring YAML is parsed once per process. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing additional safety.

* '''Probabilistic Garbage Collection''' — Stale <code>oidc_requests</code> rows are cleaned up on a small percentage (10%) of new request creations rather than scheduled. This amortizes cleanup cost across normal usage and avoids adding a scheduler dependency to the application.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== New Dependencies ==

=== openid_connect ===

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>oidc_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

=== rack-attack ===

The <code>rack-attack</code> gem ([https://github.com/rack/rack-attack github.com/rack/rack-attack]) was added to provide rate limiting on the OIDC endpoints. Without it, an attacker could spam <code>POST /auth/client-select</code> to fill the <code>oidc_requests</code> table or repeatedly probe <code>POST /auth/callback</code> to attempt token guessing.

* '''Throttle abuse before it reaches the application:''' Rack-level middleware rejects abusive clients before any controller code runs, protecting both the database and the IdP discovery endpoints from being hammered.
* '''Per-IP throttling on OIDC endpoints:''' <code>POST /auth/client-select</code> is rate-limited to prevent table-fill attacks and discovery spam (each request creates a row and triggers an IdP discovery call). <code>POST /auth/callback</code> is rate-limited to slow brute-force state guessing — even though the state values have 256 bits of entropy and won't realistically be guessed, throttling prevents wasted work and log noise.
* '''Lightweight and well-established:''' Single gem, no external dependencies (uses Rails cache for storage), maintained by the Rack team, used by tens of thousands of production Rails apps.
* '''Configuration in code:''' Rules live in <code>config/initializers/rack_attack.rb</code> and are version-controlled alongside the rest of the auth configuration, rather than living in a gateway or load balancer config.

The tradeoff is that rate limiting at the application layer is best-effort — a sufficiently distributed attack can still overwhelm the app. For production deployment, a gateway-level rate limit (e.g. nginx, Cloudflare) should be added in front of <code>rack-attack</code> as defense in depth. <code>rack-attack</code> is documented as the application-layer baseline, not the only line of defense.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests (74 total) ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing
* .authorization_uri_for! Raises a uniqueness error when two rows have the same state

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false
* #verified_email_from_code! Raises InvalidToken when the token's nonce doesn't match (tampered/replayed token)

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

'''Rate limiting (Rack::Attack)'''
* <code>POST /auth/client-select</code>: 5 requests from one IP all succeed (within limit)
* <code>POST /auth/client-select</code>: 6th request from same IP gets 429 with "Rate limit exceeded"
* <code>POST /auth/client-select</code>: throttled response includes a Retry-After header
* <code>POST /auth/client-select</code>: hitting the limit on one IP does not affect a different IP
* <code>POST /auth/callback</code>: 10 requests from one IP all succeed (within limit)
* <code>POST /auth/callback</code>: 11th request from same IP gets 429 with "Rate limit exceeded"
* <code>POST /auth/callback</code>: throttled response includes a Retry-After header

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

=== Story 15: Backend — Rate Limiting on OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints rate-limited at the application layer, '''so that''' abusive clients cannot fill the <code>oidc_requests</code> table, hammer the IdP discovery endpoint, or brute-force callback state values.

'''Acceptance Criteria:'''
* Add the <code>rack-attack</code> gem to the Gemfile.
* Configure throttles in <code>config/initializers/rack_attack.rb</code>:
** <code>POST /auth/client-select</code>: throttled per IP (e.g. 10 requests per minute) to prevent table-fill and discovery-spam attacks.
** <code>POST /auth/callback</code>: throttled per IP (e.g. 20 requests per minute) to slow brute-force state guessing.
* Throttled requests return HTTP 429 with a JSON body matching the existing error response shape (<code>{ error: "Too many requests" }</code>).
* Use the Rails cache (<code>Rails.cache</code>) as the backing store so no additional infrastructure is required.
* Document the rationale in the initializer with a brief comment, including the note that gateway-level rate limiting (nginx, Cloudflare) should be added in front for defense in depth in production.
* Add request specs verifying:
** A burst of requests above the threshold returns 429.
** Requests under the threshold succeed normally.
** Different IPs are throttled independently.
* Verify existing endpoints (login, etc.) are not affected by the new rules.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://youtu.be/ES6VWZxkj_w| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-26T17:06:29Z

Jweisz: /* Design Patterns */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Provider configuration is validated at boot via config/initializers/oidc.rb. In production, a provider with any missing required key raises OidcConfig::InvalidConfiguration, which prevents the application from starting with a misconfigured OIDC provider. In all other environments (development, test), the invalid provider is skipped with a warning logged so that local development and CI are not blocked when OIDC credentials are not configured.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Login ===
At one point it was suggested that OIDC completely replace password login if configured. We considered this idea, however, given this feature must support multiple institutions, some of which may want OIDC and others which may not and there is no institution context pre-login at this time, we felt that probably falls under account management and is beyond the scope of this assignment.

=== Logout ===
Logout will not be impacted. The OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is required and must be true.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each identity provider is defined as a YAML configuration block with its own credentials, issuer, and scopes. <code>OidcRequest.authorization_uri_for!</code> and <code>OidcLoginController#callback</code> operate on whatever provider key is passed in, with no <code>if provider == "google"</code> branching. Adding a new institution's SSO requires only a new YAML entry and environment variables — no code changes anywhere.

* '''Command''' — CleanupStaleOidcRequestsJob: The work of deleting stale <code>oidc_requests</code> rows is encapsulated as a background job that can be enqueued, retried, or deferred by Active Job. The job itself is a single line (<code>OidcRequest.delete_stale</code>). This separates the decision of when to clean up (probabilistic, at row creation time) from the act of cleaning up (the job), and means cleanup can be safely moved to a scheduler later with no logic changes.

* Provider configuration is memoized as class-level state in <code>OidcConfig</code> and cleared via <code>reload!</code>, ensuring YAML is parsed once per process.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== New Dependencies ==

=== openid_connect ===

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>oidc_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

=== rack-attack ===

The <code>rack-attack</code> gem ([https://github.com/rack/rack-attack github.com/rack/rack-attack]) was added to provide rate limiting on the OIDC endpoints. Without it, an attacker could spam <code>POST /auth/client-select</code> to fill the <code>oidc_requests</code> table or repeatedly probe <code>POST /auth/callback</code> to attempt token guessing.

* '''Throttle abuse before it reaches the application:''' Rack-level middleware rejects abusive clients before any controller code runs, protecting both the database and the IdP discovery endpoints from being hammered.
* '''Per-IP throttling on OIDC endpoints:''' <code>POST /auth/client-select</code> is rate-limited to prevent table-fill attacks and discovery spam (each request creates a row and triggers an IdP discovery call). <code>POST /auth/callback</code> is rate-limited to slow brute-force state guessing — even though the state values have 256 bits of entropy and won't realistically be guessed, throttling prevents wasted work and log noise.
* '''Lightweight and well-established:''' Single gem, no external dependencies (uses Rails cache for storage), maintained by the Rack team, used by tens of thousands of production Rails apps.
* '''Configuration in code:''' Rules live in <code>config/initializers/rack_attack.rb</code> and are version-controlled alongside the rest of the auth configuration, rather than living in a gateway or load balancer config.

The tradeoff is that rate limiting at the application layer is best-effort — a sufficiently distributed attack can still overwhelm the app. For production deployment, a gateway-level rate limit (e.g. nginx, Cloudflare) should be added in front of <code>rack-attack</code> as defense in depth. <code>rack-attack</code> is documented as the application-layer baseline, not the only line of defense.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests (74 total) ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing
* .authorization_uri_for! Raises a uniqueness error when two rows have the same state

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false
* #verified_email_from_code! Raises InvalidToken when the token's nonce doesn't match (tampered/replayed token)

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

'''Rate limiting (Rack::Attack)'''
* <code>POST /auth/client-select</code>: 5 requests from one IP all succeed (within limit)
* <code>POST /auth/client-select</code>: 6th request from same IP gets 429 with "Rate limit exceeded"
* <code>POST /auth/client-select</code>: throttled response includes a Retry-After header
* <code>POST /auth/client-select</code>: hitting the limit on one IP does not affect a different IP
* <code>POST /auth/callback</code>: 10 requests from one IP all succeed (within limit)
* <code>POST /auth/callback</code>: 11th request from same IP gets 429 with "Rate limit exceeded"
* <code>POST /auth/callback</code>: throttled response includes a Retry-After header

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

=== Story 15: Backend — Rate Limiting on OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints rate-limited at the application layer, '''so that''' abusive clients cannot fill the <code>oidc_requests</code> table, hammer the IdP discovery endpoint, or brute-force callback state values.

'''Acceptance Criteria:'''
* Add the <code>rack-attack</code> gem to the Gemfile.
* Configure throttles in <code>config/initializers/rack_attack.rb</code>:
** <code>POST /auth/client-select</code>: throttled per IP (e.g. 10 requests per minute) to prevent table-fill and discovery-spam attacks.
** <code>POST /auth/callback</code>: throttled per IP (e.g. 20 requests per minute) to slow brute-force state guessing.
* Throttled requests return HTTP 429 with a JSON body matching the existing error response shape (<code>{ error: "Too many requests" }</code>).
* Use the Rails cache (<code>Rails.cache</code>) as the backing store so no additional infrastructure is required.
* Document the rationale in the initializer with a brief comment, including the note that gateway-level rate limiting (nginx, Cloudflare) should be added in front for defense in depth in production.
* Add request specs verifying:
** A burst of requests above the threshold returns 429.
** Requests under the threshold succeed normally.
** Different IPs are throttled independently.
* Verify existing endpoints (login, etc.) are not affected by the new rules.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://youtu.be/ES6VWZxkj_w| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-26T13:34:37Z

Jweisz: /* Demo Video */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Provider configuration is validated at boot via config/initializers/oidc.rb. In production, a provider with any missing required key raises OidcConfig::InvalidConfiguration, which prevents the application from starting with a misconfigured OIDC provider. In all other environments (development, test), the invalid provider is skipped with a warning logged so that local development and CI are not blocked when OIDC credentials are not configured.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Login ===
At one point it was suggested that OIDC completely replace password login if configured. We considered this idea, however, given this feature must support multiple institutions, some of which may want OIDC and others which may not and there is no institution context pre-login at this time, we felt that probably falls under account management and is beyond the scope of this assignment.

=== Logout ===
Logout will not be impacted. The OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is required and must be true.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each identity provider is defined as a YAML configuration block with its own credentials, issuer, and scopes. <code>OidcRequest.authorization_uri_for!</code> and <code>OidcLoginController#callback</code> operate on whatever provider key is passed in, with no <code>if provider == "google"</code> branching. Adding a new institution's SSO requires only a new YAML entry and environment variables — no code changes anywhere.

* '''Facade''' — OidcLoginController: The controller exposes three simple, clean endpoints (providers, client_select, callback) while hiding the underlying complexity: YAML parsing, PKCE generation, database row management, provider discovery, token exchange, JWKS verification, and user matching all happen inside <code>OidcConfig</code> and <code>OidcRequest</code>.

* '''Chain of Responsibility''' — callback error handling: The callback action processes a sequence of steps -> consume state, exchange code, verify token, match user. Each can fail in a different way.

* '''Command''' — CleanupStaleOidcRequestsJob: The work of deleting stale <code>oidc_requests</code> rows is encapsulated as a background job that can be enqueued, retried, or deferred by Active Job. The job itself is a single line (<code>OidcRequest.delete_stale</code>). This separates the decision of when to clean up (probabilistic, at row creation time) from the act of cleaning up (the job), and means cleanup can be safely moved to a scheduler later with no logic changes.

* '''Null Object (graceful degradation)''' — OidcModal: When <code>GET /auth/providers</code> fails or returns an empty list, <code>OidcModal</code> renders nothing at all. The login page behaves exactly as if OIDC were never configured, and the standard username/password form is completely unaffected. This is cleaner than showing a loading spinner or error state, because from the user's perspective there is simply no SSO option instead of a broken one.

* Provider configuration is memoized as class-level state in <code>OidcConfig</code> and cleared via <code>reload!</code>, ensuring YAML is parsed once per process.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== New Dependencies ==

=== openid_connect ===

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>oidc_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

=== rack-attack ===

The <code>rack-attack</code> gem ([https://github.com/rack/rack-attack github.com/rack/rack-attack]) was added to provide rate limiting on the OIDC endpoints. Without it, an attacker could spam <code>POST /auth/client-select</code> to fill the <code>oidc_requests</code> table or repeatedly probe <code>POST /auth/callback</code> to attempt token guessing.

* '''Throttle abuse before it reaches the application:''' Rack-level middleware rejects abusive clients before any controller code runs, protecting both the database and the IdP discovery endpoints from being hammered.
* '''Per-IP throttling on OIDC endpoints:''' <code>POST /auth/client-select</code> is rate-limited to prevent table-fill attacks and discovery spam (each request creates a row and triggers an IdP discovery call). <code>POST /auth/callback</code> is rate-limited to slow brute-force state guessing — even though the state values have 256 bits of entropy and won't realistically be guessed, throttling prevents wasted work and log noise.
* '''Lightweight and well-established:''' Single gem, no external dependencies (uses Rails cache for storage), maintained by the Rack team, used by tens of thousands of production Rails apps.
* '''Configuration in code:''' Rules live in <code>config/initializers/rack_attack.rb</code> and are version-controlled alongside the rest of the auth configuration, rather than living in a gateway or load balancer config.

The tradeoff is that rate limiting at the application layer is best-effort — a sufficiently distributed attack can still overwhelm the app. For production deployment, a gateway-level rate limit (e.g. nginx, Cloudflare) should be added in front of <code>rack-attack</code> as defense in depth. <code>rack-attack</code> is documented as the application-layer baseline, not the only line of defense.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests (74 total) ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing
* .authorization_uri_for! Raises a uniqueness error when two rows have the same state

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false
* #verified_email_from_code! Raises InvalidToken when the token's nonce doesn't match (tampered/replayed token)

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

'''Rate limiting (Rack::Attack)'''
* <code>POST /auth/client-select</code>: 5 requests from one IP all succeed (within limit)
* <code>POST /auth/client-select</code>: 6th request from same IP gets 429 with "Rate limit exceeded"
* <code>POST /auth/client-select</code>: throttled response includes a Retry-After header
* <code>POST /auth/client-select</code>: hitting the limit on one IP does not affect a different IP
* <code>POST /auth/callback</code>: 10 requests from one IP all succeed (within limit)
* <code>POST /auth/callback</code>: 11th request from same IP gets 429 with "Rate limit exceeded"
* <code>POST /auth/callback</code>: throttled response includes a Retry-After header

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

=== Story 15: Backend — Rate Limiting on OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints rate-limited at the application layer, '''so that''' abusive clients cannot fill the <code>oidc_requests</code> table, hammer the IdP discovery endpoint, or brute-force callback state values.

'''Acceptance Criteria:'''
* Add the <code>rack-attack</code> gem to the Gemfile.
* Configure throttles in <code>config/initializers/rack_attack.rb</code>:
** <code>POST /auth/client-select</code>: throttled per IP (e.g. 10 requests per minute) to prevent table-fill and discovery-spam attacks.
** <code>POST /auth/callback</code>: throttled per IP (e.g. 20 requests per minute) to slow brute-force state guessing.
* Throttled requests return HTTP 429 with a JSON body matching the existing error response shape (<code>{ error: "Too many requests" }</code>).
* Use the Rails cache (<code>Rails.cache</code>) as the backing store so no additional infrastructure is required.
* Document the rationale in the initializer with a brief comment, including the note that gateway-level rate limiting (nginx, Cloudflare) should be added in front for defense in depth in production.
* Add request specs verifying:
** A burst of requests above the threshold returns 429.
** Requests under the threshold succeed normally.
** Different IPs are throttled independently.
* Verify existing endpoints (login, etc.) are not affected by the new rules.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://youtu.be/ES6VWZxkj_w| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-25T21:12:00Z

Jweisz: /* Login */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Login ===
At one point it was suggested that OIDC completely replace password login if configured. We considered this idea, however, given this feature must support multiple institutions, some of which may want OIDC and others which may not and there is no institution context pre-login at this time, we felt that probably falls under account management and is beyond the scope of this assignment.

=== Logout ===
Logout will not be impacted. The OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is required and must be true.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

* '''Singleton pattern''' — <code>OidcConfig</code> is effectively a singleton: all methods are class-level, provider configuration is memoized in a class-level variable, and <code>reload!</code> resets that state. This ensures a single source of truth for provider configuration and avoids repeated YAML parsing per request. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing any additional safety — the class-level approach achieves the same guarantees with cleaner call syntax.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== New Dependencies ==

=== openid_connect ===

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>oidc_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

=== rack-attack ===

The <code>rack-attack</code> gem ([https://github.com/rack/rack-attack github.com/rack/rack-attack]) was added to provide rate limiting on the OIDC endpoints. Without it, an attacker could spam <code>POST /auth/client-select</code> to fill the <code>oidc_requests</code> table or repeatedly probe <code>POST /auth/callback</code> to attempt token guessing.

* '''Throttle abuse before it reaches the application:''' Rack-level middleware rejects abusive clients before any controller code runs, protecting both the database and the IdP discovery endpoints from being hammered.
* '''Per-IP throttling on OIDC endpoints:''' <code>POST /auth/client-select</code> is rate-limited to prevent table-fill attacks and discovery spam (each request creates a row and triggers an IdP discovery call). <code>POST /auth/callback</code> is rate-limited to slow brute-force state guessing — even though the state values have 256 bits of entropy and won't realistically be guessed, throttling prevents wasted work and log noise.
* '''Lightweight and well-established:''' Single gem, no external dependencies (uses Rails cache for storage), maintained by the Rack team, used by tens of thousands of production Rails apps.
* '''Configuration in code:''' Rules live in <code>config/initializers/rack_attack.rb</code> and are version-controlled alongside the rest of the auth configuration, rather than living in a gateway or load balancer config.

The tradeoff is that rate limiting at the application layer is best-effort — a sufficiently distributed attack can still overwhelm the app. For production deployment, a gateway-level rate limit (e.g. nginx, Cloudflare) should be added in front of <code>rack-attack</code> as defense in depth. <code>rack-attack</code> is documented as the application-layer baseline, not the only line of defense.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

=== Story 15: Backend — Rate Limiting on OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints rate-limited at the application layer, '''so that''' abusive clients cannot fill the <code>oidc_requests</code> table, hammer the IdP discovery endpoint, or brute-force callback state values.

'''Acceptance Criteria:'''
* Add the <code>rack-attack</code> gem to the Gemfile.
* Configure throttles in <code>config/initializers/rack_attack.rb</code>:
** <code>POST /auth/client-select</code>: throttled per IP (e.g. 10 requests per minute) to prevent table-fill and discovery-spam attacks.
** <code>POST /auth/callback</code>: throttled per IP (e.g. 20 requests per minute) to slow brute-force state guessing.
* Throttled requests return HTTP 429 with a JSON body matching the existing error response shape (<code>{ error: "Too many requests" }</code>).
* Use the Rails cache (<code>Rails.cache</code>) as the backing store so no additional infrastructure is required.
* Document the rationale in the initializer with a brief comment, including the note that gateway-level rate limiting (nginx, Cloudflare) should be added in front for defense in depth in production.
* Add request specs verifying:
** A burst of requests above the threshold returns 429.
** Requests under the threshold succeed normally.
** Different IPs are throttled independently.
* Verify existing endpoints (login, etc.) are not affected by the new rules.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-25T21:10:56Z

Jweisz: /* Login */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Login ===
At one point it was suggested that OIDC completely replace password login if configured. We considered this idea, however, given this feature must support multiple institution, some of which may want OIDC and others which may not, we felt that probably falls under account management and is beyond the scope of this assignment.

=== Logout ===
Logout will not be impacted. The OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is required and must be true.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

* '''Singleton pattern''' — <code>OidcConfig</code> is effectively a singleton: all methods are class-level, provider configuration is memoized in a class-level variable, and <code>reload!</code> resets that state. This ensures a single source of truth for provider configuration and avoids repeated YAML parsing per request. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing any additional safety — the class-level approach achieves the same guarantees with cleaner call syntax.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== New Dependencies ==

=== openid_connect ===

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>oidc_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

=== rack-attack ===

The <code>rack-attack</code> gem ([https://github.com/rack/rack-attack github.com/rack/rack-attack]) was added to provide rate limiting on the OIDC endpoints. Without it, an attacker could spam <code>POST /auth/client-select</code> to fill the <code>oidc_requests</code> table or repeatedly probe <code>POST /auth/callback</code> to attempt token guessing.

* '''Throttle abuse before it reaches the application:''' Rack-level middleware rejects abusive clients before any controller code runs, protecting both the database and the IdP discovery endpoints from being hammered.
* '''Per-IP throttling on OIDC endpoints:''' <code>POST /auth/client-select</code> is rate-limited to prevent table-fill attacks and discovery spam (each request creates a row and triggers an IdP discovery call). <code>POST /auth/callback</code> is rate-limited to slow brute-force state guessing — even though the state values have 256 bits of entropy and won't realistically be guessed, throttling prevents wasted work and log noise.
* '''Lightweight and well-established:''' Single gem, no external dependencies (uses Rails cache for storage), maintained by the Rack team, used by tens of thousands of production Rails apps.
* '''Configuration in code:''' Rules live in <code>config/initializers/rack_attack.rb</code> and are version-controlled alongside the rest of the auth configuration, rather than living in a gateway or load balancer config.

The tradeoff is that rate limiting at the application layer is best-effort — a sufficiently distributed attack can still overwhelm the app. For production deployment, a gateway-level rate limit (e.g. nginx, Cloudflare) should be added in front of <code>rack-attack</code> as defense in depth. <code>rack-attack</code> is documented as the application-layer baseline, not the only line of defense.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

=== Story 15: Backend — Rate Limiting on OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints rate-limited at the application layer, '''so that''' abusive clients cannot fill the <code>oidc_requests</code> table, hammer the IdP discovery endpoint, or brute-force callback state values.

'''Acceptance Criteria:'''
* Add the <code>rack-attack</code> gem to the Gemfile.
* Configure throttles in <code>config/initializers/rack_attack.rb</code>:
** <code>POST /auth/client-select</code>: throttled per IP (e.g. 10 requests per minute) to prevent table-fill and discovery-spam attacks.
** <code>POST /auth/callback</code>: throttled per IP (e.g. 20 requests per minute) to slow brute-force state guessing.
* Throttled requests return HTTP 429 with a JSON body matching the existing error response shape (<code>{ error: "Too many requests" }</code>).
* Use the Rails cache (<code>Rails.cache</code>) as the backing store so no additional infrastructure is required.
* Document the rationale in the initializer with a brief comment, including the note that gateway-level rate limiting (nginx, Cloudflare) should be added in front for defense in depth in production.
* Add request specs verifying:
** A burst of requests above the threshold returns 429.
** Requests under the threshold succeed normally.
** Different IPs are throttled independently.
* Verify existing endpoints (login, etc.) are not affected by the new rules.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-25T21:09:42Z

Jweisz: /* Design Requirements */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Login ===
At one point it was suggested that OIDC completely replace password login if configured. We considered this idea, however, given this feature must support multiple institutions and that decision is generally made at the user level either via a nullable password or an oidc flag, we felt that falls under account management and is beyond the scope of this assignment.

=== Logout ===
Logout will not be impacted. The OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is required and must be true.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

* '''Singleton pattern''' — <code>OidcConfig</code> is effectively a singleton: all methods are class-level, provider configuration is memoized in a class-level variable, and <code>reload!</code> resets that state. This ensures a single source of truth for provider configuration and avoids repeated YAML parsing per request. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing any additional safety — the class-level approach achieves the same guarantees with cleaner call syntax.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== New Dependencies ==

=== openid_connect ===

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>oidc_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

=== rack-attack ===

The <code>rack-attack</code> gem ([https://github.com/rack/rack-attack github.com/rack/rack-attack]) was added to provide rate limiting on the OIDC endpoints. Without it, an attacker could spam <code>POST /auth/client-select</code> to fill the <code>oidc_requests</code> table or repeatedly probe <code>POST /auth/callback</code> to attempt token guessing.

* '''Throttle abuse before it reaches the application:''' Rack-level middleware rejects abusive clients before any controller code runs, protecting both the database and the IdP discovery endpoints from being hammered.
* '''Per-IP throttling on OIDC endpoints:''' <code>POST /auth/client-select</code> is rate-limited to prevent table-fill attacks and discovery spam (each request creates a row and triggers an IdP discovery call). <code>POST /auth/callback</code> is rate-limited to slow brute-force state guessing — even though the state values have 256 bits of entropy and won't realistically be guessed, throttling prevents wasted work and log noise.
* '''Lightweight and well-established:''' Single gem, no external dependencies (uses Rails cache for storage), maintained by the Rack team, used by tens of thousands of production Rails apps.
* '''Configuration in code:''' Rules live in <code>config/initializers/rack_attack.rb</code> and are version-controlled alongside the rest of the auth configuration, rather than living in a gateway or load balancer config.

The tradeoff is that rate limiting at the application layer is best-effort — a sufficiently distributed attack can still overwhelm the app. For production deployment, a gateway-level rate limit (e.g. nginx, Cloudflare) should be added in front of <code>rack-attack</code> as defense in depth. <code>rack-attack</code> is documented as the application-layer baseline, not the only line of defense.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

=== Story 15: Backend — Rate Limiting on OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints rate-limited at the application layer, '''so that''' abusive clients cannot fill the <code>oidc_requests</code> table, hammer the IdP discovery endpoint, or brute-force callback state values.

'''Acceptance Criteria:'''
* Add the <code>rack-attack</code> gem to the Gemfile.
* Configure throttles in <code>config/initializers/rack_attack.rb</code>:
** <code>POST /auth/client-select</code>: throttled per IP (e.g. 10 requests per minute) to prevent table-fill and discovery-spam attacks.
** <code>POST /auth/callback</code>: throttled per IP (e.g. 20 requests per minute) to slow brute-force state guessing.
* Throttled requests return HTTP 429 with a JSON body matching the existing error response shape (<code>{ error: "Too many requests" }</code>).
* Use the Rails cache (<code>Rails.cache</code>) as the backing store so no additional infrastructure is required.
* Document the rationale in the initializer with a brief comment, including the note that gateway-level rate limiting (nginx, Cloudflare) should be added in front for defense in depth in production.
* Add request specs verifying:
** A burst of requests above the threshold returns 429.
** Requests under the threshold succeed normally.
** Different IPs are throttled independently.
* Verify existing endpoints (login, etc.) are not affected by the new rules.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-25T21:04:12Z

Jweisz: /* Logout */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. The OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is required and must be true.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

* '''Singleton pattern''' — <code>OidcConfig</code> is effectively a singleton: all methods are class-level, provider configuration is memoized in a class-level variable, and <code>reload!</code> resets that state. This ensures a single source of truth for provider configuration and avoids repeated YAML parsing per request. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing any additional safety — the class-level approach achieves the same guarantees with cleaner call syntax.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== New Dependencies ==

=== openid_connect ===

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>oidc_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

=== rack-attack ===

The <code>rack-attack</code> gem ([https://github.com/rack/rack-attack github.com/rack/rack-attack]) was added to provide rate limiting on the OIDC endpoints. Without it, an attacker could spam <code>POST /auth/client-select</code> to fill the <code>oidc_requests</code> table or repeatedly probe <code>POST /auth/callback</code> to attempt token guessing.

* '''Throttle abuse before it reaches the application:''' Rack-level middleware rejects abusive clients before any controller code runs, protecting both the database and the IdP discovery endpoints from being hammered.
* '''Per-IP throttling on OIDC endpoints:''' <code>POST /auth/client-select</code> is rate-limited to prevent table-fill attacks and discovery spam (each request creates a row and triggers an IdP discovery call). <code>POST /auth/callback</code> is rate-limited to slow brute-force state guessing — even though the state values have 256 bits of entropy and won't realistically be guessed, throttling prevents wasted work and log noise.
* '''Lightweight and well-established:''' Single gem, no external dependencies (uses Rails cache for storage), maintained by the Rack team, used by tens of thousands of production Rails apps.
* '''Configuration in code:''' Rules live in <code>config/initializers/rack_attack.rb</code> and are version-controlled alongside the rest of the auth configuration, rather than living in a gateway or load balancer config.

The tradeoff is that rate limiting at the application layer is best-effort — a sufficiently distributed attack can still overwhelm the app. For production deployment, a gateway-level rate limit (e.g. nginx, Cloudflare) should be added in front of <code>rack-attack</code> as defense in depth. <code>rack-attack</code> is documented as the application-layer baseline, not the only line of defense.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

=== Story 15: Backend — Rate Limiting on OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints rate-limited at the application layer, '''so that''' abusive clients cannot fill the <code>oidc_requests</code> table, hammer the IdP discovery endpoint, or brute-force callback state values.

'''Acceptance Criteria:'''
* Add the <code>rack-attack</code> gem to the Gemfile.
* Configure throttles in <code>config/initializers/rack_attack.rb</code>:
** <code>POST /auth/client-select</code>: throttled per IP (e.g. 10 requests per minute) to prevent table-fill and discovery-spam attacks.
** <code>POST /auth/callback</code>: throttled per IP (e.g. 20 requests per minute) to slow brute-force state guessing.
* Throttled requests return HTTP 429 with a JSON body matching the existing error response shape (<code>{ error: "Too many requests" }</code>).
* Use the Rails cache (<code>Rails.cache</code>) as the backing store so no additional infrastructure is required.
* Document the rationale in the initializer with a brief comment, including the note that gateway-level rate limiting (nginx, Cloudflare) should be added in front for defense in depth in production.
* Add request specs verifying:
** A burst of requests above the threshold returns 429.
** Requests under the threshold succeed normally.
** Different IPs are throttled independently.
* Verify existing endpoints (login, etc.) are not affected by the new rules.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-25T21:01:49Z

Jweisz: /* Security */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is required and must be true.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

* '''Singleton pattern''' — <code>OidcConfig</code> is effectively a singleton: all methods are class-level, provider configuration is memoized in a class-level variable, and <code>reload!</code> resets that state. This ensures a single source of truth for provider configuration and avoids repeated YAML parsing per request. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing any additional safety — the class-level approach achieves the same guarantees with cleaner call syntax.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== New Dependencies ==

=== openid_connect ===

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>oidc_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

=== rack-attack ===

The <code>rack-attack</code> gem ([https://github.com/rack/rack-attack github.com/rack/rack-attack]) was added to provide rate limiting on the OIDC endpoints. Without it, an attacker could spam <code>POST /auth/client-select</code> to fill the <code>oidc_requests</code> table or repeatedly probe <code>POST /auth/callback</code> to attempt token guessing.

* '''Throttle abuse before it reaches the application:''' Rack-level middleware rejects abusive clients before any controller code runs, protecting both the database and the IdP discovery endpoints from being hammered.
* '''Per-IP throttling on OIDC endpoints:''' <code>POST /auth/client-select</code> is rate-limited to prevent table-fill attacks and discovery spam (each request creates a row and triggers an IdP discovery call). <code>POST /auth/callback</code> is rate-limited to slow brute-force state guessing — even though the state values have 256 bits of entropy and won't realistically be guessed, throttling prevents wasted work and log noise.
* '''Lightweight and well-established:''' Single gem, no external dependencies (uses Rails cache for storage), maintained by the Rack team, used by tens of thousands of production Rails apps.
* '''Configuration in code:''' Rules live in <code>config/initializers/rack_attack.rb</code> and are version-controlled alongside the rest of the auth configuration, rather than living in a gateway or load balancer config.

The tradeoff is that rate limiting at the application layer is best-effort — a sufficiently distributed attack can still overwhelm the app. For production deployment, a gateway-level rate limit (e.g. nginx, Cloudflare) should be added in front of <code>rack-attack</code> as defense in depth. <code>rack-attack</code> is documented as the application-layer baseline, not the only line of defense.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

=== Story 15: Backend — Rate Limiting on OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints rate-limited at the application layer, '''so that''' abusive clients cannot fill the <code>oidc_requests</code> table, hammer the IdP discovery endpoint, or brute-force callback state values.

'''Acceptance Criteria:'''
* Add the <code>rack-attack</code> gem to the Gemfile.
* Configure throttles in <code>config/initializers/rack_attack.rb</code>:
** <code>POST /auth/client-select</code>: throttled per IP (e.g. 10 requests per minute) to prevent table-fill and discovery-spam attacks.
** <code>POST /auth/callback</code>: throttled per IP (e.g. 20 requests per minute) to slow brute-force state guessing.
* Throttled requests return HTTP 429 with a JSON body matching the existing error response shape (<code>{ error: "Too many requests" }</code>).
* Use the Rails cache (<code>Rails.cache</code>) as the backing store so no additional infrastructure is required.
* Document the rationale in the initializer with a brief comment, including the note that gateway-level rate limiting (nginx, Cloudflare) should be added in front for defense in depth in production.
* Add request specs verifying:
** A burst of requests above the threshold returns 429.
** Requests under the threshold succeed normally.
** Different IPs are throttled independently.
* Verify existing endpoints (login, etc.) are not affected by the new rules.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-25T21:00:54Z

Jweisz: /* Design Patterns */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

* '''Singleton pattern''' — <code>OidcConfig</code> is effectively a singleton: all methods are class-level, provider configuration is memoized in a class-level variable, and <code>reload!</code> resets that state. This ensures a single source of truth for provider configuration and avoids repeated YAML parsing per request. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing any additional safety — the class-level approach achieves the same guarantees with cleaner call syntax.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== New Dependencies ==

=== openid_connect ===

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>oidc_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

=== rack-attack ===

The <code>rack-attack</code> gem ([https://github.com/rack/rack-attack github.com/rack/rack-attack]) was added to provide rate limiting on the OIDC endpoints. Without it, an attacker could spam <code>POST /auth/client-select</code> to fill the <code>oidc_requests</code> table or repeatedly probe <code>POST /auth/callback</code> to attempt token guessing.

* '''Throttle abuse before it reaches the application:''' Rack-level middleware rejects abusive clients before any controller code runs, protecting both the database and the IdP discovery endpoints from being hammered.
* '''Per-IP throttling on OIDC endpoints:''' <code>POST /auth/client-select</code> is rate-limited to prevent table-fill attacks and discovery spam (each request creates a row and triggers an IdP discovery call). <code>POST /auth/callback</code> is rate-limited to slow brute-force state guessing — even though the state values have 256 bits of entropy and won't realistically be guessed, throttling prevents wasted work and log noise.
* '''Lightweight and well-established:''' Single gem, no external dependencies (uses Rails cache for storage), maintained by the Rack team, used by tens of thousands of production Rails apps.
* '''Configuration in code:''' Rules live in <code>config/initializers/rack_attack.rb</code> and are version-controlled alongside the rest of the auth configuration, rather than living in a gateway or load balancer config.

The tradeoff is that rate limiting at the application layer is best-effort — a sufficiently distributed attack can still overwhelm the app. For production deployment, a gateway-level rate limit (e.g. nginx, Cloudflare) should be added in front of <code>rack-attack</code> as defense in depth. <code>rack-attack</code> is documented as the application-layer baseline, not the only line of defense.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

=== Story 15: Backend — Rate Limiting on OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints rate-limited at the application layer, '''so that''' abusive clients cannot fill the <code>oidc_requests</code> table, hammer the IdP discovery endpoint, or brute-force callback state values.

'''Acceptance Criteria:'''
* Add the <code>rack-attack</code> gem to the Gemfile.
* Configure throttles in <code>config/initializers/rack_attack.rb</code>:
** <code>POST /auth/client-select</code>: throttled per IP (e.g. 10 requests per minute) to prevent table-fill and discovery-spam attacks.
** <code>POST /auth/callback</code>: throttled per IP (e.g. 20 requests per minute) to slow brute-force state guessing.
* Throttled requests return HTTP 429 with a JSON body matching the existing error response shape (<code>{ error: "Too many requests" }</code>).
* Use the Rails cache (<code>Rails.cache</code>) as the backing store so no additional infrastructure is required.
* Document the rationale in the initializer with a brief comment, including the note that gateway-level rate limiting (nginx, Cloudflare) should be added in front for defense in depth in production.
* Add request specs verifying:
** A burst of requests above the threshold returns 429.
** Requests under the threshold succeed normally.
** Different IPs are throttled independently.
* Verify existing endpoints (login, etc.) are not affected by the new rules.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-25T21:00:37Z

Jweisz: /* Design Patterns */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

* '''Singleton pattern''' — <code>OidcConfig</code> is effectively a singleton: all methods are class-level, provider configuration is memoized in a class-level variable, and <code>reload!</code> resets that state. This ensures a single source of truth for provider configuration and avoids repeated YAML parsing per request. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing any additional safety — the class-level approach achieves the same guarantees with cleaner call syntax.

* '''Probabilistic garbage collection''' — Stale <code>oidc_requests</code> rows are cleaned up on a small percentage of new request creations rather than via a scheduled job. This amortizes cleanup cost across normal usage and avoids adding a scheduler dependency to the application.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== New Dependencies ==

=== openid_connect ===

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>oidc_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

=== rack-attack ===

The <code>rack-attack</code> gem ([https://github.com/rack/rack-attack github.com/rack/rack-attack]) was added to provide rate limiting on the OIDC endpoints. Without it, an attacker could spam <code>POST /auth/client-select</code> to fill the <code>oidc_requests</code> table or repeatedly probe <code>POST /auth/callback</code> to attempt token guessing.

* '''Throttle abuse before it reaches the application:''' Rack-level middleware rejects abusive clients before any controller code runs, protecting both the database and the IdP discovery endpoints from being hammered.
* '''Per-IP throttling on OIDC endpoints:''' <code>POST /auth/client-select</code> is rate-limited to prevent table-fill attacks and discovery spam (each request creates a row and triggers an IdP discovery call). <code>POST /auth/callback</code> is rate-limited to slow brute-force state guessing — even though the state values have 256 bits of entropy and won't realistically be guessed, throttling prevents wasted work and log noise.
* '''Lightweight and well-established:''' Single gem, no external dependencies (uses Rails cache for storage), maintained by the Rack team, used by tens of thousands of production Rails apps.
* '''Configuration in code:''' Rules live in <code>config/initializers/rack_attack.rb</code> and are version-controlled alongside the rest of the auth configuration, rather than living in a gateway or load balancer config.

The tradeoff is that rate limiting at the application layer is best-effort — a sufficiently distributed attack can still overwhelm the app. For production deployment, a gateway-level rate limit (e.g. nginx, Cloudflare) should be added in front of <code>rack-attack</code> as defense in depth. <code>rack-attack</code> is documented as the application-layer baseline, not the only line of defense.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

=== Story 15: Backend — Rate Limiting on OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints rate-limited at the application layer, '''so that''' abusive clients cannot fill the <code>oidc_requests</code> table, hammer the IdP discovery endpoint, or brute-force callback state values.

'''Acceptance Criteria:'''
* Add the <code>rack-attack</code> gem to the Gemfile.
* Configure throttles in <code>config/initializers/rack_attack.rb</code>:
** <code>POST /auth/client-select</code>: throttled per IP (e.g. 10 requests per minute) to prevent table-fill and discovery-spam attacks.
** <code>POST /auth/callback</code>: throttled per IP (e.g. 20 requests per minute) to slow brute-force state guessing.
* Throttled requests return HTTP 429 with a JSON body matching the existing error response shape (<code>{ error: "Too many requests" }</code>).
* Use the Rails cache (<code>Rails.cache</code>) as the backing store so no additional infrastructure is required.
* Document the rationale in the initializer with a brief comment, including the note that gateway-level rate limiting (nginx, Cloudflare) should be added in front for defense in depth in production.
* Add request specs verifying:
** A burst of requests above the threshold returns 429.
** Requests under the threshold succeed normally.
** Different IPs are throttled independently.
* Verify existing endpoints (login, etc.) are not affected by the new rules.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-24T19:08:20Z

Jweisz: /* Backend */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

* '''Singleton pattern''' — <code>OidcConfig</code> is effectively a singleton: all methods are class-level, provider configuration is memoized in a class-level variable, and <code>reload!</code> resets that state. This ensures a single source of truth for provider configuration and avoids repeated YAML parsing per request. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing any additional safety — the class-level approach achieves the same guarantees with cleaner call syntax.

* '''Template Method pattern''' — The OIDC login flow (fetch providers → build authorization URL → exchange code → verify token → match user) follows a fixed sequence of steps that is identical for every provider. Only the per-provider configuration values vary; the orchestrating methods in <code>OidcRequest</code> and <code>OidcLoginController</code> are shared across all providers.

* '''Service Object pattern''' — <code>OidcRequest</code> encapsulates the full OIDC flow (state generation, PKCE construction, token exchange, ID token verification, user matching) as cohesive methods on a single ActiveRecord model rather than spreading logic across the controller. The controller stays thin and delegates all protocol work to the model.

* '''Atomic Consume (compensating database pattern)''' — <code>consume_recent_by_state!</code> finds, locks, and destroys the matching row within a single transaction, preventing replay attacks and race conditions where two concurrent callbacks could both claim the same state.

* '''Probabilistic garbage collection''' — Stale <code>oidc_requests</code> rows are cleaned up on a small percentage of new request creations rather than via a scheduled job. This amortizes cleanup cost across normal usage and avoids adding a scheduler dependency to the application.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== New Dependencies ==

=== openid_connect ===

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>oidc_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

=== rack-attack ===

The <code>rack-attack</code> gem ([https://github.com/rack/rack-attack github.com/rack/rack-attack]) was added to provide rate limiting on the OIDC endpoints. Without it, an attacker could spam <code>POST /auth/client-select</code> to fill the <code>oidc_requests</code> table or repeatedly probe <code>POST /auth/callback</code> to attempt token guessing.

* '''Throttle abuse before it reaches the application:''' Rack-level middleware rejects abusive clients before any controller code runs, protecting both the database and the IdP discovery endpoints from being hammered.
* '''Per-IP throttling on OIDC endpoints:''' <code>POST /auth/client-select</code> is rate-limited to prevent table-fill attacks and discovery spam (each request creates a row and triggers an IdP discovery call). <code>POST /auth/callback</code> is rate-limited to slow brute-force state guessing — even though the state values have 256 bits of entropy and won't realistically be guessed, throttling prevents wasted work and log noise.
* '''Lightweight and well-established:''' Single gem, no external dependencies (uses Rails cache for storage), maintained by the Rack team, used by tens of thousands of production Rails apps.
* '''Configuration in code:''' Rules live in <code>config/initializers/rack_attack.rb</code> and are version-controlled alongside the rest of the auth configuration, rather than living in a gateway or load balancer config.

The tradeoff is that rate limiting at the application layer is best-effort — a sufficiently distributed attack can still overwhelm the app. For production deployment, a gateway-level rate limit (e.g. nginx, Cloudflare) should be added in front of <code>rack-attack</code> as defense in depth. <code>rack-attack</code> is documented as the application-layer baseline, not the only line of defense.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

=== Story 15: Backend — Rate Limiting on OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints rate-limited at the application layer, '''so that''' abusive clients cannot fill the <code>oidc_requests</code> table, hammer the IdP discovery endpoint, or brute-force callback state values.

'''Acceptance Criteria:'''
* Add the <code>rack-attack</code> gem to the Gemfile.
* Configure throttles in <code>config/initializers/rack_attack.rb</code>:
** <code>POST /auth/client-select</code>: throttled per IP (e.g. 10 requests per minute) to prevent table-fill and discovery-spam attacks.
** <code>POST /auth/callback</code>: throttled per IP (e.g. 20 requests per minute) to slow brute-force state guessing.
* Throttled requests return HTTP 429 with a JSON body matching the existing error response shape (<code>{ error: "Too many requests" }</code>).
* Use the Rails cache (<code>Rails.cache</code>) as the backing store so no additional infrastructure is required.
* Document the rationale in the initializer with a brief comment, including the note that gateway-level rate limiting (nginx, Cloudflare) should be added in front for defense in depth in production.
* Add request specs verifying:
** A burst of requests above the threshold returns 429.
** Requests under the threshold succeed normally.
** Different IPs are throttled independently.
* Verify existing endpoints (login, etc.) are not affected by the new rules.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-24T19:05:46Z

Jweisz: /* Planning */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

* '''Singleton pattern''' — <code>OidcConfig</code> is effectively a singleton: all methods are class-level, provider configuration is memoized in a class-level variable, and <code>reload!</code> resets that state. This ensures a single source of truth for provider configuration and avoids repeated YAML parsing per request. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing any additional safety — the class-level approach achieves the same guarantees with cleaner call syntax.

* '''Template Method pattern''' — The OIDC login flow (fetch providers → build authorization URL → exchange code → verify token → match user) follows a fixed sequence of steps that is identical for every provider. Only the per-provider configuration values vary; the orchestrating methods in <code>OidcRequest</code> and <code>OidcLoginController</code> are shared across all providers.

* '''Service Object pattern''' — <code>OidcRequest</code> encapsulates the full OIDC flow (state generation, PKCE construction, token exchange, ID token verification, user matching) as cohesive methods on a single ActiveRecord model rather than spreading logic across the controller. The controller stays thin and delegates all protocol work to the model.

* '''Atomic Consume (compensating database pattern)''' — <code>consume_recent_by_state!</code> finds, locks, and destroys the matching row within a single transaction, preventing replay attacks and race conditions where two concurrent callbacks could both claim the same state.

* '''Probabilistic garbage collection''' — Stale <code>oidc_requests</code> rows are cleaned up on a small percentage of new request creations rather than via a scheduled job. This amortizes cleanup cost across normal usage and avoids adding a scheduler dependency to the application.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== New Dependencies ==

=== openid_connect ===

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>oidc_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

=== rack-attack ===

The <code>rack-attack</code> gem ([https://github.com/rack/rack-attack github.com/rack/rack-attack]) was added to provide rate limiting on the OIDC endpoints. Without it, an attacker could spam <code>POST /auth/client-select</code> to fill the <code>oidc_requests</code> table or repeatedly probe <code>POST /auth/callback</code> to attempt token guessing.

* '''Throttle abuse before it reaches the application:''' Rack-level middleware rejects abusive clients before any controller code runs, protecting both the database and the IdP discovery endpoints from being hammered.
* '''Per-IP throttling on OIDC endpoints:''' <code>POST /auth/client-select</code> is rate-limited to prevent table-fill attacks and discovery spam (each request creates a row and triggers an IdP discovery call). <code>POST /auth/callback</code> is rate-limited to slow brute-force state guessing — even though the state values have 256 bits of entropy and won't realistically be guessed, throttling prevents wasted work and log noise.
* '''Lightweight and well-established:''' Single gem, no external dependencies (uses Rails cache for storage), maintained by the Rack team, used by tens of thousands of production Rails apps.
* '''Configuration in code:''' Rules live in <code>config/initializers/rack_attack.rb</code> and are version-controlled alongside the rest of the auth configuration, rather than living in a gateway or load balancer config.

The tradeoff is that rate limiting at the application layer is best-effort — a sufficiently distributed attack can still overwhelm the app. For production deployment, a gateway-level rate limit (e.g. nginx, Cloudflare) should be added in front of <code>rack-attack</code> as defense in depth. <code>rack-attack</code> is documented as the application-layer baseline, not the only line of defense.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

=== Story 15: Backend — Rate Limiting on OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints rate-limited at the application layer, '''so that''' abusive clients cannot fill the <code>oidc_requests</code> table, hammer the IdP discovery endpoint, or brute-force callback state values.

'''Acceptance Criteria:'''
* Add the <code>rack-attack</code> gem to the Gemfile.
* Configure throttles in <code>config/initializers/rack_attack.rb</code>:
** <code>POST /auth/client-select</code>: throttled per IP (e.g. 10 requests per minute) to prevent table-fill and discovery-spam attacks.
** <code>POST /auth/callback</code>: throttled per IP (e.g. 20 requests per minute) to slow brute-force state guessing.
* Throttled requests return HTTP 429 with a JSON body matching the existing error response shape (<code>{ error: "Too many requests" }</code>).
* Use the Rails cache (<code>Rails.cache</code>) as the backing store so no additional infrastructure is required.
* Document the rationale in the initializer with a brief comment, including the note that gateway-level rate limiting (nginx, Cloudflare) should be added in front for defense in depth in production.
* Add request specs verifying:
** A burst of requests above the threshold returns 429.
** Requests under the threshold succeed normally.
** Different IPs are throttled independently.
* Verify existing endpoints (login, etc.) are not affected by the new rules.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-24T19:02:45Z

Jweisz: /* Library Choice */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

* '''Singleton pattern''' — <code>OidcConfig</code> is effectively a singleton: all methods are class-level, provider configuration is memoized in a class-level variable, and <code>reload!</code> resets that state. This ensures a single source of truth for provider configuration and avoids repeated YAML parsing per request. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing any additional safety — the class-level approach achieves the same guarantees with cleaner call syntax.

* '''Template Method pattern''' — The OIDC login flow (fetch providers → build authorization URL → exchange code → verify token → match user) follows a fixed sequence of steps that is identical for every provider. Only the per-provider configuration values vary; the orchestrating methods in <code>OidcRequest</code> and <code>OidcLoginController</code> are shared across all providers.

* '''Service Object pattern''' — <code>OidcRequest</code> encapsulates the full OIDC flow (state generation, PKCE construction, token exchange, ID token verification, user matching) as cohesive methods on a single ActiveRecord model rather than spreading logic across the controller. The controller stays thin and delegates all protocol work to the model.

* '''Atomic Consume (compensating database pattern)''' — <code>consume_recent_by_state!</code> finds, locks, and destroys the matching row within a single transaction, preventing replay attacks and race conditions where two concurrent callbacks could both claim the same state.

* '''Probabilistic garbage collection''' — Stale <code>oidc_requests</code> rows are cleaned up on a small percentage of new request creations rather than via a scheduled job. This amortizes cleanup cost across normal usage and avoids adding a scheduler dependency to the application.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== New Dependencies ==

=== openid_connect ===

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>oidc_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

=== rack-attack ===

The <code>rack-attack</code> gem ([https://github.com/rack/rack-attack github.com/rack/rack-attack]) was added to provide rate limiting on the OIDC endpoints. Without it, an attacker could spam <code>POST /auth/client-select</code> to fill the <code>oidc_requests</code> table or repeatedly probe <code>POST /auth/callback</code> to attempt token guessing.

* '''Throttle abuse before it reaches the application:''' Rack-level middleware rejects abusive clients before any controller code runs, protecting both the database and the IdP discovery endpoints from being hammered.
* '''Per-IP throttling on OIDC endpoints:''' <code>POST /auth/client-select</code> is rate-limited to prevent table-fill attacks and discovery spam (each request creates a row and triggers an IdP discovery call). <code>POST /auth/callback</code> is rate-limited to slow brute-force state guessing — even though the state values have 256 bits of entropy and won't realistically be guessed, throttling prevents wasted work and log noise.
* '''Lightweight and well-established:''' Single gem, no external dependencies (uses Rails cache for storage), maintained by the Rack team, used by tens of thousands of production Rails apps.
* '''Configuration in code:''' Rules live in <code>config/initializers/rack_attack.rb</code> and are version-controlled alongside the rest of the auth configuration, rather than living in a gateway or load balancer config.

The tradeoff is that rate limiting at the application layer is best-effort — a sufficiently distributed attack can still overwhelm the app. For production deployment, a gateway-level rate limit (e.g. nginx, Cloudflare) should be added in front of <code>rack-attack</code> as defense in depth. <code>rack-attack</code> is documented as the application-layer baseline, not the only line of defense.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-24T19:02:07Z

Jweisz: /* Library Choice */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

* '''Singleton pattern''' — <code>OidcConfig</code> is effectively a singleton: all methods are class-level, provider configuration is memoized in a class-level variable, and <code>reload!</code> resets that state. This ensures a single source of truth for provider configuration and avoids repeated YAML parsing per request. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing any additional safety — the class-level approach achieves the same guarantees with cleaner call syntax.

* '''Template Method pattern''' — The OIDC login flow (fetch providers → build authorization URL → exchange code → verify token → match user) follows a fixed sequence of steps that is identical for every provider. Only the per-provider configuration values vary; the orchestrating methods in <code>OidcRequest</code> and <code>OidcLoginController</code> are shared across all providers.

* '''Service Object pattern''' — <code>OidcRequest</code> encapsulates the full OIDC flow (state generation, PKCE construction, token exchange, ID token verification, user matching) as cohesive methods on a single ActiveRecord model rather than spreading logic across the controller. The controller stays thin and delegates all protocol work to the model.

* '''Atomic Consume (compensating database pattern)''' — <code>consume_recent_by_state!</code> finds, locks, and destroys the matching row within a single transaction, preventing replay attacks and race conditions where two concurrent callbacks could both claim the same state.

* '''Probabilistic garbage collection''' — Stale <code>oidc_requests</code> rows are cleaned up on a small percentage of new request creations rather than via a scheduled job. This amortizes cleanup cost across normal usage and avoids adding a scheduler dependency to the application.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

=== openid_connect ===

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>oidc_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

=== rack-attack ===

The <code>rack-attack</code> gem ([https://github.com/rack/rack-attack github.com/rack/rack-attack]) was added to provide rate limiting on the OIDC endpoints. Without it, an attacker could spam <code>POST /auth/client-select</code> to fill the <code>oidc_requests</code> table or repeatedly probe <code>POST /auth/callback</code> to attempt token guessing.

* '''Throttle abuse before it reaches the application:''' Rack-level middleware rejects abusive clients before any controller code runs, protecting both the database and the IdP discovery endpoints from being hammered.
* '''Per-IP throttling on OIDC endpoints:''' <code>POST /auth/client-select</code> is rate-limited to prevent table-fill attacks and discovery spam (each request creates a row and triggers an IdP discovery call). <code>POST /auth/callback</code> is rate-limited to slow brute-force state guessing — even though the state values have 256 bits of entropy and won't realistically be guessed, throttling prevents wasted work and log noise.
* '''Lightweight and well-established:''' Single gem, no external dependencies (uses Rails cache for storage), maintained by the Rack team, used by tens of thousands of production Rails apps.
* '''Configuration in code:''' Rules live in <code>config/initializers/rack_attack.rb</code> and are version-controlled alongside the rest of the auth configuration, rather than living in a gateway or load balancer config.

The tradeoff is that rate limiting at the application layer is best-effort — a sufficiently distributed attack can still overwhelm the app. For production deployment, a gateway-level rate limit (e.g. nginx, Cloudflare) should be added in front of <code>rack-attack</code> as defense in depth. <code>rack-attack</code> is documented as the application-layer baseline, not the only line of defense.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-24T19:00:14Z

Jweisz:

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

* '''Singleton pattern''' — <code>OidcConfig</code> is effectively a singleton: all methods are class-level, provider configuration is memoized in a class-level variable, and <code>reload!</code> resets that state. This ensures a single source of truth for provider configuration and avoids repeated YAML parsing per request. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing any additional safety — the class-level approach achieves the same guarantees with cleaner call syntax.

* '''Template Method pattern''' — The OIDC login flow (fetch providers → build authorization URL → exchange code → verify token → match user) follows a fixed sequence of steps that is identical for every provider. Only the per-provider configuration values vary; the orchestrating methods in <code>OidcRequest</code> and <code>OidcLoginController</code> are shared across all providers.

* '''Service Object pattern''' — <code>OidcRequest</code> encapsulates the full OIDC flow (state generation, PKCE construction, token exchange, ID token verification, user matching) as cohesive methods on a single ActiveRecord model rather than spreading logic across the controller. The controller stays thin and delegates all protocol work to the model.

* '''Atomic Consume (compensating database pattern)''' — <code>consume_recent_by_state!</code> finds, locks, and destroys the matching row within a single transaction, preventing replay attacks and race conditions where two concurrent callbacks could both claim the same state.

* '''Probabilistic garbage collection''' — Stale <code>oidc_requests</code> rows are cleaned up on a small percentage of new request creations rather than via a scheduled job. This amortizes cleanup cost across normal usage and avoids adding a scheduler dependency to the application.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-24T18:57:32Z

Jweisz: /* Tests */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

* '''Singleton pattern''' — <code>OidcConfig</code> is effectively a singleton: all methods are class-level, provider configuration is memoized in a class-level variable, and <code>reload!</code> resets that state. This ensures a single source of truth for provider configuration and avoids repeated YAML parsing per request. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing any additional safety — the class-level approach achieves the same guarantees with cleaner call syntax.

* '''Template Method pattern''' — The OIDC login flow (fetch providers → build authorization URL → exchange code → verify token → match user) follows a fixed sequence of steps that is identical for every provider. Only the per-provider configuration values vary; the orchestrating methods in <code>OidcRequest</code> and <code>OidcLoginController</code> are shared across all providers.

* '''Service Object pattern''' — <code>OidcRequest</code> encapsulates the full OIDC flow (state generation, PKCE construction, token exchange, ID token verification, user matching) as cohesive methods on a single ActiveRecord model rather than spreading logic across the controller. The controller stays thin and delegates all protocol work to the model.

* '''Atomic Consume (compensating database pattern)''' — <code>consume_recent_by_state!</code> finds, locks, and destroys the matching row within a single transaction, preventing replay attacks and race conditions where two concurrent callbacks could both claim the same state.

* '''Probabilistic garbage collection''' — Stale <code>oidc_requests</code> rows are cleaned up on a small percentage of new request creations rather than via a scheduled job. This amortizes cleanup cost across normal usage and avoids adding a scheduler dependency to the application.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests ==

=== Backend (RSpec) ===

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

=== Frontend (Vitest) ===

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-24T18:52:48Z

Jweisz: /* File Diffs */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

* '''Singleton pattern''' — <code>OidcConfig</code> is effectively a singleton: all methods are class-level, provider configuration is memoized in a class-level variable, and <code>reload!</code> resets that state. This ensures a single source of truth for provider configuration and avoids repeated YAML parsing per request. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing any additional safety — the class-level approach achieves the same guarantees with cleaner call syntax.

* '''Template Method pattern''' — The OIDC login flow (fetch providers → build authorization URL → exchange code → verify token → match user) follows a fixed sequence of steps that is identical for every provider. Only the per-provider configuration values vary; the orchestrating methods in <code>OidcRequest</code> and <code>OidcLoginController</code> are shared across all providers.

* '''Service Object pattern''' — <code>OidcRequest</code> encapsulates the full OIDC flow (state generation, PKCE construction, token exchange, ID token verification, user matching) as cohesive methods on a single ActiveRecord model rather than spreading logic across the controller. The controller stays thin and delegates all protocol work to the model.

* '''Atomic Consume (compensating database pattern)''' — <code>consume_recent_by_state!</code> finds, locks, and destroys the matching row within a single transaction, preventing replay attacks and race conditions where two concurrent callbacks could both claim the same state.

* '''Probabilistic garbage collection''' — Stale <code>oidc_requests</code> rows are cleaned up on a small percentage of new request creations rather than via a scheduled job. This amortizes cleanup cost across normal usage and avoids adding a scheduler dependency to the application.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Pull Requests ===
* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

=== Frontend ===
src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Tests ==

=== Backend (RSpec) ===

==== [https://github.com/expertiza/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb spec/models/oidc_request_spec.rb] ====

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests and preserves the row
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''Probabilistic cleanup on create'''
* Enqueues CleanupStaleOidcRequestsJob when rand falls under the threshold
* Does not enqueue when rand falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns provider authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email when email_verified is true
* Raises AuthenticationError when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Matches user when DB stores values with leading or trailing whitespace
* Raises AuthenticationError when email is blank
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither username nor email match

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

==== [https://github.com/expertiza/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] ====

'''.providers'''
* Loads providers from YAML and evaluates ERB env vars
* Memoizes results until reload! is called
* Skips providers missing required keys and warns
* Returns an empty hash when no providers key exists
* Returns an empty hash when YAML is empty
* Returns an empty hash when providers key is null
* Returns an empty hash when the top-level YAML is not a Hash
* Returns an empty hash when the providers value is not a Hash
* Supports YAML aliases in provider definitions

'''Production behavior'''
* Raises InvalidConfiguration when a provider is missing required keys
* Raises InvalidConfiguration when the top-level YAML is not a Hash
* Raises InvalidConfiguration when the providers value is not a Hash

'''.find'''
* Returns a provider config by key
* Raises ProviderNotFound for unknown provider keys

'''.public_list'''
* Returns only id and name for each provider, never secrets

'''.scopes_for'''
* Parses whitespace-delimited scope strings
* Parses comma-delimited scope strings
* Parses mixed comma and whitespace delimiters
* Falls back to default scopes when scopes is nil
* Falls back to default scopes when scopes key is absent

==== [https://github.com/expertiza/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] ====

'''#generate_jwt'''
* Encodes the user attributes (id, name, full_name, role, institution_id, exp) into a JWT
* Defaults to 24 hour expiry
* Raises an error when the token signature is invalid (tampered token rejected)

==== [https://github.com/expertiza/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] ====

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback — happy path'''
* Exchanges valid code and state for a session JWT

'''POST /auth/callback — generic 401 "Authentication failed"'''
* When no user matches the username and email
* When email matches but username does not
* When state is invalid or expired
* When token verification fails
* When the stored provider no longer exists in config

'''POST /auth/callback — other errors'''
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails

=== Frontend (Vitest) ===

==== [https://github.com/expertiza/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] ====

'''OidcModal Component'''
* Renders nothing when GET /auth/providers returns an empty array
* Renders nothing when GET /auth/providers fails
* Renders SSO button when providers are returned
* Opens the modal when the SSO button is pressed
* Populates the provider dropdown with configured providers
* Disables submit until both username and provider are provided
* Posts provider id and username to /auth/client-select on submit
* Redirects the browser to the returned authorization URL on success
* Does not redirect when client-select fails

==== [https://github.com/expertiza/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] ====

'''OidcCallback Component'''
* Posts code and state to POST /auth/callback on mount
* Stores session JWT and dispatches auth state on success
* Redirects to dashboard on successful login
* Displays error alert and redirects to login on backend failure
* Handles IdP error query parameter without calling the backend
* Redirects to login when code or state query parameters are missing
* Shows "Completing login..." message while request is in flight

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-24T00:15:00Z

Jweisz: /* Planning */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

* '''Singleton pattern''' — <code>OidcConfig</code> is effectively a singleton: all methods are class-level, provider configuration is memoized in a class-level variable, and <code>reload!</code> resets that state. This ensures a single source of truth for provider configuration and avoids repeated YAML parsing per request. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing any additional safety — the class-level approach achieves the same guarantees with cleaner call syntax.

* '''Template Method pattern''' — The OIDC login flow (fetch providers → build authorization URL → exchange code → verify token → match user) follows a fixed sequence of steps that is identical for every provider. Only the per-provider configuration values vary; the orchestrating methods in <code>OidcRequest</code> and <code>OidcLoginController</code> are shared across all providers.

* '''Service Object pattern''' — <code>OidcRequest</code> encapsulates the full OIDC flow (state generation, PKCE construction, token exchange, ID token verification, user matching) as cohesive methods on a single ActiveRecord model rather than spreading logic across the controller. The controller stays thin and delegates all protocol work to the model.

* '''Atomic Consume (compensating database pattern)''' — <code>consume_recent_by_state!</code> finds, locks, and destroys the matching row within a single transaction, preventing replay attacks and race conditions where two concurrent callbacks could both claim the same state.

* '''Probabilistic garbage collection''' — Stale <code>oidc_requests</code> rows are cleaned up on a small percentage of new request creations rather than via a scheduled job. This amortizes cleanup cost across normal usage and avoids adding a scheduler dependency to the application.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Pull Requests ===

* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
Application code ([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335]):

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

RSpec tests:

spec/models/oidc_request_spec.rb — Atomic state consumption and replay prevention, probabilistic cleanup enqueuing, authorization URL construction with username, ID token verification with strict email_verified check, case-insensitive user matching with whitespace normalization, client construction
spec/models/oidc_config_spec.rb — YAML loading and ERB interpolation, memoization and reload, required key validation (warn in dev, raise InvalidConfiguration in production), scope normalization, public_list secrets exclusion, ProviderNotFound lookup
spec/models/user_spec.rb — <code>User#generate_jwt</code> payload structure, default and custom expiry, rejection of tampered tokens
spec/requests/oidc_login_spec.rb — Endpoint tests covering the happy path, 400 for missing params, 404 for unknown provider, 502 for discovery failures, and a generic 401 "Authentication failed" for all callback failure modes (invalid state, token verification failure, username/email mismatch, deleted provider)

=== Frontend ===
Application code ([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172]):

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

Vitest tests:

src/components/Modals/OidcModal.test.tsx — SSO button conditional rendering, modal form with username and provider dropdown, redirect to authorization URL on submit
src/pages/OidcCallback/OidcCallback.test.tsx — Token exchange on mount, success flow (JWT storage, auth dispatch, dashboard redirect), error flows (backend failure, IdP error param, missing code/state)

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

* [https://github.com/users/johnmweisz/projects/9 Backend project board]
* [https://github.com/users/johnmweisz/projects/8 Frontend project board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* In production, raise <code>OidcConfig::InvalidConfiguration</code> to block startup with misconfigured providers; in other environments, skip invalid providers with a warning so local development and CI are not blocked.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, not null, unique, indexed), <code>nonce</code> (not null), <code>code_verifier</code> (not null), <code>provider</code> (not null), <code>username</code> (not null), and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Expose a <code>delete_stale</code> class method that deletes rows older than the validity window.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and stale deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if the <code>email_verified</code> claim is not explicitly <code>true</code>.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive with whitespace trimmed on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — SSO Modal with Username and Provider Selection ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display an SSO button when providers are returned.
* On button press, open a modal with a username text input and a <code>Form.Select</code> dropdown populated with the configured providers.
* Hide or disable the submit action until both username and provider are provided.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, form validation, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' submitting the SSO form to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On submit, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a scheduled job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* Add a <code>CleanupStaleOidcRequestsJob</code> ActiveJob that calls <code>OidcRequest.delete_stale</code>.
* On <code>after_create</code> of <code>OidcRequest</code>, enqueue the job with a 10% probability (<code>CLEANUP_PROBABILITY</code>).
* Use a <code>VALIDITY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add tests verifying stale rows are deleted, fresh rows are preserved, and the job is enqueued at the expected probability.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Request specs for the three OIDC endpoints covering happy paths and all documented error responses (400, 401, 404, 502).
* Model specs for <code>OidcRequest</code> covering atomic state consumption, replay prevention, expiry, probabilistic cleanup enqueuing, case-insensitive user matching with whitespace normalization, strict <code>email_verified</code> handling, and PKCE code verifier flow.
* Model specs for <code>OidcConfig</code> covering YAML loading, ERB interpolation, memoization and reload, missing key detection (warn in dev, raise in production), scope normalization, and <code>public_list</code> secrets exclusion.
* Model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly. Many of these tests are added incrementally alongside each feature story; this story captures the consolidated coverage expectation and gap analysis.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Component tests for <code>OidcModal</code>:
** Renders nothing on empty or failed providers response.
** Renders SSO button when providers are returned.
** Opens the modal when the SSO button is pressed.
** Populates the provider dropdown with configured providers.
** Requires both username and provider before submit is enabled.
** Includes provider id and username in the <code>POST /auth/client-select</code> payload.
** Redirects the browser to the returned authorization URL on success.
** Does not redirect on failure.
* Component tests for <code>OidcCallback</code>:
** Posts code and state to <code>POST /auth/callback</code> on mount.
** Stores the session JWT and dispatches auth state on success.
** Redirects to the dashboard on success.
** Displays an error alert and redirects to login on backend failure.
** Handles the IdP <code>error</code> query parameter without calling the backend.
** Redirects to login when code or state are missing.
** Shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-24T00:12:09Z

Jweisz: /* File Diffs */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

* '''Singleton pattern''' — <code>OidcConfig</code> is effectively a singleton: all methods are class-level, provider configuration is memoized in a class-level variable, and <code>reload!</code> resets that state. This ensures a single source of truth for provider configuration and avoids repeated YAML parsing per request. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing any additional safety — the class-level approach achieves the same guarantees with cleaner call syntax.

* '''Template Method pattern''' — The OIDC login flow (fetch providers → build authorization URL → exchange code → verify token → match user) follows a fixed sequence of steps that is identical for every provider. Only the per-provider configuration values vary; the orchestrating methods in <code>OidcRequest</code> and <code>OidcLoginController</code> are shared across all providers.

* '''Service Object pattern''' — <code>OidcRequest</code> encapsulates the full OIDC flow (state generation, PKCE construction, token exchange, ID token verification, user matching) as cohesive methods on a single ActiveRecord model rather than spreading logic across the controller. The controller stays thin and delegates all protocol work to the model.

* '''Atomic Consume (compensating database pattern)''' — <code>consume_recent_by_state!</code> finds, locks, and destroys the matching row within a single transaction, preventing replay attacks and race conditions where two concurrent callbacks could both claim the same state.

* '''Probabilistic garbage collection''' — Stale <code>oidc_requests</code> rows are cleaned up on a small percentage of new request creations rather than via a scheduled job. This amortizes cleanup cost across normal usage and avoids adding a scheduler dependency to the application.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Pull Requests ===

* Backend: [https://github.com/expertiza/reimplementation-back-end/pull/335 reimplementation-back-end#335]
* Frontend: [https://github.com/expertiza/reimplementation-front-end/pull/172 reimplementation-front-end#172]

=== Backend ===
Application code ([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335]):

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation (strict in production), scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table

RSpec tests:

spec/models/oidc_request_spec.rb — Atomic state consumption and replay prevention, probabilistic cleanup enqueuing, authorization URL construction with username, ID token verification with strict email_verified check, case-insensitive user matching with whitespace normalization, client construction
spec/models/oidc_config_spec.rb — YAML loading and ERB interpolation, memoization and reload, required key validation (warn in dev, raise InvalidConfiguration in production), scope normalization, public_list secrets exclusion, ProviderNotFound lookup
spec/models/user_spec.rb — <code>User#generate_jwt</code> payload structure, default and custom expiry, rejection of tampered tokens
spec/requests/oidc_login_spec.rb — Endpoint tests covering the happy path, 400 for missing params, 404 for unknown provider, 502 for discovery failures, and a generic 401 "Authentication failed" for all callback failure modes (invalid state, token verification failure, username/email mismatch, deleted provider)

=== Frontend ===
Application code ([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172]):

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

Vitest tests:

src/components/Modals/OidcModal.test.tsx — SSO button conditional rendering, modal form with username and provider dropdown, redirect to authorization URL on submit
src/pages/OidcCallback/OidcCallback.test.tsx — Token exchange on mount, success flow (JWT storage, auth dispatch, dashboard redirect), error flows (backend failure, IdP error param, missing code/state)

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

[https://github.com/users/johnmweisz/projects/8 frontend board]

[https://github.com/users/johnmweisz/projects/9 backend board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* Skip providers with missing keys and log a warning rather than crashing the app.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, <code>username</code>, and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>recent</code> scope for expiry filtering and a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Probabilistically clean up stale rows inside <code>authorization_uri_for!</code> (10% chance per call) to keep the table bounded without requiring a scheduled job.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and cleanup.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if an <code>email_verified</code> claim is present and false.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — Provider Dropdown with Username Input on Login Page ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display SSO Button when providers are configured properly
* On SSO Button press, renders the modal with a username text input and a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* Hide the dropdown until the username input is non-empty.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, username-gated dropdown visibility, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' the session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default expiry, custom expiry, and signature verification (tampered tokens rejected).
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a background job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* In <code>OidcRequest.authorization_uri_for!</code>, run a DELETE for rows older than the expiry window with a 10% probability per call (<code>if rand < 0.1</code>).
* Use an <code>EXPIRY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add a test verifying that stale rows are eventually removed and fresh rows are preserved.
* Document the rationale in the model with a brief inline comment.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover <code>client-select</code>: happy path, missing params (400), unknown provider (404), discovery failure (502).
* Cover <code>callback</code> happy path: valid code and state exchanged for a session JWT, row consumed after use.
* Cover <code>callback</code> generic 401 "Authentication failed" for: invalid or expired state, replayed state, no matching user, username/email mismatch, token verification failure (bad signature, issuer, audience, or nonce), unverified email, unknown provider on consumed row.
* Cover <code>callback</code> missing params (400) and discovery failure (502).
* Add model specs for <code>OidcRequest</code> covering: atomic state consumption, replay prevention, expiry window, case-insensitive user matching, <code>email_verified</code> claim handling, and PKCE code verifier sent to the token endpoint.
* Add model specs for <code>OidcConfig</code> covering: config loading, ERB interpolation, missing key detection, scope normalization, <code>public_list</code> secrets exclusion, and unknown provider lookup.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Add component tests for <code>OidcModal</code>:
** renders nothing on empty or failed providers response
** renders SSO button when providers are returned
** displays modal when SSO button is pressed
** displays providers in dropdown when providers are returned,
** requires username and provider to both be filled out before SSO can be pressed
** includes both provider id and username in the <code>POST /auth/client-select</code> payload,
** redirects the browser to the returned authorization URL on success
** does not redirect on failure.
* Add component tests for <code>OidcCallback</code>:
** posts code and state to <code>POST /auth/callback</code> on mount
** stores session JWT and dispatches auth state on success
** redirects to dashboard on success
** displays error alert and redirects to login on backend failure
** handles IdP <code>error</code> query parameter without calling the backend
** redirects to login when code or state are missing
** shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-24T00:10:15Z

Jweisz: /* Provider Configuration (OidcConfig) */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

* '''Singleton pattern''' — <code>OidcConfig</code> is effectively a singleton: all methods are class-level, provider configuration is memoized in a class-level variable, and <code>reload!</code> resets that state. This ensures a single source of truth for provider configuration and avoids repeated YAML parsing per request. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing any additional safety — the class-level approach achieves the same guarantees with cleaner call syntax.

* '''Template Method pattern''' — The OIDC login flow (fetch providers → build authorization URL → exchange code → verify token → match user) follows a fixed sequence of steps that is identical for every provider. Only the per-provider configuration values vary; the orchestrating methods in <code>OidcRequest</code> and <code>OidcLoginController</code> are shared across all providers.

* '''Service Object pattern''' — <code>OidcRequest</code> encapsulates the full OIDC flow (state generation, PKCE construction, token exchange, ID token verification, user matching) as cohesive methods on a single ActiveRecord model rather than spreading logic across the controller. The controller stays thin and delegates all protocol work to the model.

* '''Atomic Consume (compensating database pattern)''' — <code>consume_recent_by_state!</code> finds, locks, and destroys the matching row within a single transaction, preventing replay attacks and race conditions where two concurrent callbacks could both claim the same state.

* '''Probabilistic garbage collection''' — Stale <code>oidc_requests</code> rows are cleaned up on a small percentage of new request creations rather than via a scheduled job. This amortizes cleanup cost across normal usage and avoids adding a scheduler dependency to the application.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used; non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Backend (Rails) ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation, scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>, enqueued probabilistically on request creation
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table
db/migrate/*_add_username_to_oidc_requests.rb — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

spec/models/oidc_request_spec.rb — Model tests covering:

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests (and preserves the row)
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''after_create probabilistic cleanup'''
* Enqueues CleanupStaleOidcRequestsJob when <code>rand</code> falls under the threshold
* Does not enqueue when <code>rand</code> falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email
* Passes when email_verified claim is true
* Passes when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither matches

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

spec/models/oidc_config_spec.rb — Config loading, ERB env var interpolation, memoization and reload, missing key detection with warning log, YAML edge cases (empty file, null providers key, aliases), <code>public_list</code> secrets exclusion, <code>find</code> lookup and ProviderNotFound, scope normalization (whitespace and comma-delimited, default fallback)

spec/requests/oidc_login_spec.rb — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback'''
* Happy path: exchanges valid code and state for a session JWT
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails
* Returns generic 401 "Authentication failed" for:
** No user matching the username and email
** Email matches but username does not
** Invalid or expired state
** Token verification failure
** Stored provider no longer exists in config

spec/models/user_spec.rb — Tests for <code>User#generate_jwt</code> covering payload structure

=== Frontend (React) ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.test.tsx — SSO modal display and provider dropdown component tests
src/pages/OidcCallback/OidcCallback.test.tsx — Callback page tests

'''OidcModal Component'''
* Renders SSO button when providers are configured, renders nothing when the providers response is empty or fails
* Displays the modal form with username input and provider dropdown when providers are returned
* Posts the provider id and username to <code>/auth/client-select</code> on selection and redirects the browser to the returned authorization URL

'''OidcCallback Component'''
* Posts code and state to <code>/auth/callback</code> on mount, stores the session JWT, dispatches auth state, and redirects to the dashboard on success
* Displays an error and redirects to login on backend failure, on IdP <code>error</code> query param (without calling the backend), and on missing code or state

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

[https://github.com/users/johnmweisz/projects/8 frontend board]

[https://github.com/users/johnmweisz/projects/9 backend board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* Skip providers with missing keys and log a warning rather than crashing the app.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, <code>username</code>, and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>recent</code> scope for expiry filtering and a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Probabilistically clean up stale rows inside <code>authorization_uri_for!</code> (10% chance per call) to keep the table bounded without requiring a scheduled job.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and cleanup.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if an <code>email_verified</code> claim is present and false.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — Provider Dropdown with Username Input on Login Page ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display SSO Button when providers are configured properly
* On SSO Button press, renders the modal with a username text input and a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* Hide the dropdown until the username input is non-empty.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, username-gated dropdown visibility, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' the session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default expiry, custom expiry, and signature verification (tampered tokens rejected).
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a background job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* In <code>OidcRequest.authorization_uri_for!</code>, run a DELETE for rows older than the expiry window with a 10% probability per call (<code>if rand < 0.1</code>).
* Use an <code>EXPIRY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add a test verifying that stale rows are eventually removed and fresh rows are preserved.
* Document the rationale in the model with a brief inline comment.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover <code>client-select</code>: happy path, missing params (400), unknown provider (404), discovery failure (502).
* Cover <code>callback</code> happy path: valid code and state exchanged for a session JWT, row consumed after use.
* Cover <code>callback</code> generic 401 "Authentication failed" for: invalid or expired state, replayed state, no matching user, username/email mismatch, token verification failure (bad signature, issuer, audience, or nonce), unverified email, unknown provider on consumed row.
* Cover <code>callback</code> missing params (400) and discovery failure (502).
* Add model specs for <code>OidcRequest</code> covering: atomic state consumption, replay prevention, expiry window, case-insensitive user matching, <code>email_verified</code> claim handling, and PKCE code verifier sent to the token endpoint.
* Add model specs for <code>OidcConfig</code> covering: config loading, ERB interpolation, missing key detection, scope normalization, <code>public_list</code> secrets exclusion, and unknown provider lookup.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Add component tests for <code>OidcModal</code>:
** renders nothing on empty or failed providers response
** renders SSO button when providers are returned
** displays modal when SSO button is pressed
** displays providers in dropdown when providers are returned,
** requires username and provider to both be filled out before SSO can be pressed
** includes both provider id and username in the <code>POST /auth/client-select</code> payload,
** redirects the browser to the returned authorization URL on success
** does not redirect on failure.
* Add component tests for <code>OidcCallback</code>:
** posts code and state to <code>POST /auth/callback</code> on mount
** stores session JWT and dispatches auth state on success
** redirects to dashboard on success
** displays error alert and redirects to login on backend failure
** handles IdP <code>error</code> query parameter without calling the backend
** redirects to login when code or state are missing
** shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-24T00:07:28Z

Jweisz: /* Design Patterns */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

* '''Singleton pattern''' — <code>OidcConfig</code> is effectively a singleton: all methods are class-level, provider configuration is memoized in a class-level variable, and <code>reload!</code> resets that state. This ensures a single source of truth for provider configuration and avoids repeated YAML parsing per request. Ruby's <code>Singleton</code> module was not used because it would require changing every call site from <code>OidcConfig.find(...)</code> to <code>OidcConfig.instance.find(...)</code> without providing any additional safety — the class-level approach achieves the same guarantees with cleaner call syntax.

* '''Template Method pattern''' — The OIDC login flow (fetch providers → build authorization URL → exchange code → verify token → match user) follows a fixed sequence of steps that is identical for every provider. Only the per-provider configuration values vary; the orchestrating methods in <code>OidcRequest</code> and <code>OidcLoginController</code> are shared across all providers.

* '''Service Object pattern''' — <code>OidcRequest</code> encapsulates the full OIDC flow (state generation, PKCE construction, token exchange, ID token verification, user matching) as cohesive methods on a single ActiveRecord model rather than spreading logic across the controller. The controller stays thin and delegates all protocol work to the model.

* '''Atomic Consume (compensating database pattern)''' — <code>consume_recent_by_state!</code> finds, locks, and destroys the matching row within a single transaction, preventing replay attacks and race conditions where two concurrent callbacks could both claim the same state.

* '''Probabilistic garbage collection''' — Stale <code>oidc_requests</code> rows are cleaned up on a small percentage of new request creations rather than via a scheduled job. This amortizes cleanup cost across normal usage and avoids adding a scheduler dependency to the application.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used — non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Backend (Rails) ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation, scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>, enqueued probabilistically on request creation
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table
db/migrate/*_add_username_to_oidc_requests.rb — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

spec/models/oidc_request_spec.rb — Model tests covering:

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests (and preserves the row)
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''after_create probabilistic cleanup'''
* Enqueues CleanupStaleOidcRequestsJob when <code>rand</code> falls under the threshold
* Does not enqueue when <code>rand</code> falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email
* Passes when email_verified claim is true
* Passes when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither matches

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

spec/models/oidc_config_spec.rb — Config loading, ERB env var interpolation, memoization and reload, missing key detection with warning log, YAML edge cases (empty file, null providers key, aliases), <code>public_list</code> secrets exclusion, <code>find</code> lookup and ProviderNotFound, scope normalization (whitespace and comma-delimited, default fallback)

spec/requests/oidc_login_spec.rb — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback'''
* Happy path: exchanges valid code and state for a session JWT
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails
* Returns generic 401 "Authentication failed" for:
** No user matching the username and email
** Email matches but username does not
** Invalid or expired state
** Token verification failure
** Stored provider no longer exists in config

spec/models/user_spec.rb — Tests for <code>User#generate_jwt</code> covering payload structure

=== Frontend (React) ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.test.tsx — SSO modal display and provider dropdown component tests
src/pages/OidcCallback/OidcCallback.test.tsx — Callback page tests

'''OidcModal Component'''
* Renders SSO button when providers are configured, renders nothing when the providers response is empty or fails
* Displays the modal form with username input and provider dropdown when providers are returned
* Posts the provider id and username to <code>/auth/client-select</code> on selection and redirects the browser to the returned authorization URL

'''OidcCallback Component'''
* Posts code and state to <code>/auth/callback</code> on mount, stores the session JWT, dispatches auth state, and redirects to the dashboard on success
* Displays an error and redirects to login on backend failure, on IdP <code>error</code> query param (without calling the backend), and on missing code or state

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

[https://github.com/users/johnmweisz/projects/8 frontend board]

[https://github.com/users/johnmweisz/projects/9 backend board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* Skip providers with missing keys and log a warning rather than crashing the app.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, <code>username</code>, and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>recent</code> scope for expiry filtering and a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Probabilistically clean up stale rows inside <code>authorization_uri_for!</code> (10% chance per call) to keep the table bounded without requiring a scheduled job.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and cleanup.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if an <code>email_verified</code> claim is present and false.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — Provider Dropdown with Username Input on Login Page ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display SSO Button when providers are configured properly
* On SSO Button press, renders the modal with a username text input and a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* Hide the dropdown until the username input is non-empty.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, username-gated dropdown visibility, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' the session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default expiry, custom expiry, and signature verification (tampered tokens rejected).
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a background job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* In <code>OidcRequest.authorization_uri_for!</code>, run a DELETE for rows older than the expiry window with a 10% probability per call (<code>if rand < 0.1</code>).
* Use an <code>EXPIRY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add a test verifying that stale rows are eventually removed and fresh rows are preserved.
* Document the rationale in the model with a brief inline comment.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover <code>client-select</code>: happy path, missing params (400), unknown provider (404), discovery failure (502).
* Cover <code>callback</code> happy path: valid code and state exchanged for a session JWT, row consumed after use.
* Cover <code>callback</code> generic 401 "Authentication failed" for: invalid or expired state, replayed state, no matching user, username/email mismatch, token verification failure (bad signature, issuer, audience, or nonce), unverified email, unknown provider on consumed row.
* Cover <code>callback</code> missing params (400) and discovery failure (502).
* Add model specs for <code>OidcRequest</code> covering: atomic state consumption, replay prevention, expiry window, case-insensitive user matching, <code>email_verified</code> claim handling, and PKCE code verifier sent to the token endpoint.
* Add model specs for <code>OidcConfig</code> covering: config loading, ERB interpolation, missing key detection, scope normalization, <code>public_list</code> secrets exclusion, and unknown provider lookup.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Add component tests for <code>OidcModal</code>:
** renders nothing on empty or failed providers response
** renders SSO button when providers are returned
** displays modal when SSO button is pressed
** displays providers in dropdown when providers are returned,
** requires username and provider to both be filled out before SSO can be pressed
** includes both provider id and username in the <code>POST /auth/client-select</code> payload,
** redirects the browser to the returned authorization URL on success
** does not redirect on failure.
* Add component tests for <code>OidcCallback</code>:
** posts code and state to <code>POST /auth/callback</code> on mount
** stores session JWT and dispatches auth state on success
** redirects to dashboard on success
** displays error alert and redirects to login on backend failure
** handles IdP <code>error</code> query parameter without calling the backend
** redirects to login when code or state are missing
** shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-24T00:06:32Z

Jweisz: /* Design Patterns */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===

* '''Strategy pattern''' — Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

* '''Singleton pattern''' — <code>OidcConfig</code> is effectively a singleton: all methods are class-level, provider configuration is memoized in a class-level variable, and <code>reload!</code> resets that state. This ensures a single source of truth for provider configuration and avoids repeated YAML parsing per request.

* '''Template Method pattern''' — The OIDC login flow (fetch providers → build authorization URL → exchange code → verify token → match user) follows a fixed sequence of steps that is identical for every provider. Only the per-provider configuration values vary; the orchestrating methods in <code>OidcRequest</code> and <code>OidcLoginController</code> are shared across all providers.

* '''Service Object pattern''' — <code>OidcRequest</code> encapsulates the full OIDC flow (state generation, PKCE construction, token exchange, ID token verification, user matching) as cohesive methods on a single ActiveRecord model rather than spreading logic across the controller. The controller stays thin and delegates all protocol work to the model.

* '''Atomic Consume (compensating database pattern)''' — <code>consume_recent_by_state!</code> finds, locks, and destroys the matching row within a single transaction, preventing replay attacks and race conditions where two concurrent callbacks could both claim the same state.

* '''Probabilistic garbage collection''' — Stale <code>oidc_requests</code> rows are cleaned up on a small percentage of new request creations rather than via a scheduled job. This amortizes cleanup cost across normal usage and avoids adding a scheduler dependency to the application.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used — non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Backend (Rails) ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation, scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>, enqueued probabilistically on request creation
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table
db/migrate/*_add_username_to_oidc_requests.rb — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

spec/models/oidc_request_spec.rb — Model tests covering:

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests (and preserves the row)
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''after_create probabilistic cleanup'''
* Enqueues CleanupStaleOidcRequestsJob when <code>rand</code> falls under the threshold
* Does not enqueue when <code>rand</code> falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email
* Passes when email_verified claim is true
* Passes when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither matches

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

spec/models/oidc_config_spec.rb — Config loading, ERB env var interpolation, memoization and reload, missing key detection with warning log, YAML edge cases (empty file, null providers key, aliases), <code>public_list</code> secrets exclusion, <code>find</code> lookup and ProviderNotFound, scope normalization (whitespace and comma-delimited, default fallback)

spec/requests/oidc_login_spec.rb — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback'''
* Happy path: exchanges valid code and state for a session JWT
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails
* Returns generic 401 "Authentication failed" for:
** No user matching the username and email
** Email matches but username does not
** Invalid or expired state
** Token verification failure
** Stored provider no longer exists in config

spec/models/user_spec.rb — Tests for <code>User#generate_jwt</code> covering payload structure

=== Frontend (React) ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.test.tsx — SSO modal display and provider dropdown component tests
src/pages/OidcCallback/OidcCallback.test.tsx — Callback page tests

'''OidcModal Component'''
* Renders SSO button when providers are configured, renders nothing when the providers response is empty or fails
* Displays the modal form with username input and provider dropdown when providers are returned
* Posts the provider id and username to <code>/auth/client-select</code> on selection and redirects the browser to the returned authorization URL

'''OidcCallback Component'''
* Posts code and state to <code>/auth/callback</code> on mount, stores the session JWT, dispatches auth state, and redirects to the dashboard on success
* Displays an error and redirects to login on backend failure, on IdP <code>error</code> query param (without calling the backend), and on missing code or state

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

[https://github.com/users/johnmweisz/projects/8 frontend board]

[https://github.com/users/johnmweisz/projects/9 backend board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* Skip providers with missing keys and log a warning rather than crashing the app.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, <code>username</code>, and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>recent</code> scope for expiry filtering and a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Probabilistically clean up stale rows inside <code>authorization_uri_for!</code> (10% chance per call) to keep the table bounded without requiring a scheduled job.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and cleanup.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if an <code>email_verified</code> claim is present and false.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — Provider Dropdown with Username Input on Login Page ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display SSO Button when providers are configured properly
* On SSO Button press, renders the modal with a username text input and a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* Hide the dropdown until the username input is non-empty.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, username-gated dropdown visibility, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' the session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default expiry, custom expiry, and signature verification (tampered tokens rejected).
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a background job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* In <code>OidcRequest.authorization_uri_for!</code>, run a DELETE for rows older than the expiry window with a 10% probability per call (<code>if rand < 0.1</code>).
* Use an <code>EXPIRY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add a test verifying that stale rows are eventually removed and fresh rows are preserved.
* Document the rationale in the model with a brief inline comment.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover <code>client-select</code>: happy path, missing params (400), unknown provider (404), discovery failure (502).
* Cover <code>callback</code> happy path: valid code and state exchanged for a session JWT, row consumed after use.
* Cover <code>callback</code> generic 401 "Authentication failed" for: invalid or expired state, replayed state, no matching user, username/email mismatch, token verification failure (bad signature, issuer, audience, or nonce), unverified email, unknown provider on consumed row.
* Cover <code>callback</code> missing params (400) and discovery failure (502).
* Add model specs for <code>OidcRequest</code> covering: atomic state consumption, replay prevention, expiry window, case-insensitive user matching, <code>email_verified</code> claim handling, and PKCE code verifier sent to the token endpoint.
* Add model specs for <code>OidcConfig</code> covering: config loading, ERB interpolation, missing key detection, scope normalization, <code>public_list</code> secrets exclusion, and unknown provider lookup.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Add component tests for <code>OidcModal</code>:
** renders nothing on empty or failed providers response
** renders SSO button when providers are returned
** displays modal when SSO button is pressed
** displays providers in dropdown when providers are returned,
** requires username and provider to both be filled out before SSO can be pressed
** includes both provider id and username in the <code>POST /auth/client-select</code> payload,
** redirects the browser to the returned authorization URL on success
** does not redirect on failure.
* Add component tests for <code>OidcCallback</code>:
** posts code and state to <code>POST /auth/callback</code> on mount
** stores session JWT and dispatches auth state on success
** redirects to dashboard on success
** displays error alert and redirects to login on backend failure
** handles IdP <code>error</code> query parameter without calling the backend
** redirects to login when code or state are missing
** shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-24T00:05:31Z

Jweisz: /* Design */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present when accessed. In production, invalid configuration raises <code>OidcConfig::InvalidConfiguration</code> to prevent startup with a misconfigured provider. In other environments, invalid providers are skipped with a warning to avoid blocking local development and CI where OIDC may not be fully configured. Validation runs at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately in production.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Both parameters are required; missing parameters return a 400. Fetch the provider's <code>.well-known/openid-configuration</code> document using the <code>openid_connect</code> gem to resolve endpoints and JWKS keys. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>oidc_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. With a 10% probability per request, enqueue a <code>CleanupStaleOidcRequestsJob</code> to amortize the cost of deleting stale rows without requiring a dedicated scheduler. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Both parameters are required. Atomically look up and destroy the matching <code>oidc_requests</code> row by state within a database transaction with row-level locking, rejecting the request if no row is found or if the row is older than 5 minutes. The atomic consume prevents replay. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. The <code>email_verified</code> claim must be explicitly <code>true</code>; tokens without it or with a false value are rejected. Match the user by both the stored username and the verified email claim from the ID token using case-insensitive, whitespace-trimmed comparison (emails are not unique in Expertiza, so username disambiguates). If a match is found, issue a session JWT via <code>user.generate_jwt</code> — the same method used by the existing password login. Return a generic 401 "Authentication failed" for all verification or matching failures (invalid state, replayed state, token verification failure, unverified email, no matching user, unknown provider) to avoid leaking which specific check failed.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, selects a provider, and clicks "Continue with SSO", the form posts to <code>/auth/client-select</code> with both the provider id and username. On success, the browser is redirected to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===
The implementation uses the '''Strategy pattern''' for provider configuration. Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || not null, unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables. Stale rows are cleaned up probabilistically on new request creation (10% chance to enqueue <code>CleanupStaleOidcRequestsJob</code>), avoiding the need for a dedicated scheduler.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are handled based on environment: in production, startup fails with <code>OidcConfig::InvalidConfiguration</code> to prevent running with misconfigured providers; in other environments, the invalid provider is skipped with a warning so local development and CI are not blocked. Discovery is always used — non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Backend (Rails) ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation, scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>, enqueued probabilistically on request creation
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table
db/migrate/*_add_username_to_oidc_requests.rb — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

spec/models/oidc_request_spec.rb — Model tests covering:

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests (and preserves the row)
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''after_create probabilistic cleanup'''
* Enqueues CleanupStaleOidcRequestsJob when <code>rand</code> falls under the threshold
* Does not enqueue when <code>rand</code> falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email
* Passes when email_verified claim is true
* Passes when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither matches

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

spec/models/oidc_config_spec.rb — Config loading, ERB env var interpolation, memoization and reload, missing key detection with warning log, YAML edge cases (empty file, null providers key, aliases), <code>public_list</code> secrets exclusion, <code>find</code> lookup and ProviderNotFound, scope normalization (whitespace and comma-delimited, default fallback)

spec/requests/oidc_login_spec.rb — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback'''
* Happy path: exchanges valid code and state for a session JWT
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails
* Returns generic 401 "Authentication failed" for:
** No user matching the username and email
** Email matches but username does not
** Invalid or expired state
** Token verification failure
** Stored provider no longer exists in config

spec/models/user_spec.rb — Tests for <code>User#generate_jwt</code> covering payload structure

=== Frontend (React) ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.test.tsx — SSO modal display and provider dropdown component tests
src/pages/OidcCallback/OidcCallback.test.tsx — Callback page tests

'''OidcModal Component'''
* Renders SSO button when providers are configured, renders nothing when the providers response is empty or fails
* Displays the modal form with username input and provider dropdown when providers are returned
* Posts the provider id and username to <code>/auth/client-select</code> on selection and redirects the browser to the returned authorization URL

'''OidcCallback Component'''
* Posts code and state to <code>/auth/callback</code> on mount, stores the session JWT, dispatches auth state, and redirects to the dashboard on success
* Displays an error and redirects to login on backend failure, on IdP <code>error</code> query param (without calling the backend), and on missing code or state

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

[https://github.com/users/johnmweisz/projects/8 frontend board]

[https://github.com/users/johnmweisz/projects/9 backend board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* Skip providers with missing keys and log a warning rather than crashing the app.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, <code>username</code>, and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>recent</code> scope for expiry filtering and a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Probabilistically clean up stale rows inside <code>authorization_uri_for!</code> (10% chance per call) to keep the table bounded without requiring a scheduled job.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and cleanup.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if an <code>email_verified</code> claim is present and false.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — Provider Dropdown with Username Input on Login Page ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display SSO Button when providers are configured properly
* On SSO Button press, renders the modal with a username text input and a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* Hide the dropdown until the username input is non-empty.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, username-gated dropdown visibility, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' the session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default expiry, custom expiry, and signature verification (tampered tokens rejected).
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a background job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* In <code>OidcRequest.authorization_uri_for!</code>, run a DELETE for rows older than the expiry window with a 10% probability per call (<code>if rand < 0.1</code>).
* Use an <code>EXPIRY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add a test verifying that stale rows are eventually removed and fresh rows are preserved.
* Document the rationale in the model with a brief inline comment.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover <code>client-select</code>: happy path, missing params (400), unknown provider (404), discovery failure (502).
* Cover <code>callback</code> happy path: valid code and state exchanged for a session JWT, row consumed after use.
* Cover <code>callback</code> generic 401 "Authentication failed" for: invalid or expired state, replayed state, no matching user, username/email mismatch, token verification failure (bad signature, issuer, audience, or nonce), unverified email, unknown provider on consumed row.
* Cover <code>callback</code> missing params (400) and discovery failure (502).
* Add model specs for <code>OidcRequest</code> covering: atomic state consumption, replay prevention, expiry window, case-insensitive user matching, <code>email_verified</code> claim handling, and PKCE code verifier sent to the token endpoint.
* Add model specs for <code>OidcConfig</code> covering: config loading, ERB interpolation, missing key detection, scope normalization, <code>public_list</code> secrets exclusion, and unknown provider lookup.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Add component tests for <code>OidcModal</code>:
** renders nothing on empty or failed providers response
** renders SSO button when providers are returned
** displays modal when SSO button is pressed
** displays providers in dropdown when providers are returned,
** requires username and provider to both be filled out before SSO can be pressed
** includes both provider id and username in the <code>POST /auth/client-select</code> payload,
** redirects the browser to the returned authorization URL on success
** does not redirect on failure.
* Add component tests for <code>OidcCallback</code>:
** posts code and state to <code>POST /auth/callback</code> on mount
** stores session JWT and dispatches auth state on success
** redirects to dashboard on success
** displays error alert and redirects to login on backend failure
** handles IdP <code>error</code> query parameter without calling the backend
** redirects to login when code or state are missing
** shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-23T22:27:34Z

Jweisz: /* Account Matching */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza; multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present at boot via <code>config/initializers/oidc.rb</code>. For providers with <code>discovery: true</code>, the <code>.well-known/openid-configuration</code> document is fetched using the <code>openid_connect</code> gem to resolve the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Discovery results are not aggressively cached to allow for key rotation; on signature verification failure, keys are re-fetched and verification is retried once.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>auth_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Look up the matching <code>auth_requests</code> row by state, rejecting the request if no row is found or if the row is older than 5 minutes. Delete the row to prevent reuse. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. Extract the user's email from the ID token claims and look up a matching local user and compare against username entry to ensure unique match. If a match is found, issue a session JWT using the same <code>JsonWebToken.encode</code> method and payload structure as the existing <code>AuthenticationController#login</code> action. If no match is found, return a 404 error indicating no local account exists for that email.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, provider and clicks Continue with SSO, the form does a <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, it redirects the browser to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===
The implementation uses the '''Strategy pattern''' for provider configuration. Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are skipped at boot with a warning logged, and they do not appear in <code>public_list</code>. Discovery is always used — non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Backend (Rails) ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation, scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>, enqueued probabilistically on request creation
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table
db/migrate/*_add_username_to_oidc_requests.rb — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

spec/models/oidc_request_spec.rb — Model tests covering:

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests (and preserves the row)
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''after_create probabilistic cleanup'''
* Enqueues CleanupStaleOidcRequestsJob when <code>rand</code> falls under the threshold
* Does not enqueue when <code>rand</code> falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email
* Passes when email_verified claim is true
* Passes when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither matches

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

spec/models/oidc_config_spec.rb — Config loading, ERB env var interpolation, memoization and reload, missing key detection with warning log, YAML edge cases (empty file, null providers key, aliases), <code>public_list</code> secrets exclusion, <code>find</code> lookup and ProviderNotFound, scope normalization (whitespace and comma-delimited, default fallback)

spec/requests/oidc_login_spec.rb — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback'''
* Happy path: exchanges valid code and state for a session JWT
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails
* Returns generic 401 "Authentication failed" for:
** No user matching the username and email
** Email matches but username does not
** Invalid or expired state
** Token verification failure
** Stored provider no longer exists in config

spec/models/user_spec.rb — Tests for <code>User#generate_jwt</code> covering payload structure

=== Frontend (React) ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.test.tsx — SSO modal display and provider dropdown component tests
src/pages/OidcCallback/OidcCallback.test.tsx — Callback page tests

'''OidcModal Component'''
* Renders SSO button when providers are configured, renders nothing when the providers response is empty or fails
* Displays the modal form with username input and provider dropdown when providers are returned
* Posts the provider id and username to <code>/auth/client-select</code> on selection and redirects the browser to the returned authorization URL

'''OidcCallback Component'''
* Posts code and state to <code>/auth/callback</code> on mount, stores the session JWT, dispatches auth state, and redirects to the dashboard on success
* Displays an error and redirects to login on backend failure, on IdP <code>error</code> query param (without calling the backend), and on missing code or state

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

[https://github.com/users/johnmweisz/projects/8 frontend board]

[https://github.com/users/johnmweisz/projects/9 backend board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* Skip providers with missing keys and log a warning rather than crashing the app.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, <code>username</code>, and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>recent</code> scope for expiry filtering and a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Probabilistically clean up stale rows inside <code>authorization_uri_for!</code> (10% chance per call) to keep the table bounded without requiring a scheduled job.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and cleanup.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if an <code>email_verified</code> claim is present and false.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — Provider Dropdown with Username Input on Login Page ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display SSO Button when providers are configured properly
* On SSO Button press, renders the modal with a username text input and a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* Hide the dropdown until the username input is non-empty.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, username-gated dropdown visibility, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' the session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default expiry, custom expiry, and signature verification (tampered tokens rejected).
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a background job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* In <code>OidcRequest.authorization_uri_for!</code>, run a DELETE for rows older than the expiry window with a 10% probability per call (<code>if rand < 0.1</code>).
* Use an <code>EXPIRY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add a test verifying that stale rows are eventually removed and fresh rows are preserved.
* Document the rationale in the model with a brief inline comment.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover <code>client-select</code>: happy path, missing params (400), unknown provider (404), discovery failure (502).
* Cover <code>callback</code> happy path: valid code and state exchanged for a session JWT, row consumed after use.
* Cover <code>callback</code> generic 401 "Authentication failed" for: invalid or expired state, replayed state, no matching user, username/email mismatch, token verification failure (bad signature, issuer, audience, or nonce), unverified email, unknown provider on consumed row.
* Cover <code>callback</code> missing params (400) and discovery failure (502).
* Add model specs for <code>OidcRequest</code> covering: atomic state consumption, replay prevention, expiry window, case-insensitive user matching, <code>email_verified</code> claim handling, and PKCE code verifier sent to the token endpoint.
* Add model specs for <code>OidcConfig</code> covering: config loading, ERB interpolation, missing key detection, scope normalization, <code>public_list</code> secrets exclusion, and unknown provider lookup.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Add component tests for <code>OidcModal</code>:
** renders nothing on empty or failed providers response
** renders SSO button when providers are returned
** displays modal when SSO button is pressed
** displays providers in dropdown when providers are returned,
** requires username and provider to both be filled out before SSO can be pressed
** includes both provider id and username in the <code>POST /auth/client-select</code> payload,
** redirects the browser to the returned authorization URL on success
** does not redirect on failure.
* Add component tests for <code>OidcCallback</code>:
** posts code and state to <code>POST /auth/callback</code> on mount
** stores session JWT and dispatches auth state on success
** redirects to dashboard on success
** displays error alert and redirects to login on backend failure
** handles IdP <code>error</code> query parameter without calling the backend
** redirects to login when code or state are missing
** shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-23T22:20:03Z

Jweisz: /* Frontend */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza — multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present at boot via <code>config/initializers/oidc.rb</code>. For providers with <code>discovery: true</code>, the <code>.well-known/openid-configuration</code> document is fetched using the <code>openid_connect</code> gem to resolve the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Discovery results are not aggressively cached to allow for key rotation; on signature verification failure, keys are re-fetched and verification is retried once.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>auth_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Look up the matching <code>auth_requests</code> row by state, rejecting the request if no row is found or if the row is older than 5 minutes. Delete the row to prevent reuse. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. Extract the user's email from the ID token claims and look up a matching local user and compare against username entry to ensure unique match. If a match is found, issue a session JWT using the same <code>JsonWebToken.encode</code> method and payload structure as the existing <code>AuthenticationController#login</code> action. If no match is found, return a 404 error indicating no local account exists for that email.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|1000px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|1000px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, provider and clicks Continue with SSO, the form does a <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, it redirects the browser to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===
The implementation uses the '''Strategy pattern''' for provider configuration. Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are skipped at boot with a warning logged, and they do not appear in <code>public_list</code>. Discovery is always used — non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Backend (Rails) ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation, scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>, enqueued probabilistically on request creation
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table
db/migrate/*_add_username_to_oidc_requests.rb — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

spec/models/oidc_request_spec.rb — Model tests covering:

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests (and preserves the row)
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''after_create probabilistic cleanup'''
* Enqueues CleanupStaleOidcRequestsJob when <code>rand</code> falls under the threshold
* Does not enqueue when <code>rand</code> falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email
* Passes when email_verified claim is true
* Passes when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither matches

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

spec/models/oidc_config_spec.rb — Config loading, ERB env var interpolation, memoization and reload, missing key detection with warning log, YAML edge cases (empty file, null providers key, aliases), <code>public_list</code> secrets exclusion, <code>find</code> lookup and ProviderNotFound, scope normalization (whitespace and comma-delimited, default fallback)

spec/requests/oidc_login_spec.rb — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback'''
* Happy path: exchanges valid code and state for a session JWT
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails
* Returns generic 401 "Authentication failed" for:
** No user matching the username and email
** Email matches but username does not
** Invalid or expired state
** Token verification failure
** Stored provider no longer exists in config

spec/models/user_spec.rb — Tests for <code>User#generate_jwt</code> covering payload structure

=== Frontend (React) ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.test.tsx — SSO modal display and provider dropdown component tests
src/pages/OidcCallback/OidcCallback.test.tsx — Callback page tests

'''OidcModal Component'''
* Renders SSO button when providers are configured, renders nothing when the providers response is empty or fails
* Displays the modal form with username input and provider dropdown when providers are returned
* Posts the provider id and username to <code>/auth/client-select</code> on selection and redirects the browser to the returned authorization URL

'''OidcCallback Component'''
* Posts code and state to <code>/auth/callback</code> on mount, stores the session JWT, dispatches auth state, and redirects to the dashboard on success
* Displays an error and redirects to login on backend failure, on IdP <code>error</code> query param (without calling the backend), and on missing code or state

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

[https://github.com/users/johnmweisz/projects/8 frontend board]

[https://github.com/users/johnmweisz/projects/9 backend board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* Skip providers with missing keys and log a warning rather than crashing the app.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, <code>username</code>, and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>recent</code> scope for expiry filtering and a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Probabilistically clean up stale rows inside <code>authorization_uri_for!</code> (10% chance per call) to keep the table bounded without requiring a scheduled job.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and cleanup.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if an <code>email_verified</code> claim is present and false.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — Provider Dropdown with Username Input on Login Page ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display SSO Button when providers are configured properly
* On SSO Button press, renders the modal with a username text input and a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* Hide the dropdown until the username input is non-empty.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, username-gated dropdown visibility, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' the session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default expiry, custom expiry, and signature verification (tampered tokens rejected).
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a background job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* In <code>OidcRequest.authorization_uri_for!</code>, run a DELETE for rows older than the expiry window with a 10% probability per call (<code>if rand < 0.1</code>).
* Use an <code>EXPIRY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add a test verifying that stale rows are eventually removed and fresh rows are preserved.
* Document the rationale in the model with a brief inline comment.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover <code>client-select</code>: happy path, missing params (400), unknown provider (404), discovery failure (502).
* Cover <code>callback</code> happy path: valid code and state exchanged for a session JWT, row consumed after use.
* Cover <code>callback</code> generic 401 "Authentication failed" for: invalid or expired state, replayed state, no matching user, username/email mismatch, token verification failure (bad signature, issuer, audience, or nonce), unverified email, unknown provider on consumed row.
* Cover <code>callback</code> missing params (400) and discovery failure (502).
* Add model specs for <code>OidcRequest</code> covering: atomic state consumption, replay prevention, expiry window, case-insensitive user matching, <code>email_verified</code> claim handling, and PKCE code verifier sent to the token endpoint.
* Add model specs for <code>OidcConfig</code> covering: config loading, ERB interpolation, missing key detection, scope normalization, <code>public_list</code> secrets exclusion, and unknown provider lookup.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Add component tests for <code>OidcModal</code>:
** renders nothing on empty or failed providers response
** renders SSO button when providers are returned
** displays modal when SSO button is pressed
** displays providers in dropdown when providers are returned,
** requires username and provider to both be filled out before SSO can be pressed
** includes both provider id and username in the <code>POST /auth/client-select</code> payload,
** redirects the browser to the returned authorization URL on success
** does not redirect on failure.
* Add component tests for <code>OidcCallback</code>:
** posts code and state to <code>POST /auth/callback</code> on mount
** stores session JWT and dispatches auth state on success
** redirects to dashboard on success
** displays error alert and redirects to login on backend failure
** handles IdP <code>error</code> query parameter without calling the backend
** redirects to login when code or state are missing
** shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-23T22:19:40Z

Jweisz: /* Backend */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza — multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present at boot via <code>config/initializers/oidc.rb</code>. For providers with <code>discovery: true</code>, the <code>.well-known/openid-configuration</code> document is fetched using the <code>openid_connect</code> gem to resolve the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Discovery results are not aggressively cached to allow for key rotation; on signature verification failure, keys are re-fetched and verification is retried once.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id and username. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>auth_requests</code> table containing the state, nonce, code verifier, provider id, username, and creation timestamp. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint that accepts the authorization code and state. Look up the matching <code>auth_requests</code> row by state, rejecting the request if no row is found or if the row is older than 5 minutes. Delete the row to prevent reuse. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. Extract the user's email from the ID token claims and look up a matching local user and compare against username entry to ensure unique match. If a match is found, issue a session JWT using the same <code>JsonWebToken.encode</code> method and payload structure as the existing <code>AuthenticationController#login</code> action. If no match is found, return a 404 error indicating no local account exists for that email.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|500px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|500px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, provider and clicks Continue with SSO, the form does a <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, it redirects the browser to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===
The implementation uses the '''Strategy pattern''' for provider configuration. Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are skipped at boot with a warning logged, and they do not appear in <code>public_list</code>. Discovery is always used — non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Backend (Rails) ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation, scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>, enqueued probabilistically on request creation
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table
db/migrate/*_add_username_to_oidc_requests.rb — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

spec/models/oidc_request_spec.rb — Model tests covering:

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests (and preserves the row)
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''after_create probabilistic cleanup'''
* Enqueues CleanupStaleOidcRequestsJob when <code>rand</code> falls under the threshold
* Does not enqueue when <code>rand</code> falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email
* Passes when email_verified claim is true
* Passes when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither matches

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

spec/models/oidc_config_spec.rb — Config loading, ERB env var interpolation, memoization and reload, missing key detection with warning log, YAML edge cases (empty file, null providers key, aliases), <code>public_list</code> secrets exclusion, <code>find</code> lookup and ProviderNotFound, scope normalization (whitespace and comma-delimited, default fallback)

spec/requests/oidc_login_spec.rb — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback'''
* Happy path: exchanges valid code and state for a session JWT
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails
* Returns generic 401 "Authentication failed" for:
** No user matching the username and email
** Email matches but username does not
** Invalid or expired state
** Token verification failure
** Stored provider no longer exists in config

spec/models/user_spec.rb — Tests for <code>User#generate_jwt</code> covering payload structure

=== Frontend (React) ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.test.tsx — SSO modal display and provider dropdown component tests
src/pages/OidcCallback/OidcCallback.test.tsx — Callback page tests

'''OidcModal Component'''
* Renders SSO button when providers are configured, renders nothing when the providers response is empty or fails
* Displays the modal form with username input and provider dropdown when providers are returned
* Posts the provider id and username to <code>/auth/client-select</code> on selection and redirects the browser to the returned authorization URL

'''OidcCallback Component'''
* Posts code and state to <code>/auth/callback</code> on mount, stores the session JWT, dispatches auth state, and redirects to the dashboard on success
* Displays an error and redirects to login on backend failure, on IdP <code>error</code> query param (without calling the backend), and on missing code or state

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

[https://github.com/users/johnmweisz/projects/8 frontend board]

[https://github.com/users/johnmweisz/projects/9 backend board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* Skip providers with missing keys and log a warning rather than crashing the app.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, <code>username</code>, and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>recent</code> scope for expiry filtering and a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Probabilistically clean up stale rows inside <code>authorization_uri_for!</code> (10% chance per call) to keep the table bounded without requiring a scheduled job.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and cleanup.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if an <code>email_verified</code> claim is present and false.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — Provider Dropdown with Username Input on Login Page ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display SSO Button when providers are configured properly
* On SSO Button press, renders the modal with a username text input and a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* Hide the dropdown until the username input is non-empty.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, username-gated dropdown visibility, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' the session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default expiry, custom expiry, and signature verification (tampered tokens rejected).
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a background job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* In <code>OidcRequest.authorization_uri_for!</code>, run a DELETE for rows older than the expiry window with a 10% probability per call (<code>if rand < 0.1</code>).
* Use an <code>EXPIRY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add a test verifying that stale rows are eventually removed and fresh rows are preserved.
* Document the rationale in the model with a brief inline comment.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover <code>client-select</code>: happy path, missing params (400), unknown provider (404), discovery failure (502).
* Cover <code>callback</code> happy path: valid code and state exchanged for a session JWT, row consumed after use.
* Cover <code>callback</code> generic 401 "Authentication failed" for: invalid or expired state, replayed state, no matching user, username/email mismatch, token verification failure (bad signature, issuer, audience, or nonce), unverified email, unknown provider on consumed row.
* Cover <code>callback</code> missing params (400) and discovery failure (502).
* Add model specs for <code>OidcRequest</code> covering: atomic state consumption, replay prevention, expiry window, case-insensitive user matching, <code>email_verified</code> claim handling, and PKCE code verifier sent to the token endpoint.
* Add model specs for <code>OidcConfig</code> covering: config loading, ERB interpolation, missing key detection, scope normalization, <code>public_list</code> secrets exclusion, and unknown provider lookup.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Add component tests for <code>OidcModal</code>:
** renders nothing on empty or failed providers response
** renders SSO button when providers are returned
** displays modal when SSO button is pressed
** displays providers in dropdown when providers are returned,
** requires username and provider to both be filled out before SSO can be pressed
** includes both provider id and username in the <code>POST /auth/client-select</code> payload,
** redirects the browser to the returned authorization URL on success
** does not redirect on failure.
* Add component tests for <code>OidcCallback</code>:
** posts code and state to <code>POST /auth/callback</code> on mount
** stores session JWT and dispatches auth state on success
** redirects to dashboard on success
** displays error alert and redirects to login on backend failure
** handles IdP <code>error</code> query parameter without calling the backend
** redirects to login when code or state are missing
** shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-23T14:35:58Z

Jweisz: /* Feature Requirements */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Design Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza — multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present at boot via <code>config/initializers/oidc.rb</code>. For providers with <code>discovery: true</code>, the <code>.well-known/openid-configuration</code> document is fetched using the <code>openid_connect</code> gem to resolve the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Discovery results are not aggressively cached to allow for key rotation; on signature verification failure, keys are re-fetched and verification is retried once.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>auth_requests</code> table containing the state, nonce, code verifier, provider id, and creation timestamp. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint (and a temporary <code>GET</code> for direct IdP redirect during backend-only testing) that accepts the authorization code and state. Look up the matching <code>auth_requests</code> row by state, rejecting the request if no row is found or if the row is older than 5 minutes. Delete the row to prevent reuse. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. Extract the user's email from the ID token claims and look up a matching local user. If a match is found, issue a session JWT using the same <code>JsonWebToken.encode</code> method and payload structure as the existing <code>AuthenticationController#login</code> action. If no match is found, return a 404 error indicating no local account exists for that email.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|500px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|500px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, provider and clicks Continue with SSO, the form does a <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, it redirects the browser to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===
The implementation uses the '''Strategy pattern''' for provider configuration. Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are skipped at boot with a warning logged, and they do not appear in <code>public_list</code>. Discovery is always used — non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Backend (Rails) ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation, scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>, enqueued probabilistically on request creation
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table
db/migrate/*_add_username_to_oidc_requests.rb — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

spec/models/oidc_request_spec.rb — Model tests covering:

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests (and preserves the row)
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''after_create probabilistic cleanup'''
* Enqueues CleanupStaleOidcRequestsJob when <code>rand</code> falls under the threshold
* Does not enqueue when <code>rand</code> falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email
* Passes when email_verified claim is true
* Passes when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither matches

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

spec/models/oidc_config_spec.rb — Config loading, ERB env var interpolation, memoization and reload, missing key detection with warning log, YAML edge cases (empty file, null providers key, aliases), <code>public_list</code> secrets exclusion, <code>find</code> lookup and ProviderNotFound, scope normalization (whitespace and comma-delimited, default fallback)

spec/requests/oidc_login_spec.rb — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback'''
* Happy path: exchanges valid code and state for a session JWT
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails
* Returns generic 401 "Authentication failed" for:
** No user matching the username and email
** Email matches but username does not
** Invalid or expired state
** Token verification failure
** Stored provider no longer exists in config

spec/models/user_spec.rb — Tests for <code>User#generate_jwt</code> covering payload structure

=== Frontend (React) ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.test.tsx — SSO modal display and provider dropdown component tests
src/pages/OidcCallback/OidcCallback.test.tsx — Callback page tests

'''OidcModal Component'''
* Renders SSO button when providers are configured, renders nothing when the providers response is empty or fails
* Displays the modal form with username input and provider dropdown when providers are returned
* Posts the provider id and username to <code>/auth/client-select</code> on selection and redirects the browser to the returned authorization URL

'''OidcCallback Component'''
* Posts code and state to <code>/auth/callback</code> on mount, stores the session JWT, dispatches auth state, and redirects to the dashboard on success
* Displays an error and redirects to login on backend failure, on IdP <code>error</code> query param (without calling the backend), and on missing code or state

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

[https://github.com/users/johnmweisz/projects/8 frontend board]

[https://github.com/users/johnmweisz/projects/9 backend board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* Skip providers with missing keys and log a warning rather than crashing the app.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, <code>username</code>, and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>recent</code> scope for expiry filtering and a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Probabilistically clean up stale rows inside <code>authorization_uri_for!</code> (10% chance per call) to keep the table bounded without requiring a scheduled job.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and cleanup.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if an <code>email_verified</code> claim is present and false.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — Provider Dropdown with Username Input on Login Page ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display SSO Button when providers are configured properly
* On SSO Button press, renders the modal with a username text input and a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* Hide the dropdown until the username input is non-empty.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, username-gated dropdown visibility, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' the session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default expiry, custom expiry, and signature verification (tampered tokens rejected).
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a background job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* In <code>OidcRequest.authorization_uri_for!</code>, run a DELETE for rows older than the expiry window with a 10% probability per call (<code>if rand < 0.1</code>).
* Use an <code>EXPIRY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add a test verifying that stale rows are eventually removed and fresh rows are preserved.
* Document the rationale in the model with a brief inline comment.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover <code>client-select</code>: happy path, missing params (400), unknown provider (404), discovery failure (502).
* Cover <code>callback</code> happy path: valid code and state exchanged for a session JWT, row consumed after use.
* Cover <code>callback</code> generic 401 "Authentication failed" for: invalid or expired state, replayed state, no matching user, username/email mismatch, token verification failure (bad signature, issuer, audience, or nonce), unverified email, unknown provider on consumed row.
* Cover <code>callback</code> missing params (400) and discovery failure (502).
* Add model specs for <code>OidcRequest</code> covering: atomic state consumption, replay prevention, expiry window, case-insensitive user matching, <code>email_verified</code> claim handling, and PKCE code verifier sent to the token endpoint.
* Add model specs for <code>OidcConfig</code> covering: config loading, ERB interpolation, missing key detection, scope normalization, <code>public_list</code> secrets exclusion, and unknown provider lookup.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Add component tests for <code>OidcModal</code>:
** renders nothing on empty or failed providers response
** renders SSO button when providers are returned
** displays modal when SSO button is pressed
** displays providers in dropdown when providers are returned,
** requires username and provider to both be filled out before SSO can be pressed
** includes both provider id and username in the <code>POST /auth/client-select</code> payload,
** redirects the browser to the returned authorization URL on success
** does not redirect on failure.
* Add component tests for <code>OidcCallback</code>:
** posts code and state to <code>POST /auth/callback</code> on mount
** stores session JWT and dispatches auth state on success
** redirects to dashboard on success
** displays error alert and redirects to login on backend failure
** handles IdP <code>error</code> query parameter without calling the backend
** redirects to login when code or state are missing
** shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-23T14:34:32Z

Jweisz: /* Demo */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Feature Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza — multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present at boot via <code>config/initializers/oidc.rb</code>. For providers with <code>discovery: true</code>, the <code>.well-known/openid-configuration</code> document is fetched using the <code>openid_connect</code> gem to resolve the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Discovery results are not aggressively cached to allow for key rotation; on signature verification failure, keys are re-fetched and verification is retried once.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>auth_requests</code> table containing the state, nonce, code verifier, provider id, and creation timestamp. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint (and a temporary <code>GET</code> for direct IdP redirect during backend-only testing) that accepts the authorization code and state. Look up the matching <code>auth_requests</code> row by state, rejecting the request if no row is found or if the row is older than 5 minutes. Delete the row to prevent reuse. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. Extract the user's email from the ID token claims and look up a matching local user. If a match is found, issue a session JWT using the same <code>JsonWebToken.encode</code> method and payload structure as the existing <code>AuthenticationController#login</code> action. If no match is found, return a 404 error indicating no local account exists for that email.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|500px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|500px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, provider and clicks Continue with SSO, the form does a <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, it redirects the browser to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===
The implementation uses the '''Strategy pattern''' for provider configuration. Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are skipped at boot with a warning logged, and they do not appear in <code>public_list</code>. Discovery is always used — non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Backend (Rails) ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation, scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>, enqueued probabilistically on request creation
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table
db/migrate/*_add_username_to_oidc_requests.rb — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

spec/models/oidc_request_spec.rb — Model tests covering:

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests (and preserves the row)
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''after_create probabilistic cleanup'''
* Enqueues CleanupStaleOidcRequestsJob when <code>rand</code> falls under the threshold
* Does not enqueue when <code>rand</code> falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email
* Passes when email_verified claim is true
* Passes when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither matches

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

spec/models/oidc_config_spec.rb — Config loading, ERB env var interpolation, memoization and reload, missing key detection with warning log, YAML edge cases (empty file, null providers key, aliases), <code>public_list</code> secrets exclusion, <code>find</code> lookup and ProviderNotFound, scope normalization (whitespace and comma-delimited, default fallback)

spec/requests/oidc_login_spec.rb — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback'''
* Happy path: exchanges valid code and state for a session JWT
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails
* Returns generic 401 "Authentication failed" for:
** No user matching the username and email
** Email matches but username does not
** Invalid or expired state
** Token verification failure
** Stored provider no longer exists in config

spec/models/user_spec.rb — Tests for <code>User#generate_jwt</code> covering payload structure

=== Frontend (React) ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.test.tsx — SSO modal display and provider dropdown component tests
src/pages/OidcCallback/OidcCallback.test.tsx — Callback page tests

'''OidcModal Component'''
* Renders SSO button when providers are configured, renders nothing when the providers response is empty or fails
* Displays the modal form with username input and provider dropdown when providers are returned
* Posts the provider id and username to <code>/auth/client-select</code> on selection and redirects the browser to the returned authorization URL

'''OidcCallback Component'''
* Posts code and state to <code>/auth/callback</code> on mount, stores the session JWT, dispatches auth state, and redirects to the dashboard on success
* Displays an error and redirects to login on backend failure, on IdP <code>error</code> query param (without calling the backend), and on missing code or state

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

[https://github.com/users/johnmweisz/projects/8 frontend board]

[https://github.com/users/johnmweisz/projects/9 backend board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* Skip providers with missing keys and log a warning rather than crashing the app.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, <code>username</code>, and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>recent</code> scope for expiry filtering and a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Probabilistically clean up stale rows inside <code>authorization_uri_for!</code> (10% chance per call) to keep the table bounded without requiring a scheduled job.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and cleanup.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if an <code>email_verified</code> claim is present and false.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — Provider Dropdown with Username Input on Login Page ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display SSO Button when providers are configured properly
* On SSO Button press, renders the modal with a username text input and a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* Hide the dropdown until the username input is non-empty.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, username-gated dropdown visibility, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' the session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default expiry, custom expiry, and signature verification (tampered tokens rejected).
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a background job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* In <code>OidcRequest.authorization_uri_for!</code>, run a DELETE for rows older than the expiry window with a 10% probability per call (<code>if rand < 0.1</code>).
* Use an <code>EXPIRY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add a test verifying that stale rows are eventually removed and fresh rows are preserved.
* Document the rationale in the model with a brief inline comment.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover <code>client-select</code>: happy path, missing params (400), unknown provider (404), discovery failure (502).
* Cover <code>callback</code> happy path: valid code and state exchanged for a session JWT, row consumed after use.
* Cover <code>callback</code> generic 401 "Authentication failed" for: invalid or expired state, replayed state, no matching user, username/email mismatch, token verification failure (bad signature, issuer, audience, or nonce), unverified email, unknown provider on consumed row.
* Cover <code>callback</code> missing params (400) and discovery failure (502).
* Add model specs for <code>OidcRequest</code> covering: atomic state consumption, replay prevention, expiry window, case-insensitive user matching, <code>email_verified</code> claim handling, and PKCE code verifier sent to the token endpoint.
* Add model specs for <code>OidcConfig</code> covering: config loading, ERB interpolation, missing key detection, scope normalization, <code>public_list</code> secrets exclusion, and unknown provider lookup.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Add component tests for <code>OidcModal</code>:
** renders nothing on empty or failed providers response
** renders SSO button when providers are returned
** displays modal when SSO button is pressed
** displays providers in dropdown when providers are returned,
** requires username and provider to both be filled out before SSO can be pressed
** includes both provider id and username in the <code>POST /auth/client-select</code> payload,
** redirects the browser to the returned authorization URL on success
** does not redirect on failure.
* Add component tests for <code>OidcCallback</code>:
** posts code and state to <code>POST /auth/callback</code> on mount
** stores session JWT and dispatches auth state on success
** redirects to dashboard on success
** displays error alert and redirects to login on backend failure
** handles IdP <code>error</code> query parameter without calling the backend
** redirects to login when code or state are missing
** shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-23T14:34:21Z

Jweisz: /* Setup */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Feature Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza — multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present at boot via <code>config/initializers/oidc.rb</code>. For providers with <code>discovery: true</code>, the <code>.well-known/openid-configuration</code> document is fetched using the <code>openid_connect</code> gem to resolve the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Discovery results are not aggressively cached to allow for key rotation; on signature verification failure, keys are re-fetched and verification is retried once.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>auth_requests</code> table containing the state, nonce, code verifier, provider id, and creation timestamp. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint (and a temporary <code>GET</code> for direct IdP redirect during backend-only testing) that accepts the authorization code and state. Look up the matching <code>auth_requests</code> row by state, rejecting the request if no row is found or if the row is older than 5 minutes. Delete the row to prevent reuse. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. Extract the user's email from the ID token claims and look up a matching local user. If a match is found, issue a session JWT using the same <code>JsonWebToken.encode</code> method and payload structure as the existing <code>AuthenticationController#login</code> action. If no match is found, return a 404 error indicating no local account exists for that email.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|500px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|500px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, provider and clicks Continue with SSO, the form does a <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, it redirects the browser to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===
The implementation uses the '''Strategy pattern''' for provider configuration. Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are skipped at boot with a warning logged, and they do not appear in <code>public_list</code>. Discovery is always used — non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Backend (Rails) ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation, scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>, enqueued probabilistically on request creation
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table
db/migrate/*_add_username_to_oidc_requests.rb — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

spec/models/oidc_request_spec.rb — Model tests covering:

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests (and preserves the row)
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''after_create probabilistic cleanup'''
* Enqueues CleanupStaleOidcRequestsJob when <code>rand</code> falls under the threshold
* Does not enqueue when <code>rand</code> falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email
* Passes when email_verified claim is true
* Passes when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither matches

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

spec/models/oidc_config_spec.rb — Config loading, ERB env var interpolation, memoization and reload, missing key detection with warning log, YAML edge cases (empty file, null providers key, aliases), <code>public_list</code> secrets exclusion, <code>find</code> lookup and ProviderNotFound, scope normalization (whitespace and comma-delimited, default fallback)

spec/requests/oidc_login_spec.rb — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback'''
* Happy path: exchanges valid code and state for a session JWT
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails
* Returns generic 401 "Authentication failed" for:
** No user matching the username and email
** Email matches but username does not
** Invalid or expired state
** Token verification failure
** Stored provider no longer exists in config

spec/models/user_spec.rb — Tests for <code>User#generate_jwt</code> covering payload structure

=== Frontend (React) ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.test.tsx — SSO modal display and provider dropdown component tests
src/pages/OidcCallback/OidcCallback.test.tsx — Callback page tests

'''OidcModal Component'''
* Renders SSO button when providers are configured, renders nothing when the providers response is empty or fails
* Displays the modal form with username input and provider dropdown when providers are returned
* Posts the provider id and username to <code>/auth/client-select</code> on selection and redirects the browser to the returned authorization URL

'''OidcCallback Component'''
* Posts code and state to <code>/auth/callback</code> on mount, stores the session JWT, dispatches auth state, and redirects to the dashboard on success
* Displays an error and redirects to login on backend failure, on IdP <code>error</code> query param (without calling the backend), and on missing code or state

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

[https://github.com/users/johnmweisz/projects/8 frontend board]

[https://github.com/users/johnmweisz/projects/9 backend board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* Skip providers with missing keys and log a warning rather than crashing the app.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, <code>username</code>, and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>recent</code> scope for expiry filtering and a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Probabilistically clean up stale rows inside <code>authorization_uri_for!</code> (10% chance per call) to keep the table bounded without requiring a scheduled job.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and cleanup.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if an <code>email_verified</code> claim is present and false.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — Provider Dropdown with Username Input on Login Page ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display SSO Button when providers are configured properly
* On SSO Button press, renders the modal with a username text input and a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* Hide the dropdown until the username input is non-empty.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, username-gated dropdown visibility, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' the session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default expiry, custom expiry, and signature verification (tampered tokens rejected).
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a background job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* In <code>OidcRequest.authorization_uri_for!</code>, run a DELETE for rows older than the expiry window with a 10% probability per call (<code>if rand < 0.1</code>).
* Use an <code>EXPIRY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add a test verifying that stale rows are eventually removed and fresh rows are preserved.
* Document the rationale in the model with a brief inline comment.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover <code>client-select</code>: happy path, missing params (400), unknown provider (404), discovery failure (502).
* Cover <code>callback</code> happy path: valid code and state exchanged for a session JWT, row consumed after use.
* Cover <code>callback</code> generic 401 "Authentication failed" for: invalid or expired state, replayed state, no matching user, username/email mismatch, token verification failure (bad signature, issuer, audience, or nonce), unverified email, unknown provider on consumed row.
* Cover <code>callback</code> missing params (400) and discovery failure (502).
* Add model specs for <code>OidcRequest</code> covering: atomic state consumption, replay prevention, expiry window, case-insensitive user matching, <code>email_verified</code> claim handling, and PKCE code verifier sent to the token endpoint.
* Add model specs for <code>OidcConfig</code> covering: config loading, ERB interpolation, missing key detection, scope normalization, <code>public_list</code> secrets exclusion, and unknown provider lookup.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Add component tests for <code>OidcModal</code>:
** renders nothing on empty or failed providers response
** renders SSO button when providers are returned
** displays modal when SSO button is pressed
** displays providers in dropdown when providers are returned,
** requires username and provider to both be filled out before SSO can be pressed
** includes both provider id and username in the <code>POST /auth/client-select</code> payload,
** redirects the browser to the returned authorization URL on success
** does not redirect on failure.
* Add component tests for <code>OidcCallback</code>:
** posts code and state to <code>POST /auth/callback</code> on mount
** stores session JWT and dispatches auth state on success
** redirects to dashboard on success
** displays error alert and redirects to login on backend failure
** handles IdP <code>error</code> query parameter without calling the backend
** redirects to login when code or state are missing
** shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== NCSU Google Provider Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-23T14:33:19Z

Jweisz:

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Feature Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza — multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present at boot via <code>config/initializers/oidc.rb</code>. For providers with <code>discovery: true</code>, the <code>.well-known/openid-configuration</code> document is fetched using the <code>openid_connect</code> gem to resolve the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Discovery results are not aggressively cached to allow for key rotation; on signature verification failure, keys are re-fetched and verification is retried once.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>auth_requests</code> table containing the state, nonce, code verifier, provider id, and creation timestamp. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint (and a temporary <code>GET</code> for direct IdP redirect during backend-only testing) that accepts the authorization code and state. Look up the matching <code>auth_requests</code> row by state, rejecting the request if no row is found or if the row is older than 5 minutes. Delete the row to prevent reuse. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. Extract the user's email from the ID token claims and look up a matching local user. If a match is found, issue a session JWT using the same <code>JsonWebToken.encode</code> method and payload structure as the existing <code>AuthenticationController#login</code> action. If no match is found, return a 404 error indicating no local account exists for that email.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|500px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|500px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, provider and clicks Continue with SSO, the form does a <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, it redirects the browser to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===
The implementation uses the '''Strategy pattern''' for provider configuration. Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are skipped at boot with a warning logged, and they do not appear in <code>public_list</code>. Discovery is always used — non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Backend (Rails) ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation, scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>, enqueued probabilistically on request creation
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table
db/migrate/*_add_username_to_oidc_requests.rb — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

spec/models/oidc_request_spec.rb — Model tests covering:

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests (and preserves the row)
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''after_create probabilistic cleanup'''
* Enqueues CleanupStaleOidcRequestsJob when <code>rand</code> falls under the threshold
* Does not enqueue when <code>rand</code> falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email
* Passes when email_verified claim is true
* Passes when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither matches

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

spec/models/oidc_config_spec.rb — Config loading, ERB env var interpolation, memoization and reload, missing key detection with warning log, YAML edge cases (empty file, null providers key, aliases), <code>public_list</code> secrets exclusion, <code>find</code> lookup and ProviderNotFound, scope normalization (whitespace and comma-delimited, default fallback)

spec/requests/oidc_login_spec.rb — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback'''
* Happy path: exchanges valid code and state for a session JWT
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails
* Returns generic 401 "Authentication failed" for:
** No user matching the username and email
** Email matches but username does not
** Invalid or expired state
** Token verification failure
** Stored provider no longer exists in config

spec/models/user_spec.rb — Tests for <code>User#generate_jwt</code> covering payload structure

=== Frontend (React) ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.test.tsx — SSO modal display and provider dropdown component tests
src/pages/OidcCallback/OidcCallback.test.tsx — Callback page tests

'''OidcModal Component'''
* Renders SSO button when providers are configured, renders nothing when the providers response is empty or fails
* Displays the modal form with username input and provider dropdown when providers are returned
* Posts the provider id and username to <code>/auth/client-select</code> on selection and redirects the browser to the returned authorization URL

'''OidcCallback Component'''
* Posts code and state to <code>/auth/callback</code> on mount, stores the session JWT, dispatches auth state, and redirects to the dashboard on success
* Displays an error and redirects to login on backend failure, on IdP <code>error</code> query param (without calling the backend), and on missing code or state

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

[https://github.com/users/johnmweisz/projects/8 frontend board]

[https://github.com/users/johnmweisz/projects/9 backend board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* Skip providers with missing keys and log a warning rather than crashing the app.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, <code>username</code>, and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>recent</code> scope for expiry filtering and a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Probabilistically clean up stale rows inside <code>authorization_uri_for!</code> (10% chance per call) to keep the table bounded without requiring a scheduled job.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and cleanup.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if an <code>email_verified</code> claim is present and false.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — Provider Dropdown with Username Input on Login Page ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display SSO Button when providers are configured properly
* On SSO Button press, renders the modal with a username text input and a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* Hide the dropdown until the username input is non-empty.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, username-gated dropdown visibility, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' the session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default expiry, custom expiry, and signature verification (tampered tokens rejected).
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a background job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* In <code>OidcRequest.authorization_uri_for!</code>, run a DELETE for rows older than the expiry window with a 10% probability per call (<code>if rand < 0.1</code>).
* Use an <code>EXPIRY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add a test verifying that stale rows are eventually removed and fresh rows are preserved.
* Document the rationale in the model with a brief inline comment.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover <code>client-select</code>: happy path, missing params (400), unknown provider (404), discovery failure (502).
* Cover <code>callback</code> happy path: valid code and state exchanged for a session JWT, row consumed after use.
* Cover <code>callback</code> generic 401 "Authentication failed" for: invalid or expired state, replayed state, no matching user, username/email mismatch, token verification failure (bad signature, issuer, audience, or nonce), unverified email, unknown provider on consumed row.
* Cover <code>callback</code> missing params (400) and discovery failure (502).
* Add model specs for <code>OidcRequest</code> covering: atomic state consumption, replay prevention, expiry window, case-insensitive user matching, <code>email_verified</code> claim handling, and PKCE code verifier sent to the token endpoint.
* Add model specs for <code>OidcConfig</code> covering: config loading, ERB interpolation, missing key detection, scope normalization, <code>public_list</code> secrets exclusion, and unknown provider lookup.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Add component tests for <code>OidcModal</code>:
** renders nothing on empty or failed providers response
** renders SSO button when providers are returned
** displays modal when SSO button is pressed
** displays providers in dropdown when providers are returned,
** requires username and provider to both be filled out before SSO can be pressed
** includes both provider id and username in the <code>POST /auth/client-select</code> payload,
** redirects the browser to the returned authorization URL on success
** does not redirect on failure.
* Add component tests for <code>OidcCallback</code>:
** posts code and state to <code>POST /auth/callback</code> on mount
** stores session JWT and dispatches auth state on success
** redirects to dashboard on success
** displays error alert and redirects to login on backend failure
** handles IdP <code>error</code> query parameter without calling the backend
** redirects to login when code or state are missing
** shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

== Demo ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-23T14:32:06Z

Jweisz:

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Feature Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza — multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present at boot via <code>config/initializers/oidc.rb</code>. For providers with <code>discovery: true</code>, the <code>.well-known/openid-configuration</code> document is fetched using the <code>openid_connect</code> gem to resolve the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Discovery results are not aggressively cached to allow for key rotation; on signature verification failure, keys are re-fetched and verification is retried once.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>auth_requests</code> table containing the state, nonce, code verifier, provider id, and creation timestamp. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint (and a temporary <code>GET</code> for direct IdP redirect during backend-only testing) that accepts the authorization code and state. Look up the matching <code>auth_requests</code> row by state, rejecting the request if no row is found or if the row is older than 5 minutes. Delete the row to prevent reuse. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. Extract the user's email from the ID token claims and look up a matching local user. If a match is found, issue a session JWT using the same <code>JsonWebToken.encode</code> method and payload structure as the existing <code>AuthenticationController#login</code> action. If no match is found, return a 404 error indicating no local account exists for that email.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|500px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|500px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, provider and clicks Continue with SSO, the form does a <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, it redirects the browser to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===
The implementation uses the '''Strategy pattern''' for provider configuration. Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are skipped at boot with a warning logged, and they do not appear in <code>public_list</code>. Discovery is always used — non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Backend (Rails) ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation, scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>, enqueued probabilistically on request creation
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table
db/migrate/*_add_username_to_oidc_requests.rb — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

spec/models/oidc_request_spec.rb — Model tests covering:

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests (and preserves the row)
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''after_create probabilistic cleanup'''
* Enqueues CleanupStaleOidcRequestsJob when <code>rand</code> falls under the threshold
* Does not enqueue when <code>rand</code> falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email
* Passes when email_verified claim is true
* Passes when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither matches

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

spec/models/oidc_config_spec.rb — Config loading, ERB env var interpolation, memoization and reload, missing key detection with warning log, YAML edge cases (empty file, null providers key, aliases), <code>public_list</code> secrets exclusion, <code>find</code> lookup and ProviderNotFound, scope normalization (whitespace and comma-delimited, default fallback)

spec/requests/oidc_login_spec.rb — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback'''
* Happy path: exchanges valid code and state for a session JWT
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails
* Returns generic 401 "Authentication failed" for:
** No user matching the username and email
** Email matches but username does not
** Invalid or expired state
** Token verification failure
** Stored provider no longer exists in config

spec/models/user_spec.rb — Tests for <code>User#generate_jwt</code> covering payload structure

=== Frontend (React) ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.test.tsx — SSO modal display and provider dropdown component tests
src/pages/OidcCallback/OidcCallback.test.tsx — Callback page tests

'''OidcModal Component'''
* Renders SSO button when providers are configured, renders nothing when the providers response is empty or fails
* Displays the modal form with username input and provider dropdown when providers are returned
* Posts the provider id and username to <code>/auth/client-select</code> on selection and redirects the browser to the returned authorization URL

'''OidcCallback Component'''
* Posts code and state to <code>/auth/callback</code> on mount, stores the session JWT, dispatches auth state, and redirects to the dashboard on success
* Displays an error and redirects to login on backend failure, on IdP <code>error</code> query param (without calling the backend), and on missing code or state

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

[https://github.com/users/johnmweisz/projects/8 frontend board]

[https://github.com/users/johnmweisz/projects/9 backend board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* Skip providers with missing keys and log a warning rather than crashing the app.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, <code>username</code>, and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>recent</code> scope for expiry filtering and a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Probabilistically clean up stale rows inside <code>authorization_uri_for!</code> (10% chance per call) to keep the table bounded without requiring a scheduled job.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and cleanup.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if an <code>email_verified</code> claim is present and false.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — Provider Dropdown with Username Input on Login Page ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display SSO Button when providers are configured properly
* On SSO Button press, renders the modal with a username text input and a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* Hide the dropdown until the username input is non-empty.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, username-gated dropdown visibility, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' the session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default expiry, custom expiry, and signature verification (tampered tokens rejected).
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a background job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* In <code>OidcRequest.authorization_uri_for!</code>, run a DELETE for rows older than the expiry window with a 10% probability per call (<code>if rand < 0.1</code>).
* Use an <code>EXPIRY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add a test verifying that stale rows are eventually removed and fresh rows are preserved.
* Document the rationale in the model with a brief inline comment.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover <code>client-select</code>: happy path, missing params (400), unknown provider (404), discovery failure (502).
* Cover <code>callback</code> happy path: valid code and state exchanged for a session JWT, row consumed after use.
* Cover <code>callback</code> generic 401 "Authentication failed" for: invalid or expired state, replayed state, no matching user, username/email mismatch, token verification failure (bad signature, issuer, audience, or nonce), unverified email, unknown provider on consumed row.
* Cover <code>callback</code> missing params (400) and discovery failure (502).
* Add model specs for <code>OidcRequest</code> covering: atomic state consumption, replay prevention, expiry window, case-insensitive user matching, <code>email_verified</code> claim handling, and PKCE code verifier sent to the token endpoint.
* Add model specs for <code>OidcConfig</code> covering: config loading, ERB interpolation, missing key detection, scope normalization, <code>public_list</code> secrets exclusion, and unknown provider lookup.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Add component tests for <code>OidcModal</code>:
** renders nothing on empty or failed providers response
** renders SSO button when providers are returned
** displays modal when SSO button is pressed
** displays providers in dropdown when providers are returned,
** requires username and provider to both be filled out before SSO can be pressed
** includes both provider id and username in the <code>POST /auth/client-select</code> payload,
** redirects the browser to the returned authorization URL on success
** does not redirect on failure.
* Add component tests for <code>OidcCallback</code>:
** posts code and state to <code>POST /auth/callback</code> on mount
** stores session JWT and dispatches auth state on success
** redirects to dashboard on success
** displays error alert and redirects to login on backend failure
** handles IdP <code>error</code> query parameter without calling the backend
** redirects to login when code or state are missing
** shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== Demo ==

[https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

<gallery>
Image:LoginPageWithSSOButton.png | Login Page with SSO Button
Image:SSOLoginModal.png | SSO Login Modal
</gallery>
todo add screenshots of oidc login at each step

== Setup ==

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-23T14:31:42Z

Jweisz: /* Configuration */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Feature Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza — multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present at boot via <code>config/initializers/oidc.rb</code>. For providers with <code>discovery: true</code>, the <code>.well-known/openid-configuration</code> document is fetched using the <code>openid_connect</code> gem to resolve the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Discovery results are not aggressively cached to allow for key rotation; on signature verification failure, keys are re-fetched and verification is retried once.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>auth_requests</code> table containing the state, nonce, code verifier, provider id, and creation timestamp. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint (and a temporary <code>GET</code> for direct IdP redirect during backend-only testing) that accepts the authorization code and state. Look up the matching <code>auth_requests</code> row by state, rejecting the request if no row is found or if the row is older than 5 minutes. Delete the row to prevent reuse. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. Extract the user's email from the ID token claims and look up a matching local user. If a match is found, issue a session JWT using the same <code>JsonWebToken.encode</code> method and payload structure as the existing <code>AuthenticationController#login</code> action. If no match is found, return a 404 error indicating no local account exists for that email.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|500px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|500px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, provider and clicks Continue with SSO, the form does a <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, it redirects the browser to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===
The implementation uses the '''Strategy pattern''' for provider configuration. Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are skipped at boot with a warning logged, and they do not appear in <code>public_list</code>. Discovery is always used — non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Backend (Rails) ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation, scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>, enqueued probabilistically on request creation
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table
db/migrate/*_add_username_to_oidc_requests.rb — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

spec/models/oidc_request_spec.rb — Model tests covering:

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests (and preserves the row)
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''after_create probabilistic cleanup'''
* Enqueues CleanupStaleOidcRequestsJob when <code>rand</code> falls under the threshold
* Does not enqueue when <code>rand</code> falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email
* Passes when email_verified claim is true
* Passes when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither matches

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

spec/models/oidc_config_spec.rb — Config loading, ERB env var interpolation, memoization and reload, missing key detection with warning log, YAML edge cases (empty file, null providers key, aliases), <code>public_list</code> secrets exclusion, <code>find</code> lookup and ProviderNotFound, scope normalization (whitespace and comma-delimited, default fallback)

spec/requests/oidc_login_spec.rb — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback'''
* Happy path: exchanges valid code and state for a session JWT
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails
* Returns generic 401 "Authentication failed" for:
** No user matching the username and email
** Email matches but username does not
** Invalid or expired state
** Token verification failure
** Stored provider no longer exists in config

spec/models/user_spec.rb — Tests for <code>User#generate_jwt</code> covering payload structure

=== Frontend (React) ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.test.tsx — SSO modal display and provider dropdown component tests
src/pages/OidcCallback/OidcCallback.test.tsx — Callback page tests

'''OidcModal Component'''
* Renders SSO button when providers are configured, renders nothing when the providers response is empty or fails
* Displays the modal form with username input and provider dropdown when providers are returned
* Posts the provider id and username to <code>/auth/client-select</code> on selection and redirects the browser to the returned authorization URL

'''OidcCallback Component'''
* Posts code and state to <code>/auth/callback</code> on mount, stores the session JWT, dispatches auth state, and redirects to the dashboard on success
* Displays an error and redirects to login on backend failure, on IdP <code>error</code> query param (without calling the backend), and on missing code or state

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

[https://github.com/users/johnmweisz/projects/8 frontend board]

[https://github.com/users/johnmweisz/projects/9 backend board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* Skip providers with missing keys and log a warning rather than crashing the app.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, <code>username</code>, and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>recent</code> scope for expiry filtering and a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Probabilistically clean up stale rows inside <code>authorization_uri_for!</code> (10% chance per call) to keep the table bounded without requiring a scheduled job.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and cleanup.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if an <code>email_verified</code> claim is present and false.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — Provider Dropdown with Username Input on Login Page ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display SSO Button when providers are configured properly
* On SSO Button press, renders the modal with a username text input and a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* Hide the dropdown until the username input is non-empty.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, username-gated dropdown visibility, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' the session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default expiry, custom expiry, and signature verification (tampered tokens rejected).
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a background job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* In <code>OidcRequest.authorization_uri_for!</code>, run a DELETE for rows older than the expiry window with a 10% probability per call (<code>if rand < 0.1</code>).
* Use an <code>EXPIRY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add a test verifying that stale rows are eventually removed and fresh rows are preserved.
* Document the rationale in the model with a brief inline comment.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover <code>client-select</code>: happy path, missing params (400), unknown provider (404), discovery failure (502).
* Cover <code>callback</code> happy path: valid code and state exchanged for a session JWT, row consumed after use.
* Cover <code>callback</code> generic 401 "Authentication failed" for: invalid or expired state, replayed state, no matching user, username/email mismatch, token verification failure (bad signature, issuer, audience, or nonce), unverified email, unknown provider on consumed row.
* Cover <code>callback</code> missing params (400) and discovery failure (502).
* Add model specs for <code>OidcRequest</code> covering: atomic state consumption, replay prevention, expiry window, case-insensitive user matching, <code>email_verified</code> claim handling, and PKCE code verifier sent to the token endpoint.
* Add model specs for <code>OidcConfig</code> covering: config loading, ERB interpolation, missing key detection, scope normalization, <code>public_list</code> secrets exclusion, and unknown provider lookup.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Add component tests for <code>OidcModal</code>:
** renders nothing on empty or failed providers response
** renders SSO button when providers are returned
** displays modal when SSO button is pressed
** displays providers in dropdown when providers are returned,
** requires username and provider to both be filled out before SSO can be pressed
** includes both provider id and username in the <code>POST /auth/client-select</code> payload,
** redirects the browser to the returned authorization URL on success
** does not redirect on failure.
* Add component tests for <code>OidcCallback</code>:
** posts code and state to <code>POST /auth/callback</code> on mount
** stores session JWT and dispatches auth state on success
** redirects to dashboard on success
** displays error alert and redirects to login on backend failure
** handles IdP <code>error</code> query parameter without calling the backend
** redirects to login when code or state are missing
** shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== Demo ==

[https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

<gallery>
Image:LoginPageWithSSOButton.png | Login Page with SSO Button
Image:SSOLoginModal.png | SSO Login Modal
</gallery>
todo add screenshots of oidc login at each step

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-23T14:31:12Z

Jweisz: /* Requirements */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Feature Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza — multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present at boot via <code>config/initializers/oidc.rb</code>. For providers with <code>discovery: true</code>, the <code>.well-known/openid-configuration</code> document is fetched using the <code>openid_connect</code> gem to resolve the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Discovery results are not aggressively cached to allow for key rotation; on signature verification failure, keys are re-fetched and verification is retried once.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>auth_requests</code> table containing the state, nonce, code verifier, provider id, and creation timestamp. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint (and a temporary <code>GET</code> for direct IdP redirect during backend-only testing) that accepts the authorization code and state. Look up the matching <code>auth_requests</code> row by state, rejecting the request if no row is found or if the row is older than 5 minutes. Delete the row to prevent reuse. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. Extract the user's email from the ID token claims and look up a matching local user. If a match is found, issue a session JWT using the same <code>JsonWebToken.encode</code> method and payload structure as the existing <code>AuthenticationController#login</code> action. If no match is found, return a 404 error indicating no local account exists for that email.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|500px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|500px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, provider and clicks Continue with SSO, the form does a <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, it redirects the browser to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===
The implementation uses the '''Strategy pattern''' for provider configuration. Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are skipped at boot with a warning logged, and they do not appear in <code>public_list</code>. Discovery is always used — non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Backend (Rails) ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation, scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>, enqueued probabilistically on request creation
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table
db/migrate/*_add_username_to_oidc_requests.rb — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

spec/models/oidc_request_spec.rb — Model tests covering:

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests (and preserves the row)
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''after_create probabilistic cleanup'''
* Enqueues CleanupStaleOidcRequestsJob when <code>rand</code> falls under the threshold
* Does not enqueue when <code>rand</code> falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email
* Passes when email_verified claim is true
* Passes when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither matches

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

spec/models/oidc_config_spec.rb — Config loading, ERB env var interpolation, memoization and reload, missing key detection with warning log, YAML edge cases (empty file, null providers key, aliases), <code>public_list</code> secrets exclusion, <code>find</code> lookup and ProviderNotFound, scope normalization (whitespace and comma-delimited, default fallback)

spec/requests/oidc_login_spec.rb — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback'''
* Happy path: exchanges valid code and state for a session JWT
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails
* Returns generic 401 "Authentication failed" for:
** No user matching the username and email
** Email matches but username does not
** Invalid or expired state
** Token verification failure
** Stored provider no longer exists in config

spec/models/user_spec.rb — Tests for <code>User#generate_jwt</code> covering payload structure

=== Frontend (React) ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.test.tsx — SSO modal display and provider dropdown component tests
src/pages/OidcCallback/OidcCallback.test.tsx — Callback page tests

'''OidcModal Component'''
* Renders SSO button when providers are configured, renders nothing when the providers response is empty or fails
* Displays the modal form with username input and provider dropdown when providers are returned
* Posts the provider id and username to <code>/auth/client-select</code> on selection and redirects the browser to the returned authorization URL

'''OidcCallback Component'''
* Posts code and state to <code>/auth/callback</code> on mount, stores the session JWT, dispatches auth state, and redirects to the dashboard on success
* Displays an error and redirects to login on backend failure, on IdP <code>error</code> query param (without calling the backend), and on missing code or state

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

[https://github.com/users/johnmweisz/projects/8 frontend board]

[https://github.com/users/johnmweisz/projects/9 backend board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* Skip providers with missing keys and log a warning rather than crashing the app.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, <code>username</code>, and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>recent</code> scope for expiry filtering and a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Probabilistically clean up stale rows inside <code>authorization_uri_for!</code> (10% chance per call) to keep the table bounded without requiring a scheduled job.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and cleanup.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if an <code>email_verified</code> claim is present and false.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — Provider Dropdown with Username Input on Login Page ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display SSO Button when providers are configured properly
* On SSO Button press, renders the modal with a username text input and a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* Hide the dropdown until the username input is non-empty.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, username-gated dropdown visibility, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' the session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default expiry, custom expiry, and signature verification (tampered tokens rejected).
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a background job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* In <code>OidcRequest.authorization_uri_for!</code>, run a DELETE for rows older than the expiry window with a 10% probability per call (<code>if rand < 0.1</code>).
* Use an <code>EXPIRY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add a test verifying that stale rows are eventually removed and fresh rows are preserved.
* Document the rationale in the model with a brief inline comment.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover <code>client-select</code>: happy path, missing params (400), unknown provider (404), discovery failure (502).
* Cover <code>callback</code> happy path: valid code and state exchanged for a session JWT, row consumed after use.
* Cover <code>callback</code> generic 401 "Authentication failed" for: invalid or expired state, replayed state, no matching user, username/email mismatch, token verification failure (bad signature, issuer, audience, or nonce), unverified email, unknown provider on consumed row.
* Cover <code>callback</code> missing params (400) and discovery failure (502).
* Add model specs for <code>OidcRequest</code> covering: atomic state consumption, replay prevention, expiry window, case-insensitive user matching, <code>email_verified</code> claim handling, and PKCE code verifier sent to the token endpoint.
* Add model specs for <code>OidcConfig</code> covering: config loading, ERB interpolation, missing key detection, scope normalization, <code>public_list</code> secrets exclusion, and unknown provider lookup.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Add component tests for <code>OidcModal</code>:
** renders nothing on empty or failed providers response
** renders SSO button when providers are returned
** displays modal when SSO button is pressed
** displays providers in dropdown when providers are returned,
** requires username and provider to both be filled out before SSO can be pressed
** includes both provider id and username in the <code>POST /auth/client-select</code> payload,
** redirects the browser to the returned authorization URL on success
** does not redirect on failure.
* Add component tests for <code>OidcCallback</code>:
** posts code and state to <code>POST /auth/callback</code> on mount
** stores session JWT and dispatches auth state on success
** redirects to dashboard on success
** displays error alert and redirects to login on backend failure
** handles IdP <code>error</code> query parameter without calling the backend
** redirects to login when code or state are missing
** shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== Demo ==

[https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

<gallery>
Image:LoginPageWithSSOButton.png | Login Page with SSO Button
Image:SSOLoginModal.png | SSO Login Modal
</gallery>
todo add screenshots of oidc login at each step

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-22T17:52:48Z

Jweisz: /* Demo */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza — multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present at boot via <code>config/initializers/oidc.rb</code>. For providers with <code>discovery: true</code>, the <code>.well-known/openid-configuration</code> document is fetched using the <code>openid_connect</code> gem to resolve the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Discovery results are not aggressively cached to allow for key rotation; on signature verification failure, keys are re-fetched and verification is retried once.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>auth_requests</code> table containing the state, nonce, code verifier, provider id, and creation timestamp. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint (and a temporary <code>GET</code> for direct IdP redirect during backend-only testing) that accepts the authorization code and state. Look up the matching <code>auth_requests</code> row by state, rejecting the request if no row is found or if the row is older than 5 minutes. Delete the row to prevent reuse. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. Extract the user's email from the ID token claims and look up a matching local user. If a match is found, issue a session JWT using the same <code>JsonWebToken.encode</code> method and payload structure as the existing <code>AuthenticationController#login</code> action. If no match is found, return a 404 error indicating no local account exists for that email.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|500px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|500px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, provider and clicks Continue with SSO, the form does a <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, it redirects the browser to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===
The implementation uses the '''Strategy pattern''' for provider configuration. Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are skipped at boot with a warning logged, and they do not appear in <code>public_list</code>. Discovery is always used — non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Backend (Rails) ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation, scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>, enqueued probabilistically on request creation
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table
db/migrate/*_add_username_to_oidc_requests.rb — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

spec/models/oidc_request_spec.rb — Model tests covering:

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests (and preserves the row)
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''after_create probabilistic cleanup'''
* Enqueues CleanupStaleOidcRequestsJob when <code>rand</code> falls under the threshold
* Does not enqueue when <code>rand</code> falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email
* Passes when email_verified claim is true
* Passes when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither matches

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

spec/models/oidc_config_spec.rb — Config loading, ERB env var interpolation, memoization and reload, missing key detection with warning log, YAML edge cases (empty file, null providers key, aliases), <code>public_list</code> secrets exclusion, <code>find</code> lookup and ProviderNotFound, scope normalization (whitespace and comma-delimited, default fallback)

spec/requests/oidc_login_spec.rb — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback'''
* Happy path: exchanges valid code and state for a session JWT
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails
* Returns generic 401 "Authentication failed" for:
** No user matching the username and email
** Email matches but username does not
** Invalid or expired state
** Token verification failure
** Stored provider no longer exists in config

spec/models/user_spec.rb — Tests for <code>User#generate_jwt</code> covering payload structure

=== Frontend (React) ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.test.tsx — SSO modal display and provider dropdown component tests
src/pages/OidcCallback/OidcCallback.test.tsx — Callback page tests

'''OidcModal Component'''
* Renders SSO button when providers are configured, renders nothing when the providers response is empty or fails
* Displays the modal form with username input and provider dropdown when providers are returned
* Posts the provider id and username to <code>/auth/client-select</code> on selection and redirects the browser to the returned authorization URL

'''OidcCallback Component'''
* Posts code and state to <code>/auth/callback</code> on mount, stores the session JWT, dispatches auth state, and redirects to the dashboard on success
* Displays an error and redirects to login on backend failure, on IdP <code>error</code> query param (without calling the backend), and on missing code or state

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

[https://github.com/users/johnmweisz/projects/8 frontend board]

[https://github.com/users/johnmweisz/projects/9 backend board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* Skip providers with missing keys and log a warning rather than crashing the app.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, <code>username</code>, and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>recent</code> scope for expiry filtering and a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Probabilistically clean up stale rows inside <code>authorization_uri_for!</code> (10% chance per call) to keep the table bounded without requiring a scheduled job.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and cleanup.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if an <code>email_verified</code> claim is present and false.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — Provider Dropdown with Username Input on Login Page ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display SSO Button when providers are configured properly
* On SSO Button press, renders the modal with a username text input and a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* Hide the dropdown until the username input is non-empty.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, username-gated dropdown visibility, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' the session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default expiry, custom expiry, and signature verification (tampered tokens rejected).
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a background job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* In <code>OidcRequest.authorization_uri_for!</code>, run a DELETE for rows older than the expiry window with a 10% probability per call (<code>if rand < 0.1</code>).
* Use an <code>EXPIRY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add a test verifying that stale rows are eventually removed and fresh rows are preserved.
* Document the rationale in the model with a brief inline comment.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover <code>client-select</code>: happy path, missing params (400), unknown provider (404), discovery failure (502).
* Cover <code>callback</code> happy path: valid code and state exchanged for a session JWT, row consumed after use.
* Cover <code>callback</code> generic 401 "Authentication failed" for: invalid or expired state, replayed state, no matching user, username/email mismatch, token verification failure (bad signature, issuer, audience, or nonce), unverified email, unknown provider on consumed row.
* Cover <code>callback</code> missing params (400) and discovery failure (502).
* Add model specs for <code>OidcRequest</code> covering: atomic state consumption, replay prevention, expiry window, case-insensitive user matching, <code>email_verified</code> claim handling, and PKCE code verifier sent to the token endpoint.
* Add model specs for <code>OidcConfig</code> covering: config loading, ERB interpolation, missing key detection, scope normalization, <code>public_list</code> secrets exclusion, and unknown provider lookup.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Add component tests for <code>OidcModal</code>:
** renders nothing on empty or failed providers response
** renders SSO button when providers are returned
** displays modal when SSO button is pressed
** displays providers in dropdown when providers are returned,
** requires username and provider to both be filled out before SSO can be pressed
** includes both provider id and username in the <code>POST /auth/client-select</code> payload,
** redirects the browser to the returned authorization URL on success
** does not redirect on failure.
* Add component tests for <code>OidcCallback</code>:
** posts code and state to <code>POST /auth/callback</code> on mount
** stores session JWT and dispatches auth state on success
** redirects to dashboard on success
** displays error alert and redirects to login on backend failure
** handles IdP <code>error</code> query parameter without calling the backend
** redirects to login when code or state are missing
** shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== Demo ==

[https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

<gallery>
Image:LoginPageWithSSOButton.png | Login Page with SSO Button
Image:SSOLoginModal.png | SSO Login Modal
</gallery>
todo add screenshots of oidc login at each step

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-22T16:21:49Z

Jweisz: /* Frontend */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza — multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present at boot via <code>config/initializers/oidc.rb</code>. For providers with <code>discovery: true</code>, the <code>.well-known/openid-configuration</code> document is fetched using the <code>openid_connect</code> gem to resolve the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Discovery results are not aggressively cached to allow for key rotation; on signature verification failure, keys are re-fetched and verification is retried once.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>auth_requests</code> table containing the state, nonce, code verifier, provider id, and creation timestamp. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint (and a temporary <code>GET</code> for direct IdP redirect during backend-only testing) that accepts the authorization code and state. Look up the matching <code>auth_requests</code> row by state, rejecting the request if no row is found or if the row is older than 5 minutes. Delete the row to prevent reuse. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. Extract the user's email from the ID token claims and look up a matching local user. If a match is found, issue a session JWT using the same <code>JsonWebToken.encode</code> method and payload structure as the existing <code>AuthenticationController#login</code> action. If no match is found, return a 404 error indicating no local account exists for that email.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.

[[File:LoginPageWithSSOButton.png|500px|Login Page with SSO Button]]
[[File:SSOLoginModal.png|500px|SSO Login Modal]]

* '''Initiate Login (Step 2):''' Once the user enters their username, provider and clicks Continue with SSO, the form does a <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, it redirects the browser to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===
The implementation uses the '''Strategy pattern''' for provider configuration. Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are skipped at boot with a warning logged, and they do not appear in <code>public_list</code>. Discovery is always used — non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Backend (Rails) ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation, scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>, enqueued probabilistically on request creation
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table
db/migrate/*_add_username_to_oidc_requests.rb — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

spec/models/oidc_request_spec.rb — Model tests covering:

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests (and preserves the row)
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''after_create probabilistic cleanup'''
* Enqueues CleanupStaleOidcRequestsJob when <code>rand</code> falls under the threshold
* Does not enqueue when <code>rand</code> falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email
* Passes when email_verified claim is true
* Passes when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither matches

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

spec/models/oidc_config_spec.rb — Config loading, ERB env var interpolation, memoization and reload, missing key detection with warning log, YAML edge cases (empty file, null providers key, aliases), <code>public_list</code> secrets exclusion, <code>find</code> lookup and ProviderNotFound, scope normalization (whitespace and comma-delimited, default fallback)

spec/requests/oidc_login_spec.rb — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback'''
* Happy path: exchanges valid code and state for a session JWT
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails
* Returns generic 401 "Authentication failed" for:
** No user matching the username and email
** Email matches but username does not
** Invalid or expired state
** Token verification failure
** Stored provider no longer exists in config

spec/models/user_spec.rb — Tests for <code>User#generate_jwt</code> covering payload structure

=== Frontend (React) ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.test.tsx — SSO modal display and provider dropdown component tests
src/pages/OidcCallback/OidcCallback.test.tsx — Callback page tests

'''OidcModal Component'''
* Renders SSO button when providers are configured, renders nothing when the providers response is empty or fails
* Displays the modal form with username input and provider dropdown when providers are returned
* Posts the provider id and username to <code>/auth/client-select</code> on selection and redirects the browser to the returned authorization URL

'''OidcCallback Component'''
* Posts code and state to <code>/auth/callback</code> on mount, stores the session JWT, dispatches auth state, and redirects to the dashboard on success
* Displays an error and redirects to login on backend failure, on IdP <code>error</code> query param (without calling the backend), and on missing code or state

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

[https://github.com/users/johnmweisz/projects/8 frontend board]

[https://github.com/users/johnmweisz/projects/9 backend board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* Skip providers with missing keys and log a warning rather than crashing the app.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, <code>username</code>, and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>recent</code> scope for expiry filtering and a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Probabilistically clean up stale rows inside <code>authorization_uri_for!</code> (10% chance per call) to keep the table bounded without requiring a scheduled job.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and cleanup.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if an <code>email_verified</code> claim is present and false.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — Provider Dropdown with Username Input on Login Page ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display SSO Button when providers are configured properly
* On SSO Button press, renders the modal with a username text input and a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* Hide the dropdown until the username input is non-empty.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, username-gated dropdown visibility, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' the session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default expiry, custom expiry, and signature verification (tampered tokens rejected).
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a background job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* In <code>OidcRequest.authorization_uri_for!</code>, run a DELETE for rows older than the expiry window with a 10% probability per call (<code>if rand < 0.1</code>).
* Use an <code>EXPIRY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add a test verifying that stale rows are eventually removed and fresh rows are preserved.
* Document the rationale in the model with a brief inline comment.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover <code>client-select</code>: happy path, missing params (400), unknown provider (404), discovery failure (502).
* Cover <code>callback</code> happy path: valid code and state exchanged for a session JWT, row consumed after use.
* Cover <code>callback</code> generic 401 "Authentication failed" for: invalid or expired state, replayed state, no matching user, username/email mismatch, token verification failure (bad signature, issuer, audience, or nonce), unverified email, unknown provider on consumed row.
* Cover <code>callback</code> missing params (400) and discovery failure (502).
* Add model specs for <code>OidcRequest</code> covering: atomic state consumption, replay prevention, expiry window, case-insensitive user matching, <code>email_verified</code> claim handling, and PKCE code verifier sent to the token endpoint.
* Add model specs for <code>OidcConfig</code> covering: config loading, ERB interpolation, missing key detection, scope normalization, <code>public_list</code> secrets exclusion, and unknown provider lookup.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Add component tests for <code>OidcModal</code>:
** renders nothing on empty or failed providers response
** renders SSO button when providers are returned
** displays modal when SSO button is pressed
** displays providers in dropdown when providers are returned,
** requires username and provider to both be filled out before SSO can be pressed
** includes both provider id and username in the <code>POST /auth/client-select</code> payload,
** redirects the browser to the returned authorization URL on success
** does not redirect on failure.
* Add component tests for <code>OidcCallback</code>:
** posts code and state to <code>POST /auth/callback</code> on mount
** stores session JWT and dispatches auth state on success
** redirects to dashboard on success
** displays error alert and redirects to login on backend failure
** handles IdP <code>error</code> query parameter without calling the backend
** redirects to login when code or state are missing
** shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== Demo ==
<gallery>
Image:LoginPageWithSSOButton.png | Login Page with SSO Button
Image:SSOLoginModal.png | SSO Login Modal
</gallery>
todo add screenshots of oidc login at each step

File:OIDC Flow Updated.png

2026-04-22T16:14:39Z

Jweisz: Jweisz uploaded a new version of File:OIDC Flow Updated.png

== Summary ==
Shows the design flow of oidc login

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-22T16:11:58Z

Jweisz: /* Design */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza — multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC_Flow_Updated.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present at boot via <code>config/initializers/oidc.rb</code>. For providers with <code>discovery: true</code>, the <code>.well-known/openid-configuration</code> document is fetched using the <code>openid_connect</code> gem to resolve the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Discovery results are not aggressively cached to allow for key rotation; on signature verification failure, keys are re-fetched and verification is retried once.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>auth_requests</code> table containing the state, nonce, code verifier, provider id, and creation timestamp. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint (and a temporary <code>GET</code> for direct IdP redirect during backend-only testing) that accepts the authorization code and state. Look up the matching <code>auth_requests</code> row by state, rejecting the request if no row is found or if the row is older than 5 minutes. Delete the row to prevent reuse. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. Extract the user's email from the ID token claims and look up a matching local user. If a match is found, issue a session JWT using the same <code>JsonWebToken.encode</code> method and payload structure as the existing <code>AuthenticationController#login</code> action. If no match is found, return a 404 error indicating no local account exists for that email.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.
<gallery>
Image:LoginPageWithSSOButton.png | Login Page with SSO Button
Image:SSOLoginModal.png | SSO Login Modal
</gallery>
* '''Initiate Login (Step 2):''' Once the user enters their username, provider and clicks Continue with SSO, the form does a <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, it redirects the browser to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===
The implementation uses the '''Strategy pattern''' for provider configuration. Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are skipped at boot with a warning logged, and they do not appear in <code>public_list</code>. Discovery is always used — non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Backend (Rails) ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation, scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>, enqueued probabilistically on request creation
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table
db/migrate/*_add_username_to_oidc_requests.rb — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

spec/models/oidc_request_spec.rb — Model tests covering:

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests (and preserves the row)
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''after_create probabilistic cleanup'''
* Enqueues CleanupStaleOidcRequestsJob when <code>rand</code> falls under the threshold
* Does not enqueue when <code>rand</code> falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email
* Passes when email_verified claim is true
* Passes when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither matches

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

spec/models/oidc_config_spec.rb — Config loading, ERB env var interpolation, memoization and reload, missing key detection with warning log, YAML edge cases (empty file, null providers key, aliases), <code>public_list</code> secrets exclusion, <code>find</code> lookup and ProviderNotFound, scope normalization (whitespace and comma-delimited, default fallback)

spec/requests/oidc_login_spec.rb — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback'''
* Happy path: exchanges valid code and state for a session JWT
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails
* Returns generic 401 "Authentication failed" for:
** No user matching the username and email
** Email matches but username does not
** Invalid or expired state
** Token verification failure
** Stored provider no longer exists in config

spec/models/user_spec.rb — Tests for <code>User#generate_jwt</code> covering payload structure

=== Frontend (React) ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.test.tsx — SSO modal display and provider dropdown component tests
src/pages/OidcCallback/OidcCallback.test.tsx — Callback page tests

'''OidcModal Component'''
* Renders SSO button when providers are configured, renders nothing when the providers response is empty or fails
* Displays the modal form with username input and provider dropdown when providers are returned
* Posts the provider id and username to <code>/auth/client-select</code> on selection and redirects the browser to the returned authorization URL

'''OidcCallback Component'''
* Posts code and state to <code>/auth/callback</code> on mount, stores the session JWT, dispatches auth state, and redirects to the dashboard on success
* Displays an error and redirects to login on backend failure, on IdP <code>error</code> query param (without calling the backend), and on missing code or state

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

[https://github.com/users/johnmweisz/projects/8 frontend board]

[https://github.com/users/johnmweisz/projects/9 backend board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* Skip providers with missing keys and log a warning rather than crashing the app.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, <code>username</code>, and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>recent</code> scope for expiry filtering and a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Probabilistically clean up stale rows inside <code>authorization_uri_for!</code> (10% chance per call) to keep the table bounded without requiring a scheduled job.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and cleanup.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if an <code>email_verified</code> claim is present and false.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — Provider Dropdown with Username Input on Login Page ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display SSO Button when providers are configured properly
* On SSO Button press, renders the modal with a username text input and a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* Hide the dropdown until the username input is non-empty.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, username-gated dropdown visibility, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' the session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default expiry, custom expiry, and signature verification (tampered tokens rejected).
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a background job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* In <code>OidcRequest.authorization_uri_for!</code>, run a DELETE for rows older than the expiry window with a 10% probability per call (<code>if rand < 0.1</code>).
* Use an <code>EXPIRY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add a test verifying that stale rows are eventually removed and fresh rows are preserved.
* Document the rationale in the model with a brief inline comment.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover <code>client-select</code>: happy path, missing params (400), unknown provider (404), discovery failure (502).
* Cover <code>callback</code> happy path: valid code and state exchanged for a session JWT, row consumed after use.
* Cover <code>callback</code> generic 401 "Authentication failed" for: invalid or expired state, replayed state, no matching user, username/email mismatch, token verification failure (bad signature, issuer, audience, or nonce), unverified email, unknown provider on consumed row.
* Cover <code>callback</code> missing params (400) and discovery failure (502).
* Add model specs for <code>OidcRequest</code> covering: atomic state consumption, replay prevention, expiry window, case-insensitive user matching, <code>email_verified</code> claim handling, and PKCE code verifier sent to the token endpoint.
* Add model specs for <code>OidcConfig</code> covering: config loading, ERB interpolation, missing key detection, scope normalization, <code>public_list</code> secrets exclusion, and unknown provider lookup.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Add component tests for <code>OidcModal</code>:
** renders nothing on empty or failed providers response
** renders SSO button when providers are returned
** displays modal when SSO button is pressed
** displays providers in dropdown when providers are returned,
** requires username and provider to both be filled out before SSO can be pressed
** includes both provider id and username in the <code>POST /auth/client-select</code> payload,
** redirects the browser to the returned authorization URL on success
** does not redirect on failure.
* Add component tests for <code>OidcCallback</code>:
** posts code and state to <code>POST /auth/callback</code> on mount
** stores session JWT and dispatches auth state on success
** redirects to dashboard on success
** displays error alert and redirects to login on backend failure
** handles IdP <code>error</code> query parameter without calling the backend
** redirects to login when code or state are missing
** shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== Demo ==
<gallery>
Image:LoginPageWithSSOButton.png | Login Page with SSO Button
Image:SSOLoginModal.png | SSO Login Modal
</gallery>
todo add screenshots of oidc login at each step

File:OIDC Flow Updated.png

2026-04-22T16:11:38Z

Jweisz: Shows the design flow of oidc login

== Summary ==
Shows the design flow of oidc login

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-22T16:10:15Z

Jweisz: /* Design */

== Purpose ==

Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. Supporting these standard protocols at sites where they are in use is more secure for the application, provides a familiar and streamlined login experience, and frees Expertiza from managing credentials for users whose institution already does so. This design introduces [https://openid.net/developers/how-connect-works/ OIDC] login as an additional authentication option alongside the existing username and password login. Both methods will continue to be supported, allowing users to choose their preferred approach.

== Requirements ==
=== Authentication Flow ===
Users enter their Expertiza username on the login page and select a provider from a dropdown. The frontend posts the username and provider to the backend, which returns an authorization URL. The user is redirected to the school's OIDC provider, authenticates, and is redirected back to the frontend callback. The callback posts the authorization code and state to the backend to complete login. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Matching ===
Match the authenticated user by both the Expertiza username (provided before login) and the verified email claim from the ID token. Username is required because email addresses are not unique in Expertiza — multiple accounts may share the same email. Matching is case-insensitive on both fields. The provider must validate email with the <code>email_verified</code> claim and if it is not <code>true</code>, the login is rejected. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, a generic authentication error is returned.

=== Configuration ===
* OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>).
* Client credentials (client ID, client secret) are stored in environment variables and injected via ERB.
* Providers must support OIDC discovery;
** Their endpoints and JWKS keys are fetched automatically from the <code>.well-known/openid-configuration</code> document.
* The system supports multiple OIDC provider configurations simultaneously.
* Providers with missing required configuration are skipped at boot with a warning logged.

You can find more details about how to set up the Google OIDC Provider at [https://wiki.expertiza.ncsu.edu/index.php?title=Google_OIDC_Setup Google OIDC Setup]

=== State Management ===
OIDC state, nonce, PKCE code verifier, username, and provider key are stored server-side in an <code>oidc_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and consumed (deleted) on successful callback. A probabilistic inline cleanup removes stale rows on new request creation to keep the table bounded without requiring a scheduled job. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted. Expertiza remains the authentication server; the OIDC flow is only used to verify the user's identity with an external provider at login time. Once the user is authenticated, Expertiza issues its own session JWT, and all subsequent requests use that local session. The IdP session is independent of the Expertiza session, so logging out of Expertiza (destroying the local session) does not affect the user's session at the IdP, and logging out of the IdP does not affect the user's Expertiza session. RP-initiated logout (ending the IdP session as part of application logout) is out of scope.

=== Error Handling ===
All callback failure modes (invalid state, expired state, replayed state, no matching user, mismatched username or email, failed token verification, unverified email, unknown provider) return a generic "Authentication failed" response with HTTP 401 to avoid leaking information about which specific check failed. Provider communication failures (discovery or token endpoint unreachable) return HTTP 502. Missing required parameters return HTTP 400. Unknown providers on <code>client-select</code> return HTTP 404.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. State rows are atomically consumed in a database transaction with row-level locking to prevent race conditions on replay. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE. The <code>email_verified</code> claim is checked when present.

=== Testing ===
Backend and frontend are tested independently. Backend request and model specs stub the identity provider's discovery, token, and JWKS endpoints to exercise the full controller and model logic (state management, token exchange, ID token verification, user matching, case-insensitive lookup, email verification) without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, username input, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC Provider-2026-04-06-223511.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present at boot via <code>config/initializers/oidc.rb</code>. For providers with <code>discovery: true</code>, the <code>.well-known/openid-configuration</code> document is fetched using the <code>openid_connect</code> gem to resolve the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Discovery results are not aggressively cached to allow for key rotation; on signature verification failure, keys are re-fetched and verification is retried once.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>auth_requests</code> table containing the state, nonce, code verifier, provider id, and creation timestamp. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint (and a temporary <code>GET</code> for direct IdP redirect during backend-only testing) that accepts the authorization code and state. Look up the matching <code>auth_requests</code> row by state, rejecting the request if no row is found or if the row is older than 5 minutes. Delete the row to prevent reuse. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. Extract the user's email from the ID token claims and look up a matching local user. If a match is found, issue a session JWT using the same <code>JsonWebToken.encode</code> method and payload structure as the existing <code>AuthenticationController#login</code> action. If no match is found, return a 404 error indicating no local account exists for that email.

=== Frontend ===
* '''Login Page (Step 1):'''
** On page load, the <code>OidcModal</code> component calls <code>GET /auth/providers</code>
*** If the request fails or returns empty, the component renders nothing, and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
*** If providers are found, an SSO login button is displayed.
** Once the SSO Button is clicked, a modal displays with a username field and a dropdown (<code>Form.Select</code>) for each configured provider.
<gallery>
Image:LoginPageWithSSOButton.png | Login Page with SSO Button
Image:SSOLoginModal.png | SSO Login Modal
</gallery>
* '''Initiate Login (Step 2):''' Once the user enters their username, provider and clicks Continue with SSO, the form does a <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, it redirects the browser to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend, and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, we store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===
The implementation uses the '''Strategy pattern''' for provider configuration. Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

=== Schema (OidcRequest) ===
The <code>oidc_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.
{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>username</code> || string || not null || Expertiza username entered before login; used alongside the verified email claim to match an existing user (emails are not unique)
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}
No foreign keys or associations to other tables.

=== Provider Configuration (OidcConfig) ===

The <code>OidcConfig</code> model loads OIDC identity provider definitions from <code>config/oidc_providers.yml</code> at boot. Each provider is defined as a keyed entry under <code>providers:</code>. The top-level key is the provider id used in API requests and stored in the <code>oidc_requests.provider</code> column. Client credentials are injected from environment variables via ERB to keep secrets out of version control.

{| class="wikitable"
! Key !! Required !! Purpose
|-
| ''provider key'' (e.g. <code>google-ncsu</code>) || yes || Unique identifier for this provider. Sent by the frontend in <code>POST /auth/client-select</code> and stored on the <code>oidc_requests</code> row. Use a short, URL-safe slug.
|-
| <code>display_name</code> || yes || Human-readable name shown to users in the login dropdown (e.g. "Google NCSU").
|-
| <code>issuer</code> || yes || The OIDC issuer URL (e.g. <code>https://accounts.google.com</code>). Used to fetch the <code>.well-known/openid-configuration</code> discovery document, which provides the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Must match the <code>iss</code> claim in ID tokens issued by this provider.
|-
| <code>client_id</code> || yes || OAuth client identifier obtained when registering the application with the identity provider. Sent in the authorization request and token exchange. Typically injected via <code><%= ENV['PROVIDER_CLIENT_ID'] %></code>.
|-
| <code>client_secret</code> || yes || OAuth client secret obtained during registration. Used to authenticate the backend to the token endpoint. Must be kept secret — always injected via <code><%= ENV['PROVIDER_CLIENT_SECRET'] %></code>, never hardcoded.
|-
| <code>redirect_uri</code> || yes || The URL the identity provider redirects to after authentication. Must exactly match the value registered with the provider (scheme, host, port, and path). Should point to the frontend callback route (e.g. <code>http://localhost:3000/auth/callback</code>).
|-
| <code>scopes</code> || no || Space-separated OIDC scopes requested from the provider. Defaults to <code>openid email profile</code> if omitted. The <code>openid</code> scope is required to receive an ID token; <code>email</code> is required for account matching.
|}

<code>OidcConfig</code> exposes <code>find(provider_key)</code> for internal lookups and <code>public_list</code> for the frontend-facing <code>GET /auth/providers</code> response (which only includes id and display name, never secrets or endpoints). Providers missing any required key are skipped at boot with a warning logged, and they do not appear in <code>public_list</code>. Discovery is always used — non-discovery providers are not supported. The configuration is validated once at boot via <code>config/initializers/oidc.rb</code>.

Example:

<pre>
providers:
google-ncsu:
display_name: Google NCSU
issuer: https://accounts.google.com
client_id: <%= ENV['GOOG_CLIENT_ID'] %>
client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %>
redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %>
scopes: openid email profile
</pre>

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs ==

=== Backend (Rails) ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

app/controllers/oidc_login_controller.rb — Thin controller for providers, client_select, and callback actions with centralized error handling
app/models/oidc_request.rb — ActiveRecord model owning state/nonce/PKCE/username storage, OIDC flow, account matching, and probabilistic stale cleanup
app/models/oidc_config.rb — YAML config loader with validation, scope normalization, and public_list filtering
app/models/user.rb — Added <code>generate_jwt</code> method shared with password login
app/jobs/cleanup_stale_oidc_requests_job.rb — ActiveJob that calls <code>OidcRequest.delete_stale</code>, enqueued probabilistically on request creation
config/oidc_providers.yml — Provider configuration (ERB for env var injection)
config/initializers/oidc.rb — Boot-time config validation
config/routes.rb — New routes for the three OIDC endpoints
db/migrate/*_create_oidc_requests.rb — Migration for oidc_requests table
db/migrate/*_add_username_to_oidc_requests.rb — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/expertiza/reimplementation-back-end/pull/335 PR #335])

spec/models/oidc_request_spec.rb — Model tests covering:

'''.consume_recent_by_state!'''
* Returns and destroys a recent request matching state
* Raises RecordNotFound for unknown state
* Raises RecordNotFound for expired requests (and preserves the row)
* Prevents replay by destroying the row on consumption

'''.delete_stale'''
* Deletes rows older than the validity window and preserves fresh rows

'''after_create probabilistic cleanup'''
* Enqueues CleanupStaleOidcRequestsJob when <code>rand</code> falls under the threshold
* Does not enqueue when <code>rand</code> falls above the threshold

'''.authorization_uri_for!'''
* Creates an oidc_requests row with username and returns authorization URI
* Uses default scopes when provider scopes are missing

'''#verified_email_from_code!'''
* Exchanges code, verifies token, and returns email
* Passes when email_verified claim is true
* Passes when email_verified claim is absent
* Raises AuthenticationError when email_verified is false

'''#authenticate_user!'''
* Matches user by exact username and email
* Matches case-insensitively on username
* Matches case-insensitively on email
* Matches case-insensitively on both fields
* Raises AuthenticationError when email matches but username does not
* Raises AuthenticationError when username matches but email does not
* Raises AuthenticationError when neither matches

'''.new_client'''
* Builds an OpenIDConnect::Client with provider credentials and discovery endpoints

spec/models/oidc_config_spec.rb — Config loading, ERB env var interpolation, memoization and reload, missing key detection with warning log, YAML edge cases (empty file, null providers key, aliases), <code>public_list</code> secrets exclusion, <code>find</code> lookup and ProviderNotFound, scope normalization (whitespace and comma-delimited, default fallback)

spec/requests/oidc_login_spec.rb — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked

'''POST /auth/client-select'''
* Returns authorization URL for a valid provider and username
* Returns 400 when required parameters are missing
* Returns 404 for unknown provider
* Returns 502 when provider discovery fails

'''POST /auth/callback'''
* Happy path: exchanges valid code and state for a session JWT
* Returns 400 when required parameters are missing
* Returns 502 when provider discovery fails
* Returns generic 401 "Authentication failed" for:
** No user matching the username and email
** Email matches but username does not
** Invalid or expired state
** Token verification failure
** Stored provider no longer exists in config

spec/models/user_spec.rb — Tests for <code>User#generate_jwt</code> covering payload structure

=== Frontend (React) ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.tsx — Modal displaying the SSO button and provider dropdown with username input
src/pages/OidcCallback/OidcCallback.tsx — Callback page handling code exchange and auth state dispatch
src/pages/Authentication/Login.tsx — Existing login page with the <code>OidcModal</code> component added below the password form
src/App.tsx — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/expertiza/reimplementation-front-end/pull/172 PR #172])

src/components/Modals/OidcModal.test.tsx — SSO modal display and provider dropdown component tests
src/pages/OidcCallback/OidcCallback.test.tsx — Callback page tests

'''OidcModal Component'''
* Renders SSO button when providers are configured, renders nothing when the providers response is empty or fails
* Displays the modal form with username input and provider dropdown when providers are returned
* Posts the provider id and username to <code>/auth/client-select</code> on selection and redirects the browser to the returned authorization URL

'''OidcCallback Component'''
* Posts code and state to <code>/auth/callback</code> on mount, stores the session JWT, dispatches auth state, and redirects to the dashboard on success
* Displays an error and redirects to login on backend failure, on IdP <code>error</code> query param (without calling the backend), and on missing code or state

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
/auth/callback → React OidcCallback component (frontend route)

== Planning ==

[https://github.com/users/johnmweisz/projects/8 frontend board]

[https://github.com/users/johnmweisz/projects/9 backend board]

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML, exposing methods to list providers, look up a provider by key, and normalize scopes.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>.
* Skip providers with missing keys and log a warning rather than crashing the app.
* Validate configuration at boot via <code>config/initializers/oidc.rb</code> so issues surface immediately on deploy.
* Add unit tests for config loading, validation, missing key detection, scope normalization, and <code>public_list</code> secrets exclusion.

=== Story 2: Backend — OIDC Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, PKCE code verifier, and username, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>oidc_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, <code>username</code>, and <code>created_at</code>.
* Create the <code>OidcRequest</code> model with a <code>recent</code> scope for expiry filtering and a <code>consume_recent_by_state!</code> method that atomically finds, locks, and destroys the row in a transaction to prevent replay.
* Probabilistically clean up stale rows inside <code>authorization_uri_for!</code> (10% chance per call) to keep the table bounded without requiring a scheduled job.
* Add unit tests for creation, atomic consumption, expiry, replay prevention, and cleanup.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that accepts a provider and username, and returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept required <code>provider</code> and <code>username</code> params (return 400 on missing params).
* Look up the provider config and fetch the discovery document.
* Generate cryptographically random state, nonce, and PKCE code verifier and challenge.
* Insert a row into <code>oidc_requests</code> with state, nonce, code_verifier, provider, and username.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, unknown provider, and discovery failure.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept required <code>code</code> and <code>state</code> params (return 400 on missing params).
* Atomically consume the matching <code>oidc_requests</code> row by state, rejecting if not found, expired, or already consumed.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, audience (client_id), and nonce.
* Reject the login if an <code>email_verified</code> claim is present and false.
* Match an existing user by username (from <code>oidc_requests</code>) and email (from ID token), case-insensitive on both.
* On match: issue a session JWT via <code>user.generate_jwt</code> and return <code>{ token }</code>.
* Return a generic 401 "Authentication failed" for all verification and matching failures to avoid information leakage.
* Return a 502 if provider discovery fails.
* Add request specs covering the happy path, missing params, invalid/expired state, replay, token verification failure, username/email mismatch, unverified email, and unknown provider.

=== Story 6: Frontend — Provider Dropdown with Username Input on Login Page ===
'''As a''' user, '''I want''' to enter my username and select a provider on the login page, '''so that''' I can authenticate with my school credentials against the correct Expertiza account.

'''Acceptance Criteria:'''
* Create an <code>OidcModal</code> component that calls <code>GET /auth/providers</code> on mount.
* Display SSO Button when providers are configured properly
* On SSO Button press, renders the modal with a username text input and a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* Hide the dropdown until the username input is non-empty.
* If the providers request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers, username-gated dropdown visibility, and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id and username.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the payload, redirect, and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Unified Session Response ===
'''As a''' developer, '''I want''' the session token generation shared by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic into a shared method on the <code>User</code> model (<code>user.generate_jwt</code>).
* Update <code>AuthenticationController#login</code> to use the shared method without changing its external response shape.
* Use the shared method in <code>OidcLoginController#callback</code>.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default expiry, custom expiry, and signature verification (tampered tokens rejected).
* Verify existing password login request specs still pass.

=== Story 10: Frontend — Externalize Hardcoded Configuration ===
'''As a''' developer, '''I want''' the frontend API base URL moved to configuration, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the API base URL (currently <code>http://localhost:3002</code>) to an environment variable (e.g. <code>REACT_APP_API_URL</code>).
* Replace all hardcoded references in <code>OidcModal</code>, <code>OidcCallback</code>, and <code>Login</code> components.
* Document the variable in the README.
* Ensure all existing tests continue to pass after the extraction.

=== Story 11: Backend — Swagger Documentation for OIDC Endpoints ===
'''As a''' developer, '''I want''' the OIDC endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

=== Story 12: Backend — Probabilistic Cleanup of Stale OIDC Requests ===
'''As a''' developer, '''I want''' stale OIDC request rows cleaned up automatically without a background job, '''so that''' the table does not grow unbounded from abandoned login attempts and no additional infrastructure is required.

'''Acceptance Criteria:'''
* In <code>OidcRequest.authorization_uri_for!</code>, run a DELETE for rows older than the expiry window with a 10% probability per call (<code>if rand < 0.1</code>).
* Use an <code>EXPIRY_WINDOW</code> constant so the cleanup threshold matches the consumption window.
* Add a test verifying that stale rows are eventually removed and fresh rows are preserved.
* Document the rationale in the model with a brief inline comment.

=== Story 13: Backend — Tests ===
'''As a''' developer, '''I want''' RSpec coverage for the OIDC backend, '''so that''' I have confidence the endpoints, models, and security checks work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Stub the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover <code>client-select</code>: happy path, missing params (400), unknown provider (404), discovery failure (502).
* Cover <code>callback</code> happy path: valid code and state exchanged for a session JWT, row consumed after use.
* Cover <code>callback</code> generic 401 "Authentication failed" for: invalid or expired state, replayed state, no matching user, username/email mismatch, token verification failure (bad signature, issuer, audience, or nonce), unverified email, unknown provider on consumed row.
* Cover <code>callback</code> missing params (400) and discovery failure (502).
* Add model specs for <code>OidcRequest</code> covering: atomic state consumption, replay prevention, expiry window, case-insensitive user matching, <code>email_verified</code> claim handling, and PKCE code verifier sent to the token endpoint.
* Add model specs for <code>OidcConfig</code> covering: config loading, ERB interpolation, missing key detection, scope normalization, <code>public_list</code> secrets exclusion, and unknown provider lookup.
* Add model specs for <code>User#generate_jwt</code> covering payload structure, default and custom expiry, and rejection of tampered tokens.
* Verify the existing <code>AuthenticationController#login</code> specs still pass unchanged.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

=== Story 14: Frontend — Tests ===
'''As a''' developer, '''I want''' Vitest coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Mock axios calls to avoid external requests in tests.
* Add component tests for <code>OidcModal</code>:
** renders nothing on empty or failed providers response
** renders SSO button when providers are returned
** displays modal when SSO button is pressed
** displays providers in dropdown when providers are returned,
** requires username and provider to both be filled out before SSO can be pressed
** includes both provider id and username in the <code>POST /auth/client-select</code> payload,
** redirects the browser to the returned authorization URL on success
** does not redirect on failure.
* Add component tests for <code>OidcCallback</code>:
** posts code and state to <code>POST /auth/callback</code> on mount
** stores session JWT and dispatches auth state on success
** redirects to dashboard on success
** displays error alert and redirects to login on backend failure
** handles IdP <code>error</code> query parameter without calling the backend
** redirects to login when code or state are missing
** shows a "Completing login..." message while the token exchange is in progress.
* Verify the existing login page renders and functions correctly with and without the <code>OidcModal</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== Demo ==
<gallery>
Image:LoginPageWithSSOButton.png | Login Page with SSO Button
Image:SSOLoginModal.png | SSO Login Modal
</gallery>
todo add screenshots of oidc login at each step