maksit-certs-ui/assets/docs/LOGIN_AND_REFRESH_TOKEN_ARCHITECTURE.md

Login and Refresh Token Architecture

This document describes how authentication (login), token refresh, and logout work across the MaksIT.CertsUI WebAPI and WebUI.

Audience: Backend (C# / ASP.NET) and Frontend (TypeScript / React) developers.

MaksIT.CertsUI persists users and refresh tokens in PostgreSQL. Shared MaksIT.Models types may include optional 2FA fields; behavior follows this WebAPI and WebUI implementation.

---

1. Overview

• Access token: Short-lived JWT used in the Authorization: Bearer <token> header for API calls.
• Refresh token: Opaque string stored with the user in PostgreSQL; used to obtain a new access token (and optionally a new refresh token) when the access token expires.
• Login returns both tokens; the client stores them and uses the access token until it expires, then calls refresh with the refresh token.
• Logout revokes the current session (or all sessions) on the server and clears tokens on the client. On Certs, logout requires Authorization: Bearer with the current access JWT; the server matches that token when removing the session (see §3.4).

---

2. Token model

2.1 Backend: JwtToken (domain)

Location: src/MaksIT.CertsUI/Domain/JwtToken.cs

Property	Type	Description
Id	Guid	Token identifier.
Token	string	The JWT access token string.
TokenType	string	Typically "Bearer".
IssuedAt	DateTime	When the token was issued (UTC).
ExpiresAt	DateTime	When the access token expires.
RefreshToken	string	Opaque refresh token.
RefreshTokenExpiresAt	DateTime	When the refresh token expires.
IsRevoked	bool	If true, token is treated as unusable (revoked entries are removed when resolving refresh).

• A User holds a list of JwtToken instances (multiple devices/sessions).
• New tokens are upserted via User.UpsertJwtToken.

2.2 API response: LoginResponse

Location: src/MaksIT.Models/LetsEncryptServer/Identity/Login/LoginResponse.cs

Returned by login and refresh:

• TokenType (e.g. "Bearer")
• Token (access JWT)
• ExpiresAt (access token expiry)
• RefreshToken
• RefreshTokenExpiresAt

There is no Username field on this model; the WebUI derives display name from JWT claims when hydrating identity (identitySlice).

---

3. Backend flow

3.1 Layers

Layer	Component	Responsibility
API	IdentityController	Login, refresh, logout, and authenticated PATCH user.
Service	IdentityService	Validates credentials, issues JWTs via JwtGenerator, maps domain JwtToken to LoginResponse, persists users via IUserStore.
Domain	User	Password validation, JWT token list (upsert/remove/revoke).
Persistence	IUserStore	Users and JWT rows persist in PostgreSQL.

3.2 Login

Endpoint: POST /api/identity/login
Controller: IdentityController.Login → IdentityService.LoginAsync

1. Resolve user by username (IUserStore.GetByNameAsync).
2. Validate password (User.ValidatePassword) with configured pepper.
3. Optional 2FA fields on LoginRequest are not validated by Certs—ignored if sent.
4. Generate access JWT via JwtGenerator.TryGenerateToken (secret, issuer, audience, expiration from config).
5. Generate opaque refresh token and build a domain JwtToken with access + refresh expiry (RefreshExpiration from config).
6. Upsert token on user, SetLastLogin, IIdentityPersistenceService.WriteAsync.
7. Return LoginResponse (no username field; client uses JWT claims).

Request body (LoginRequest): username, password, optional unused twoFactorCode / twoFactorRecoveryCode (shared model shape only).

3.3 Refresh

Endpoint: POST /api/identity/refresh
Controller: IdentityController.RefreshToken → IdentityService.RefreshTokenAsync

Request body (RefreshTokenRequest): refreshToken only (src/MaksIT.Models/LetsEncryptServer/Identity/Login/RefreshTokenRequest.cs). The WebUI may send a force flag for parity with shared thunk code; the Certs API model does not include it (extra properties are typically ignored by the serializer).

1. Resolve user by refresh token (IUserStore.GetByRefreshTokenAsync).
2. Remove revoked JWT rows (RemoveRevokedJwtTokens).
3. Find the token where RefreshToken matches.
4. Unauthorized if not found → e.g. “Invalid refresh token.”
5. If the access token is still valid (UtcNow <= token.ExpiresAt): update last login, WriteAsync, return the same LoginResponse (no new JWT). This API does not implement a server-side force refresh path.
6. If access expired but refresh is still valid (UtcNow <= RefreshTokenExpiresAt): issue a new access JWT + new refresh token, upsert token, save, return new LoginResponse.
7. If refresh is expired: remove that token record, return 401 “Refresh token has expired.”

3.4 Logout

Endpoint: POST /api/identity/logout (requires JwtAuthorizationFilter — send Authorization: Bearer)
Controller: IdentityController.Logout → IdentityService.Logout

1. Resolve user by access JWT from the validated Bearer token (GetByAccessTokenAsync / token string from JWT context).
2. If found: LogoutFromAllDevices → RevokeAllJwtTokens(); else → RemoveJwtToken(accessToken) for the current session.
3. WriteAsync if the user was updated.
4. Return success (implementation may still return OK if the token was unknown—clients should clear local state regardless).

Request body (LogoutRequest): token (access JWT, for shared model parity), logoutFromAllDevices — the server uses the Bearer access token for lookup.

---

4. Frontend flow

4.1 Identity state and storage

Redux: identitySlice (src/MaksIT.WebUI/src/redux/slices/identitySlice.ts)

• State: identity: Identity | null, hydrated: boolean, status, showUserOffcanvas.
• Persistence: Login/refresh responses are written to localStorage via writeIdentity; on load, setIdentityFromLocalStorage reads and hydrates state and enriches from JWT claims (userId, username, roles, isGlobalAdmin, acls when those claims exist).

Identity type extends LoginResponse with client-side fields: userId, username, roles, isGlobalAdmin, acls.

4.2 Login UI

Component: LoginScreen (src/MaksIT.WebUI/src/components/LoginScreen.tsx)

• Form: username and password; 2FA inputs are commented out until the backend supports them.
• On submit: dispatch(login(loginRequest)).
• On successful login, identitySlice stores the response in state and localStorage; LoginScreen redirects when identity is present and refresh token is not expired.

4.3 Route protection

Component: Authorization (src/MaksIT.WebUI/src/components/Authorization.tsx)

• Wraps protected routes.
• On mount, if not hydrated, dispatches setIdentityFromLocalStorage().
• When hydrated: if identity is missing or refreshTokenExpiresAt is in the past, redirects to /login (with state.from for return URL).
• Renders children only when hydrated and refresh token is not expired.

Refresh token expiry is what forces re-login; the access token may expire while refresh is still valid (handled by axios).

4.4 Axios: token attachment and refresh

File: src/MaksIT.WebUI/src/axiosConfig.ts

• Excluded URLs (no Bearer token, no refresh loop): login and refresh routes (GetApiRoute(ApiRoutes.identityLogin).route, GetApiRoute(ApiRoutes.identityRefresh).route).
• Request interceptor: If access token is expired but refresh is still valid by client clock, await a single shared refreshJwt(); on success attach new Authorization; on failure dispatch clearIdentity() and reject (do not send protected calls with an expired access token).
• Response interceptor: On 401, optionally retry once after refresh when refresh is still valid; on refresh failure, clearIdentity().
• Serialization: isRefreshing / refreshPromise so concurrent requests share one refresh.

4.5 Async thunks and clearIdentity

• login: POST login; on success writes identity and enriches from JWT.
• refreshJwt(force?): POST refresh with refreshToken (and optional force in body for shared code paths; server ignores force on Certs). On failure, identity cleared.
• logout: POST logout with access token in body, then clear state/localStorage.
• clearIdentity(): Clears Redux and localStorage without calling logout API (used when refresh fails).

---

5. API summary

Method	Endpoint	Bearer required	Purpose
POST	/api/identity/login	No	Login; returns access + refresh token.
POST	/api/identity/refresh	No	Exchange refresh token for same or new tokens.
POST	/api/identity/logout	Yes	Revoke session(s); Bearer identifies the access token to remove.

Other identity routes (e.g. PATCH /api/identity/user/{id}) use JwtAuthorizationFilter and require a valid JWT.

Base route: api/identity (IdentityController, AppMap).

---

6. Sequence overview

Login: User submits credentials → POST /api/identity/login → user row updated with new JwtToken in PostgreSQL → WebUI stores identity → redirect into app.

Authenticated request (access token valid): Interceptor adds Authorization: Bearer → API validates JWT.

Access expired, refresh valid: Interceptor awaits refreshJwt() → POST /api/identity/refresh → updated identity → original request retried with new token.

401 on protected request: Response interceptor attempts refresh; if refresh returns 401, clearIdentity() and redirect to /login.

Logout: POST /api/identity/logout with Authorization: Bearer and body { token, logoutFromAllDevices } → server removes token(s) from the user row → client clears storage.

Use Certs resources in examples (e.g. accounts, certificate flows): no protected API should run after refresh has failed without clearing identity.

---

7. Security notes

• Passwords use salt + server-side pepper; not stored in plain text.
• Refresh tokens are stored per user in PostgreSQL; expiry and invalidation are enforced in IdentityService.RefreshTokenAsync.
• 2FA is not implemented on the Certs WebAPI; do not enable the WebUI 2FA fields until backend support exists.
• Login/refresh do not require Bearer; logout and other protected identity routes use JwtAuthorizationFilter.
• Frontend keeps one identity in localStorage; refresh is serialized to avoid duplicate refresh storms.

---

8. Key files reference

Area	File
Domain – User	src/MaksIT.CertsUI/Domain/User.cs
Domain – JwtToken	src/MaksIT.CertsUI/Domain/JwtToken.cs
API service	src/MaksIT.CertsUI/Services/IdentityService.cs
API controller	src/MaksIT.CertsUI/Controllers/IdentityController.cs
API models	src/MaksIT.Models/LetsEncryptServer/Identity/Login/, .../Logout/
Frontend – state	src/MaksIT.WebUI/src/redux/slices/identitySlice.ts
Frontend – HTTP	src/MaksIT.WebUI/src/axiosConfig.ts
Frontend – routes	src/MaksIT.WebUI/src/components/Authorization.tsx
Frontend – login UI	src/MaksIT.WebUI/src/components/LoginScreen.tsx
Frontend – API map	src/MaksIT.WebUI/src/AppMap.tsx