Expertiza_Wiki - User contributions [en]

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

2026-04-27T23:59:50Z

Jcmonseu:

== Purpose ==

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

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

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

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

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

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

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

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

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

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

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

== Design ==

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

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

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

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

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

=== Design Patterns ===

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

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

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

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

=== Provider Configuration (OidcConfig) ===

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

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

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

Example:

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

== New Dependencies ==

=== openid_connect ===

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

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

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

=== rack-attack ===

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

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

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

== File Diffs ==

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

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

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

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

== Tests (74 total) ==

=== Backend (RSpec) ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Frontend (Vitest) ===

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

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

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

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

== Planning ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== NCSU Google Provider Setup ==

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

== Demo Video ==

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

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

2026-04-26T01:48:22Z

Jcmonseu:

== Purpose ==

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

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

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

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

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

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

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

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

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

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

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

== Design ==

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

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

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

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

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

=== Design Patterns ===

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

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

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

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

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

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

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

=== Provider Configuration (OidcConfig) ===

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

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

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

Example:

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

== New Dependencies ==

=== openid_connect ===

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

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

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

=== rack-attack ===

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

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

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

== File Diffs ==

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

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

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

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

== Tests (74 total) ==

=== Backend (RSpec) ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Frontend (Vitest) ===

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

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

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

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

== Planning ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== NCSU Google Provider Setup ==

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

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

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

2026-04-26T01:47:20Z

Jcmonseu: /* Tests */

== Purpose ==

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

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

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

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

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

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

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

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

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

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

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

== Design ==

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

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

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

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

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

=== Design Patterns ===

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

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

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

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

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

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

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

=== Provider Configuration (OidcConfig) ===

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

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

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

Example:

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

== New Dependencies ==

=== openid_connect ===

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

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

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

=== rack-attack ===

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

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

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

== File Diffs ==

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

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

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

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

== Tests (74 total) ==

=== Backend (RSpec) ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Frontend (Vitest) ===

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

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

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

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

== Planning ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== NCSU Google Provider Setup ==

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

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

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

2026-04-26T01:26:32Z

Jcmonseu: /* Design Patterns */

== Purpose ==

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

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

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

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

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

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

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

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

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

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

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

== Design ==

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

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

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

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

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

=== Design Patterns ===

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

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

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

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

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

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

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

=== Provider Configuration (OidcConfig) ===

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

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

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

Example:

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

== New Dependencies ==

=== openid_connect ===

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

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

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

=== rack-attack ===

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

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

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

== File Diffs ==

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

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

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

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

== Tests ==

=== Backend (RSpec) ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Frontend (Vitest) ===

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

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

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

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

== Planning ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== NCSU Google Provider Setup ==

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

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

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

2026-04-26T01:19:09Z

Jcmonseu:

== Purpose ==

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

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

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

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

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

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

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

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

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

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

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

== Design ==

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

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

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

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

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

=== Design Patterns ===

* '''Strategy pattern''' — Each 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.

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

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

=== Provider Configuration (OidcConfig) ===

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

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

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

Example:

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

== New Dependencies ==

=== openid_connect ===

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

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

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

=== rack-attack ===

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

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

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

== File Diffs ==

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

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

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

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

== Tests ==

=== Backend (RSpec) ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Frontend (Vitest) ===

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

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

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

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

== Planning ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== NCSU Google Provider Setup ==

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

== Demo Video ==

You can view the feature in action as well as edge cases, tests, and swagger by watching the [https://drive.google.com/file/d/1I8UrZVbHRGVYDu4LCYoYVtCCm946jCZp/view?usp=sharing| Demo Video]

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

2026-04-14T21:40:06Z

Jcmonseu: /* Purpose */

== Purpose ==
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 select a provider from a dropdown on the login page that redirects them to the school's OIDC provider, authenticates them, and redirects back to the application with a valid session. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown. On provider selection, the frontend posts to the backend, which returns an authorization URL. After the user completes the OIDC flow, the IdP redirects back to the frontend callback, which posts the authorization code and state to the backend to complete login.

=== 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 Linking ===
Match the authenticated user's email from the ID token to an existing local account. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, an 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 that support OIDC discovery have their endpoints and JWKS keys fetched automatically. The system supports multiple OIDC provider configurations simultaneously. The configuration is validated at boot via an initializer, surfacing missing values immediately on deploy rather than at login time.

=== State Management ===
OIDC state, nonce, and PKCE code verifier are stored server-side in an <code>auth_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 deleted after use. This table is named generically to support future federated auth protocols such as SAML. 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.

=== Error Handling ===
Gracefully handle failures such as no local account matching the authenticated email, expired or invalid state parameters, token exchange errors, ID token verification errors, and user-denied consent at the IdP.

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

=== Testing ===
Backend and frontend are tested independently. Backend request specs use WebMock to stub the identity provider's discovery, token, and JWKS endpoints, allowing the full controller logic (state management, token exchange, ID token verification, user matching) to be tested without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, 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 ===

The <code>auth_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>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}

No foreign keys or associations to other tables. This table is intentionally generic to support future federated auth protocols such as SAML.

== 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 and Additions (Prototype and subject to change) ==

