Security hardening
With DEBUG=false, identity-service turns on HTTPS redirects, HSTS, secure cookies, TLS to PostgreSQL, and rate limits. This page lists those defaults, and the few settings you must adapt to your deployment: trusted proxies and, optionally, CORS.
Rate limiting
Abuse-prone endpoints are rate limited, with counters in the shared cache (Redis):
| Scope | Default | Endpoints | Variable |
|---|---|---|---|
oauth | 30 per minute per IP | /api/v1/authorize, OAuth callback, confirm, exchange, provider login | AUTH_RATE_LIMIT_OAUTH |
mcp_register | 10 per hour per IP | POST /oauth/mcp/register (dynamic client registration) | AUTH_RATE_LIMIT_MCP_REGISTER |
mcp_signin | 30 per 5 minutes per IP | GET/POST /oauth/mcp/signin | AUTH_RATE_LIMIT_MCP_SIGNIN |
token_refresh | 60 per minute per IP | POST /api/v1/token?grant_type=refresh_token | AUTH_RATE_LIMIT_TOKEN_REFRESH |
auth_settings | 30 per minute per IP | GET /api/v1/settings | AUTH_RATE_LIMIT_SETTINGS |
magic_link | 10 per minute | POST /api/v1/magic-link/request, per IP, per email, and per company | AUTH_RATE_LIMIT_MAGIC_LINK |
token_exchange | 30 per minute per IP | POST /oauth/token with the token exchange grant (region role) | AUTH_RATE_LIMIT_TOKEN_EXCHANGE |
invitation | 30 per 5 minutes per company | POST /api/v1/invitations | AUTH_RATE_LIMIT_INVITATION |
admin_login | 10 per 5 minutes per IP | POST /admin/login/ | AUTH_RATE_LIMIT_ADMIN_LOGIN |
pat | 30 per minute per user | GET and POST /api/v1/personal-access-tokens, revoke | AUTH_RATE_LIMIT_PAT |
AUTH_RATE_LIMIT_ENABLED=false turns all limits off. Do not do this in production.
HTTPS and cookies
With DEBUG=false, these settings default to on. Each can be overridden with an environment variable of the same name (see .env.example):
| Setting | Default in production |
|---|---|
SECURE_SSL_REDIRECT | true: redirects HTTP to HTTPS. Turn it off only behind a TLS proxy that already redirects |
SECURE_HSTS_SECONDS | 31536000 (one year), with SECURE_HSTS_INCLUDE_SUBDOMAINS=true |
SESSION_COOKIE_SECURE, CSRF_COOKIE_SECURE | true. Cookie names are then __Host-sessionid and __Host-csrftoken. CSRF_COOKIE_HTTPONLY is true. Neither cookie sets Domain. On local HTTP the names follow SHELLUI_INSTANCE_ROLE: shellui_region_sessionid and shellui_region_csrftoken, or shellui_global_sessionid and shellui_global_csrftoken. Standalone HTTP keeps sessionid and csrftoken. Browsers reject the __Host- prefix without Secure |
POSTGRES_SSL_REQUIRE | true when POSTGRES_DATABASE_URL is set. Turn it off only for a local PostgreSQL without TLS |
Trusted proxies and client IP
Rate limits and the sign-in event log use the client IP. By default it is REMOTE_ADDR, so a client cannot fake its IP with an X-Forwarded-For header.
Behind a reverse proxy (Traefik, Coolify, nginx), list the proxy in TRUSTED_PROXY_IPS (IPs or CIDR ranges, comma-separated). When the direct peer is trusted, identity-service reads X-Forwarded-For from the right, skips trusted hops, and uses the first untrusted address. A fake address added by the client on the left is ignored.
# nginx on the same host
TRUSTED_PROXY_IPS=127.0.0.1,::1
# private load balancer subnet
TRUSTED_PROXY_IPS=10.0.0.0/8
With Coolify or Traefik, list the Traefik container or ingress subnet.
CORS (browser API calls)
Shellui shells run on many domains, and call public /api/v1/* endpoints from the browser before they have a token. A fixed CORS_ALLOWED_ORIGINS list cannot follow multi-tenant hosting, so the default is permissive:
| Setup | Settings |
|---|---|
| Default (recommended) | CORS_ALLOW_ALL_ORIGINS=true with CORS_ALLOW_CREDENTIALS=false. The API uses Bearer tokens in the Authorization header, not cookies |
| Locked down | CORS_ALLOW_ALL_ORIGINS=false, and first-party origins in CORS_ALLOWED_ORIGINS |
| Refused | CORS_ALLOW_ALL_ORIGINS=true with CORS_ALLOW_CREDENTIALS=true: startup fails, because any origin could then send credentials |
CORS does not control where tokens go after sign-in. The company redirect allowlist is the strict boundary for redirect_to and the one-time code exchange.
OpenID and provisioning endpoints do not use that allow-all policy. Set OIDC_CORS_ALLOWED_ORIGINS to the browser origins that may call them. An origin that is not on the list receives no Access-Control-Allow-Origin header. See Instance roles.
SESSION_COOKIE_DOMAIN and CSRF_COOKIE_DOMAIN are unset. Do not set a parent domain: session and CSRF cookies stay on the host that set them. manage.py check --deploy reports federation.E001 if either domain is set.
OAuth redirects
Loopback redirect targets (127.0.0.1, localhost, ::1) are allowed only with DEBUG=true or OAUTH_ALLOW_LOOPBACK_REDIRECTS=true. In production, add the real shell origins to the company redirect allowlist.
GET /api/v1/settings returns only provider slugs and feature flags to anonymous callers. OAuth client IDs and labels are included only for signed-in members of the company.
A desktop deep link is accepted when its scheme is in the company desktop_redirect_schemes list. It is not an allowlist row. The implicit -dev variant of a listed scheme (shellui-playground allowing shellui-playground-dev) is accepted when DEBUG=true, or when that company has allow_desktop_dev_scheme on. Otherwise that name is accepted only if it is listed. Every session code, including http(s), requires S256 PKCE. POST /api/v1/oauth/session skips the Origin check only after that verifier matches for a custom-scheme redirect. A missing or wrong code_verifier is rejected and the code stays unused. An http(s) redirect requires Origin, and that header must match the redirect origin. See OAuth login and Desktop apps.
Account deletion
DELETE /api/v1/user refuses personal access tokens and the last owner of a company, and requires a recent sign-in: the token's auth_time must be within SELF_SERVICE_ACCOUNT_DELETE_MAX_IAT_AGE (5 minutes by default). A token refresh keeps auth_time, so the user must sign in again. See Account deletion.
Personal access tokens
New PATs last 30 days by default (PERSONAL_ACCESS_TOKEN_LIFETIME). Changing the value does not shorten tokens already issued: they keep their expiry until they expire or are revoked. See Metrics and access tokens.
Related
- Configuration: every environment variable
- JWT and JWKS: signing keys and verification
- SAML single sign-on: assertion checks