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.

Related: This repo’s WebUI identity layer is aligned with MaksIT-Vault LOGIN_AND_REFRESH_TOKEN_ARCHITECTURE.md when both projects sit side by side under the same parent folder; otherwise open that path in your Vault clone. Vault documents 2FA, API-key RBAC, and a database-backed user store. MaksIT.CertsUI uses a settings-backed user list, no 2FA on the backend (optional LoginRequest fields exist for shared models but are ignored; the WebUI 2FA inputs are commented out), and no Vault-style ACL product surface—JWT may still carry role/ACL claims for shared MaksIT.Core JWT helpers, but Certs is not an ACL administration app.

---

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 settings; 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, the logout HTTP endpoint does not require a Authorization header; it identifies the session via the access token in the JSON body (see §3.4).

---

2. Token model

2.1 Backend: JwtToken (domain)

Location: src/MaksIT.Webapi/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	Loads/saves settings, validates credentials, issues JWTs via JwtGenerator, maps domain JwtToken to LoginResponse.
Domain	User	Password validation, JWT token list (upsert/remove/revoke).
Persistence	ISettingsService	Users and tokens persist in application settings (not a separate identity database).

3.2 Login

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

1. Load settings via ISettingsService.LoadAsync.
2. Resolve user by username (GetUserByName).
3. Validate password (User.ValidatePassword) with configured pepper.
4. Optional 2FA fields on LoginRequest are not validated by Certs—ignored if sent.
5. Generate access JWT via JwtGenerator.TryGenerateToken (secret, issuer, audience, expiration from config).
6. Generate opaque refresh token and build a domain JwtToken with access + refresh expiry (RefreshExpiration from config).
7. Upsert token on user, SetLastLogin, persist settings.
8. 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. Load settings.
2. Resolve user by refresh token (GetByRefreshToken).
3. Remove revoked JWT rows (RemoveRevokedJwtTokens).
4. Find the token where RefreshToken matches.
5. Unauthorized if not found → e.g. “Invalid refresh token.”
6. If the access token is still valid (UtcNow <= token.ExpiresAt): update last login, save settings, return the same LoginResponse (no new JWT). There is no server-side force refresh path like Vault.
7. If access expired but refresh is still valid (UtcNow <= RefreshTokenExpiresAt): issue a new access JWT + new refresh token, upsert token, save, return new LoginResponse.
8. If refresh is expired: remove that token record, return 401 “Refresh token has expired.”

3.4 Logout

Endpoint: POST /api/identity/logout (no JwtAuthorizationFilter on this action)
Controller: IdentityController.Logout → IdentityService.Logout

1. Load settings.
2. Resolve user by access JWT string in the body (LogoutRequest.Token) via GetByJwtToken.
3. If found: LogoutFromAllDevices → RevokeAllJwtTokens(); else → RemoveJwtToken(token) for the current session.
4. Persist settings if the user was updated.
5. Return success (implementation may still return OK if the token was unknown—clients should clear local state regardless).

Request body (LogoutRequest): token (access JWT), logoutFromAllDevices.

The WebUI sends the current access token from stored identity; it does not rely on a Bearer header for this route.

---

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	No	Revoke session(s) using access token in body.

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 → settings updated with new JwtToken → 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 body { token, logoutFromAllDevices } → server removes token(s) from settings → client clears storage.

Replace illustrative “organizations” examples in Vault with Certs resources (e.g. accounts, certificate flows)—the mechanism is the same: 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 settings; 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; other protected controllers 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.Webapi/Domain/User.cs
Domain – JwtToken	src/MaksIT.Webapi/Domain/JwtToken.cs
API service	src/MaksIT.Webapi/Services/IdentityService.cs
API controller	src/MaksIT.Webapi/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