Expertiza_Wiki - User contributions [en]

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

2026-04-20T14:11:31Z

Jvargas6: /* Story 14: Frontend — 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. It is more secure for applications to use the standard approach at sites where they are in use, and it also frees Expertiza from managing passwords, and thus removes the risk of compromise. By integrating [https://openid.net/developers/how-connect-works/ OIDC] login, users can authenticate using their existing university credentials, providing a familiar and streamlined login experience. Traditional username and password login will continue to be supported alongside OIDC, allowing users to choose their preferred authentication method.

== 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. If the provider includes an <code>email_verified</code> claim and 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/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/controllers/oidc_login_controller.rb app/controllers/oidc_login_controller.rb] — Thin controller for providers, client_select, and callback actions with centralized error handling
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_request.rb app/models/oidc_request.rb] — ActiveRecord model owning state/nonce/PKCE/username storage and the full OIDC flow
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_config.rb app/models/oidc_config.rb] — YAML config loader with validation and scope normalization
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/user.rb app/models/user.rb] — Added <code>generate_jwt</code> method shared with password login
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/oidc_providers.yml config/oidc_providers.yml] — Provider configuration (ERB for env var injection)
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/initializers/oidc.rb config/initializers/oidc.rb] — Boot-time config validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/routes.rb config/routes.rb] — New routes for the three OIDC endpoints
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260407003623_create_oidc_requests.rb db/migrate/*_create_oidc_requests.rb] — Migration for oidc_requests table
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260414000000_add_username_to_oidc_requests.rb db/migrate/*_add_username_to_oidc_requests.rb] — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb 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)
* Supports a custom recency window
* Prevents replay by destroying the row on consumption

'''.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

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb 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

'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] — Tests for <code>User#generate_jwt</code> covering payload structure, default expiry, and signature verification
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] — Config loading, validation, missing keys, public_list secrets exclusion, provider lookup, scope normalization

=== Frontend (React) ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.tsx src/components/Modals/OidcModal.tsx] — Modal that displays SSO Button Component and Provider dropdown component with username input
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.tsx src/pages/OidcCallback/OidcCallback.tsx] — Callback page handling code exchange and auth state dispatch
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/Authentication/Login.tsx src/pages/Authentication/Login.tsx] — Existing login page with the <code>OidcModal</code> component added below the password form
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/App.tsx src/App.tsx] — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

* [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] — SSO Modal display and Provider dropdown component tests
* [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] — Callback page tests

'''OidcModal Component'''
* Renders SSO Button if SSO 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
GET /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

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

2026-04-20T14:07:26Z

Jvargas6: /* Story 10: Frontend — Externalize Hardcoded 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. It is more secure for applications to use the standard approach at sites where they are in use, and it also frees Expertiza from managing passwords, and thus removes the risk of compromise. By integrating [https://openid.net/developers/how-connect-works/ OIDC] login, users can authenticate using their existing university credentials, providing a familiar and streamlined login experience. Traditional username and password login will continue to be supported alongside OIDC, allowing users to choose their preferred authentication method.

== 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. If the provider includes an <code>email_verified</code> claim and 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/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/controllers/oidc_login_controller.rb app/controllers/oidc_login_controller.rb] — Thin controller for providers, client_select, and callback actions with centralized error handling
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_request.rb app/models/oidc_request.rb] — ActiveRecord model owning state/nonce/PKCE/username storage and the full OIDC flow
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_config.rb app/models/oidc_config.rb] — YAML config loader with validation and scope normalization
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/user.rb app/models/user.rb] — Added <code>generate_jwt</code> method shared with password login
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/oidc_providers.yml config/oidc_providers.yml] — Provider configuration (ERB for env var injection)
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/initializers/oidc.rb config/initializers/oidc.rb] — Boot-time config validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/routes.rb config/routes.rb] — New routes for the three OIDC endpoints
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260407003623_create_oidc_requests.rb db/migrate/*_create_oidc_requests.rb] — Migration for oidc_requests table
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260414000000_add_username_to_oidc_requests.rb db/migrate/*_add_username_to_oidc_requests.rb] — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb 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)
* Supports a custom recency window
* Prevents replay by destroying the row on consumption

'''.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

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb 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

'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] — Tests for <code>User#generate_jwt</code> covering payload structure, default expiry, and signature verification
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] — Config loading, validation, missing keys, public_list secrets exclusion, provider lookup, scope normalization

=== Frontend (React) ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.tsx src/components/Modals/OidcModal.tsx] — Modal that displays SSO Button Component and Provider dropdown component with username input
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.tsx src/pages/OidcCallback/OidcCallback.tsx] — Callback page handling code exchange and auth state dispatch
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/Authentication/Login.tsx src/pages/Authentication/Login.tsx] — Existing login page with the <code>OidcModal</code> component added below the password form
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/App.tsx src/App.tsx] — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

* [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] — SSO Modal display and Provider dropdown component tests
* [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] — Callback page tests

'''OidcModal Component'''
* Renders SSO Button if SSO 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
GET /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>OidcLogin</code>: renders dropdown when providers are returned, renders nothing on empty or failed providers response, dropdown is hidden until the username input has a value, 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>OidcLogin</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

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

2026-04-20T14:06:55Z

Jvargas6: /* Story 6: Frontend — Provider Dropdown with Username Input on Login Page */

== 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. It is more secure for applications to use the standard approach at sites where they are in use, and it also frees Expertiza from managing passwords, and thus removes the risk of compromise. By integrating [https://openid.net/developers/how-connect-works/ OIDC] login, users can authenticate using their existing university credentials, providing a familiar and streamlined login experience. Traditional username and password login will continue to be supported alongside OIDC, allowing users to choose their preferred authentication method.

== 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. If the provider includes an <code>email_verified</code> claim and 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/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/controllers/oidc_login_controller.rb app/controllers/oidc_login_controller.rb] — Thin controller for providers, client_select, and callback actions with centralized error handling
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_request.rb app/models/oidc_request.rb] — ActiveRecord model owning state/nonce/PKCE/username storage and the full OIDC flow
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_config.rb app/models/oidc_config.rb] — YAML config loader with validation and scope normalization
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/user.rb app/models/user.rb] — Added <code>generate_jwt</code> method shared with password login
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/oidc_providers.yml config/oidc_providers.yml] — Provider configuration (ERB for env var injection)
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/initializers/oidc.rb config/initializers/oidc.rb] — Boot-time config validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/routes.rb config/routes.rb] — New routes for the three OIDC endpoints
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260407003623_create_oidc_requests.rb db/migrate/*_create_oidc_requests.rb] — Migration for oidc_requests table
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260414000000_add_username_to_oidc_requests.rb db/migrate/*_add_username_to_oidc_requests.rb] — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb 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)
* Supports a custom recency window
* Prevents replay by destroying the row on consumption

'''.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

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb 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

'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] — Tests for <code>User#generate_jwt</code> covering payload structure, default expiry, and signature verification
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] — Config loading, validation, missing keys, public_list secrets exclusion, provider lookup, scope normalization

=== Frontend (React) ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.tsx src/components/Modals/OidcModal.tsx] — Modal that displays SSO Button Component and Provider dropdown component with username input
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.tsx src/pages/OidcCallback/OidcCallback.tsx] — Callback page handling code exchange and auth state dispatch
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/Authentication/Login.tsx src/pages/Authentication/Login.tsx] — Existing login page with the <code>OidcModal</code> component added below the password form
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/App.tsx src/App.tsx] — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

* [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] — SSO Modal display and Provider dropdown component tests
* [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] — Callback page tests

'''OidcModal Component'''
* Renders SSO Button if SSO 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
GET /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>OidcLogin</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>OidcLogin</code>: renders dropdown when providers are returned, renders nothing on empty or failed providers response, dropdown is hidden until the username input has a value, 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>OidcLogin</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

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

2026-04-20T14:05:29Z

Jvargas6: /* Frontend (React) */