=== 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] — Controller with providers, client_select, and callback actions
[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
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/auth_request.rb app/models/auth_request.rb] — ActiveRecord model for state/nonce/PKCE storage
[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/db/migrate/20260407003623_create_auth_requests.rb db/migrate/*_create_auth_requests.rb] — Migration for auth_requests table

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

'''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
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/auth_request_spec.rb spec/models/auth_request_spec.rb] — State uniqueness, expiry scope, cleanup of stale rows
'''TODO''' [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
* '''TODO''' Returns empty array when no providers configured

'''POST /auth/client-select'''
* '''TODO''' Returns authorization URL with expected query parameters (client_id, redirect_uri, scope, state, nonce, code_challenge)
* '''TODO''' Creates an auth_requests row
* '''TODO''' Returns 404 for unknown provider

'''POST /auth/callback — Happy Path'''
* '''TODO''' Exchanges valid code and state for a session JWT with same payload structure as password login
* '''TODO''' Deletes the auth_requests row after successful use

'''POST /auth/callback — CSRF Protection (State Validation)'''
* '''TODO''' Rejects unknown state (422)
* '''TODO''' Rejects expired state older than 5 minutes (422)
* '''TODO''' Rejects already-consumed state / replay (422)

'''POST /auth/callback — Replay Protection (Nonce Validation)'''
* '''TODO''' Rejects ID token with mismatched nonce

'''POST /auth/callback — Token Verification'''
* '''TODO''' Rejects ID token with invalid signature
* '''TODO''' Rejects ID token with mismatched issuer
* '''TODO''' Rejects ID token with mismatched audience (client_id)

'''POST /auth/callback — User Matching'''
* '''TODO''' Returns 404 when no local user matches the email
* '''TODO''' Matches correct user when multiple users exist

'''POST /auth/callback — PKCE'''
* '''TODO''' Sends code_verifier to the token endpoint during code exchange

=== 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
[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

=== 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'''
* '''TODO''' Renders dropdown with providers when GET /auth/providers returns a non-empty list
* '''TODO''' Renders nothing when GET /auth/providers returns an empty array
* '''TODO''' Renders nothing when GET /auth/providers fails
* '''TODO''' Calls POST /auth/client-select with selected provider id on dropdown change
* '''TODO''' Redirects browser to returned authorization URL on successful client-select
* '''TODO''' Does not redirect when client-select fails
* '''TODO''' Existing login form remains visible and functional alongside the dropdown

'''OidcCallback Component'''
* '''TODO''' Posts code and state to POST /auth/callback on mount
* '''TODO''' Stores session JWT and dispatches auth state on success
* '''TODO''' Redirects to dashboard on successful login
* '''TODO''' Displays error alert and redirects to login on backend failure (e.g. no matching account)
* '''TODO''' Displays error and redirects to login when IdP returns an error parameter (e.g. user denied consent) without calling the backend
* '''TODO''' Redirects to login when code or state query parameters are missing
* '''TODO''' Shows "Completing login..." message while request is in flight

=== 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

== Development Stories (Planning) ==

=== 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 at boot, exposing methods to list providers and look up a provider by id.
* 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>, <code>scopes</code>.
* Raise a clear boot-time error if required values are missing via <code>config/initializers/oidc.rb</code>.
* Add unit tests for config loading, validation, and missing key detection.

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

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>auth_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, and <code>created_at</code>.
* Create the <code>AuthRequest</code> model with a uniqueness validation on state, an <code>expired</code> scope, and a <code>cleanup_expired</code> class method.
* Add a rake task or scheduled job to periodically clean up expired rows.
* Add unit tests for creation, lookup, expiry, and deletion.

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

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

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

'''Acceptance Criteria:'''
* Accept a <code>provider</code> param and look up the provider config.
* Generate cryptographically random state, nonce, and PKCE code verifier/challenge.
* Insert a row into <code>auth_requests</code>.
* 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.
* Add request specs covering the happy path, unknown provider, and that the auth_requests row is created.

=== 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 <code>code</code> and <code>state</code> params.
* Look up and delete the matching <code>auth_requests</code> row. Reject if not found or expired.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, client_id, and nonce.
* Extract the email claim and match to an existing local user.
* On match: issue a session JWT using the same payload structure as <code>AuthenticationController#login</code> and return it with the user profile.
* On no match: return a 404 error indicating no local account was found.
* Handle <code>ActiveRecord::RecordNotFound</code> (invalid/expired state) and <code>InvalidToken</code> (verification failure) exceptions.
* Add request specs covering the happy path, expired state, invalid state, and no matching user.

=== Story 6: Frontend — Provider Dropdown on Login Page ===
'''As a''' user, '''I want''' to see a provider dropdown on the login page, '''so that''' I can authenticate with my school credentials.

'''Acceptance Criteria:'''
* Create an <code>OidcLogin</code> component that calls <code>GET /auth/providers</code> on mount.
* Render a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* If the 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 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.
* 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 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 — Tests ===
'''As a''' developer, '''I want''' test coverage for the OIDC backend, '''so that''' I have confidence the endpoints and models 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>.
* Mock the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover error scenarios: expired state, invalid state, unknown provider, no matching user, invalid ID token.
* Add model specs for <code>AuthRequest</code> covering creation, uniqueness, expiry scope, and cleanup.
* Add unit tests for <code>OidcConfig</code> covering loading, validation, and missing key detection.
* Verify the existing <code>AuthenticationController#login</code> is unaffected.

=== Story 10: Frontend — Tests ===
'''As a''' developer, '''I want''' test coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Add component tests for <code>OidcLogin</code>: renders dropdown when providers are returned, renders nothing on empty or failed response, triggers <code>POST /auth/client-select</code> on selection.
* Add component tests for <code>OidcCallback</code>: posts code and state to backend on mount, redirects to dashboard on success, displays error and redirects to login on failure, handles IdP error parameter without calling the backend.
* Mock axios calls to avoid external requests in tests.
* Verify the existing login page renders and functions correctly with and without the <code>OidcLogin</code> component.

=== Additional Refactoring Stories ===

==== Story 11: Backend — Unified Session Response ====
'''As a''' developer, '''I want''' the session object returned to the frontend clearly defined and reusable 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 from <code>AuthenticationController#login</code> and <code>OidcLoginController#callback</code> into a shared method on the <code>User</code> model (e.g. <code>user.generate_jwt</code>).
* Define a consistent response structure (e.g. <code>{ token, user: { id, name, full_name, role, institution_id } }</code>) and use it in both controllers.
* Update the existing password login endpoint to use the shared method without changing its external response shape.
* Add or update request specs for both login endpoints to assert the response structure matches.

==== Story 12: Frontend — Externalize Hardcoded Configuration ====
'''As a''' developer, '''I want''' all hardcoded values moved to isolated configuration files, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the frontend API base URL to an environment variable or shared config file (e.g. <code>.env</code> with <code>REACT_APP_API_URL</code>) and replace all hardcoded references.
* Ensure all existing tests continue to pass after the extraction.

==== Story 13: Backend — Swagger Documentation for Provider Endpoints ====
'''As a''' developer, '''I want''' the OIDC provider 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 (including 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 14: Backend — Cleanup Expired Auth Requests ====
'''As a''' developer, '''I want''' expired auth request rows cleaned up automatically, '''so that''' the table does not grow unbounded from abandoned login attempts.

'''Acceptance Criteria:'''
* Add a recurring ActiveJob solid_queue <code>auth_requests:cleanup</code> that calls <code>AuthRequest.cleanup_expired</code>.
* The task deletes all rows with <code>created_at</code> older than 5 minutes.
* Schedule the task to run periodically (e.g. 24 hours).
* Add a test verifying that only expired rows are deleted.

== Demo ==

todo add screenshots of oidc login at each step

CSC/ECE 517 Spring 2026

2026-04-14T21:36:05Z

Jcmonseu:

* [[CSC/ECE 517 Spring 2026 - E2600. Reimplement review_mapping_controller]]
* [[CSC/ECE 517 Spring 2026 - E2601. Reimplement student quizzes]]
* [[CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view]]
* [[CSC/ECE 517 Spring 2026 - E2603. Implement ViewSubmissions frontend]]
* [[CSC/ECE 517 Spring 2026 - E2604. Finish Password Resets]]
* [[CSC/ECE 517 Spring 2026 - E2606. Finishing Import and Export helper module]]
* [[CSC/ECE 517 Spring 2026 - E2607. ResponseController Frontend]]
* [[CSC/ECE 517 Spring 2026 - E2609. Review calibration]]
* [[CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing]]
* [[CSC/ECE 517 Spring 2026 - E2615. Testing User model and Users controller]]
* [[CSC/ECE 517 Spring 2026 - E2617. Testing Questionnaire and Course Models]]
* [[CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing]]
* [[CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins]]

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

2026-04-07T01:37:18Z

Jcmonseu: /* Implementation */

== 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]

== Project Background ==

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 ===

When the user enters the website, they are presented with login fields. If they do not remember their password, they can select the ''Forgot password?'' link. 
[[File:ExpertizaPasswordLogin.png]]

 The user is now presented with a new window. This is where they will input their email to receive a token for resetting their password. 
