Generic OpenID Connect

Connect any application that supports OpenID Connect sign-in. The pages for Grafana, Forgejo, Nextcloud, Kubernetes, Proxmox VE, Outline and Headscale apply the same steps to specific applications.

The examples use https://auth.example.com as Halo's address. Replace it with your HALO_PUBLIC_URL.

Register the application in Halo

1. In the console, open Applications and choose Add application.
2. Choose OpenID Connect and Continue.
3. Choose where the application runs:
   • Web application if it runs on a server and can keep a secret. Pick the Custom template, or a template for a known application.
   • Single-page app if it runs entirely in the browser.
   • Native or CLI for desktop, mobile and command-line tools.
4. Choose Continue, enter the application's name and its redirect URI, and choose Create application.
5. Copy the values Halo shows: the issuer, the client ID, and for web applications the client secret. Halo shows the secret only once.
6. Choose Open application, go to Users & groups, choose Assign group, and pick the groups whose members may sign in. Until you assign a group, nobody can sign in.

For a service that calls an API with its own credentials, choose OAuth 2.0 service in step 2 instead; see client credentials.

Values for the application

Most applications need only the discovery URL, the client ID and the client secret. Use the rest when an application asks for each endpoint separately.

The issuer must match exactly, without a trailing slash. Every token's iss claim carries it.

Client authentication

• Web applications authenticate to the token endpoint with their client secret, either with HTTP Basic (client_secret_basic) or as client_id and client_secret form fields (client_secret_post). Use PKCE as well if the application supports it.
• Single-page and native applications are public clients without a secret. They must send a PKCE challenge with code_challenge_method=S256; Halo refuses their sign-in requests otherwise.
• Token introspection accepts the client secret over HTTP Basic only.

Redirect URIs

Halo sends people back only to redirect URIs registered on the application, and the URI in the request must match one exactly: scheme, host, port, path and trailing slash. Halo registers only https:// addresses without a #fragment, except http://localhost and http://127.0.0.1.

For native applications, Halo ignores the port of a loopback redirect URI: registering http://localhost:8000 also accepts http://localhost:18000. Path and query must still match.

The console's form registers one redirect URI when you create the application. Add more, and post-logout redirect URIs, on the application's page afterwards, or create the application through the API with several.

Claims

Halo includes the requested claims in the ID token as well as in the userinfo response, so applications that read only the ID token still get groups.

Halo's groups claim carries group names, such as "Grafana editors", not ids. When you map groups to roles in an application, use the names exactly as they appear in the console.

Tokens

Change the lifetimes and refresh token rotation on the application's page. New applications start with the defaults from Security defaults.

Halo checks that the person is still active and still assigned to the application on every token, refresh, userinfo and introspection request.

Re-authentication and sign-out

• Send prompt=login, or a max_age in seconds, to make Halo ask the person to sign in again even when they have a Halo session.
• Send prompt=none to check for a Halo session without showing any page. Halo issues a code when the browser has a session it accepts for this application, and otherwise redirects back with login_required (no usable session) or interaction_required (not assigned, or blocked by an access policy).
• Send the person to /oauth2/logout with the ID token as id_token_hint to sign them out. Halo revokes the application's tokens and ends the Halo session named in the token's sid claim, so other applications need a new sign-in too. Add post_logout_redirect_uri to send the person back afterwards; it must be registered on the application as a post-logout redirect URI, which you add on the application's page or send as postLogoutUris to the API.

Client credentials

A service application gets a client secret and no redirect URI. Request a token with the client credentials grant:

curl -u "hl_…:hls_…" https://auth.example.com/oauth2/token \
  -d grant_type=client_credentials -d scope="billing:read"

Halo returns a JWT access token whose sub is the client ID, with only the requested scopes that are registered on the application or granted to it on an API resource. Prefer API resources for your own APIs: the token then carries the API's identifier in aud.

Troubleshooting