203 lines
6.1 KiB
Markdown
203 lines
6.1 KiB
Markdown
# Authentication & Security
|
|
|
|
This document covers how the API handles authentication, token lifecycle, and access control.
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
The API uses **JWE (JSON Web Encryption)** tokens — AES-256-GCM encrypted — rather than plain signed JWTs. Clients cannot inspect token claims. The flow is stateless: no server-side sessions. All state is carried in tokens or stored in MongoDB.
|
|
|
|
Two token types are in play:
|
|
|
|
| Token | Lifetime | Purpose |
|
|
|---|---|---|
|
|
| Access token | 1 hour | Authenticate API requests via `Authorization: Bearer` |
|
|
| Refresh token | 30 days | Exchange for a new access token without re-logging in |
|
|
|
|
---
|
|
|
|
## Token Structure
|
|
|
|
Both token types share a base structure but carry a `type` claim (`"access"` or `"refresh"`) that prevents cross-use — the API rejects a refresh token presented as a Bearer token and vice versa.
|
|
|
|
**Access token claims:**
|
|
|
|
| Claim | Value |
|
|
|---|---|
|
|
| `sub` | User email |
|
|
| `type` | `"access"` |
|
|
| `authorities` | Array of roles, e.g. `["ROLE_USER"]` |
|
|
| `jti` | UUIDv7 — unique token ID used for revocation lookup |
|
|
| `iat` / `exp` / `iss` | Standard JWT timestamps and issuer |
|
|
|
|
**Refresh token claims:** `sub`, `type`, `jti`, `iat`, `exp`, `iss` (no `authorities`).
|
|
|
|
**Encryption:** `JWE` with `dir` key management and `A256GCM` content encryption, keyed from `JWT_ENCRYPTION_SECRET` (Base64-encoded 32-byte AES key).
|
|
|
|
---
|
|
|
|
## Authentication Flow
|
|
|
|
### Login
|
|
|
|
```
|
|
POST /v1/auth/login
|
|
Content-Type: application/json
|
|
|
|
{ "email": "user@example.com", "password": "..." }
|
|
```
|
|
|
|
1. User is looked up by email in MongoDB.
|
|
2. Password is verified via Argon2 (memory-hard, GPU-resistant).
|
|
3. A new access token and a refresh token family are created.
|
|
4. Both tokens are returned.
|
|
|
|
```json
|
|
{
|
|
"accessToken": "<jwe>",
|
|
"refreshToken": "<jwe>",
|
|
"tokenType": "Bearer",
|
|
"expiresIn": 3600
|
|
}
|
|
```
|
|
|
|
Authentication errors always return `401` regardless of whether the email exists, to prevent account enumeration.
|
|
|
|
### Using the Access Token
|
|
|
|
Pass the access token in every request to a protected endpoint:
|
|
|
|
```
|
|
Authorization: Bearer <accessToken>
|
|
```
|
|
|
|
The `JwtAuthenticationFilter` runs on every request:
|
|
1. Extracts and decrypts the Bearer token.
|
|
2. Checks the token's `jti` against the MongoDB revocation blocklist.
|
|
3. Loads the user and sets the security context.
|
|
4. Unauthenticated requests pass through; endpoint authorization rules handle the rejection.
|
|
|
|
### Token Refresh
|
|
|
|
```
|
|
POST /v1/auth/refresh
|
|
Content-Type: application/json
|
|
|
|
{ "refreshToken": "<jwe>" }
|
|
```
|
|
|
|
Returns a new access token and a new refresh token. The old refresh token is immediately invalidated. See [Refresh Token Rotation & Theft Detection](#refresh-token-rotation--theft-detection) below.
|
|
|
|
### Logout
|
|
|
|
```
|
|
POST /v1/auth/logout
|
|
Authorization: Bearer <accessToken>
|
|
```
|
|
|
|
1. The current access token's `jti` is added to the revocation blocklist.
|
|
2. All refresh tokens for the user are revoked.
|
|
|
|
The blocklist entry lives until the access token's own `exp`, then MongoDB TTL removes it automatically — the blocklist never grows unboundedly.
|
|
|
|
---
|
|
|
|
## Refresh Token Rotation & Theft Detection
|
|
|
|
Every login starts a **token family** (tracked by `familyId`). Each refresh produces a new token in the same family; the previous token is marked revoked.
|
|
|
|
**Theft detection:** If a refresh token is presented and it's already marked revoked, but its family still has an active sibling, the system infers a stolen token was reused:
|
|
|
|
1. The entire token family is revoked (all active sessions from that login).
|
|
2. A security event is logged with the attacker's IP.
|
|
3. Both the legitimate owner and the attacker are forced to re-authenticate.
|
|
|
|
If a revoked token's family has no active siblings, it's treated as a simple re-consumption (returns `401` without the family wipe).
|
|
|
|
**Session limits:** Each user may have at most 5 active refresh token families (concurrent sessions). When the limit is reached, the oldest session is automatically revoked.
|
|
|
|
---
|
|
|
|
## Roles & Access Control
|
|
|
|
Two roles are defined:
|
|
|
|
| Role | Description |
|
|
|---|---|
|
|
| `ROLE_USER` | Default for all registered accounts |
|
|
| `ROLE_ADMIN` | Required for user management operations |
|
|
|
|
Authorization is enforced at two levels:
|
|
- **Route level** — `SecurityConfig` permits public routes and rejects unauthenticated requests to protected ones.
|
|
- **Method level** — `@PreAuthorize("hasRole('ROLE_ADMIN')")` on admin controllers.
|
|
|
|
**Endpoint authorization summary:**
|
|
|
|
| Endpoint | Auth | Role |
|
|
|---|---|---|
|
|
| `POST /v1/auth/login` | — | — |
|
|
| `POST /v1/auth/refresh` | — | — |
|
|
| `POST /v1/auth/logout` | Bearer | Any |
|
|
| `GET /v1/users/me` | Bearer | Any |
|
|
| `GET /v1/users` | Bearer | `ROLE_ADMIN` |
|
|
| `POST /v1/admin/users` | Bearer | `ROLE_ADMIN` |
|
|
| `GET /v1/health` | — | — |
|
|
|
|
---
|
|
|
|
## Password Storage
|
|
|
|
Passwords are hashed with **Argon2** via the `password4j` library. Only the hash is stored; plaintext is never persisted. Comparison uses constant-time evaluation.
|
|
|
|
---
|
|
|
|
## MongoDB Collections
|
|
|
|
| Collection | Purpose | TTL |
|
|
|---|---|---|
|
|
| `users` | User accounts (email unique-indexed) | — |
|
|
| `refresh_tokens` | Active and revoked refresh tokens (hash-stored, not plaintext) | `expiresAt` |
|
|
| `revoked_access_tokens` | Access token blocklist by `jti` | `expiresAt` |
|
|
|
|
TTL indexes on `expiresAt` in both token collections ensure automatic cleanup with no manual housekeeping.
|
|
|
|
---
|
|
|
|
## Error Responses
|
|
|
|
All errors return a consistent structure:
|
|
|
|
```json
|
|
{
|
|
"status": 401,
|
|
"message": "Invalid credentials",
|
|
"path": "/v1/auth/login"
|
|
}
|
|
```
|
|
|
|
| Scenario | Status |
|
|
|---|---|
|
|
| Bad credentials / unknown email | `401` |
|
|
| Invalid or expired token | `401` |
|
|
| Token reuse / security breach | `401` |
|
|
| Authenticated but insufficient role | `403` |
|
|
| Validation error | `400` |
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
| Variable | Description |
|
|
|---|---|
|
|
| `JWT_ENCRYPTION_SECRET` | Base64-encoded 32-byte AES key (required) |
|
|
| `jwt.access-token-expiration` | Access token TTL in ms (default: `3600000` — 1 hour) |
|
|
| `jwt.refresh-token-expiration` | Refresh token TTL in ms (default: `2592000000` — 30 days) |
|
|
| `jwt.issuer` | Issuer claim value (default: `kotlin-api`) |
|
|
|
|
Generate a secret:
|
|
|
|
```bash
|
|
openssl rand -base64 32 | tr -d '\n'
|
|
```
|