Unreleased

An access package names the groups it grants, who may approve it, how long it may last, and whether the person must give a reason. The request can be approved, denied, cancelled, or revoked, and it expires on its own. Approvers are notified by email when SMTP is configured. Nobody approves their own request.

An access review asks reviewers to keep or remove each member of a group by a due date. When the review completes, Halo applies the removals. An overdue review stays visible.

Joiner, mover, and leaver rules add or remove groups when a profile matches, and each run is recorded.

An invite or a reset link works once and expires after the setup link lifetime, 7 days by default. An administrator can reset someone's sign-in methods from the console and send a new link.

With SMTP configured, Halo emails invitations, resets, magic links, and access request notices. Messages sit in an outbox and are retried. In development, GET /api/v1/dev/outbox shows the latest messages.

A magic link signs the person in once, lasts 10 minutes, and is limited to 5 links per person in 15 minutes. Without SMTP, Halo still works: the administrator copies the link and passes it on.

Applications sign in through the authorization code flow. PKCE is required for single-page and native applications. Refresh tokens rotate. Service applications can use client credentials.

The provider serves userinfo, token introspection, revocation, RP-initiated logout, discovery, and signing keys. ID tokens are signed with RS256. They carry a groups claim with the person's group names and, when the application requests the profile scope, a picture claim.

Signing keys rotate in place. A new key signs immediately, and the previous key stays in the JWKS for 7 days. email_verified is set when a person redeems an emailed link or signs in through a provider that verified the address, and it is cleared when the address changes.

Halo is a SAML 2.0 identity provider. It publishes metadata, accepts SP-initiated and IdP-initiated sign-in, and signs assertions. NameID format and attribute names are set per application, and service provider metadata can be imported.

When the person has a profile picture, the assertion includes its URL as a picture attribute. New SAML certificates are listed beside the previous certificate until that certificate is removed.

The guides for AWS IAM Identity Center and Slack are on this site, and examples/go-saml-sp is a small service provider in the repository.

Halo can be the SSH certificate authority for hosts you administer. Group-to-principal mappings decide which principals a person receives, and the certificate lifetime is configurable.

halo login starts the device flow and waits. The person confirms the sign-in in the browser. halo ssh-cert writes the certificate. Those sessions show up in the account portal and the console, and they can be signed out like a browser session.

The account portal is where a person sees their profile and adds a passkey, a security key, an authenticator app, or recovery codes. They can unlink a federated account and sign out a session, including a Halo CLI session.

The same pages list the applications they can open, the access they can request, the approvals waiting on them, the reviews assigned to them, and their recent activity.

The home page leads with directory counts, the signed-in administrator's roles, open risk events, and shortcuts, above the items that need a decision today.

From there an administrator works with users, assigned and rule-based groups, service accounts, devices, and applications. Application pages edit redirect URIs, scopes, and token lifetimes. Client secrets are shown once, rotate with a 24-hour grace period, and can be revoked.

The same console covers API resources, provisioning, roles, policies, infrastructure access, governance, sign-in methods, identity providers, sessions, the sign-in log, the audit log, risk events, API keys, webhooks, and settings.

A person uploads a PNG, JPEG, or WebP from the account portal. A user administrator can set the same picture on that person's page in the console. A global administrator sets the organization logo from the overview, or from Settings, under Branding.

Halo keeps the image in PostgreSQL unless HALO_S3_ENDPOINT, HALO_S3_BUCKET, HALO_S3_ACCESS_KEY_ID, and HALO_S3_SECRET_ACCESS_KEY are set. Those variables point at an S3-compatible bucket such as Cloudflare R2, Backblaze B2, iDrive e2, or MinIO. Halo still serves the file, so the bucket can stay private.

Applications that request the OpenID Connect profile scope receive the picture URL as the picture claim, in the ID token and in userinfo. SAML assertions include the same URL as a picture attribute. Outbound SCIM sends it as the user's photo.

An access policy matches people, groups, applications, network zones, device trust, sign-in risk, and sign-in method. The effect is allow, block, or require a passkey. Report-only mode records what the policy would have done, and the simulator checks a decision before it is enforced.

Halo tracks devices and their trust level. Risk signals cover a risky network, repeated failures, a new device, and a new network. Security administrators resolve or dismiss the resulting risk events.

HALO_TRUSTED_PROXIES tells Halo which reverse proxies may set the client address, so the address on a sign-in stays the person's address rather than the proxy's.

Halo accepts Google, Microsoft Entra ID, GitHub, and a generic OpenID Connect provider. The flow uses PKCE. Halo matches a verified email address, and an administrator can limit which email domains may sign in.

A person who has never had an account can be created on first sign-in and placed in the default groups. An existing account can be linked, and the person can unlink it from the account portal.

Sign-in is a passkey or a security key, an authenticator app (TOTP), or a single-use recovery code. There is no password field and Halo stores no passwords.

An administrator can turn each method off for the organization. prompt=login, prompt=none, and max_age are supported. A completed sign-in can only be redeemed in the browser session that completed it.

Sessions are bound to the device that started them. Blocking a device signs it out. Device authorization requests are limited per address, and a client that polls too fast receives slow_down.

Anything the console does is available under /api/v1. Roles are global, security, user, helpdesk, and application administrator, plus auditor. A global administrator passes every check. Every administrative change writes an audit event in the same transaction.

The OpenAPI 3.1 document is served at /api/v1/openapi.yaml on the Halo server.

API resources are your own APIs: each has scopes, an identifier, and a token lifetime. An application granted those scopes receives a JWT access token with the API in aud. Service accounts hold roles and owners. Their API keys can carry the api and scim scopes, and a key can expire.

Halo serves SCIM 2.0 at /scim/v2 for users and for groups that are assigned to the application. The server has been checked against the request shapes Okta and Microsoft Entra ID send.

Outbound SCIM creates, updates, and deactivates the people assigned to an application. It runs every 2 minutes, and an administrator can run it on demand. A profile picture is sent as the user's photo.

Webhooks deliver audit and sign-in events. Each delivery is signed with HMAC-SHA256 over a timestamp and the raw body. Failed deliveries are retried, and the delivery log shows what was sent.

curl -fsSL https://halo.scala.gg/install.sh | sh installs Docker when it is missing, writes the environment file, and starts Halo. The script stays on the host as halo.sh to create the first administrator and to start, stop, restart, update, and follow logs.

The same deployment is Docker Compose: PostgreSQL, the Go server, the web interface, and Caddy for TLS. Images are published to ghcr.io/scalastudios/halo-server and halo-web for linux/amd64 and linux/arm64. deploy/compose.build.yml builds from a checkout instead.

halo serve, migrate, bootstrap, seed-demo, dev-session, and rotate-secret-key are the server commands. rotate-secret-key re-seals every stored secret under a new HALO_SECRET_KEY.

The guides cover email, policies, governance, federation, provisioning, webhooks, API resources, and infrastructure access. Integration guides cover Grafana, Forgejo, Nextcloud, Kubernetes, Proxmox VE, Outline, Headscale, AWS IAM Identity Center, and Slack.

examples/go-web-client is a small Go application that signs in with Halo. The repository also includes a contributing guide, a security policy, a code of conduct, and issue and pull request templates.

Continuous integration runs go vet, go test, type checking, and the web build. halo seed-demo loads the Fernway Systems organization, with data for every area of the console.

Recovery codes are 16 characters, 80 bits, and stored as HMAC-SHA256 with a key derived from HALO_SECRET_KEY.

Migration 0010_hardening deletes codes generated by earlier development builds. Those codes no longer work. Generate a new set from the account portal.