== 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. It is more secure for applications to use the standard approach at sites where they are in use, and it also frees Expertiza from managing passwords, and thus removes the risk of compromise. By integrating [https://openid.net/developers/how-connect-works/ OIDC] login, users can authenticate using their existing university credentials, providing a familiar and streamlined login experience. Traditional username and password login will continue to be supported alongside OIDC, allowing users to choose their preferred authentication method.

== 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. If the provider includes an <code>email_verified</code> claim and 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/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/controllers/oidc_login_controller.rb app/controllers/oidc_login_controller.rb] — Thin controller for providers, client_select, and callback actions with centralized error handling
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_request.rb app/models/oidc_request.rb] — ActiveRecord model owning state/nonce/PKCE/username storage and the full OIDC flow
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_config.rb app/models/oidc_config.rb] — YAML config loader with validation and scope normalization
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/user.rb app/models/user.rb] — Added <code>generate_jwt</code> method shared with password login
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/oidc_providers.yml config/oidc_providers.yml] — Provider configuration (ERB for env var injection)
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/initializers/oidc.rb config/initializers/oidc.rb] — Boot-time config validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/routes.rb config/routes.rb] — New routes for the three OIDC endpoints
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260407003623_create_oidc_requests.rb db/migrate/*_create_oidc_requests.rb] — Migration for oidc_requests table
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260414000000_add_username_to_oidc_requests.rb db/migrate/*_add_username_to_oidc_requests.rb] — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb 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)
* Supports a custom recency window
* Prevents replay by destroying the row on consumption

'''.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

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb 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

'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] — Tests for <code>User#generate_jwt</code> covering payload structure, default expiry, and signature verification
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] — Config loading, validation, missing keys, public_list secrets exclusion, provider lookup, scope normalization

=== Frontend (React) ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.tsx src/components/Modals/OidcModal.tsx] — Modal that displays SSO Button Component and Provider dropdown component with username input
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.tsx src/pages/OidcCallback/OidcCallback.tsx] — Callback page handling code exchange and auth state dispatch
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/Authentication/Login.tsx src/pages/Authentication/Login.tsx] — Existing login page with the <code>OidcModal</code> component added below the password form
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/App.tsx src/App.tsx] — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

* [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] — SSO Modal display and Provider dropdown component tests
* [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] — Callback page tests

'''OidcModal Component'''
* Renders SSO Button if SSO 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
GET /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>OidcLogin</code> component that calls <code>GET /auth/providers</code> on mount.
* Render 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>OidcLogin</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>OidcLogin</code>: renders dropdown when providers are returned, renders nothing on empty or failed providers response, dropdown is hidden until the username input has a value, 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>OidcLogin</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

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

2026-04-20T14:04:56Z

Jvargas6: /* Frontend (Vitest) 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. It is more secure for applications to use the standard approach at sites where they are in use, and it also frees Expertiza from managing passwords, and thus removes the risk of compromise. By integrating [https://openid.net/developers/how-connect-works/ OIDC] login, users can authenticate using their existing university credentials, providing a familiar and streamlined login experience. Traditional username and password login will continue to be supported alongside OIDC, allowing users to choose their preferred authentication method.

== 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. If the provider includes an <code>email_verified</code> claim and 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/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/controllers/oidc_login_controller.rb app/controllers/oidc_login_controller.rb] — Thin controller for providers, client_select, and callback actions with centralized error handling
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_request.rb app/models/oidc_request.rb] — ActiveRecord model owning state/nonce/PKCE/username storage and the full OIDC flow
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_config.rb app/models/oidc_config.rb] — YAML config loader with validation and scope normalization
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/user.rb app/models/user.rb] — Added <code>generate_jwt</code> method shared with password login
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/oidc_providers.yml config/oidc_providers.yml] — Provider configuration (ERB for env var injection)
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/initializers/oidc.rb config/initializers/oidc.rb] — Boot-time config validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/routes.rb config/routes.rb] — New routes for the three OIDC endpoints
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260407003623_create_oidc_requests.rb db/migrate/*_create_oidc_requests.rb] — Migration for oidc_requests table
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260414000000_add_username_to_oidc_requests.rb db/migrate/*_add_username_to_oidc_requests.rb] — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb 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)
* Supports a custom recency window
* Prevents replay by destroying the row on consumption

'''.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

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb 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

'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] — Tests for <code>User#generate_jwt</code> covering payload structure, default expiry, and signature verification
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] — Config loading, validation, missing keys, public_list secrets exclusion, provider lookup, scope normalization

=== Frontend (React) ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.tsx src/components/Modals/OidcModal.tsx] — Modal that displays SSO Button Component and Provider dropdown component with username input
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.tsx src/pages/OidcCallback/OidcCallback.tsx] — Callback page handling code exchange and auth state dispatch
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/Authentication/Login.tsx src/pages/Authentication/Login.tsx] — Existing login page with the <code>OidcLogin</code> component added below the password form
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/App.tsx src/App.tsx] — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

* [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.test.tsx src/components/Modals/OidcModal.test.tsx] — SSO Modal display and Provider dropdown component tests
* [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] — Callback page tests

'''OidcModal Component'''
* Renders SSO Button if SSO 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
GET /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>OidcLogin</code> component that calls <code>GET /auth/providers</code> on mount.
* Render 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>OidcLogin</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>OidcLogin</code>: renders dropdown when providers are returned, renders nothing on empty or failed providers response, dropdown is hidden until the username input has a value, 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>OidcLogin</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

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

2026-04-20T14:00:51Z

Jvargas6: /* Frontend (React) */

