Skip to main content

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):

ScopeDefaultEndpointsVariable
oauth30 per minute per IP/api/v1/authorize, OAuth callback, confirm, exchange, provider loginAUTH_RATE_LIMIT_OAUTH
mcp_register10 per hour per IPPOST /oauth/mcp/register (dynamic client registration)AUTH_RATE_LIMIT_MCP_REGISTER
mcp_signin30 per 5 minutes per IPGET/POST /oauth/mcp/signinAUTH_RATE_LIMIT_MCP_SIGNIN
token_refresh60 per minute per IPPOST /api/v1/token?grant_type=refresh_tokenAUTH_RATE_LIMIT_TOKEN_REFRESH
auth_settings30 per minute per IPGET /api/v1/settingsAUTH_RATE_LIMIT_SETTINGS
magic_link10 per minutePOST /api/v1/magic-link/request, per IP, per email, and per companyAUTH_RATE_LIMIT_MAGIC_LINK
token_exchange30 per minute per IPPOST /oauth/token with the token exchange grant (region role)AUTH_RATE_LIMIT_TOKEN_EXCHANGE
invitation30 per 5 minutes per companyPOST /api/v1/invitationsAUTH_RATE_LIMIT_INVITATION
admin_login10 per 5 minutes per IPPOST /admin/login/AUTH_RATE_LIMIT_ADMIN_LOGIN
pat30 per minute per userGET and POST /api/v1/personal-access-tokens, revokeAUTH_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):

SettingDefault in production
SECURE_SSL_REDIRECTtrue: redirects HTTP to HTTPS. Turn it off only behind a TLS proxy that already redirects
SECURE_HSTS_SECONDS31536000 (one year), with SECURE_HSTS_INCLUDE_SUBDOMAINS=true
SESSION_COOKIE_SECURE, CSRF_COOKIE_SECUREtrue. 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_REQUIREtrue 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:

SetupSettings
Default (recommended)CORS_ALLOW_ALL_ORIGINS=true with CORS_ALLOW_CREDENTIALS=false. The API uses Bearer tokens in the Authorization header, not cookies
Locked downCORS_ALLOW_ALL_ORIGINS=false, and first-party origins in CORS_ALLOWED_ORIGINS
RefusedCORS_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.