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_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.
`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.

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.
`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_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 before users can authenticate. Users in unapproved orgs see a "pending approval" message.

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.

← Overview Next: Authentication →