== 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. It is more secure for applications to use the standard approach at sites where they are in use, and it also frees Expertiza from managing passwords, and thus removes the risk of compromise. By integrating [https://openid.net/developers/how-connect-works/ OIDC] login, users can authenticate using their existing university credentials, providing a familiar and streamlined login experience. Traditional username and password login will continue to be supported alongside OIDC, allowing users to choose their preferred authentication method.

== 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. If the provider includes an <code>email_verified</code> claim and 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/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/controllers/oidc_login_controller.rb app/controllers/oidc_login_controller.rb] — Thin controller for providers, client_select, and callback actions with centralized error handling
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_request.rb app/models/oidc_request.rb] — ActiveRecord model owning state/nonce/PKCE/username storage and the full OIDC flow
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_config.rb app/models/oidc_config.rb] — YAML config loader with validation and scope normalization
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/user.rb app/models/user.rb] — Added <code>generate_jwt</code> method shared with password login
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/oidc_providers.yml config/oidc_providers.yml] — Provider configuration (ERB for env var injection)
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/initializers/oidc.rb config/initializers/oidc.rb] — Boot-time config validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/routes.rb config/routes.rb] — New routes for the three OIDC endpoints
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260407003623_create_oidc_requests.rb db/migrate/*_create_oidc_requests.rb] — Migration for oidc_requests table
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260414000000_add_username_to_oidc_requests.rb db/migrate/*_add_username_to_oidc_requests.rb] — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb 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)
* Supports a custom recency window
* Prevents replay by destroying the row on consumption

'''.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

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb 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

'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] — Tests for <code>User#generate_jwt</code> covering payload structure, default expiry, and signature verification
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] — Config loading, validation, missing keys, public_list secrets exclusion, provider lookup, scope normalization

=== Frontend (React) ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/Modals/OidcModal.tsx src/components/Modals/OidcModal.tsx] — Modal that displays SSO Button Component and Provider dropdown component with username input
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.tsx src/pages/OidcCallback/OidcCallback.tsx] — Callback page handling code exchange and auth state dispatch
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/Authentication/Login.tsx src/pages/Authentication/Login.tsx] — Existing login page with the <code>OidcLogin</code> component added below the password form
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/App.tsx src/App.tsx] — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.test.tsx src/components/OidcLogin/OidcLogin.test.tsx] — Provider dropdown component tests
'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] — Callback page tests

'''OidcLogin Component'''
* Renders the username input and provider dropdown when providers are returned, hides the dropdown until username is entered, and renders nothing when the providers response is empty or fails
* 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
GET /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>OidcLogin</code> component that calls <code>GET /auth/providers</code> on mount.
* Render 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>OidcLogin</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>OidcLogin</code>: renders dropdown when providers are returned, renders nothing on empty or failed providers response, dropdown is hidden until the username input has a value, 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>OidcLogin</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

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

2026-04-20T13:48:06Z

Jvargas6: /* 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. It is more secure for applications to use the standard approach at sites where they are in use, and it also frees Expertiza from managing passwords, and thus removes the risk of compromise. By integrating [https://openid.net/developers/how-connect-works/ OIDC] login, users can authenticate using their existing university credentials, providing a familiar and streamlined login experience. Traditional username and password login will continue to be supported alongside OIDC, allowing users to choose their preferred authentication method.

== 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. If the provider includes an <code>email_verified</code> claim and 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/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/controllers/oidc_login_controller.rb app/controllers/oidc_login_controller.rb] — Thin controller for providers, client_select, and callback actions with centralized error handling
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_request.rb app/models/oidc_request.rb] — ActiveRecord model owning state/nonce/PKCE/username storage and the full OIDC flow
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_config.rb app/models/oidc_config.rb] — YAML config loader with validation and scope normalization
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/user.rb app/models/user.rb] — Added <code>generate_jwt</code> method shared with password login
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/oidc_providers.yml config/oidc_providers.yml] — Provider configuration (ERB for env var injection)
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/initializers/oidc.rb config/initializers/oidc.rb] — Boot-time config validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/routes.rb config/routes.rb] — New routes for the three OIDC endpoints
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260407003623_create_oidc_requests.rb db/migrate/*_create_oidc_requests.rb] — Migration for oidc_requests table
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260414000000_add_username_to_oidc_requests.rb db/migrate/*_add_username_to_oidc_requests.rb] — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb 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)
* Supports a custom recency window
* Prevents replay by destroying the row on consumption

'''.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

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb 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

'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] — Tests for <code>User#generate_jwt</code> covering payload structure, default expiry, and signature verification
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] — Config loading, validation, missing keys, public_list secrets exclusion, provider lookup, scope normalization

=== Frontend (React) ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.tsx src/components/OidcLogin/OidcLogin.tsx] — Provider dropdown component with username input
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.tsx src/pages/OidcCallback/OidcCallback.tsx] — Callback page handling code exchange and auth state dispatch
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/Authentication/Login.tsx src/pages/Authentication/Login.tsx] — Existing login page with the <code>OidcLogin</code> component added below the password form
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/App.tsx src/App.tsx] — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.test.tsx src/components/OidcLogin/OidcLogin.test.tsx] — Provider dropdown component tests
'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] — Callback page tests

'''OidcLogin Component'''
* Renders the username input and provider dropdown when providers are returned, hides the dropdown until username is entered, and renders nothing when the providers response is empty or fails
* 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
GET /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>OidcLogin</code> component that calls <code>GET /auth/providers</code> on mount.
* Render 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>OidcLogin</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>OidcLogin</code>: renders dropdown when providers are returned, renders nothing on empty or failed providers response, dropdown is hidden until the username input has a value, 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>OidcLogin</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

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

2026-04-20T13:38:57Z

Jvargas6: /* 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. It is more secure for applications to use the standard approach at sites where they are in use, and it also frees Expertiza from managing passwords, and thus removes the risk of compromise. By integrating [https://openid.net/developers/how-connect-works/ OIDC] login, users can authenticate using their existing university credentials, providing a familiar and streamlined login experience. Traditional username and password login will continue to be supported alongside OIDC, allowing users to choose their preferred authentication method.

== 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. If the provider includes an <code>email_verified</code> claim and 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>OidcLogin</code> component calls <code>GET /auth/providers</code> and renders a dropdown (<code>Form.Select</code>) for each configured provider below the existing username and password form. 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.
* '''Initiate Login (Step 2):''' When the user selects a provider from the dropdown, <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, redirect 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, 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/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/controllers/oidc_login_controller.rb app/controllers/oidc_login_controller.rb] — Thin controller for providers, client_select, and callback actions with centralized error handling
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_request.rb app/models/oidc_request.rb] — ActiveRecord model owning state/nonce/PKCE/username storage and the full OIDC flow
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_config.rb app/models/oidc_config.rb] — YAML config loader with validation and scope normalization
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/user.rb app/models/user.rb] — Added <code>generate_jwt</code> method shared with password login
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/oidc_providers.yml config/oidc_providers.yml] — Provider configuration (ERB for env var injection)
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/initializers/oidc.rb config/initializers/oidc.rb] — Boot-time config validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/routes.rb config/routes.rb] — New routes for the three OIDC endpoints
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260407003623_create_oidc_requests.rb db/migrate/*_create_oidc_requests.rb] — Migration for oidc_requests table
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260414000000_add_username_to_oidc_requests.rb db/migrate/*_add_username_to_oidc_requests.rb] — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb 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)
* Supports a custom recency window
* Prevents replay by destroying the row on consumption

'''.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

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb 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

'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] — Tests for <code>User#generate_jwt</code> covering payload structure, default expiry, and signature verification
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] — Config loading, validation, missing keys, public_list secrets exclusion, provider lookup, scope normalization

=== Frontend (React) ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.tsx src/components/OidcLogin/OidcLogin.tsx] — Provider dropdown component with username input
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.tsx src/pages/OidcCallback/OidcCallback.tsx] — Callback page handling code exchange and auth state dispatch
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/Authentication/Login.tsx src/pages/Authentication/Login.tsx] — Existing login page with the <code>OidcLogin</code> component added below the password form
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/App.tsx src/App.tsx] — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.test.tsx src/components/OidcLogin/OidcLogin.test.tsx] — Provider dropdown component tests
'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] — Callback page tests

'''OidcLogin Component'''
* Renders the username input and provider dropdown when providers are returned, hides the dropdown until username is entered, and renders nothing when the providers response is empty or fails
* 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
GET /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>OidcLogin</code> component that calls <code>GET /auth/providers</code> on mount.
* Render 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>OidcLogin</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>OidcLogin</code>: renders dropdown when providers are returned, renders nothing on empty or failed providers response, dropdown is hidden until the username input has a value, 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>OidcLogin</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

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

2026-04-20T13:37:59Z

Jvargas6: /* 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. It is more secure for applications to use the standard approach at sites where they are in use, and it also frees Expertiza from managing passwords, and thus removes the risk of compromise. By integrating [https://openid.net/developers/how-connect-works/ OIDC] login, users can authenticate using their existing university credentials, providing a familiar and streamlined login experience. Traditional username and password login will continue to be supported alongside OIDC, allowing users to choose their preferred authentication method.

== 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. If the provider includes an <code>email_verified</code> claim and 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>OidcLogin</code> component calls <code>GET /auth/providers</code> and renders a dropdown (<code>Form.Select</code>) for each configured provider below the existing username and password form. 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.
* '''Initiate Login (Step 2):''' When the user selects a provider from the dropdown, <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, redirect 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, 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/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/controllers/oidc_login_controller.rb app/controllers/oidc_login_controller.rb] — Thin controller for providers, client_select, and callback actions with centralized error handling
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_request.rb app/models/oidc_request.rb] — ActiveRecord model owning state/nonce/PKCE/username storage and the full OIDC flow
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_config.rb app/models/oidc_config.rb] — YAML config loader with validation and scope normalization
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/user.rb app/models/user.rb] — Added <code>generate_jwt</code> method shared with password login
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/oidc_providers.yml config/oidc_providers.yml] — Provider configuration (ERB for env var injection)
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/initializers/oidc.rb config/initializers/oidc.rb] — Boot-time config validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/routes.rb config/routes.rb] — New routes for the three OIDC endpoints
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260407003623_create_oidc_requests.rb db/migrate/*_create_oidc_requests.rb] — Migration for oidc_requests table
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260414000000_add_username_to_oidc_requests.rb db/migrate/*_add_username_to_oidc_requests.rb] — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb 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)
* Supports a custom recency window
* Prevents replay by destroying the row on consumption

'''.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

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb 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

'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] — Tests for <code>User#generate_jwt</code> covering payload structure, default expiry, and signature verification
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] — Config loading, validation, missing keys, public_list secrets exclusion, provider lookup, scope normalization

=== Frontend (React) ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.tsx src/components/OidcLogin/OidcLogin.tsx] — Provider dropdown component with username input
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.tsx src/pages/OidcCallback/OidcCallback.tsx] — Callback page handling code exchange and auth state dispatch
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/Authentication/Login.tsx src/pages/Authentication/Login.tsx] — Existing login page with the <code>OidcLogin</code> component added below the password form
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/App.tsx src/App.tsx] — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.test.tsx src/components/OidcLogin/OidcLogin.test.tsx] — Provider dropdown component tests
'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] — Callback page tests

'''OidcLogin Component'''
* Renders the username input and provider dropdown when providers are returned, hides the dropdown until username is entered, and renders nothing when the providers response is empty or fails
* 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
GET /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>OidcLogin</code> component that calls <code>GET /auth/providers</code> on mount.
* Render 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>OidcLogin</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>OidcLogin</code>: renders dropdown when providers are returned, renders nothing on empty or failed providers response, dropdown is hidden until the username input has a value, 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>OidcLogin</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>
LoginPageWithSSOButton.png|Login Page with SSO Button
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-20T13:33:22Z

Jvargas6: /* 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. It is more secure for applications to use the standard approach at sites where they are in use, and it also frees Expertiza from managing passwords, and thus removes the risk of compromise. By integrating [https://openid.net/developers/how-connect-works/ OIDC] login, users can authenticate using their existing university credentials, providing a familiar and streamlined login experience. Traditional username and password login will continue to be supported alongside OIDC, allowing users to choose their preferred authentication method.

== 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. If the provider includes an <code>email_verified</code> claim and 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>OidcLogin</code> component calls <code>GET /auth/providers</code> and renders a dropdown (<code>Form.Select</code>) for each configured provider below the existing username and password form. 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.
* '''Initiate Login (Step 2):''' When the user selects a provider from the dropdown, <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, redirect 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, 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/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/controllers/oidc_login_controller.rb app/controllers/oidc_login_controller.rb] — Thin controller for providers, client_select, and callback actions with centralized error handling
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_request.rb app/models/oidc_request.rb] — ActiveRecord model owning state/nonce/PKCE/username storage and the full OIDC flow
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_config.rb app/models/oidc_config.rb] — YAML config loader with validation and scope normalization
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/user.rb app/models/user.rb] — Added <code>generate_jwt</code> method shared with password login
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/oidc_providers.yml config/oidc_providers.yml] — Provider configuration (ERB for env var injection)
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/initializers/oidc.rb config/initializers/oidc.rb] — Boot-time config validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/routes.rb config/routes.rb] — New routes for the three OIDC endpoints
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260407003623_create_oidc_requests.rb db/migrate/*_create_oidc_requests.rb] — Migration for oidc_requests table
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260414000000_add_username_to_oidc_requests.rb db/migrate/*_add_username_to_oidc_requests.rb] — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb 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)
* Supports a custom recency window
* Prevents replay by destroying the row on consumption

'''.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

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb 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

'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] — Tests for <code>User#generate_jwt</code> covering payload structure, default expiry, and signature verification
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] — Config loading, validation, missing keys, public_list secrets exclusion, provider lookup, scope normalization

=== Frontend (React) ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.tsx src/components/OidcLogin/OidcLogin.tsx] — Provider dropdown component with username input
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.tsx src/pages/OidcCallback/OidcCallback.tsx] — Callback page handling code exchange and auth state dispatch
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/Authentication/Login.tsx src/pages/Authentication/Login.tsx] — Existing login page with the <code>OidcLogin</code> component added below the password form
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/App.tsx src/App.tsx] — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.test.tsx src/components/OidcLogin/OidcLogin.test.tsx] — Provider dropdown component tests
'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] — Callback page tests

'''OidcLogin Component'''
* Renders the username input and provider dropdown when providers are returned, hides the dropdown until username is entered, and renders nothing when the providers response is empty or fails
* 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
GET /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>OidcLogin</code> component that calls <code>GET /auth/providers</code> on mount.
* Render 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>OidcLogin</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>OidcLogin</code>: renders dropdown when providers are returned, renders nothing on empty or failed providers response, dropdown is hidden until the username input has a value, 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>OidcLogin</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== Demo ==
Login Page with SSO Button:

[[File:LoginPageWithSSOButton.png]]

SSO Login Modal:

[[File:SSOLoginModal.png]]
todo add screenshots of oidc login at each step

File:LoginPageWithSSOButton.png

2026-04-20T13:31:41Z

Jvargas6:

File:SSOLoginModal.png

2026-04-20T13:30:42Z

Jvargas6:

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

2026-04-20T13:27:15Z

Jvargas6: /* 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. It is more secure for applications to use the standard approach at sites where they are in use, and it also frees Expertiza from managing passwords, and thus removes the risk of compromise. By integrating [https://openid.net/developers/how-connect-works/ OIDC] login, users can authenticate using their existing university credentials, providing a familiar and streamlined login experience. Traditional username and password login will continue to be supported alongside OIDC, allowing users to choose their preferred authentication method.

== 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. If the provider includes an <code>email_verified</code> claim and 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>OidcLogin</code> component calls <code>GET /auth/providers</code> and renders a dropdown (<code>Form.Select</code>) for each configured provider below the existing username and password form. 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.
* '''Initiate Login (Step 2):''' When the user selects a provider from the dropdown, <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, redirect 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, 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/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/controllers/oidc_login_controller.rb app/controllers/oidc_login_controller.rb] — Thin controller for providers, client_select, and callback actions with centralized error handling
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_request.rb app/models/oidc_request.rb] — ActiveRecord model owning state/nonce/PKCE/username storage and the full OIDC flow
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_config.rb app/models/oidc_config.rb] — YAML config loader with validation and scope normalization
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/user.rb app/models/user.rb] — Added <code>generate_jwt</code> method shared with password login
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/oidc_providers.yml config/oidc_providers.yml] — Provider configuration (ERB for env var injection)
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/initializers/oidc.rb config/initializers/oidc.rb] — Boot-time config validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/routes.rb config/routes.rb] — New routes for the three OIDC endpoints
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260407003623_create_oidc_requests.rb db/migrate/*_create_oidc_requests.rb] — Migration for oidc_requests table
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260414000000_add_username_to_oidc_requests.rb db/migrate/*_add_username_to_oidc_requests.rb] — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb 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)
* Supports a custom recency window
* Prevents replay by destroying the row on consumption

'''.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

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb 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

'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] — Tests for <code>User#generate_jwt</code> covering payload structure, default expiry, and signature verification
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] — Config loading, validation, missing keys, public_list secrets exclusion, provider lookup, scope normalization

=== Frontend (React) ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.tsx src/components/OidcLogin/OidcLogin.tsx] — Provider dropdown component with username input
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.tsx src/pages/OidcCallback/OidcCallback.tsx] — Callback page handling code exchange and auth state dispatch
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/Authentication/Login.tsx src/pages/Authentication/Login.tsx] — Existing login page with the <code>OidcLogin</code> component added below the password form
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/App.tsx src/App.tsx] — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.test.tsx src/components/OidcLogin/OidcLogin.test.tsx] — Provider dropdown component tests
'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] — Callback page tests

'''OidcLogin Component'''
* Renders the username input and provider dropdown when providers are returned, hides the dropdown until username is entered, and renders nothing when the providers response is empty or fails
* 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
GET /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>OidcLogin</code> component that calls <code>GET /auth/providers</code> on mount.
* Render 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>OidcLogin</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>OidcLogin</code>: renders dropdown when providers are returned, renders nothing on empty or failed providers response, dropdown is hidden until the username input has a value, 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>OidcLogin</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== Demo ==

todo add screenshots of oidc login at each step

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

2026-04-20T13:25:18Z

Jvargas6: /* 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. It is more secure for applications to use the standard approach at sites where they are in use, and it also frees Expertiza from managing passwords, and thus removes the risk of compromise. By integrating [https://openid.net/developers/how-connect-works/ OIDC] login, users can authenticate using their existing university credentials, providing a familiar and streamlined login experience. Traditional username and password login will continue to be supported alongside OIDC, allowing users to choose their preferred authentication method.

== 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. If the provider includes an <code>email_verified</code> claim and 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

=== 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>OidcLogin</code> component calls <code>GET /auth/providers</code> and renders a dropdown (<code>Form.Select</code>) for each configured provider below the existing username and password form. 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.
* '''Initiate Login (Step 2):''' When the user selects a provider from the dropdown, <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, redirect 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, 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/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/controllers/oidc_login_controller.rb app/controllers/oidc_login_controller.rb] — Thin controller for providers, client_select, and callback actions with centralized error handling
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_request.rb app/models/oidc_request.rb] — ActiveRecord model owning state/nonce/PKCE/username storage and the full OIDC flow
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_config.rb app/models/oidc_config.rb] — YAML config loader with validation and scope normalization
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/user.rb app/models/user.rb] — Added <code>generate_jwt</code> method shared with password login
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/oidc_providers.yml config/oidc_providers.yml] — Provider configuration (ERB for env var injection)
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/initializers/oidc.rb config/initializers/oidc.rb] — Boot-time config validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/routes.rb config/routes.rb] — New routes for the three OIDC endpoints
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260407003623_create_oidc_requests.rb db/migrate/*_create_oidc_requests.rb] — Migration for oidc_requests table
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260414000000_add_username_to_oidc_requests.rb db/migrate/*_add_username_to_oidc_requests.rb] — Migration adding username column for account matching

=== Backend (RSpec) Tests ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_request_spec.rb 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)
* Supports a custom recency window
* Prevents replay by destroying the row on consumption

'''.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

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb 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

'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/user_spec.rb spec/models/user_spec.rb] — Tests for <code>User#generate_jwt</code> covering payload structure, default expiry, and signature verification
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] — Config loading, validation, missing keys, public_list secrets exclusion, provider lookup, scope normalization

=== Frontend (React) ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.tsx src/components/OidcLogin/OidcLogin.tsx] — Provider dropdown component with username input
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.tsx src/pages/OidcCallback/OidcCallback.tsx] — Callback page handling code exchange and auth state dispatch
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/Authentication/Login.tsx src/pages/Authentication/Login.tsx] — Existing login page with the <code>OidcLogin</code> component added below the password form
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/App.tsx src/App.tsx] — Added <code>/auth/callback</code> route

=== Frontend (Vitest) Tests ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.test.tsx src/components/OidcLogin/OidcLogin.test.tsx] — Provider dropdown component tests
'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] — Callback page tests

'''OidcLogin Component'''
* Renders the username input and provider dropdown when providers are returned, hides the dropdown until username is entered, and renders nothing when the providers response is empty or fails
* 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
GET /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>OidcLogin</code> component that calls <code>GET /auth/providers</code> on mount.
* Render 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>OidcLogin</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>OidcLogin</code>: renders dropdown when providers are returned, renders nothing on empty or failed providers response, dropdown is hidden until the username input has a value, 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>OidcLogin</code> component.

(Note that many of these tests may be done during development, so if anything, this story is about verification and completeness)

== Demo ==

todo add screenshots of oidc login at each step

Google OIDC Setup

2026-04-20T13:21:45Z

Jvargas6: Google OIDC Provider Setup

= OIDC Setup (Google) for Expertiza Backend =

This guide explains how to configure <code>Google Cloud Console</code> so this Rails app can authenticate with OIDC and access a user's <code>email</code>.

'''Note:''' Current provider config is in <code>config/oidc_providers.yml</code> under <code>providers.google-ncsu</code>.

----

== 1: Prerequisites ==

* Google account with access to [https://console.cloud.google.com/ Google Cloud Console]
* The full stack to be running
** Vite/React Frontend
** Ruby on Rails API (This project)
** MySQL database
** Redis (currently used for caching, though not currently use for offloading temporary OIDC tokens)
* The redirect URI that matches the app config exactly
** Local example: <code>http://localhost:3000/auth/callback</code>
** This value should come from <code>GOOG_REDIRECT_URI</code> for the Rails API

----

== 2: Create or select a Google Cloud project ==

# Open [https://console.cloud.google.com/ Google Cloud Console].
# Create a [https://console.cloud.google.com/projectcreate new project] (or select an existing one).
# Make sure the selected project is the one you want for OIDC.
#* If you create a new project but had existing projects, you may need to select your new project.
#* Google will sometimes select the previous project you used rather than the newly created project.

----

== 3: Configure OAuth consent screen ==

# Go to Explore and Enable APIs: [https://console.cloud.google.com/apis/dashboard APIs Dashboard]
# Click the '''OAuth consent screen''' in the side navigation.
# Click "Get Started" and fill in the required app details
#* App name
#** Example: NCSU SSO
#* Support email
#** For local dev use your email
#* Developer contact email
#** For local dev use your email
# Choose '''External''' (unless you've been instructed otherwise for test/production).
# Agree to the API terms and create.

=== Configure Scopes ===

# Select <code>Data Access</code> in the left navigation.
# Click Add/Remove '''Scopes'''.
#* At a minimum we need to add:
#** <code>openid</code>
#** <code>email</code>, displays as <code>.../auth/userinfo.email</code>
#** <code>profile</code>, displays as <code>.../auth/userinfo.profile</code>

==== Why not "email scope only" ====

For OIDC login, Google should receive <code>openid email</code>.

* <code>email</code> gives access to the email claim.
* <code>openid</code> is required for an OIDC ID token.

If you send only <code>email</code> without <code>openid</code>, OIDC token validation will fail.

----

== 4: Add test users (if app is in Testing mode) ==

* Click <code>Audience</code> in the side navigation.
* Go to the <code>Test Users</code> section.
* Click <code>Add users</code>.
* Enter your NCSU email, press enter, and save.

----

== 5: Create OAuth client credentials ==

# Select <code>Clients</code> from the side navigation.
# Click <code>Create Client</code> at the top of the screen.
# Application type: '''Web application'''.
# Name it "Expertiza SSO".
#* Append Dev or Test to the name if necessary.
# Add '''Authorized redirect URI''':
#* Enter the frontend auth callback URL.
#** Local Dev should have the redirect URI from Step 1.
# Click Save.

'''Important:''' This is the only time you will see the secret.

The credential window gives the option to download the ID and secret as JSON.

If this is for production, download the JSON and save it to a secure key vault for future use/reference.

# Copy:
#* '''Client ID'''
#* '''Client Secret'''

----

== 6: Configure app environment variables ==

Set these environment variables for the Rails application:

* <code>GOOG_CLIENT_ID</code>
* <code>GOOG_CLIENT_SECRET</code>
* <code>GOOG_REDIRECT_URI</code>

Examples:

* PowerShell
<syntaxhighlight lang="powershell">
$env:GOOG_CLIENT_ID="<app_client_id>"
$env:GOOG_CLIENT_SECRET="<app_client_secret>"
$env:GOOG_REDIRECT_URI="<http_frontend_baseurl>/auth/callback"
</syntaxhighlight>

* bash / WSL
<syntaxhighlight lang="bash">
export GOOG_CLIENT_ID="<app_client_id>"
export GOOG_CLIENT_SECRET="<app_client_secret>"
export GOOG_REDIRECT_URI="<http_frontend_baseurl>/auth/callback"
</syntaxhighlight>

If you use Docker Compose:

* You can either add the env settings directly in Compose environment settings.
** If you use this option, do '''not''' commit the Compose file with secrets.
* You can create a <code>.env</code> file and have Docker Compose reference it. Then put the OIDC info in your env file and redeploy with Docker Compose.

Docker <code>.env</code> example:

<syntaxhighlight lang="ini">
GOOG_CLIENT_ID='xxxxxxx.apps.googleusercontent.com'
GOOG_CLIENT_SECRET='XXXXXX-xxxxxxxxxxxxxxxxxxxxxxxxx'
GOOG_REDIRECT_URI='http://localhost:3000/auth/callback'
</syntaxhighlight>

----

== 7: Verify provider config ==

<code>config/oidc_providers.yml</code> should match:

* <code>issuer: https://accounts.google.com</code>
* <code>client_id: <%= ENV['GOOG_CLIENT_ID'] %></code>
* <code>client_secret: <%= ENV['GOOG_CLIENT_SECRET'] %></code>
* <code>redirect_uri: <%= ENV['GOOG_REDIRECT_URI'] %></code>

<code>scopes</code> is currently optional in this repo.

If omitted, <code>OidcConfig.scopes_for</code> defaults to:

* <code>openid email profile</code>

If you want to restrict to email-focused login:

* Keep <code>openid email</code>
* Remove <code>profile</code> from the actual scope source:
** If the provider defines <code>scopes</code> in <code>config/oidc_providers.yml</code>, set it to <code>openid email</code>
** If <code>scopes</code> is omitted, the fallback comes from <code>OidcConfig.scopes_for</code>, so update that default if you want repo-wide behavior without <code>profile</code>

----

== 8: Quick runtime validation ==

# Start the backend.
# Call provider list endpoint:

<syntaxhighlight lang="text">
GET /auth/providers
</syntaxhighlight>

Expected result: includes <code>google-ncsu</code>.

If you get an empty array, confirm env vars are present in the running process.

----

== 9: Common issues ==

=== Empty <code>/auth/providers</code> ===

* Usually means one or more required provider fields are blank after ERB eval.
* Most often <code>GOOG_CLIENT_ID</code>, <code>GOOG_CLIENT_SECRET</code>, or <code>GOOG_REDIRECT_URI</code> is missing.
* Error reporting can be found in the Rails logs.

=== Redirect URI mismatch ===

* Google and app must match '''exactly''' (scheme, host, port, path).

=== <code>invalid_client</code> ===

* Wrong client ID/secret pair, or credentials from a different project.

=== Consent screen / test user errors ===

* Add your account as test user if app is in Testing mode.

----

== 10: Production notes ==

* Use production redirect URI (HTTPS).
* Store secrets in a secure secret manager or deployment environment.
* '''Do not commit credentials to git.'''

CSC/ECE 517 Spring 2026 - E2604. Finish Password Resets

2026-03-28T01:10:03Z

Jvargas6: /* Demo Video */