[[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.

=== Results - Frontend ===
* Implemented two new authentication pages — '''Forgot Password''' and '''Reset Password''' — enabling users to recover account access via a tokenized email link
* Both pages follow the project's established conventions: React Bootstrap layout, Formik form state management, and Yup schema validation with inline field-level error messages
* The forgot password flow sends a "POST /password_resets" request with the user's email; the reset flow reads a "?token=" query parameter from the email link and sends a "PUT /password_resets/:token" request with the new password
* Added a null-token guard on the reset page that redirects to login if no token is present in the URL, covering cases like direct navigation or broken email links
* Error handling covers all failure scenarios: server-provided error messages are shown when available, with a generic fallback for network errors and unexpected response shapes
* The login page already contained a "Forgot password?" link pointing to "/forgot-password"; both new routes were already registered in "App.tsx"

=== Results - Backend ===
* '''app/controllers/passwords_controller.rb — Implements two endpoints: POST /password_resets to trigger a reset email (silently no-ops if email not found to prevent enumeration) and "PATCH /password_resets/:token" to validate the token and apply the new password. Both actions skip JWT authentication since the user is logged out.
* '''user.rb''' — Added "generates_token_for :password_reset, expires_in: 15.minutes" using the Rails 7.1 token API. The token is HMAC-signed, time-limited, and fingerprinted against "password_salt" so it automatically invalidates after the password is changed.
* '''user_mailer.rb''' — Added "send_password_reset_email" which constructs a reset URL pointing to the frontend ("FRONTEND_URL/password_edit/check_reset_url?token=<token>") and delivers the email asynchronously via "deliver_later".
* '''app/views/user_mailer/send_password_reset_email.html.erb''' — HTML email template rendered by the mailer, containing the reset link and a note that it expires in 15 minutes.
* '''routes.rb''' — Registered "resources :password_resets, only: [:create, :update], controller: "passwords", param: :token" to wire up the two endpoints with the token as the URL parameter.
* '''en.yml''' — Added all user-facing strings under the "password_reset" namespace (email subject, success messages, and error messages) for i18n consistency.

== 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/file/d/1AtfkTxzgnguZvrckcoby2sUxKAPimElM/view?usp=sharing Frontend And Backend Test Verification]

=== 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

=== Test Results ===
* 30 total tests across the backend (16) and frontend (14), all passing with zero failures
* Backend uses RSpec to cover all controller endpoints ("POST /password_resets", "PUT /password_resets/:token"), the "UserMailer", and "User" model email normalization — including edge cases like invalid tokens, expired tokens (15-minute TTL), short passwords, and email enumeration protection
* Frontend uses Vitest + React Testing Library to test both "ForgotPassword" and "ResetPassword" components, covering rendering, form validation (empty fields, invalid email, mismatched/short passwords), success flows, network errors, and server-returned error messages
* Feature-specific backend coverage is estimated at ~95–100% for "PasswordResetsController" and "UserMailer"; the reported 59.79% overall figure reflects measurement against the entire codebase
* Frontend coverage is 96.42%/98.5% across the two components, with the only gaps being defensive error-handling branches that are low-risk by nature

=== Test Coverage ===
* Backend (reimplementation-back-end)
** spec/controllers/api/v1/password_resets_controller_spec.rb — new controller spec
** spec/mailers/user_mailer_spec.rb — new mailer spec
** spec/factories/users.rb — added :password_reset_user factory
* Frontend (reimplementation-front-end)
** src/pages/Authentication/tests/ForgotPassword.test.tsx — new test file
** src/pages/Authentication/tests/ResetPassword.test.tsx — new test file

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

File:ExpertizaPasswordLogin.png

2026-04-07T01:30:30Z

Jcmonseu:

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

2026-04-07T01:27:40Z

Jcmonseu: /* Results - Backend */

== 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]

== Project Background ==

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.

=== Results - Frontend ===
* Implemented two new authentication pages — '''Forgot Password''' and '''Reset Password''' — enabling users to recover account access via a tokenized email link
* Both pages follow the project's established conventions: React Bootstrap layout, Formik form state management, and Yup schema validation with inline field-level error messages
* The forgot password flow sends a "POST /password_resets" request with the user's email; the reset flow reads a "?token=" query parameter from the email link and sends a "PUT /password_resets/:token" request with the new password
* Added a null-token guard on the reset page that redirects to login if no token is present in the URL, covering cases like direct navigation or broken email links
* Error handling covers all failure scenarios: server-provided error messages are shown when available, with a generic fallback for network errors and unexpected response shapes
* The login page already contained a "Forgot password?" link pointing to "/forgot-password"; both new routes were already registered in "App.tsx"

=== Results - Backend ===
* '''app/controllers/passwords_controller.rb — Implements two endpoints: POST /password_resets to trigger a reset email (silently no-ops if email not found to prevent enumeration) and "PATCH /password_resets/:token" to validate the token and apply the new password. Both actions skip JWT authentication since the user is logged out.
* '''user.rb''' — Added "generates_token_for :password_reset, expires_in: 15.minutes" using the Rails 7.1 token API. The token is HMAC-signed, time-limited, and fingerprinted against "password_salt" so it automatically invalidates after the password is changed.
* '''user_mailer.rb''' — Added "send_password_reset_email" which constructs a reset URL pointing to the frontend ("FRONTEND_URL/password_edit/check_reset_url?token=<token>") and delivers the email asynchronously via "deliver_later".
* '''app/views/user_mailer/send_password_reset_email.html.erb''' — HTML email template rendered by the mailer, containing the reset link and a note that it expires in 15 minutes.
* '''routes.rb''' — Registered "resources :password_resets, only: [:create, :update], controller: "passwords", param: :token" to wire up the two endpoints with the token as the URL parameter.
* '''en.yml''' — Added all user-facing strings under the "password_reset" namespace (email subject, success messages, and error messages) for i18n consistency.

== 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/file/d/1AtfkTxzgnguZvrckcoby2sUxKAPimElM/view?usp=sharing Frontend And Backend Test Verification]

=== 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

=== Test Results ===
* 30 total tests across the backend (16) and frontend (14), all passing with zero failures
* Backend uses RSpec to cover all controller endpoints ("POST /password_resets", "PUT /password_resets/:token"), the "UserMailer", and "User" model email normalization — including edge cases like invalid tokens, expired tokens (15-minute TTL), short passwords, and email enumeration protection
* Frontend uses Vitest + React Testing Library to test both "ForgotPassword" and "ResetPassword" components, covering rendering, form validation (empty fields, invalid email, mismatched/short passwords), success flows, network errors, and server-returned error messages
* Feature-specific backend coverage is estimated at ~95–100% for "PasswordResetsController" and "UserMailer"; the reported 59.79% overall figure reflects measurement against the entire codebase
* Frontend coverage is 96.42%/98.5% across the two components, with the only gaps being defensive error-handling branches that are low-risk by nature

=== Test Coverage ===
* Backend (reimplementation-back-end)
** spec/controllers/api/v1/password_resets_controller_spec.rb — new controller spec
** spec/mailers/user_mailer_spec.rb — new mailer spec
** spec/factories/users.rb — added :password_reset_user factory
* Frontend (reimplementation-front-end)
** src/pages/Authentication/tests/ForgotPassword.test.tsx — new test file
** src/pages/Authentication/tests/ResetPassword.test.tsx — new test file

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

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

2026-04-07T01:25:26Z

Jcmonseu: /* Results - Backend */

== 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]

== Project Background ==

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.

=== Results - Frontend ===
* Implemented two new authentication pages — '''Forgot Password''' and '''Reset Password''' — enabling users to recover account access via a tokenized email link
* Both pages follow the project's established conventions: React Bootstrap layout, Formik form state management, and Yup schema validation with inline field-level error messages
* The forgot password flow sends a "POST /password_resets" request with the user's email; the reset flow reads a "?token=" query parameter from the email link and sends a "PUT /password_resets/:token" request with the new password
* Added a null-token guard on the reset page that redirects to login if no token is present in the URL, covering cases like direct navigation or broken email links
* Error handling covers all failure scenarios: server-provided error messages are shown when available, with a generic fallback for network errors and unexpected response shapes
* The login page already contained a "Forgot password?" link pointing to "/forgot-password"; both new routes were already registered in "App.tsx"

