mirror of
https://github.com/apidoorman/doorman.git
synced 2026-02-10 11:38:32 -06:00
109 lines
4.8 KiB
Markdown
109 lines
4.8 KiB
Markdown
# Operations Guide (Doorman Gateway)
|
|
|
|
This document summarizes production configuration, deployment runbooks, and key operational endpoints for Doorman.
|
|
|
|
## Environment Configuration
|
|
|
|
Recommended production defaults (see `.env`):
|
|
|
|
- HTTPS_ONLY=true — set `Secure` flag on cookies
|
|
- HTTPS_ENABLED=true — enforce CSRF double-submit for cookie auth
|
|
- CORS_STRICT=true — disallow wildcard origins; whitelist your domains via `ALLOWED_ORIGINS`
|
|
- LOG_FORMAT=json — optional JSON log output for production log pipelines
|
|
- MAX_BODY_SIZE_BYTES=1048576 — reject requests with Content-Length above 1 MB
|
|
- STRICT_RESPONSE_ENVELOPE=true — platform APIs return consistent envelopes
|
|
|
|
Unified cache/DB flags:
|
|
|
|
- MEM_OR_EXTERNAL=MEM|REDIS — unified flag for cache/DB mode
|
|
- MEM_OR_REDIS — deprecated alias still accepted for backward compatibility
|
|
|
|
JWT/Token encryption:
|
|
|
|
- JWT_SECRET_KEY — REQUIRED; gateway fails fast if missing at startup
|
|
- TOKEN_ENCRYPTION_KEY — recommended; encrypts stored API keys and user API keys at rest
|
|
|
|
Core variables:
|
|
|
|
- ALLOWED_ORIGINS — comma-separated list of allowed origins
|
|
- ALLOW_CREDENTIALS — set to true only with explicit origins
|
|
- ALLOW_METHODS, ALLOW_HEADERS — scope to what you need
|
|
- JWT_SECRET_KEY — rotate periodically; store in a secret manager
|
|
- MEM_OR_REDIS — MEM or REDIS depending on cache backing
|
|
- MONGO_DB_HOSTS, MONGO_REPLICA_SET_NAME — enable DB in non-memory mode
|
|
|
|
## Security
|
|
|
|
- Cookies: access_token_cookie is HttpOnly; set Secure via HTTPS_ONLY. CSRF cookie (`csrf_token`) issued on login/refresh.
|
|
- CSRF: when HTTPS_ENABLED=true, clients must include `X-CSRF-Token` header matching `csrf_token` cookie on protected endpoints.
|
|
- CORS: avoid wildcard with credentials; use explicit allowlists.
|
|
- Logging: includes redaction filter to reduce token/password leakage. Avoid logging PII.
|
|
- Rate limiting: Redis-based limiter; if Redis is unavailable the gateway falls back to a process-local in-memory limiter (non-distributed). Configure user limits in DB/role as needed.
|
|
- Request limits: global Content-Length check; per-route multipart (proto upload) size limits via MAX_MULTIPART_SIZE_BYTES.
|
|
- Response envelopes: `STRICT_RESPONSE_ENVELOPE=true` makes platform API responses consistent for client parsing.
|
|
|
|
## Health and Monitoring
|
|
|
|
- Liveness: `GET /platform/monitor/liveness` → `{ status: "alive" }`
|
|
- Readiness: `GET /platform/monitor/readiness` → `{ status, mongodb, redis }`
|
|
- Metrics: `GET /platform/monitor/metrics?range=24h` (auth required; manage_gateway)
|
|
- Logging: `/platform/logging/*` endpoints; requires `view_logs`/`export_logs`
|
|
|
|
## Deployment
|
|
|
|
1. Configure `.env` with production values (see above) or environment variables.
|
|
2. Run behind an HTTPS-capable reverse proxy (or enable HTTPS in-process with `HTTPS_ONLY=true` and valid certs).
|
|
3. Set ALLOWED_ORIGINS to your web client domains; set ALLOW_CREDENTIALS=true only when needed.
|
|
4. Provision Redis (recommended) and MongoDB (optional in memory-only mode). In memory mode, enable encryption key for dumps and consider TOKEN_ENCRYPTION_KEY for API keys.
|
|
5. Rotate JWT_SECRET_KEY periodically; plan for key rotation and token invalidation.
|
|
6. Memory-only mode requires a single worker (THREADS=1); multiple workers will have divergent in-memory state.
|
|
|
|
## Runbooks
|
|
|
|
- Restarting gateway:
|
|
- Graceful stop writes a final encrypted memory dump in memory-only mode.
|
|
- Token leakage suspect:
|
|
- Invalidate tokens (`/platform/authorization/invalidate`), rotate JWT secret if necessary, audit logs (redaction is best-effort).
|
|
- Elevated error rates:
|
|
- Check readiness endpoint; verify Redis/Mongo health; inspect logs via `/platform/logging/logs`.
|
|
- CORS failures:
|
|
- Verify ALLOWED_ORIGINS and CORS_STRICT settings; avoid `*` with credentials.
|
|
- Use Tools → CORS Checker (or POST `/platform/tools/cors/check`) to simulate preflight/actual decisions and view effective headers.
|
|
- CSRF errors:
|
|
- Ensure clients set `X-CSRF-Token` header to value of `csrf_token` cookie when HTTPS_ENABLED=true.
|
|
|
|
## Notes
|
|
|
|
- Gateway (proxy) responses can be optionally wrapped by STRICT_RESPONSE_ENVELOPE; confirm client contracts before enabling globally in front of external consumers.
|
|
- Prefer Authorization: Bearer header for external API consumers to reduce CSRF surface.
|
|
- User profile constraint: `custom_attributes` is limited to 10 key/value pairs per user. API returns HTTP 400 `USR016` if exceeded; UI prevents adding beyond 10.
|
|
|
|
## Strict Envelope Examples
|
|
|
|
When `STRICT_RESPONSE_ENVELOPE=true`, platform endpoints return a consistent structure.
|
|
|
|
- Success (200):
|
|
```
|
|
{
|
|
"status_code": 200,
|
|
"response": { "key": "value" }
|
|
}
|
|
```
|
|
|
|
- Created (201):
|
|
```
|
|
{
|
|
"status_code": 201,
|
|
"message": "Resource created successfully"
|
|
}
|
|
```
|
|
|
|
- Error (400/403/404):
|
|
```
|
|
{
|
|
"status_code": 403,
|
|
"error_code": "ROLE009",
|
|
"error_message": "You do not have permission to create roles"
|
|
}
|
|
```
|