Skip to content
Halo
All versions

Changelog

Unreleased

Development notes from earlier Halo builds.

5 October 2026

Added

Backend

Access requests, reviews, and lifecycle

People request access packages. Reviewers decide. Joiner, mover, and leaver rules run when someone's profile changes.

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.

OpenID Connect provider

Backend · API

Halo is an OpenID Connect provider with authorization code and PKCE, refresh tokens, userinfo, and RS256 ID tokens.

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.

SAML identity provider

Backend · Security

Halo signs applications in over SAML 2.0, with metadata, signed assertions, and guides for AWS IAM Identity Center and Slack.

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.

SSH certificates

Backend · Security

Halo is an SSH certificate authority. halo login waits on the laptop, the phone confirms it, and Halo writes a short-lived certificate.

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.

Frontend

Account portal

People manage their own sign-in methods, sessions, linked accounts, and access requests without asking an administrator.

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.

Administration console

The console opens on what needs attention, then covers users, groups, applications, policies, governance, and logs.

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.

Aether, branding, group rules and webhook events

Frontend · Backend · API · Docs

An Aether application template, colours and custom CSS for the public pages, a rule language for dynamic groups, single webhook event types, group assignments over the API, and roles from a person's page.

The application wizard has an Aether template. It asks for the Aether address and the provider slug, builds the redirect and post-logout URIs from them, sets the scopes Aether uses, and its setup guide lists the values for Aether's Connect Halo wizard, the webhook URL for suspensions and the SCIM base URL. A guide at /docs/integrations/aether walks through both sides.

Branding gains colours for the sign-in, setup and account pages, with a live preview, contrast warnings and a reset, and custom CSS added after Halo's stylesheet, up to 32 KB, optionally in the admin console too. Only global administrators can change them, and HALO_DISABLE_CUSTOM_CSS=1 turns the stylesheet off to recover from a broken one.

Rule-based groups take a rule language: email, emailDomain, name, kind and manager next to the existing attributes, the operators !=, contains, startsWith, endsWith and in, and, or, not and parentheses, true for everyone, and user.memberOf("…") for nested groups with loops rejected. Errors name the position of the problem.

Webhook endpoints subscribe to single event types, such as user.suspend, as well as families. GET /api/v1/webhooks/event-types returns each family with its types and a description, and the console's picker searches them.

PATCH /api/v1/applications/{id} accepts groupIds and replaces the assigned groups, and a field a route does not accept is refused with ERR_UNKNOWN_FIELD naming it. A global administrator changes a person's roles from their page and can choose a role when inviting them.

Passwords, application logos and assigning groups

Frontend · Backend · Security · API · Docs

An optional, discouraged password sign-in method that is off by default, logos for applications, and a searchable dialog that assigns several groups at once.

Passwords are a sign-in method for people who cannot use a passkey yet. They stay off until a security administrator turns them on under Methods and confirms a warning. Password rules limit them to selected groups, require a code from an authenticator app with every password sign-in by default, and refuse new passwords that the Have I Been Pwned range API reports as breached, a check that can be turned off for installations without internet access. A password is 15 to 256 characters with no composition rules, stored as an Argon2id hash. Failed passwords count toward the lockout, and an IP address with 4 times the lockout threshold of failed passwords within the window is refused across all accounts, to slow password spraying. Every password sign-in carries a low risk signal and reaches applications with amr: ["pwd"], or ["pwd", "otp", "mfa"] when an authenticator code came with it, and a policy that requires a passkey or security key still refuses it. Administrators set temporary passwords from a person's page or with PUT /api/v1/users/{id}/password, which the person replaces at their next sign-in. People set their own password in the account portal under Security, and the portal's home page asks them to add a passkey after a password sign-in. The settings passwordGroupIds, passwordSecondFactor and passwordBreachCheck are on PATCH /api/v1/settings, and POST /api/v1/auth/password and GET and PUT /api/v1/me/password are new.

Applications have a logo. An application administrator uploads a PNG, JPEG, WebP or SVG of up to 512 KB from the application's page or with PUT /api/v1/applications/{id}/logo, and removes it with DELETE. Logos are stored like profile pictures, in PostgreSQL or the S3 bucket, and appear in the console's application list, the account portal's Applications page, the sign-in page and the halo login confirmation page, with the application's initials when there is none.

Assigning groups to an application and adding a person to groups open a searchable dialog instead of a menu. It filters by name or description, shows each group's kind and member count, marks the groups that are already assigned, and adds every ticked group at once.

The webhook event types application.logo.update, application.logo.remove and user.password.set are new.

Profile pictures and organization logos

Frontend · Backend · Security

People set a profile picture, and a global administrator sets the organization logo. Applications that sign someone in receive the picture URL.

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.

Security

Conditional access and sign-in risk

Policies can allow, block, or require a passkey. Halo records device trust, network zones, and sign-in risk.

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.

Federated sign-in

Security · Backend

People can sign in with Google, Microsoft Entra ID, GitHub, or any OpenID Connect provider.

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.

Passkeys and sign-in methods

Halo signs people in with passkeys, security keys, authenticator apps, and recovery codes. Passwords are off by default.

Sign-in is a passkey or a security key, an authenticator app (TOTP), or a single-use recovery code. There is no password field unless a security administrator turns passwords on, and until then 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.

API

Management API and service accounts

The console is a client of /api/v1. Service accounts call the same API with a key.

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.

SCIM provisioning and webhooks

API · Backend

A directory can push people into Halo over SCIM, Halo can push them out to an application, and webhooks carry audit and sign-in events.

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.

Deploy

Docker Compose and the install script

One command installs Halo on a fresh Linux host. The images are published for amd64 and arm64.

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.

Docs

Guides on the site

The guides for running Halo and connecting applications are published at halo.scala.gg/docs.

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.

Changed

Frontend

Console loading states and pending actions

Pages in the console and the account portal show a skeleton and a progress bar as soon as you navigate, buttons stay busy until the updated page is on screen, and a failed action shows its error next to it.

Every section of the console and the account portal shows a skeleton of its layout the moment you navigate, with a thin progress bar at the top while the page loads, and the console home page fills in each card as its data arrives.

Buttons show their pending state on click and stay busy until the updated page is on screen, so an action cannot be sent twice. A busy button's label stays available to screen readers. When an action fails, its error appears next to it instead of only in a toast, and a table keeps its selection when a bulk action fails.

The command palette tells screen readers which result is highlighted, using the same listbox as the assign groups dialog.

Security

Longer recovery codes

Recovery codes are now 16 characters. Codes from earlier development builds were deleted and have to be generated again.

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.