Configuration Reference
Environment variables for the Orion server
Orion reads all configuration from environment variables at startup. No configuration files are required. Variables are case-sensitive unless noted otherwise.
Core Settings
| Variable | Required | Default | Description |
|---|---|---|---|
CUSTOMCONNSTR_OrionRestAPIContextV2 |
Required | — | PostgreSQL connection string. Example: Host=localhost;Database=orion;Username=orion;Password=secret |
ORION_BASE_URL |
Required | https://login.shanecraven.com | The public-facing base URL of the Orion server. Used for generating redirect URIs, issuer claims, and discovery endpoints. Must include scheme (https://). |
ORION_AUTH_SCHEMES |
Optional | OrganisationStandard,OrganisationUserStandard,OAuth | Comma-separated list of enabled authentication schemes. Controls which auth handlers are active. |
ORION_ALLOW_MD5 |
Optional | false | Set to true to enable legacy MD5-based HMAC validation for older SDK versions. Not recommended for new deployments. |
ORION_AUTH_MODE |
Optional | auto | How the server's own management portal authenticates: oauth (OpenID Connect, the new default for fresh setups), legacy (HMAC federation), or unset/auto to use OAuth when the orion application is OAuth-enabled, else legacy. Both auth systems are always available — client applications choose per app; this only sets the portal default. |
ORION_LEGACY_PSA_AUTH |
Optional | enabled | Set to disabled to turn off the legacy platform-system-account HMAC scheme (OrgStandard) once every service has migrated to OAuth device-identity tokens. Refused callers get a message naming the replacement. Leave unset while any system still authenticates with PSA keys — LastUsedAt on the PSA key rows shows which ones still do. |
ORION_SYSTEM_NAME |
Optional | Orion | Display name of the system shown throughout the UI (nav brand, page titles, home page, login & setup screens). Set this to rebrand the platform. |
ORION_LOGO_URL |
Optional | /Resources/orion_logo.png | URL or path of the logo shown in the nav bar, home page, and login/setup screens. Can be an absolute URL to a hosted image. |
OAuth Signing Keys
| Variable | Required | Default | Description |
|---|---|---|---|
ORION_SIGNING_KEY_PROVIDER |
Optional | Database | Key provider to use. Options: Database (default — keys are generated once and persist across restarts), EnvironmentVariable, AzureKeyVault. With EnvironmentVariable and no key supplied the server generates an EPHEMERAL key and every issued token is invalidated on restart. |
ORION_SIGNING_KEY_PRIVATE |
Required if provider=EnvVar | — | Base64-encoded RSA private key (PKCS#8 or PKCS#1). Used to sign JWTs when provider is EnvironmentVariable. |
ORION_SIGNING_KEY_ID |
Optional | orion-env-key | The kid (Key ID) value included in JWT headers and JWKS responses. |
ORION_SIGNING_KEK |
Optional | auto-generated | AES-256 Key Encryption Key (Base64) protecting signing keys stored in the database. Generated on first boot and stored in ServerSecrets if not supplied. Set it explicitly to keep key material outside the database (HSM / KMS / sealed secret) — the environment variable always wins and is never persisted. |
ORION_KEYVAULT_URI |
Required if provider=AzureKeyVault | — | Azure Key Vault URI. Example: https://my-vault.vault.azure.net/ |
FIDO2 / WebAuthn
| Variable | Required | Default | Description |
|---|---|---|---|
ORION_FIDO2_DOMAIN |
Optional | localhost | WebAuthn Relying Party (RP) domain. Must match the domain users access (e.g. login.example.com). |
ORION_FIDO2_ORIGINS |
Optional | value of ORION_BASE_URL | Space or comma-separated list of allowed WebAuthn origins. Each must be an absolute URI. |
Account Lockout
| Variable | Required | Default | Description |
|---|---|---|---|
ORION_LOCKOUT_MAX_ATTEMPTS |
Optional | 5 | Maximum failed login attempts before an account is locked. Wrong second-factor codes count too, and a correct password no longer resets the count: only a completed sign-in does. |
ORION_LOCKOUT_WINDOW_MINUTES |
Optional | 15 | Time window (minutes) in which failed attempts are counted. |
ORION_LOCKOUT_DURATION_MINUTES |
Optional | 30 | Duration (minutes) an account remains locked after exceeding max attempts. |
ORION_REVERIFY_MINUTES |
Optional | 15 | How recently a person must have signed in or confirmed it's them (/auth/verify) to add or remove a passkey or authenticator app, turn two-factor off, or link or unlink a directory identity. |
ORION_AUTH_FLOOR |
Optional | (none) | The minimum every sign-in must reach, whatever the authentication rules say: mfa (two factors), phr (a passkey) or phrh (a passkey bound to its device). Set here only, so no page and no session can lower or remove it. People without a factor that meets it add one before signing in to an application; the portal still lets them in, to add it there. Another value is ignored and reported on /setup. |
ORION_AUTH_FLOOR_ADMINS |
Optional | (none) | The same, for every organisation's administrators and the platform's (for example phr, with ORION_AUTH_FLOOR=mfa for everyone else). |
ORION_AUTH_FLOOR_FROM |
Optional | (at once) | A date (yyyy-MM-dd, UTC) from which people without a factor that meets the floor must add one. Until then their sign-in goes on past a reminder. |
ORION_FORWARDED_HEADERS |
Optional | false | true behind a proxy (a load balancer, App Service's front end, a CDN): Orion takes the visitor's address and scheme from X-Forwarded-For and X-Forwarded-Proto, from a proxy in ORION_TRUSTED_PROXIES only. Named networks, the audit and lockouts then see people's own addresses. The Authentication page shows the address Orion sees. |
ORION_TRUSTED_PROXIES |
Optional | loopback | The proxies whose forwarded headers are believed: addresses and ranges, comma separated (10.0.0.0/8, 192.0.2.10). any believes every sender: only where Orion can be reached through the proxy alone, since anyone reaching it directly could claim any address. An entry Orion cannot read is ignored and listed on /setup. |
ORION_AUTH_RULES_FILE |
Optional | (none) | A file holding the server's authentication rules and networks as JSON (the format the Authentication page downloads), applied at every start once the schema is current, whole or not at all. While it is set, the server's rules are the file's and the page shows them read-only. A file that can't be applied is listed on /setup. |
ORION_FORWARDED_LIMIT |
Optional | 1 | How many proxies in a row to read through (1 to 10), for a chain such as a CDN in front of a load balancer. |
ORION_FIDO_MDS |
Optional | off | on fetches the FIDO Metadata Service (from mds3.fidoalliance.org), from which rules name security key models, and fetches it again when FIDO publishes the next. Or the https address of a mirror (http only on the same machine). Off, a platform administrator uploads it on the platform organisation's Authentication page instead. Either way a list is used only once its signature verifies to FIDO's root. |
ORION_BREACHED_PASSWORDS |
Optional | off | on refuses a password someone chooses (registration, a reset, a forced change, turning password sign-in back on) when it has appeared in a breach, checked against Have I Been Pwned's Pwned Passwords. Only the first five characters of the password's SHA-1 are sent; Orion matches the answer itself. Or the https address of a mirror of the range API (http only on the same machine). Unreachable within three seconds, the password is accepted and a warning logged. A value Orion cannot read leaves it off and is listed on /setup. |
Redirect & OAuth Cleanup
| Variable | Required | Default | Description |
|---|---|---|---|
ORION_ALLOWED_REDIRECT_DOMAINS |
Optional | — | Space-separated list of allowed redirect domains. Supports wildcards (e.g. *.example.com). If unset, no server-level domain restriction is enforced. Only the management portal may redirect to Orion's own host without registering the URI; any other application must register it, and when this list is set Orion's host must be in it. |
ORION_OAUTH_CLEANUP_INTERVAL_MINUTES |
Optional | 30 | Interval (minutes) for the background job that cleans expired tokens, codes, and device authorizations. |
Setup Mode
| Variable | Required | Default | Description |
|---|---|---|---|
ORION_SETUP_MODE |
Optional | false | Set to true to enable the /setup endpoint for initial configuration and schema upgrades. |
ORION_SETUP_KEY |
Optional | — | A secret key to protect the setup endpoints. If set, must be provided as a query parameter (?key=...). |
ORION_SETUP_ALLOWED_HOSTS |
Optional | — | Comma-separated list of IP addresses and/or hostnames allowed to access the setup page. Hostnames are resolved via DNS on each request. If not set, no IP restriction is enforced. Example: 192.168.1.10,admin.internal.example.com |
Tokens & Sessions
| Variable | Required | Default | Description |
|---|---|---|---|
ORION_TOKEN_MODE |
Optional | jwt | Server-wide default access-token format. jwt issues self-contained tokens; verified issues opaque Orion Verified references that are introspected per request, giving instant revocation. Organisations and applications can override this. |
ORION_VERIFIED_INTROSPECT_SECRET |
Optional | — | Client secret the management portal uses to introspect its own Verified tokens (the orion application's secret). Required only when the portal itself runs in Verified mode. |
ORION_VERIFIED_CACHE_SECONDS |
Optional | 5 | Introspection cache lifetime advertised to the SDK federation filter. Higher values cut introspection traffic but widen the revocation window. |
ORION_VERIFIED_FAIL_MODE |
Optional | closed | SDK behaviour when Orion is unreachable during introspection: closed rejects the request (safe default), open accepts it. Only use open where availability outranks revocation. |
ORION_SSO_SESSION_HOURS |
Optional | 8 | Absolute lifetime of the provider-side single sign-on session, in hours. |
ORION_DEVICE_PROVISION_MAX_ACTIVE_CODES |
Optional | 50 | Maximum unredeemed device enrollment codes a single provisioning client may hold at once. Bounds abuse of the provisioning API. |
ORION_KEYVAULT_KEY_NAME |
Optional | orion-signing | Key name within Azure Key Vault when ORION_SIGNING_KEY_PROVIDER=AzureKeyVault. |
Database Schema
| Variable | Required | Default | Description |
|---|---|---|---|
ORION_AUTO_MIGRATE | No | false | Apply pending EF migrations at startup, serialised across instances by a Postgres advisory lock. Recommended for automated deployments — otherwise the only way to migrate is the /setup page, which means re-enabling setup mode on production to ship a release. |
ORION_EXIT_ON_SCHEMA_DRIFT | No | false | Stop the process when migrations are pending or a migration failed, instead of staying up and reporting 503 from /health. Leave this off unless you know you want it: on any platform that restarts failed containers it produces a crash loop, and it makes /setup — the way to apply the migrations — unreachable. The default keeps the server alive but unready, so it can be repaired. |
Probe endpoints: /health/live (process is up, no database access) and
/health = /health/ready, which returns 503 when the database is
unreachable or migrations are pending — so a bad deploy fails at the load balancer instead of
serving errors. A fresh install with no database reports setupRequired.
Dynamic Claims
| Variable | Required | Default | Description |
|---|---|---|---|
ORION_MFA_KEK | No | generated | Base64 256-bit AES key encrypting authenticator-app (TOTP) secrets at rest. Generated and stored in the database when unset, like the other KEKs; set it to keep the key outside the database. Generate: openssl rand -base64 32 |
ORION_CLAIM_PROVIDER_KEK | No | — | Base64 256-bit AES key encrypting external claim-provider secrets (API keys / HMAC secrets) at rest. Required only to store a provider secret. Generate: openssl rand -base64 32 |
ORION_CLAIM_PROVIDER_ALLOWED_HOSTS | No | — | Comma-separated hosts (exact or .suffix) that claim-provider URLs may target. SSRF guard — private/loopback ranges are always blocked. If empty, any public HTTPS host is allowed. |
ORION_CLAIM_SYNC_INTERVAL_MINUTES | No | 15 | How often the background worker pulls Sync-mode claim providers into user metadata. |
Registration & Invites
| Variable | Required | Default | Description |
|---|---|---|---|
ORION_REGISTRATION_MODE | No | invite_only | Registration mode: open (anyone can register + create orgs), user_only (register but no org creation), invite_only (admin invite links required) |
ORION_REGISTRATION_REQUIRE_EXTERNAL | No | false | If true, registration must go through an external provider (e.g. AAD). User's external identity auto-creates their Orion account. |
ORION_REQUIRE_ORG_APPROVAL | No | false | If true, new organisations require platform admin approval. Until then their members are refused at every application but the management portal, at login and wherever their session or token is presented (refresh, userinfo, introspection), and see a "pending approval" message; their administrators cannot approve applications of other organisations or change that policy. |
Multi-Organisation Applications
| Variable | Required | Default | Description |
|---|---|---|---|
ORION_MULTI_ORG_APPLICATIONS | No | true | Set false to make every application but the management portal admit only its own organisation, whatever its "Who can sign in" setting. At every start while it is set, Orion revokes the refresh tokens, Verified references and pending codes of members of other organisations. Approvals and consents are kept, and lifting it revives no token: members sign in again. Cannot be overridden from inside the application. |
Organisation Console
| Variable | Required | Default | Description |
|---|---|---|---|
ORION_SIGNIN_EXPERIENCE | No | unset | Set to new to turn on the redesigned sign-in and registration pages: sign-in asks for the email address first and then offers the directory or the password, registration is a few short steps with errors beside each field and password guidance, the consent and approval screens are redesigned, and every sign-in page gets the new look. It is server-wide, changes what is shown, never what is allowed, and the pages post the same forms either way, so it can be switched off at any time. |
ORION_ORGANISATION_CONSOLE | No | false | Turns on the organisation console for administrators: a sidebar for every management area, an overview of what needs attention, a people table, an access check, an activity log, a security posture page and organisation settings. true turns it on for every organisation; a list of organisation public ids, separated by commas, turns it on for those only, so it can be tried with a few first. Unset or false, every page is as it was before the console and its pages answer 404. It changes what is shown, never who may do what. |
External Authentication Providers
Configure external identity providers (e.g. Azure AD) via env vars following the pattern ORION_EXTERNAL_PROVIDER__<ID>__<PROPERTY>. These are the only directories whose tokens the server will accept — see External Authentication for the full walkthrough.
| Variable Pattern | Example | Description |
|---|---|---|
ORION_EXTERNAL_PROVIDER__<ID>__TYPE | aad | Provider type. Currently supported: aad (Azure AD) |
ORION_EXTERNAL_PROVIDER__<ID>__DISPLAY_NAME | Microsoft | Name shown on the login page button |
ORION_EXTERNAL_PROVIDER__<ID>__CLIENT_ID | 11111111-2222-3333-4444-555555555555 | OAuth client ID registered with the external provider |
ORION_EXTERNAL_PROVIDER__<ID>__TENANT_ID | aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee | Azure AD tenant ID (for AAD type) |
ORION_EXTERNAL_PROVIDER__<ID>__SCOPE | api://clientid/Scope | Scope to request from the external provider |
ORION_EXTERNAL_PROVIDERS_DB | true | Set false to ignore providers stored in the database entirely — only environment providers are honoured, and no policy setting can override it |
ORION_EXTERNAL_PROVIDERS_UI | true | Set false to make database providers read-only in the admin UI (they keep working) |
ORION_EXTERNAL_PROVIDER__<ID>__DISCOVERY_MODE | domain | Per-provider override: domain, identity (offer only to addresses already linked) or both. Unset inherits the policy default |
ORION_EXTERNAL_PROVIDER__<ID>__AUDIENCE | api://clientid | Optional. Expected aud of the token Orion validates. Defaults to api://<CLIENT_ID> |
ORION_EXTERNAL_PROVIDER__<ID>__DOMAINS | example.com,corp.net | Comma-separated email domains that should use this provider. Wildcards match subdomains only (*.example.com does not match example.com) |
Email (SMTP)
| Variable | Required | Default | Description |
|---|---|---|---|
orion_smtp_host |
Optional | — | SMTP server hostname (e.g. smtp.mailgun.org). |
orion_smtp_username |
Optional | — | SMTP authentication username. |
orion_smtp_password |
Optional | — | SMTP authentication password. |
orion_smtp_fromaddress |
Optional | — | The "From" email address for outgoing messages. |
orion_smtp_displayName |
Optional | — | Display name for the "From" header (e.g. Orion Identity). |
Sovereign Signing
Configuration for out-of-band JWT signing by external agents. Sovereign signing keeps private keys on separate servers — the Orion server never possesses signing key material.
| Variable | Required | Default | Description |
|---|---|---|---|
ORION_SOVEREIGN_SIGNING_TIMEOUT_SECONDS |
Optional | 300 | Maximum time for a sovereign signing request before expiry (browser flows). |
ORION_SOVEREIGN_CHALLENGE_TIMEOUT_SECONDS |
Optional | 120 | Maximum time for the user to respond to an agent-issued challenge. |
ORION_SOVEREIGN_POLL_INTERVAL_SECONDS |
Optional | 2 | SSE check interval for the wait page and internal status polling. |
ORION_SOVEREIGN_M2M_TIMEOUT_SECONDS |
Optional | 30 | Timeout for non-interactive flows (client_credentials, refresh token). Returns authorization_pending if exceeded. |
ORION_SOVEREIGN_SIGNING_POOL__<CLIENT_ID> |
Optional | — | Override: assign an application to a sovereign signing pool by env var. CLIENT_ID is uppercased with non-alphanumeric chars replaced by _. |
Device Identity / CA
Configuration for cert-based device enrollment and per-org CA. See the Device Identity page for the full guide.
| Variable | Required | Default | Description |
|---|---|---|---|
ORION_CA_KEK | Required* | — | 256-bit AES key (base64) for encrypting the device CA private key. Must differ from ORION_SIGNING_KEK. *Required when device identity is used. |
ORION_CA_VALIDITY_YEARS | Optional | 10 | CA certificate validity period. |
ORION_DEVICE_CERT_VALIDITY_DAYS | Optional | 365 | Issued device certificate validity. |
ORION_DEVICE_ENROLLMENT_TTL_MINUTES | Optional | 15 | Enrollment code lifetime. |
ORION_DEVICE_ASSERTION_MAX_AGE_SECONDS | Optional | 120 | Max age of a device assertion before rejection. |
ORION_TPM_VENDOR_ROOTS | Optional | — | Path to directory of TPM vendor root certs (PEM/CRT). Required when TPM attestation is enabled. |
ORION_TPM_REQUIRE_EK_CERT | Optional | true | Require EK cert from a known vendor. Set false only for testing. |