From 1463a8cc4212e1cead089168a513902ba062f44a Mon Sep 17 00:00:00 2001 From: Aarnav Tale Date: Fri, 5 Dec 2025 15:38:16 -0500 Subject: [PATCH] docs: go more indepth on sso setup --- docs/features/sso.md | 99 ++++++++++++++++++++++++-------------------- 1 file changed, 55 insertions(+), 44 deletions(-) diff --git a/docs/features/sso.md b/docs/features/sso.md index e991b11..16c0287 100644 --- a/docs/features/sso.md +++ b/docs/features/sso.md @@ -1,6 +1,7 @@ --- title: Single Sign-On (SSO) description: Configure Single Sign-On (SSO) authentication for Headplane. +outline: [2, 3] --- # Single Sign-On (SSO) @@ -11,66 +12,68 @@ description: Configure Single Sign-On (SSO) authentication for Headplane.
SSO Configuration Page
-Headplane supports Single Sign-On (SSO) authentication using OpenID Connect -(OIDC). This allows users to authenticate using an external Identity Provider -(IdP) that supports OIDC, streamlining the login process and enhancing security. +Single Sign-On allows users to authenticate with Headplane through an external +Identity Provider (IdP). It does this using the OpenID Connect (OIDC) protocol, +which is widely supported by many popular IdPs. -This is generally the recommended authentication method when using Headplane in -production environments as it provides the deepest integration with Headscale -and allows for seamless user management. +## Getting Started +To set up Single Sign-On (SSO) with Headplane, there are several steps involved. +As a general recommendation, please read through the entire guide before +beginning the process as there are several important factors to consider. -## Configuring OIDC -To configure Single Sign-On (SSO) you'll need to first setup a client with your -Identity Provider that supports OIDC. The exact steps to do this will vary, but -generally you'll need to be able to provide the following information to -Headplane: +### Requirements -| Field | Description | -|---------------------------|--------------------------------------------------| -| **Client ID** | The client identifier provided by your IdP. | -| **Client Secret** | The client secret provided by your IdP. | -| **Issuer URL** | The OIDC issuer URL given by your IdP. | +::: warning +If you are also using OpenID Connect (OIDC) authentication with Headscale, it is +**fundamentally important** that both Headscale and Headplane are configured to +use the *exact same client* in your Identity Provider (IdP). This means that +both services should share the same client ID and secret. -::: tip -If you are using a custom prefix other than `/admin` for the Headplane web UI, -please ensure that you adjust the redirect URL accordingly when setting up -your OIDC client. +This is necessary because Headplane relies on the user IDs provided by the IdP +to match users with their equivalent Headscale users. If Headscale and Headplane +are using different clients, the user IDs may not match up correctly, preventing +a user from viewing their devices in Headplane. ::: -Before creating the client, configure Headplane to use a redirect URL that your -IdP will accept. You'll need to set **`server.base_url`** to the public URL of your -Headplane instance in your configuration file. For example, if your Headplane -instance runs on `https://headplane.example.com/admin`, set: +You'll need the following things set up before proceeding: +- A working Headplane installation that is already configured. +- An Identity Provider (IdP) that supports OAuth2 and OpenID Connect (OIDC). +- `server.base_url` set to the public URL of your Headplane instance in your +configuration file (ie. the domain that's visible in the browser). +- A Headscale API key with a relatively long expiration time (eg. 1 year). -```yaml -server: - base_url: "https://headplane.example.com" -``` +### Configuring the Client +You'll need to create a client in your Identity Provider (IdP) that Headplane +can use for authentication. A part of that step involves giving an allowed +"redirect URL" to your IdP. This URL is where the IdP will send users back to +after they have authenticated. -and provide the following redirect URL to your IdP when creating the client: +For Headplane, the redirect URL will be in the following format, where the +domain is replaced with the value set for `server.base_url` in your Headplane +configuration: ``` https://headplane.example.com/admin/auth/callback ``` -### Headscale API Key -Once you have created the client with your IdP, you'll need to generate an API -key for Headplane to use when communicating with Headscale. You can do this by -running `headscale apikeys create -e 1y` to create an API key that is valid for -one year (you can adjust the expiration as needed). Make sure to copy the -generated API key as you will need it for the Headplane configuration. +Once you have created the client in your IdP, make note of the following +information as you'll need it for the Headplane configuration: +- Client ID +- Client Secret (if applicable) +- Issuer URL - -### Headplane Configuration -Finally, you can configure Headplane to use OIDC by adding the following fields -to your Headplane configuration file: +### OIDC Configuration +To enable OIDC authentication in Headplane, you'll need to add the necessary +configuration options via the file or environment variables. See below: ```yaml oidc: + headscale_api_key: "" issuer: "https://your-idp.com" client_id: "your-client-id" client_secret: "your-client-secret" - headscale_api_key: "" + # You can also provide the client secret via a file: + # client_secret_path: "${HOME}/secrets/headplane_oidc_client_secret.txt" # Those options should generally be sufficient, but you can also set these: # authorization_endpoint: "" @@ -82,10 +85,21 @@ oidc: # baz: "qux" ``` +Headplane automatically tries to discover the necessary OIDC endpoints but if +your IdP does not support discovery, you may need to manually specify them. + ### PKCE + +::: warning +Headplane currently only supports the **`S256`** code challenge method for PKCE. +You may need to ensure that your Identity Provider is configured to accept this +method. +::: + By default, Headplane does not use PKCE (Proof Key for Code Exchange) when communicating with the Identity Provider. PKCE is generally a best practice for -OIDC and can enhance security. To enable PKCE you'll need to set `oidc.use_pkce` +OIDC and can enhance security. *Some Identity Providers may even require PKCE +to be used.* To enable PKCE you'll need to set `oidc.use_pkce` to `true` in your Headplane configuration file: ```yaml @@ -93,9 +107,6 @@ oidc: use_pkce: true ``` -You'll also need to ensure that your Identity Provider supports PKCE and is -properly configured to handle PKCE requests from Headplane. - ## Troubleshooting Some of the common issues you may encounter when configuring OIDC with Headplane include: