Skip to content
Halo

Documentation

Configuration

Halo reads its configuration from environment variables when a halo command starts. If a required variable is missing or invalid, the command lists every problem and exits without starting, for example:

Text
halo: configuration is incomplete:
  HALO_SECRET_KEY must be 32 random bytes, base64 encoded. Generate one with: openssl rand -base64 32

Server

The Go server (halo serve and the other halo commands) reads these variables.

Variable Required Default Example
HALO_PUBLIC_URL Yes https://auth.example.com
HALO_DATABASE_URL Yes postgres://halo:secret@postgres:5432/halo
HALO_SECRET_KEY Yes Output of openssl rand -base64 32
HALO_LISTEN No :8080 127.0.0.1:8080
HALO_ORGANIZATION No Halo Fernway Systems
HALO_DEV No Off 1
HALO_TRUSTED_PROXIES No 127.0.0.1/32,::1/128 172.31.250.0/24
HALO_DISABLE_CUSTOM_CSS No Off 1
HALO_SMTP_HOST No smtp.example.com
HALO_SMTP_PORT No 587 465
HALO_SMTP_USERNAME No halo@example.com
HALO_SMTP_PASSWORD No
HALO_SMTP_FROM When HALO_SMTP_HOST is set Halo <halo@example.com>

HALO_PUBLIC_URL

The address people type to reach Halo: the web interface, not the Go server. Halo uses it in three ways:

  • It is the OpenID Connect issuer. Applications must use exactly this value, and it appears as iss in every token.
  • Its hostname is the passkey (WebAuthn) relying party ID. Passkeys only work on the hostname they were created for, so changing the hostname later means everyone needs a new passkey.
  • Its origin is the only one the same-origin check accepts.

It must be an absolute URL, and it must use https unless HALO_DEV=1. Halo removes a trailing slash.

HALO_DATABASE_URL

The PostgreSQL connection URL. Halo is developed and tested against PostgreSQL 17. Every halo command applies pending migrations when it connects, so halo serve upgrades the schema on start; halo migrate applies migrations and exits.

HALO_SECRET_KEY

32 random bytes, base64 encoded with the standard alphabet. Generate one with openssl rand -base64 32.

Halo encrypts these with this key using AES-256-GCM: the OpenID Connect and SAML signing keys, the SSH certificate authority's key, authenticator-app secrets, identity provider client secrets, webhook signing secrets, the tokens Halo uses to provision applications over SCIM, and email waiting in the outbox. It also derives from it the key that encrypts opaque access tokens and authorization codes, and the key that recovery codes are hashed with (HMAC-SHA256). Starting Halo with a different key without rotating makes those values unreadable, so nobody can sign in to applications and authenticator-app codes stop working until the original key is back. Back it up together with the database.

To replace the key, stop Halo and run halo rotate-secret-key with the current key in HALO_SECRET_KEY and the new one in HALO_NEW_SECRET_KEY. It re-encrypts every stored secret in one transaction and removes recovery codes, which cannot be re-derived, then prints what to change in your deployment. Rotate HALO_SECRET_KEY walks through it.

HALO_LISTEN

The address the Go server listens on, as host:port or :port.

HALO_ORGANIZATION

Your organization's name, shown in the console, on the sign-in page and in email. A global administrator can override it in the console under Organization; this variable is the name Halo uses while that setting is empty. The API returns the name in use from GET /api/v1/organization.

HALO_DEV

Development mode. It is on only when the value is exactly 1. Development mode:

  • allows HALO_PUBLIC_URL to use plain http,
  • removes the Secure flag from Halo's cookies,
  • lets the OpenID Connect provider run on plain http,
  • enables halo seed-demo and halo dev-session,
  • adds GET /api/v1/dev/outbox, which shows global administrators the 50 most recent emails,
  • accepts http://localhost and http://127.0.0.1 as identity provider issuers.

Never set it in production.

HALO_TRUSTED_PROXIES

A comma-separated list of CIDR ranges, such as 10.0.0.0/8,172.31.250.0/24, for the reverse proxies in front of the Go server. Halo refuses to start if an entry is not a valid CIDR range. The default trusts only the local machine.

Halo records a client IP address on every sign-in, session and audit event. When a request arrives from an address in these ranges, Halo reads X-Forwarded-For from right to left and uses the first address that is not itself in these ranges. Requests from any other address use the connecting address and ignore the header, so a client cannot forge its own address.

In the Docker Compose deployment, the Go server sits behind the web container, so set this to the subnet of the Compose network: 172.31.250.0/24 in the provided files. Without it, Halo records the web container's address for everyone.

HALO_DISABLE_CUSTOM_CSS

Turns off the custom CSS on every page when the value is exactly 1. Use it to recover from a stylesheet that broke the sign-in page: start Halo with the variable set, open Branding in the console, fix the CSS, then remove the variable and restart Halo. The Branding page says the variable is set, GET /api/v1/organization returns an empty customCss while it is, and GET /api/v1/settings returns customCssDisabled: true. The saved CSS is kept.

SMTP

HALO_SMTP_HOST, HALO_SMTP_PORT, HALO_SMTP_USERNAME, HALO_SMTP_PASSWORD and HALO_SMTP_FROM describe the mail server Halo sends email through. Email is configured when HALO_SMTP_HOST is set, and then HALO_SMTP_FROM is required.

Halo emails invite links, reset links, magic sign-in links and access request notices. Every message goes into an outbox in the database first; Halo retries failed deliveries with growing gaps, up to 5 attempts within a day. Without SMTP, messages are queued but not sent, and administrators pass invite and reset links on themselves. Email explains the outbox and magic links.

  • Port 465 uses TLS from the start of the connection. On any other port, Halo requires STARTTLS, except when the host is localhost or a loopback address.
  • With HALO_SMTP_USERNAME set, Halo authenticates with PLAIN using HALO_SMTP_USERNAME and HALO_SMTP_PASSWORD.

Web interface

The Next.js web interface reads these variables.

Variable Default Purpose
HALO_API_URL http://localhost:8080 Address of the Go server. Server-rendered pages call it at runtime, and the forwarding rules for /api, /oauth2, /.well-known, /saml and /scim point at it. next build writes those rules into the build, so set the variable both when you build and when you run.
HALO_WEB_DIST .next Directory for the Next.js build output. Lets you run two copies of the web interface from one checkout.
PORT 3200 in the Docker image Port of the production server in the Docker image. bun run dev and bun run start use port 3200.
HOSTNAME 0.0.0.0 in the Docker image Interface the production server binds to in the Docker image.

Profile pictures and application logos

Without object storage, Halo keeps each profile picture and application logo in PostgreSQL. To keep them in an S3-compatible bucket instead, set all four of these. Halo still serves the images itself, at /api/v1/users/{id}/avatar and /api/v1/applications/{id}/logo, so the bucket can stay private. Applications that sign people in receive the picture URL.

Variable Purpose
HALO_S3_ENDPOINT The S3 API address, without the bucket name. Cloudflare R2: https://<account>.r2.cloudflarestorage.com. Backblaze B2: https://s3.us-west-004.backblazeb2.com. iDrive e2: https://s3.us-east-1.idrivee2.com. MinIO: http://minio:9000.
HALO_S3_BUCKET The bucket Halo writes avatars/<user id> and logos/<application id> into.
HALO_S3_ACCESS_KEY_ID The access key.
HALO_S3_SECRET_ACCESS_KEY The secret key.
HALO_S3_REGION Optional. Defaults to auto, which Cloudflare R2 expects. Set the provider's region for Backblaze B2 and iDrive e2, such as us-west-004.

Halo addresses the bucket by path, which these providers accept. Use the same keys you would give any other S3 client.

Docker Compose deployment

.env holds the values you choose. The install script writes it to the install directory, such as /opt/halo; in a checkout of the repository it is deploy/.env. compose.yml sets HALO_PUBLIC_URL, HALO_DATABASE_URL and HALO_TRUSTED_PROXIES from them, and the other server variables above keep their defaults unless you add them to .env. Two variables are used only by the Compose files:

Variable Purpose
HALO_DOMAIN The domain Caddy obtains a certificate for and serves Halo on. HALO_PUBLIC_URL is built from it.
POSTGRES_PASSWORD The password of the halo database user. HALO_DATABASE_URL is built from it.

Development and tests

Variable Default Purpose
HALO_TEST_DATABASE_URL postgres://halo:halo@localhost:5436/halo The server where go test creates a throwaway database for each test. The user needs permission to create databases.
HALO_URL http://localhost:3200 The Halo address the end-to-end test runs against.

The example application in examples/go-web-client reads CLIENT_ID and CLIENT_SECRET from the environment. It also reads HALO_ISSUER (default http://localhost:3200), REDIRECT_URI (default http://localhost:9000/callback) and LISTEN (default localhost:9000).

Organization settings

Some settings live in the database rather than in environment variables, so you change them in the console without restarting Halo. Halo reads them again within 30 seconds of a change.

Setting Console page Default Range Who can change it
Organization name Organization HALO_ORGANIZATION Up to 100 characters Global administrator
Contact email Organization Empty Global administrator
Sign-in message Branding Empty Up to 500 characters Global administrator
Logo Branding None PNG, JPEG or WebP, up to 256 KB Global administrator
Colours Branding Halo's Six hex colours Global administrator
Custom CSS Branding Empty Up to 32 KB Global administrator
Branding in the console Branding Off Global administrator
Session lifetime Security defaults 12 hours 1 to 72 hours Security administrator
Lockout threshold Security defaults 5 failed passwords or codes 3 to 20 Security administrator
Lockout window Security defaults 15 minutes 5 minutes to 24 hours Security administrator
Setup link lifetime Security defaults 7 days 1 to 30 days Security administrator
Access token lifetime for new applications Security defaults 15 minutes 5 minutes to 24 hours Security administrator
ID token lifetime for new applications Security defaults 15 minutes 5 minutes to 24 hours Security administrator
Refresh token lifetime for new applications Security defaults 8 hours 1 hour to 90 days Security administrator
SSH certificate lifetime Infrastructure access 8 hours 5 minutes to 24 hours Security administrator
Who can use a password Methods Everyone Everyone, or selected groups Security administrator
Second factor for passwords Methods On Security administrator
Breached password check Methods On Security administrator

A new session lifetime applies to sessions that start afterwards. The token lifetimes are defaults for applications created afterwards; change an existing application's lifetimes on its own page.

The API exposes these settings at GET and PATCH /api/v1/settings. The password rules are passwordGroupIds, a list of group ids where an empty list allows everyone, passwordSecondFactor and passwordBreachCheck. They matter only while passwords are turned on under Methods; turn the breach check off when Halo has no internet access. Passwords describes them.

Colours and custom CSS

The sign-in, setup and account pages show your logo and sign-in message in Halo's own colours until you change them under Branding.

Colours. Six colours, each a six-digit hex value such as #2563eb: the accent for buttons and highlights, the background, the surface of cards and panels, the border, the text and the link colour. Halo derives the rest, such as hover and pressed states, tints and secondary text, from them. A colour you leave empty keeps Halo's. The page previews the sign-in card as you type, warns when text, secondary text or button labels fall under a 4.5:1 contrast ratio against their backgrounds, and Reset to Halo defaults clears every colour.

Custom CSS. A stylesheet added after Halo's on the same pages, for what the colours do not cover, such as fonts, corner radius, spacing or hiding an element. It may be up to 32 KB and must not contain </, which would end the style element; write \3c/ in a CSS string instead. Images, fonts and @import rules in it load only from Halo's own address, because every page carries a Content Security Policy that allows stylesheets, fonts and scripts from Halo's origin only and images from there or data: URLs. Turn on Use the colours and custom CSS in the admin console too to apply both to the console as well. Pages pick up a change within 30 seconds. If a stylesheet makes the sign-in page unusable, start Halo with HALO_DISABLE_CUSTOM_CSS=1, fix it, and remove the variable again.

Only a global administrator can change colours, custom CSS and the console switch, and each change writes a settings.update audit event naming what changed. Through the API, PATCH /api/v1/settings takes theme, an object with accent, background, surface, border, text and link, where an empty string keeps Halo's colour; customCss; and consoleBranding. GET /api/v1/organization returns the same three fields to every page without authentication. The organization JSON export includes the colours, custom CSS and console switch under settings.

Fixed values

These values cannot be changed in this version:

What Value
Magic sign-in links Expire after 10 minutes; at most 5 per person in 15 minutes
Passkey and authenticator setup steps Expire after 5 minutes
Sign-in requests from applications Expire after 15 minutes
Federated sign-in attempts Expire after 10 minutes
Device codes for halo login Expire after 10 minutes
Client secrets Valid for 365 days
Old secrets after rotation Stop working after 24 hours
Previous OpenID Connect signing keys after rotation Stay published in /oauth2/keys for 7 days
Email delivery Up to 5 attempts within 1 day
Webhook delivery Up to 8 attempts over about an hour