Dionisio
f2d35ca792
- JWT secret auto-generates and persists to <STORAGE_PATH>/.jwt_secret - Remove setup token: first admin setup is open until system initialized - Fix schema.sql: move CREATE EXTENSION pg_trgm/ltree to top - Update login UI and auth.js to remove setup token fields
150 lines
11 KiB
Markdown
Executable File
150 lines
11 KiB
Markdown
Executable File
# 29 - OIDC Architecture
|
|
|
|
OpenID Connect (OIDC) authentication follows the Authorization Code Flow. The system supports multiple identity providers (Authentik, Authelia, KeyCloak) through a single configurable integration point.
|
|
|
|
## Architecture Diagram
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ │
|
|
│ IDENTITY PROVIDER │
|
|
│ │
|
|
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ Authentik │ │ Authelia │ │ KeyCloak │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │
|
|
│ │ │ │ │
|
|
└────────────┼──────────────────────┼──────────────────────┼─────────────┘
|
|
│ │ │
|
|
│ │ │
|
|
│ │ │
|
|
│ OIDC │
|
|
│ │ │
|
|
│ │ │
|
|
┌────────────┼──────────────────────┼──────────────────────┼─────────────┐
|
|
│ │ │ │ │
|
|
│ ▼ ▼ ▼ │
|
|
│ ┌───────────────────────────────────────────────────────────────┐ │
|
|
│ │ │ │
|
|
│ │ OXICLOUD │ │
|
|
│ │ │ │
|
|
│ │ ┌───────────────┐ ┌───────────────┐ │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ │ OidcService │◄────►│ AuthService │ │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ └───────┬───────┘ └───────┬───────┘ │ │
|
|
│ │ │ │ │ │
|
|
│ │ ▼ ▼ │ │
|
|
│ │ ┌───────────────────────────────────────────┐ │ │
|
|
│ │ │ │ │ │
|
|
│ │ │ AuthApplicationService │ │ │
|
|
│ │ │ │ │ │
|
|
│ │ └───────────────────┬───────────────────────┘ │ │
|
|
│ │ │ │ │
|
|
│ │ ▼ │ │
|
|
│ │ ┌───────────────────────────────────────────┐ │ │
|
|
│ │ │ │ │ │
|
|
│ │ │ Auth Handler │ │ │
|
|
│ │ │ │ │ │
|
|
│ │ └───────────────────────────────────────────┘ │ │
|
|
│ │ │ │
|
|
│ └───────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|
▲
|
|
│
|
|
│ HTTP/HTTPS
|
|
│
|
|
│
|
|
┌────────────────────────────────────────────────────────────────────────┐
|
|
│ │
|
|
│ WEB BROWSER │
|
|
│ │
|
|
│ ┌───────────────────────────────────────────────────────────────┐ │
|
|
│ │ │ │
|
|
│ │ User Interface │ │
|
|
│ │ │ │
|
|
│ │ ┌──────────────┐ ┌──────────────┐ │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ │ Login.html │ │ auth.js │ │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ └──────────────┘ └──────────────┘ │ │
|
|
│ │ │ │
|
|
│ └───────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
└────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## OIDC Authentication Flow
|
|
|
|
The flow follows the standard Authorization Code Flow:
|
|
|
|
1. **Authentication Start** -- the user clicks "Login with [Provider]" on the login page. The frontend generates a random state for CSRF protection and requests an authorization URL from the backend.
|
|
|
|
2. **Redirect to Identity Provider** -- the backend generates and returns the authorization URL. The browser redirects the user to the provider's login page.
|
|
|
|
3. **Authentication at the Provider** -- the user authenticates (password, 2FA, etc.). The provider redirects back with an authorization code.
|
|
|
|
4. **Authorization Code Exchange** -- the frontend sends the authorization code to the backend. The backend exchanges it for access and ID tokens with the provider, then verifies the ID token and extracts user info.
|
|
|
|
5. **User Creation/Retrieval** -- the backend looks up an existing user by the provider's external ID. If none exists and auto-provisioning is enabled, a new user is created. If disabled, an error is returned.
|
|
|
|
6. **Session Token Generation** -- the backend generates its own access and refresh tokens for the user. These tokens authenticate subsequent API requests.
|
|
|
|
7. **Response to Client** -- tokens and user info are returned to the frontend. The frontend stores them and redirects to the main page.
|
|
|
|
## Main Components
|
|
|
|
### OidcService
|
|
|
|
Handles communication with OIDC providers:
|
|
- Discovers provider OIDC endpoints
|
|
- Generates authorization URLs
|
|
- Exchanges authorization codes for tokens
|
|
- Verifies tokens and extracts user info
|
|
|
|
### AuthApplicationService
|
|
|
|
Coordinates the authentication process:
|
|
- Acts as interface between the API layer and domain services
|
|
- Manages user creation/retrieval
|
|
- Coordinates access token generation
|
|
|
|
### Auth Handler
|
|
|
|
Exposes HTTP endpoints for the OIDC auth flow:
|
|
- `GET /api/auth/oidc/providers` -- lists available OIDC providers
|
|
- `GET /api/auth/oidc/authorize` -- generates an authorization URL for the OIDC provider
|
|
- `GET /api/auth/oidc/callback` -- receives the redirect from the provider with the authorization code
|
|
- `POST /api/auth/oidc/exchange` -- exchanges the authorization code for session tokens
|
|
|
|
### Frontend (login.html + auth.js)
|
|
|
|
Handles the client-side of the auth flow:
|
|
- Shows SSO button for the configured OIDC provider in `login.html`
|
|
- Initiates the authentication flow via `auth.js`
|
|
- Handles the return redirect from the provider
|
|
- Processes and stores session tokens
|
|
|
|
## Provider Configuration
|
|
|
|
One OIDC provider is configured per instance via environment variables prefixed with **OXICLOUD_OIDC_***:
|
|
|
|
1. **Single provider** per instance.
|
|
2. **Environment variables**: **OXICLOUD_OIDC_ENABLED**, **OXICLOUD_OIDC_ISSUER_URL**, **OXICLOUD_OIDC_CLIENT_ID**, **OXICLOUD_OIDC_CLIENT_SECRET**, etc.
|
|
3. **Auto-provisioning**: users can be created automatically on first OIDC login (**OXICLOUD_OIDC_AUTO_PROVISION**).
|
|
4. **Role mapping**: admin groups are configured via **OXICLOUD_OIDC_ADMIN_GROUPS**.
|
|
|
|
See `oidc-config-examples.md` for provider-specific configuration examples.
|
|
|
|
## Security
|
|
|
|
The OIDC implementation includes several security measures:
|
|
|
|
1. **CSRF protection** -- random state parameter prevents CSRF attacks.
|
|
2. **Token validation** -- JWT signatures and expiration are verified.
|
|
3. **Authorization Code Flow** -- more secure than the implicit flow.
|
|
4. **HTTPS** -- required for all OIDC communications.
|
|
5. **Client secrets** -- stored securely, never exposed to the frontend.
|