== Demo Video ==
[https://drive.google.com/file/d/1Piw2dpUQ5ldI9X1mdROg4crYI9QWxuiP/view?usp=drive_link Click to watch the demo video]

You can also [https://www.youtube.com/watch?v=gWbL0l0GJ3c Watch it on YouTube]

== Expertiza Background ==

=== What is Expertiza? ===
'''Expertiza''' is an open-source educational web application built with Ruby on Rails and jointly maintained by students and faculty at North Carolina State University (NCSU). It is available publicly on GitHub.

It supports:

* Creating and configuring assignments (individual or team-based).
* Allowing students to submit work (files, links, etc.).
* Enabling peer review and teammate evaluation.
* Letting instructors define rubrics and grading criteria.

Expertiza is designed to promote learning through iterative feedback. Students review each other’s work, reflect, improve, and resubmit. Instructors can monitor progress, manage deadlines, and assess performance.

== Reimplementation Repository ==
=== Front End Overview ===
The '''reimplementation-front-end''' project replaces Expertiza's aging Rails monolith (server-rendered ERB templates, jQuery, session cookies, no client-side state) with a decoupled React + TypeScript SPA using JWT auth, Redux, Formik/Yup forms, React Bootstrap, and Vite — separating the front end entirely from the Rails API back end.
=== Back End Overview ===
The '''reimplementation-back-end''' project transforms Expertiza from a server-rendered Rails monolith into a pure JSON REST API using stateless JWT/RSA-256 authentication, a centralized role-based authorization concern, and adds several new features including a Duties system for team role assignment, a MentoredTeam type, a TeamsParticipant join model replacing TeamsUser, an Item/Strategy pattern replacing the Question STI hierarchy, a StudentTask service object, multi-view grade reporting endpoints, a self-registration AccountRequest workflow, full invitation lifecycle management, and auto-generated Swagger API documentation.

== Project Background ==

=== Motivation ===
Account recovery and password reset functionality is a critical part of any authentication system. The current site lacks a functional password reset or "forgot password" feature, representing a significant gap in both usability and security.

This created several issues:

* Without a working reset mechanism, there is no sanctioned path for users to change this default credential after account creation. This constitutes a vulnerability that persists indefinitely if left unaddressed.
* A user who forgets their credentials has no means of recovering access independently.
* A standards-compliant password reset mechanism relies on time-limited, single-use tokens delivered to a verified email address. This ensures that only the legitimate account owner can initiate a reset. Without such a mechanism, any ad-hoc reset approach would be either insecure or unverifiable (e.g., allowing resets without proving email ownership).

This project introduces a more structured workflow for handling password reset and account recovery operations.

The goal is to provide a consistent and secure process for users who need to reset or recover their credentials while maintaining proper validation and access control.

Typical operations in this workflow include:

* requesting a password reset
* generating a secure reset token
* validating reset requests
* updating the user's password
* preventing unauthorized reset attempts

The system should ensure that these steps are handled in a secure, predictable, and maintainable way.

== Objectives ==

=== 1. Implement a unified password reset workflow ===

The system should support a consistent flow for recovering user accounts.

Typical steps include:

* User requests password reset
* System generates a reset token
* User receives reset instructions via email
* User accesses password reset page via email link
* User submits new password
* System validates and updates credentials

This workflow should be easy to maintain and extend.

=== 2. Improve security and validation ===

Password reset functionality must enforce security best practices.

This may include:

* Ensure forgot password mechanism adheres to [https://cheatsheetseries.owasp.org/cheatsheets/Forgot_Password_Cheat_Sheet.html#url-tokens industry standards].
* Ensure reset links are generated correctly across development, staging, and production environments.
* Validate forgot and reset password mechanism functions through unit, functional, performance, and integration testing.

The system should ensure that only authorized password reset requests are processed.

=== 3. Improve frontend robustness and validation ===
The password reset workflow involves several frontend steps, including requesting a reset link and submitting a new password. The frontend should handle various edge cases gracefully.

This project includes a review and refinement of the frontend behavior to ensure consistent handling of errors and validation responses.

Key areas of focus include:

* Handling invalid or expired password reset tokens
* Properly displaying backend validation errors
* Ensuring clear success and failure messages for users
* Confirming that form validation aligns with backend rules

The goal is to ensure that the password reset workflow remains reliable and user-friendly.

== Core Changes ==

In this project:

* The '''User model''' or authentication model was enhanced.
* A new '''password reset workflow''' was introduced.
* Controller logic was updated to handle reset requests.
* Routes were added to support password reset endpoints.
* Tests were added to verify authentication and recovery behavior.

== Password Reset Workflow ==

=== Purpose ===
The password reset workflow allows users who have forgotten their password to regain access to their account securely.

A typical password reset flow may look like:

* User selects "Forgot Password" in the login page.
* User provides email address associated with account.
* System generates a reset token.
* System sends reset email containing link with password token in it.
* User navigates to password reset portal and creates a new password.
* System validates the request and updates credentials

This workflow must ensure both usability and security.

=== Implementation ===

[[File:Forgotyourpassword.png]]

The PasswordsController handles two operations in the password reset flow: initiating a reset request and completing it with a new password. Both actions bypass the standard JWT authentication (skip_before_action :authenticate_request!), as they are designed for unauthenticated users.

 ''When a user submits their email to request a password reset.''
<syntaxhighlight lang="rb">
# POST /password_resets
def create
if @user
token = @user.generate_token_for(:password_reset)
UserMailer.send_password_reset_email(@user, token).deliver_later
end

# Always return a 200 OK to prevent email enumeration attacks
render json: { message: I18n.t('password_reset.email_sent') }, status: :ok
end
</syntaxhighlight>

 ''A before_action for create. It looks up the user-submitted email address and does nothing if no user is found.''
<syntaxhighlight lang="rb">
def find_user_by_email
@user = User.find_by(email: params[:email])
end
</syntaxhighlight>

 ''Assuming the email is valid, a password token is dispatched along with an HTML format email.''
<syntaxhighlight lang="rb">
generates_token_for :password_reset, expires_in: 15.minutes do
password_salt&.last(10) || updated_at.to_s
end
</syntaxhighlight>

 ''Navigating to the URL presents the user with the following password reset page.'' 
[[File:ExpertizaPasswordReset.png]]

 ''When a user submits a new password using the token from the email link.''
<syntaxhighlight lang="rb">
# PATCH/PUT /password_resets/:token
def update
if @user.update(password_params)
render json: { message: I18n.t('password_reset.updated') }, status: :ok
else
render json: { errors: @user.errors.full_messages }, status: :unprocessable_entity
end
end
</syntaxhighlight>

 ''A before_action for update. It validates and decodes the reset token from the URL.''
<syntaxhighlight lang="rb">
def find_user_by_token
@user = User.find_by_token_for(:password_reset, params[:token])

unless @user
render json: { error: I18n.t('password_reset.errors.token_expired') }, status: :unprocessable_entity
end
end
</syntaxhighlight>

 ''If the reset token is invalid or expired(find_by_token_for returns nil), the method renders a 422 Unprocessable Entity error''
<syntaxhighlight lang="rb">
def password_params
params.require(:user).permit(:password, :password_confirmation)
end
</syntaxhighlight>

=== How it works - Token Generation ===
* Tokens are generated using Rails 7.1's built-in generates_token_for API.
** When a reset is requested, PasswordsController#create calls @user.generate_token_for(:password_reset), which produces a cryptographically signed token containing:
*** A purpose tag (password_reset) so the token cannot be reused for other token-based operations.
*** An expiry timestamp embedded in the token (15-minute window).
*** A fingerprint derived from the last 10 characters of the user's password_salt, falling back to updated_at

=== How it works - Token Validation ===
* Validation occurs in PasswordsController#find_user_by_token, run as a before_action on the update endpoint:
** Rails' find_by_token_for performs several checks atomically:
*** Signature verification — the token's HMAC signature must be valid (tampered tokens fail immediately).
*** Purpose check — the token must have been generated for :password_reset specifically.
*** Expiry check — the embedded timestamp must be within the 15-minute window.
*** Fingerprint check — the password_salt fragment in the token must match the user's current state.
** If any check fails, nil is returned and the controller renders a 422 Unprocessable Entity with a generic error message ("The token has expired or is invalid.").
*** This single error message intentionally does not distinguish between expired vs. tampered tokens, avoiding information leakage.

=== How it works - Secure Password Update ===
* Once the token is validated, the update action applies the new password.
** Strong parameters filter the request, permitting only :password and :password_confirmation
*** The user has to be able to confirm the password by writing it again.
** At the storage layer:
*** has_secure_password delegates hashing to BCrypt via Rails' ActiveModel::SecurePassword. The raw password is never stored.
*** password_confirmation matching is enforced by has_secure_password — Rails raises a validation error if the two fields don't match.
*** Minimum length validation (length: { minimum: 6 }) ensures weak passwords are rejected before reaching the database.
*** Upon a successful save, password_salt changes, which immediately invalidates the reset token used.

== Security Considerations ==

Password reset systems must be designed carefully to prevent abuse.

'''Potential risks include:'''
* Unauthorized password changes
* Brute-force token guessing
* Replay attacks using old reset links
* Account enumeration
* Token leakage via URL

'''The system addresses these risks:'''
* A request cannot reach the password update logic without first passing token validation. The update action is gated by find_user_by_token as a before_action.
* Tokens produced by Rails' generates_token_for are HMAC-signed using the application's secret_key_base. They are not short numeric codes or predictable sequences — they are cryptographically random and verifiable only by the server.
* When a password is successfully updated via has_secure_password, the password_salt changes. This causes the embedded fingerprint to no longer match, immediately invalidating the used token. Old links cannot be reused even within the 15-minute window.
* The create action always returns 200 OK with the same message ("If the email exists, a reset link has been sent.") regardless of whether the submitted email matches a real account.
* The 15-minute expiry limits the window of exposure, and the token self-invalidates after use, so a leaked-but-used token is harmless. A leaked-but-unused token within 15 minutes remains a risk, but this is a standard trade-off for URL-based reset flows.

== Testing and Verification ==

[https://drive.google.com/ Test Verification Video] -> TODO

=== Goals of Testing ===

The testing strategy verifies that password reset functionality works correctly and securely.

Key goals include:

* Verifying reset request behavior
* Verifying token validation
* Verifying password updates
* Verifying proper error handling

=== Frontend Tests ===

The front end implementation achieves these goals by verifying that:
* Pages render the correct UI elements (headings, inputs, and submit buttons)
* Form validation prevents submission with invalid or mismatched input and displays appropriate error messages
* Successful API calls dispatch the correct success alerts to the user
* Failed API calls are handled gracefully, surfacing either a generic fallback or a server-provided error message
* Token validation on the reset page redirects unauthenticated users back to login

=== Backend Tests ===

The back end implementation achieves these goals by verifying that:
* Submitting a forgot-password request always returns HTTP 200 regardless of whether the email exists, preventing user enumeration
* A valid reset token triggers a password reset email sent to the correct user, containing the correct subject and a tokenized reset URL
* Successfully submitting a valid token with a new password updates the user's stored password_digest and returns HTTP 200
* Invalid, malformed, or expired tokens (>15 minutes) are rejected with HTTP 422 and an appropriate error message
* Password validation rules (minimum 6 characters) are enforced during the reset flow

== Collaborators ==
* Mentor: Prerak Manish Bhandari
* Jose Vargas
* John Weisz
* Jared Monseur