=== Results - Backend ===
* '''"app/controllers/passwords_controller.rb" — Implements two endpoints: "POST /password_resets" to trigger a reset email (silently no-ops if email not found to prevent enumeration) and "PATCH /password_resets/:token" to validate the token and apply the new password. Both actions skip JWT authentication since the user is logged out.
* '''user.rb''' — Added "generates_token_for :password_reset, expires_in: 15.minutes" using the Rails 7.1 token API. The token is HMAC-signed, time-limited, and fingerprinted against "password_salt" so it automatically invalidates after the password is changed.
* '''user_mailer.rb''' — Added "send_password_reset_email" which constructs a reset URL pointing to the frontend ("FRONTEND_URL/password_edit/check_reset_url?token=<token>") and delivers the email asynchronously via "deliver_later".
* '''"app/views/user_mailer/send_password_reset_email.html.erb"''' — HTML email template rendered by the mailer, containing the reset link and a note that it expires in 15 minutes.
* '''routes.rb''' — Registered "resources :password_resets, only: [:create, :update], controller: "passwords", param: :token" to wire up the two endpoints with the token as the URL parameter.
* '''en.yml''' — Added all user-facing strings under the "password_reset" namespace (email subject, success messages, and error messages) for i18n consistency.

== 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/file/d/1AtfkTxzgnguZvrckcoby2sUxKAPimElM/view?usp=sharing Frontend And Backend Test Verification]

=== 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

=== Test Results ===
* 30 total tests across the backend (16) and frontend (14), all passing with zero failures
* Backend uses RSpec to cover all controller endpoints ("POST /password_resets", "PUT /password_resets/:token"), the "UserMailer", and "User" model email normalization — including edge cases like invalid tokens, expired tokens (15-minute TTL), short passwords, and email enumeration protection
* Frontend uses Vitest + React Testing Library to test both "ForgotPassword" and "ResetPassword" components, covering rendering, form validation (empty fields, invalid email, mismatched/short passwords), success flows, network errors, and server-returned error messages
* Feature-specific backend coverage is estimated at ~95–100% for "PasswordResetsController" and "UserMailer"; the reported 59.79% overall figure reflects measurement against the entire codebase
* Frontend coverage is 96.42%/98.5% across the two components, with the only gaps being defensive error-handling branches that are low-risk by nature

=== Test Coverage ===
* Backend (reimplementation-back-end)
** spec/controllers/api/v1/password_resets_controller_spec.rb — new controller spec
** spec/mailers/user_mailer_spec.rb — new mailer spec
** spec/factories/users.rb — added :password_reset_user factory
* Frontend (reimplementation-front-end)
** src/pages/Authentication/tests/ForgotPassword.test.tsx — new test file
** src/pages/Authentication/tests/ResetPassword.test.tsx — new test file

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

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

2026-04-07T01:25:03Z

Jcmonseu: /* Results - Backend */

== 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]

== Project Background ==

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.

=== Results - Frontend ===
* Implemented two new authentication pages — '''Forgot Password''' and '''Reset Password''' — enabling users to recover account access via a tokenized email link
* Both pages follow the project's established conventions: React Bootstrap layout, Formik form state management, and Yup schema validation with inline field-level error messages
* The forgot password flow sends a "POST /password_resets" request with the user's email; the reset flow reads a "?token=" query parameter from the email link and sends a "PUT /password_resets/:token" request with the new password
* Added a null-token guard on the reset page that redirects to login if no token is present in the URL, covering cases like direct navigation or broken email links
* Error handling covers all failure scenarios: server-provided error messages are shown when available, with a generic fallback for network errors and unexpected response shapes
* The login page already contained a "Forgot password?" link pointing to "/forgot-password"; both new routes were already registered in "App.tsx"

=== Results - Backend ===
* '''"app/controllers/passwords_controller.rb" — Implements two endpoints: "POST /password_resets" to trigger a reset email (silently no-ops if email not found to prevent enumeration) and "PATCH /password_resets/:token" to validate the token and apply the new password. Both actions skip JWT authentication since the user is logged out.
* '''user.rb''' — Added "generates_token_for :password_reset, expires_in: 15.minutes" using the Rails 7.1 token API. The token is HMAC-signed, time-limited, and fingerprinted against "password_salt" so it automatically invalidates after the password is changed.
* '''user_mailer.rb''' — Added "send_password_reset_email" which constructs a reset URL pointing to the frontend ("FRONTEND_URL/password_edit/check_reset_url?token=<token>") and delivers the email asynchronously via "deliver_later".
* '''"app/views/user_mailer/send_password_reset_email.html.erb"''' — HTML email template rendered by the mailer, containing the reset link and a note that it expires in 15 minutes.
* '''routes.rb''' — Registered "resources :password_resets, only: [:create, :update], controller: "passwords", param: :token" to wire up the two endpoints with the token as the URL parameter.
- '''en.yml''' — Added all user-facing strings under the "password_reset" namespace (email subject, success messages, and error messages) for i18n consistency.

== 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/file/d/1AtfkTxzgnguZvrckcoby2sUxKAPimElM/view?usp=sharing Frontend And Backend Test Verification]

=== 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

=== Test Results ===
* 30 total tests across the backend (16) and frontend (14), all passing with zero failures
* Backend uses RSpec to cover all controller endpoints ("POST /password_resets", "PUT /password_resets/:token"), the "UserMailer", and "User" model email normalization — including edge cases like invalid tokens, expired tokens (15-minute TTL), short passwords, and email enumeration protection
* Frontend uses Vitest + React Testing Library to test both "ForgotPassword" and "ResetPassword" components, covering rendering, form validation (empty fields, invalid email, mismatched/short passwords), success flows, network errors, and server-returned error messages
* Feature-specific backend coverage is estimated at ~95–100% for "PasswordResetsController" and "UserMailer"; the reported 59.79% overall figure reflects measurement against the entire codebase
* Frontend coverage is 96.42%/98.5% across the two components, with the only gaps being defensive error-handling branches that are low-risk by nature

=== Test Coverage ===
* Backend (reimplementation-back-end)
** spec/controllers/api/v1/password_resets_controller_spec.rb — new controller spec
** spec/mailers/user_mailer_spec.rb — new mailer spec
** spec/factories/users.rb — added :password_reset_user factory
* Frontend (reimplementation-front-end)
** src/pages/Authentication/tests/ForgotPassword.test.tsx — new test file
** src/pages/Authentication/tests/ResetPassword.test.tsx — new test file

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

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

2026-04-07T01:24:39Z

Jcmonseu: /* Password Reset Workflow */

== 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]

== Project Background ==

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.

=== Results - Frontend ===
* Implemented two new authentication pages — '''Forgot Password''' and '''Reset Password''' — enabling users to recover account access via a tokenized email link
* Both pages follow the project's established conventions: React Bootstrap layout, Formik form state management, and Yup schema validation with inline field-level error messages
* The forgot password flow sends a "POST /password_resets" request with the user's email; the reset flow reads a "?token=" query parameter from the email link and sends a "PUT /password_resets/:token" request with the new password
* Added a null-token guard on the reset page that redirects to login if no token is present in the URL, covering cases like direct navigation or broken email links
* Error handling covers all failure scenarios: server-provided error messages are shown when available, with a generic fallback for network errors and unexpected response shapes
* The login page already contained a "Forgot password?" link pointing to "/forgot-password"; both new routes were already registered in "App.tsx"

=== Results - Backend ===
* '''"app/controllers/passwords_controller.rb"** — Implements two endpoints: "POST /password_resets" to trigger a reset email (silently no-ops if email not found to prevent enumeration) and "PATCH /password_resets/:token" to validate the token and apply the new password. Both actions skip JWT authentication since the user is logged out.
* '''user.rb''' — Added "generates_token_for :password_reset, expires_in: 15.minutes" using the Rails 7.1 token API. The token is HMAC-signed, time-limited, and fingerprinted against "password_salt" so it automatically invalidates after the password is changed.
* '''user_mailer.rb''' — Added "send_password_reset_email" which constructs a reset URL pointing to the frontend ("FRONTEND_URL/password_edit/check_reset_url?token=<token>") and delivers the email asynchronously via "deliver_later".
* '''"app/views/user_mailer/send_password_reset_email.html.erb"''' — HTML email template rendered by the mailer, containing the reset link and a note that it expires in 15 minutes.
* '''routes.rb''' — Registered "resources :password_resets, only: [:create, :update], controller: "passwords", param: :token" to wire up the two endpoints with the token as the URL parameter.
- '''en.yml''' — Added all user-facing strings under the "password_reset" namespace (email subject, success messages, and error messages) for i18n consistency.

== 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/file/d/1AtfkTxzgnguZvrckcoby2sUxKAPimElM/view?usp=sharing Frontend And Backend Test Verification]

=== 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

=== Test Results ===
* 30 total tests across the backend (16) and frontend (14), all passing with zero failures
* Backend uses RSpec to cover all controller endpoints ("POST /password_resets", "PUT /password_resets/:token"), the "UserMailer", and "User" model email normalization — including edge cases like invalid tokens, expired tokens (15-minute TTL), short passwords, and email enumeration protection
* Frontend uses Vitest + React Testing Library to test both "ForgotPassword" and "ResetPassword" components, covering rendering, form validation (empty fields, invalid email, mismatched/short passwords), success flows, network errors, and server-returned error messages
* Feature-specific backend coverage is estimated at ~95–100% for "PasswordResetsController" and "UserMailer"; the reported 59.79% overall figure reflects measurement against the entire codebase
* Frontend coverage is 96.42%/98.5% across the two components, with the only gaps being defensive error-handling branches that are low-risk by nature

=== Test Coverage ===
* Backend (reimplementation-back-end)
** spec/controllers/api/v1/password_resets_controller_spec.rb — new controller spec
** spec/mailers/user_mailer_spec.rb — new mailer spec
** spec/factories/users.rb — added :password_reset_user factory
* Frontend (reimplementation-front-end)
** src/pages/Authentication/tests/ForgotPassword.test.tsx — new test file
** src/pages/Authentication/tests/ResetPassword.test.tsx — new test file

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

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

2026-04-07T01:15:32Z

Jcmonseu: /* Testing and Verification */

== 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]

== Project Background ==

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/file/d/1AtfkTxzgnguZvrckcoby2sUxKAPimElM/view?usp=sharing Frontend And Backend Test Verification]

=== 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

=== Test Results ===
* 30 total tests across the backend (16) and frontend (14), all passing with zero failures
* Backend uses RSpec to cover all controller endpoints ("POST /password_resets", "PUT /password_resets/:token"), the "UserMailer", and "User" model email normalization — including edge cases like invalid tokens, expired tokens (15-minute TTL), short passwords, and email enumeration protection
* Frontend uses Vitest + React Testing Library to test both "ForgotPassword" and "ResetPassword" components, covering rendering, form validation (empty fields, invalid email, mismatched/short passwords), success flows, network errors, and server-returned error messages
* Feature-specific backend coverage is estimated at ~95–100% for "PasswordResetsController" and "UserMailer"; the reported 59.79% overall figure reflects measurement against the entire codebase
* Frontend coverage is 96.42%/98.5% across the two components, with the only gaps being defensive error-handling branches that are low-risk by nature

=== Test Coverage ===
* Backend (reimplementation-back-end)
** spec/controllers/api/v1/password_resets_controller_spec.rb — new controller spec
** spec/mailers/user_mailer_spec.rb — new mailer spec
** spec/factories/users.rb — added :password_reset_user factory
* Frontend (reimplementation-front-end)
** src/pages/Authentication/tests/ForgotPassword.test.tsx — new test file
** src/pages/Authentication/tests/ResetPassword.test.tsx — new test file

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

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

2026-04-04T02:06:13Z

Jcmonseu: /* Motivation */

== 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]

== Project Background ==

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/file/d/1AtfkTxzgnguZvrckcoby2sUxKAPimElM/view?usp=sharing Frontend And Backend Test Verification]

=== 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

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

2026-04-04T02:05:32Z

Jcmonseu:

== 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]

== 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/file/d/1AtfkTxzgnguZvrckcoby2sUxKAPimElM/view?usp=sharing Frontend And Backend Test Verification]

=== 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

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

2026-03-30T22:40:55Z

Jcmonseu: /* Testing and Verification */

== 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/file/d/1AtfkTxzgnguZvrckcoby2sUxKAPimElM/view?usp=sharing Frontend And Backend Test Verification]

=== 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

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

2026-03-30T22:40:10Z

Jcmonseu: /* Testing and Verification */

== 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/file/d/1AtfkTxzgnguZvrckcoby2sUxKAPimElM/view?usp=sharing Front End And Back End Test Verification]

=== 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

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

2026-03-30T00:12:07Z

Jcmonseu: /* Testing and Verification */

== 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: Will record video once all feedback is addressed

=== 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

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

2026-03-30T00:11:47Z

Jcmonseu: /* Testing and Verification */

== 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] -> Will record video once all feedback is addressed

=== 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

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

2026-03-23T23:23:02Z

Jcmonseu:

== Demo Video ==
[https://youtu.be/o3vQ4M7kFYo Click to watch the demo video]

== 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

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

2026-03-22T22:54:49Z

Jcmonseu: /* Demo Video */

== Demo Video ==
[https://www.youtube.com/watch?v=o3vQ4M7kFYo Click to watch the demo video]

== 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

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

2026-03-19T21:59:03Z

Jcmonseu: /* Testing and Verification */

== Demo Video ==
[https://drive.google.com Click to watch the demo video] -> todo

== 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

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

2026-03-19T21:55:28Z

Jcmonseu: /* Testing and Verification */

== Demo Video ==
[https://drive.google.com Click to watch the demo video] -> todo

== 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]

=== 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

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

2026-03-15T22:45:58Z

Jcmonseu: /* Security Tests */

== Demo Video ==
[https://drive.google.com Click to watch the demo video] -> todo

== 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 ===

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]

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests TODO===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

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

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

2026-03-15T22:35:10Z

Jcmonseu: /* Testing and Verification */

== Demo Video ==
[https://drive.google.com Click to watch the demo video] -> todo

== 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 ===

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]

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

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

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

2026-03-15T22:27:26Z

Jcmonseu: /* Demo Video */

== Demo Video ==
[https://drive.google.com Click to watch the demo video] -> todo

== 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 ===

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 ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

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

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

2026-03-15T22:25:52Z

Jcmonseu:

== Demo Video ==
[https://drive.google.com Click to watch the demo video]

== 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 ===

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 ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

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

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

2026-03-15T22:18:08Z

Jcmonseu: /* Collaborators */

== 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 ===

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 ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

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

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

2026-03-15T22:07:06Z

Jcmonseu: /* Routing */

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

2026-03-15T22:06:36Z

Jcmonseu: /* Security Considerations */

== 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 ===

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.

== Routing ==

Example routing structure for password reset operations:

<syntaxhighlight lang="rb">
resources :password_resets do
collection do
post :request_reset
end

member do
patch :reset_password
end
end
</syntaxhighlight>

TODO: Modify routing according to the project's implementation.

== Testing and Verification ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

== Collaborators ==

* TODO
* TODO
* TODO
* TODO

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

2026-03-15T22:05:14Z

Jcmonseu: /* Security Considerations */

== 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 ===

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 with :
* 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.

== Routing ==

Example routing structure for password reset operations:

<syntaxhighlight lang="rb">
resources :password_resets do
collection do
post :request_reset
end

member do
patch :reset_password
end
end
</syntaxhighlight>

TODO: Modify routing according to the project's implementation.

== Testing and Verification ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

== Collaborators ==

* TODO
* TODO
* TODO
* TODO

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

2026-03-15T21:46:23Z

Jcmonseu: /* Security Considerations */

== 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 ===

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

To mitigate these risks, the system may include:

* TODO: token expiration
* TODO: rate limiting
* TODO: secure password hashing
* TODO: audit logging

== Routing ==

Example routing structure for password reset operations:

<syntaxhighlight lang="rb">
resources :password_resets do
collection do
post :request_reset
end

member do
patch :reset_password
end
end
</syntaxhighlight>

TODO: Modify routing according to the project's implementation.

== Testing and Verification ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

== Collaborators ==

* TODO
* TODO
* TODO
* TODO

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

2026-03-15T21:45:13Z

Jcmonseu: /* Testing Strategy */

== 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 ===

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

To mitigate these risks, the system may include:

* TODO: token expiration
* TODO: rate limiting
* TODO: secure password hashing
* TODO: audit logging

== Routing ==

Example routing structure for password reset operations:

<syntaxhighlight lang="rb">
resources :password_resets do
collection do
post :request_reset
end

member do
patch :reset_password
end
end
</syntaxhighlight>

TODO: Modify routing according to the project's implementation.

== Testing and Verification ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

== Collaborators ==

* TODO
* TODO
* TODO
* TODO

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

2026-03-15T21:44:21Z

Jcmonseu: /* Password Reset Workflow */

== 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 ===

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

To mitigate these risks, the system may include:

* TODO: token expiration
* TODO: rate limiting
* TODO: secure password hashing
* TODO: audit logging

== Routing ==

Example routing structure for password reset operations:

<syntaxhighlight lang="rb">
resources :password_resets do
collection do
post :request_reset
end

member do
patch :reset_password
end
end
</syntaxhighlight>

TODO: Modify routing according to the project's implementation.

== Testing Strategy ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

== Collaborators ==

* TODO
* TODO
* TODO
* TODO

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

2026-03-15T21:41:06Z

Jcmonseu: /* Updating the Password */

== 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 ===

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 ===

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

To mitigate these risks, the system may include:

* TODO: token expiration
* TODO: rate limiting
* TODO: secure password hashing
* TODO: audit logging

== Routing ==

Example routing structure for password reset operations:

<syntaxhighlight lang="rb">
resources :password_resets do
collection do
post :request_reset
end

member do
patch :reset_password
end
end
</syntaxhighlight>

TODO: Modify routing according to the project's implementation.

== Testing Strategy ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

== Collaborators ==

* TODO
* TODO
* TODO
* TODO

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

2026-03-15T21:03:38Z

Jcmonseu: /* Token Management */

== 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 ===

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 ===

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

== Updating the Password ==

=== Purpose ===
After the reset token has been verified, the system allows the user to submit a new password.

=== Implementation ===

<syntaxhighlight lang="rb">
def update_password
# TODO: validate token
# TODO: validate password rules
# TODO: save updated credentials
end
</syntaxhighlight>

=== How it works ===

* The system confirms that the reset request is valid.
* Password requirements are checked.
* The new password is stored securely.
* The reset token is invalidated to prevent reuse.

== 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

To mitigate these risks, the system may include:

* TODO: token expiration
* TODO: rate limiting
* TODO: secure password hashing
* TODO: audit logging

== Routing ==

Example routing structure for password reset operations:

<syntaxhighlight lang="rb">
resources :password_resets do
collection do
post :request_reset
end

member do
patch :reset_password
end
end
</syntaxhighlight>

TODO: Modify routing according to the project's implementation.

== Testing Strategy ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

== Collaborators ==

* TODO
* TODO
* TODO
* TODO

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

2026-03-15T21:02:59Z

Jcmonseu: /* How it works — Tokens */

== 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 ===

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 ===

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

== Token Management ==

=== Purpose ===
Reset tokens allow the system to verify that the password reset request is legitimate.

Tokens typically have the following properties:

* unique per request
* difficult to guess
* time-limited
* associated with a specific user account

=== How it works ===

* When a reset request is initiated, the system generates a token.
* The token is associated with the requesting user.
* The token is included in the password reset link.
* When the user submits a new password, the token is verified.

If validation fails, the reset attempt is rejected.

== Updating the Password ==

=== Purpose ===
After the reset token has been verified, the system allows the user to submit a new password.

=== Implementation ===

<syntaxhighlight lang="rb">
def update_password
# TODO: validate token
# TODO: validate password rules
# TODO: save updated credentials
end
</syntaxhighlight>

=== How it works ===

* The system confirms that the reset request is valid.
* Password requirements are checked.
* The new password is stored securely.
* The reset token is invalidated to prevent reuse.

== 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

To mitigate these risks, the system may include:

* TODO: token expiration
* TODO: rate limiting
* TODO: secure password hashing
* TODO: audit logging

== Routing ==

Example routing structure for password reset operations:

<syntaxhighlight lang="rb">
resources :password_resets do
collection do
post :request_reset
end

member do
patch :reset_password
end
end
</syntaxhighlight>

TODO: Modify routing according to the project's implementation.

== Testing Strategy ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

== Collaborators ==

* TODO
* TODO
* TODO
* TODO

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

2026-03-15T21:02:45Z

Jcmonseu: /* How it works */

== 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 ===

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 — Tokens ===

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

== Token Management ==

=== Purpose ===
Reset tokens allow the system to verify that the password reset request is legitimate.

Tokens typically have the following properties:

* unique per request
* difficult to guess
* time-limited
* associated with a specific user account

=== How it works ===

* When a reset request is initiated, the system generates a token.
* The token is associated with the requesting user.
* The token is included in the password reset link.
* When the user submits a new password, the token is verified.

If validation fails, the reset attempt is rejected.

== Updating the Password ==

=== Purpose ===
After the reset token has been verified, the system allows the user to submit a new password.

=== Implementation ===

<syntaxhighlight lang="rb">
def update_password
# TODO: validate token
# TODO: validate password rules
# TODO: save updated credentials
end
</syntaxhighlight>

=== How it works ===

* The system confirms that the reset request is valid.
* Password requirements are checked.
* The new password is stored securely.
* The reset token is invalidated to prevent reuse.

== 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

To mitigate these risks, the system may include:

* TODO: token expiration
* TODO: rate limiting
* TODO: secure password hashing
* TODO: audit logging

== Routing ==

Example routing structure for password reset operations:

<syntaxhighlight lang="rb">
resources :password_resets do
collection do
post :request_reset
end

member do
patch :reset_password
end
end
</syntaxhighlight>

TODO: Modify routing according to the project's implementation.

== Testing Strategy ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

== Collaborators ==

* TODO
* TODO
* TODO
* TODO

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

2026-03-15T21:00:46Z

Jcmonseu: /* How it works */

== 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 ===

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 ===

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

== Token Management ==

=== Purpose ===
Reset tokens allow the system to verify that the password reset request is legitimate.

Tokens typically have the following properties:

* unique per request
* difficult to guess
* time-limited
* associated with a specific user account

=== How it works ===

* When a reset request is initiated, the system generates a token.
* The token is associated with the requesting user.
* The token is included in the password reset link.
* When the user submits a new password, the token is verified.

If validation fails, the reset attempt is rejected.

== Updating the Password ==

=== Purpose ===
After the reset token has been verified, the system allows the user to submit a new password.

=== Implementation ===

<syntaxhighlight lang="rb">
def update_password
# TODO: validate token
# TODO: validate password rules
# TODO: save updated credentials
end
</syntaxhighlight>

=== How it works ===

* The system confirms that the reset request is valid.
* Password requirements are checked.
* The new password is stored securely.
* The reset token is invalidated to prevent reuse.

== 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

To mitigate these risks, the system may include:

* TODO: token expiration
* TODO: rate limiting
* TODO: secure password hashing
* TODO: audit logging

== Routing ==

Example routing structure for password reset operations:

<syntaxhighlight lang="rb">
resources :password_resets do
collection do
post :request_reset
end

member do
patch :reset_password
end
end
</syntaxhighlight>

TODO: Modify routing according to the project's implementation.

== Testing Strategy ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

== Collaborators ==

* TODO
* TODO
* TODO
* TODO

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

2026-03-15T20:46:25Z

Jcmonseu: /* Implementation */

== 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 ===

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 ===

* TODO: explain how reset tokens are generated
* TODO: explain how tokens are validated
* TODO: explain how passwords are updated securely

== Token Management ==

=== Purpose ===
Reset tokens allow the system to verify that the password reset request is legitimate.

Tokens typically have the following properties:

* unique per request
* difficult to guess
* time-limited
* associated with a specific user account

=== How it works ===

* When a reset request is initiated, the system generates a token.
* The token is associated with the requesting user.
* The token is included in the password reset link.
* When the user submits a new password, the token is verified.

If validation fails, the reset attempt is rejected.

== Updating the Password ==

=== Purpose ===
After the reset token has been verified, the system allows the user to submit a new password.

=== Implementation ===

<syntaxhighlight lang="rb">
def update_password
# TODO: validate token
# TODO: validate password rules
# TODO: save updated credentials
end
</syntaxhighlight>

=== How it works ===

* The system confirms that the reset request is valid.
* Password requirements are checked.
* The new password is stored securely.
* The reset token is invalidated to prevent reuse.

== 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

To mitigate these risks, the system may include:

* TODO: token expiration
* TODO: rate limiting
* TODO: secure password hashing
* TODO: audit logging

== Routing ==

Example routing structure for password reset operations:

<syntaxhighlight lang="rb">
resources :password_resets do
collection do
post :request_reset
end

member do
patch :reset_password
end
end
</syntaxhighlight>

TODO: Modify routing according to the project's implementation.

== Testing Strategy ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

== Collaborators ==

* TODO
* TODO
* TODO
* TODO

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

2026-03-15T20:43:45Z

Jcmonseu: /* Implementation */

== 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 ===

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 ===

* TODO: explain how reset tokens are generated
* TODO: explain how tokens are validated
* TODO: explain how passwords are updated securely

== Token Management ==

=== Purpose ===
Reset tokens allow the system to verify that the password reset request is legitimate.

Tokens typically have the following properties:

* unique per request
* difficult to guess
* time-limited
* associated with a specific user account

=== Implementation ===

Example structure:

<syntaxhighlight lang="rb">
def generate_reset_token
# TODO: create secure token
end

def token_valid?
# TODO: verify token existence
# TODO: check expiration
end
</syntaxhighlight>

=== How it works ===

* When a reset request is initiated, the system generates a token.
* The token is associated with the requesting user.
* The token is included in the password reset link.
* When the user submits a new password, the token is verified.

If validation fails, the reset attempt is rejected.

== Updating the Password ==

=== Purpose ===
After the reset token has been verified, the system allows the user to submit a new password.

=== Implementation ===

<syntaxhighlight lang="rb">
def update_password
# TODO: validate token
# TODO: validate password rules
# TODO: save updated credentials
end
</syntaxhighlight>

=== How it works ===

* The system confirms that the reset request is valid.
* Password requirements are checked.
* The new password is stored securely.
* The reset token is invalidated to prevent reuse.

== 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

To mitigate these risks, the system may include:

* TODO: token expiration
* TODO: rate limiting
* TODO: secure password hashing
* TODO: audit logging

== Routing ==

Example routing structure for password reset operations:

<syntaxhighlight lang="rb">
resources :password_resets do
collection do
post :request_reset
end

member do
patch :reset_password
end
end
</syntaxhighlight>

TODO: Modify routing according to the project's implementation.

== Testing Strategy ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

== Collaborators ==

* TODO
* TODO
* TODO
* TODO

File:ExpertizaPasswordReset.png

2026-03-15T20:39:18Z

Jcmonseu:

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

2026-03-15T20:32:28Z

Jcmonseu: /* Implementation */

== 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 ===

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>

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

* TODO: explain how reset tokens are generated
* TODO: explain how tokens are validated
* TODO: explain how passwords are updated securely

== Token Management ==

=== Purpose ===
Reset tokens allow the system to verify that the password reset request is legitimate.

Tokens typically have the following properties:

* unique per request
* difficult to guess
* time-limited
* associated with a specific user account

=== Implementation ===

Example structure:

<syntaxhighlight lang="rb">
def generate_reset_token
# TODO: create secure token
end

def token_valid?
# TODO: verify token existence
# TODO: check expiration
end
</syntaxhighlight>

=== How it works ===

* When a reset request is initiated, the system generates a token.
* The token is associated with the requesting user.
* The token is included in the password reset link.
* When the user submits a new password, the token is verified.

If validation fails, the reset attempt is rejected.

== Updating the Password ==

=== Purpose ===
After the reset token has been verified, the system allows the user to submit a new password.

=== Implementation ===

<syntaxhighlight lang="rb">
def update_password
# TODO: validate token
# TODO: validate password rules
# TODO: save updated credentials
end
</syntaxhighlight>

=== How it works ===

* The system confirms that the reset request is valid.
* Password requirements are checked.
* The new password is stored securely.
* The reset token is invalidated to prevent reuse.

== 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

To mitigate these risks, the system may include:

* TODO: token expiration
* TODO: rate limiting
* TODO: secure password hashing
* TODO: audit logging

== Routing ==

Example routing structure for password reset operations:

<syntaxhighlight lang="rb">
resources :password_resets do
collection do
post :request_reset
end

member do
patch :reset_password
end
end
</syntaxhighlight>

TODO: Modify routing according to the project's implementation.

== Testing Strategy ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

== Collaborators ==

* TODO
* TODO
* TODO
* TODO

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

2026-03-13T01:10:12Z

Jcmonseu: /* Implementation */

== 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 ===

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>

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

 ''TODO'' -> reformat to follow reset steps
<syntaxhighlight lang="rb">
def find_user_by_email
@user = User.find_by(email: params[:email])
end
</syntaxhighlight>

 ''TODO''-> reformat to follow reset steps
<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>

 ''TODO''-> reformat to follow reset steps
<syntaxhighlight lang="rb">
def password_params
params.require(:user).permit(:password, :password_confirmation)
end
</syntaxhighlight>

=== How it works ===

* TODO: explain how reset tokens are generated
* TODO: explain how tokens are validated
* TODO: explain how passwords are updated securely

== Token Management ==

=== Purpose ===
Reset tokens allow the system to verify that the password reset request is legitimate.

Tokens typically have the following properties:

* unique per request
* difficult to guess
* time-limited
* associated with a specific user account

=== Implementation ===

Example structure:

<syntaxhighlight lang="rb">
def generate_reset_token
# TODO: create secure token
end

def token_valid?
# TODO: verify token existence
# TODO: check expiration
end
</syntaxhighlight>

=== How it works ===

* When a reset request is initiated, the system generates a token.
* The token is associated with the requesting user.
* The token is included in the password reset link.
* When the user submits a new password, the token is verified.

If validation fails, the reset attempt is rejected.

== Updating the Password ==

=== Purpose ===
After the reset token has been verified, the system allows the user to submit a new password.

=== Implementation ===

<syntaxhighlight lang="rb">
def update_password
# TODO: validate token
# TODO: validate password rules
# TODO: save updated credentials
end
</syntaxhighlight>

=== How it works ===

* The system confirms that the reset request is valid.
* Password requirements are checked.
* The new password is stored securely.
* The reset token is invalidated to prevent reuse.

== 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

To mitigate these risks, the system may include:

* TODO: token expiration
* TODO: rate limiting
* TODO: secure password hashing
* TODO: audit logging

== Routing ==

Example routing structure for password reset operations:

<syntaxhighlight lang="rb">
resources :password_resets do
collection do
post :request_reset
end

member do
patch :reset_password
end
end
</syntaxhighlight>

TODO: Modify routing according to the project's implementation.

== Testing Strategy ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

== Collaborators ==

* TODO
* TODO
* TODO
* TODO

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

2026-03-13T01:09:14Z

Jcmonseu: /* Implementation */

== 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 ===

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>

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

 ''TODO''
<syntaxhighlight lang="rb">
def find_user_by_email
@user = User.find_by(email: params[:email])
end
</syntaxhighlight>

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

 ''TODO''
<syntaxhighlight lang="rb">
def password_params
params.require(:user).permit(:password, :password_confirmation)
end
</syntaxhighlight>

=== How it works ===

* TODO: explain how reset tokens are generated
* TODO: explain how tokens are validated
* TODO: explain how passwords are updated securely

== Token Management ==

=== Purpose ===
Reset tokens allow the system to verify that the password reset request is legitimate.

Tokens typically have the following properties:

* unique per request
* difficult to guess
* time-limited
* associated with a specific user account

=== Implementation ===

Example structure:

<syntaxhighlight lang="rb">
def generate_reset_token
# TODO: create secure token
end

def token_valid?
# TODO: verify token existence
# TODO: check expiration
end
</syntaxhighlight>

=== How it works ===

* When a reset request is initiated, the system generates a token.
* The token is associated with the requesting user.
* The token is included in the password reset link.
* When the user submits a new password, the token is verified.

If validation fails, the reset attempt is rejected.

== Updating the Password ==

=== Purpose ===
After the reset token has been verified, the system allows the user to submit a new password.

=== Implementation ===

<syntaxhighlight lang="rb">
def update_password
# TODO: validate token
# TODO: validate password rules
# TODO: save updated credentials
end
</syntaxhighlight>

=== How it works ===

* The system confirms that the reset request is valid.
* Password requirements are checked.
* The new password is stored securely.
* The reset token is invalidated to prevent reuse.

== 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

To mitigate these risks, the system may include:

* TODO: token expiration
* TODO: rate limiting
* TODO: secure password hashing
* TODO: audit logging

== Routing ==

Example routing structure for password reset operations:

<syntaxhighlight lang="rb">
resources :password_resets do
collection do
post :request_reset
end

member do
patch :reset_password
end
end
</syntaxhighlight>

TODO: Modify routing according to the project's implementation.

== Testing Strategy ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

== Collaborators ==

* TODO
* TODO
* TODO
* TODO

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

2026-03-13T01:06:43Z

Jcmonseu: /* Implementation */

== 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 ===

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>

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

=== How it works ===

* TODO: explain how reset tokens are generated
* TODO: explain how tokens are validated
* TODO: explain how passwords are updated securely

== Token Management ==

=== Purpose ===
Reset tokens allow the system to verify that the password reset request is legitimate.

Tokens typically have the following properties:

* unique per request
* difficult to guess
* time-limited
* associated with a specific user account

=== Implementation ===

Example structure:

<syntaxhighlight lang="rb">
def generate_reset_token
# TODO: create secure token
end

def token_valid?
# TODO: verify token existence
# TODO: check expiration
end
</syntaxhighlight>

=== How it works ===

* When a reset request is initiated, the system generates a token.
* The token is associated with the requesting user.
* The token is included in the password reset link.
* When the user submits a new password, the token is verified.

If validation fails, the reset attempt is rejected.

== Updating the Password ==

=== Purpose ===
After the reset token has been verified, the system allows the user to submit a new password.

=== Implementation ===

<syntaxhighlight lang="rb">
def update_password
# TODO: validate token
# TODO: validate password rules
# TODO: save updated credentials
end
</syntaxhighlight>

=== How it works ===

* The system confirms that the reset request is valid.
* Password requirements are checked.
* The new password is stored securely.
* The reset token is invalidated to prevent reuse.

== 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

To mitigate these risks, the system may include:

* TODO: token expiration
* TODO: rate limiting
* TODO: secure password hashing
* TODO: audit logging

== Routing ==

Example routing structure for password reset operations:

<syntaxhighlight lang="rb">
resources :password_resets do
collection do
post :request_reset
end

member do
patch :reset_password
end
end
</syntaxhighlight>

TODO: Modify routing according to the project's implementation.

== Testing Strategy ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

== Collaborators ==

* TODO
* TODO
* TODO
* TODO

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

2026-03-13T01:02:42Z

Jcmonseu: /* Implementation */

== 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 ===

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.

<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

# 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>

=== How it works ===

* TODO: explain how reset tokens are generated
* TODO: explain how tokens are validated
* TODO: explain how passwords are updated securely

== Token Management ==

=== Purpose ===
Reset tokens allow the system to verify that the password reset request is legitimate.

Tokens typically have the following properties:

* unique per request
* difficult to guess
* time-limited
* associated with a specific user account

=== Implementation ===

Example structure:

<syntaxhighlight lang="rb">
def generate_reset_token
# TODO: create secure token
end

def token_valid?
# TODO: verify token existence
# TODO: check expiration
end
</syntaxhighlight>

=== How it works ===

* When a reset request is initiated, the system generates a token.
* The token is associated with the requesting user.
* The token is included in the password reset link.
* When the user submits a new password, the token is verified.

If validation fails, the reset attempt is rejected.

== Updating the Password ==

=== Purpose ===
After the reset token has been verified, the system allows the user to submit a new password.

=== Implementation ===

<syntaxhighlight lang="rb">
def update_password
# TODO: validate token
# TODO: validate password rules
# TODO: save updated credentials
end
</syntaxhighlight>

=== How it works ===

* The system confirms that the reset request is valid.
* Password requirements are checked.
* The new password is stored securely.
* The reset token is invalidated to prevent reuse.

== 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

To mitigate these risks, the system may include:

* TODO: token expiration
* TODO: rate limiting
* TODO: secure password hashing
* TODO: audit logging

== Routing ==

Example routing structure for password reset operations:

<syntaxhighlight lang="rb">
resources :password_resets do
collection do
post :request_reset
end

member do
patch :reset_password
end
end
</syntaxhighlight>

TODO: Modify routing according to the project's implementation.

== Testing Strategy ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

== Collaborators ==

* TODO
* TODO
* TODO
* TODO

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

2026-03-13T01:00:52Z

Jcmonseu: /* Implementation */

== 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 ===

TODO: Describe where the password reset logic is implemented.

Example structure:

<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

# 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>

=== How it works ===

* TODO: explain how reset tokens are generated
* TODO: explain how tokens are validated
* TODO: explain how passwords are updated securely

== Token Management ==

=== Purpose ===
Reset tokens allow the system to verify that the password reset request is legitimate.

Tokens typically have the following properties:

* unique per request
* difficult to guess
* time-limited
* associated with a specific user account

=== Implementation ===

Example structure:

<syntaxhighlight lang="rb">
def generate_reset_token
# TODO: create secure token
end

def token_valid?
# TODO: verify token existence
# TODO: check expiration
end
</syntaxhighlight>

=== How it works ===

* When a reset request is initiated, the system generates a token.
* The token is associated with the requesting user.
* The token is included in the password reset link.
* When the user submits a new password, the token is verified.

If validation fails, the reset attempt is rejected.

== Updating the Password ==

=== Purpose ===
After the reset token has been verified, the system allows the user to submit a new password.

=== Implementation ===

<syntaxhighlight lang="rb">
def update_password
# TODO: validate token
# TODO: validate password rules
# TODO: save updated credentials
end
</syntaxhighlight>

=== How it works ===

* The system confirms that the reset request is valid.
* Password requirements are checked.
* The new password is stored securely.
* The reset token is invalidated to prevent reuse.

== 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

To mitigate these risks, the system may include:

* TODO: token expiration
* TODO: rate limiting
* TODO: secure password hashing
* TODO: audit logging

== Routing ==

Example routing structure for password reset operations:

<syntaxhighlight lang="rb">
resources :password_resets do
collection do
post :request_reset
end

member do
patch :reset_password
end
end
</syntaxhighlight>

TODO: Modify routing according to the project's implementation.

== Testing Strategy ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

== Collaborators ==

* TODO
* TODO
* TODO
* TODO

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

2026-03-13T00:54:08Z

Jcmonseu: /* Purpose */

== 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 ===

TODO: Describe where the password reset logic is implemented.

Example structure:

<syntaxhighlight lang="rb">
def request_password_reset
# TODO: locate user account
# TODO: generate secure reset token
# TODO: send reset instructions
end

def reset_password
# TODO: validate token
# TODO: update password
end
</syntaxhighlight>

=== How it works ===

* TODO: explain how reset tokens are generated
* TODO: explain how tokens are validated
* TODO: explain how passwords are updated securely

== Token Management ==

=== Purpose ===
Reset tokens allow the system to verify that the password reset request is legitimate.

Tokens typically have the following properties:

* unique per request
* difficult to guess
* time-limited
* associated with a specific user account

=== Implementation ===

Example structure:

<syntaxhighlight lang="rb">
def generate_reset_token
# TODO: create secure token
end

def token_valid?
# TODO: verify token existence
# TODO: check expiration
end
</syntaxhighlight>

=== How it works ===

* When a reset request is initiated, the system generates a token.
* The token is associated with the requesting user.
* The token is included in the password reset link.
* When the user submits a new password, the token is verified.

If validation fails, the reset attempt is rejected.

== Updating the Password ==

=== Purpose ===
After the reset token has been verified, the system allows the user to submit a new password.

=== Implementation ===

<syntaxhighlight lang="rb">
def update_password
# TODO: validate token
# TODO: validate password rules
# TODO: save updated credentials
end
</syntaxhighlight>

=== How it works ===

* The system confirms that the reset request is valid.
* Password requirements are checked.
* The new password is stored securely.
* The reset token is invalidated to prevent reuse.

== 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

To mitigate these risks, the system may include:

* TODO: token expiration
* TODO: rate limiting
* TODO: secure password hashing
* TODO: audit logging

== Routing ==

Example routing structure for password reset operations:

<syntaxhighlight lang="rb">
resources :password_resets do
collection do
post :request_reset
end

member do
patch :reset_password
end
end
</syntaxhighlight>

TODO: Modify routing according to the project's implementation.

== Testing Strategy ==

=== 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

=== Model Tests ===

Model tests may verify:

* TODO: token generation
* TODO: token expiration behavior
* TODO: password validation rules

=== Controller Tests ===

Controller tests verify:

* TODO: reset request creation
* TODO: reset token validation
* TODO: successful password update
* TODO: rejection of invalid requests

=== Security Tests ===

Security tests ensure that:

* invalid tokens are rejected
* expired tokens cannot be used
* password updates require valid authentication

== Collaborators ==

* TODO
* TODO
* TODO
* TODO