gsadmin/headplane
1
0
Fork 0
mirror of https://github.com/tale/headplane.git synced 2026-09-04 19:25:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: go more indepth on sso setup

Browse Source
This commit is contained in:
Aarnav Tale
2025-12-05 15:38:16 -05:00
parent 3a3e5ca65e
commit 1463a8cc42
1 changed files with 55 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/sso.md
+55 -44
View File
@@ -1,6 +1,7 @@
--- ---
title: Single Sign-On (SSO) title: Single Sign-On (SSO)
description: Configure Single Sign-On (SSO) authentication for Headplane. description: Configure Single Sign-On (SSO) authentication for Headplane.
outline: [2, 3]
--- ---
# Single Sign-On (SSO) # Single Sign-On (SSO)
@@ -11,66 +12,68 @@ description: Configure Single Sign-On (SSO) authentication for Headplane.
<figcaption>SSO Configuration Page</figcaption> <figcaption>SSO Configuration Page</figcaption>
</figure> </figure>
Headplane supports Single Sign-On (SSO) authentication using OpenID Connect Single Sign-On allows users to authenticate with Headplane through an external
(OIDC). This allows users to authenticate using an external Identity Provider Identity Provider (IdP). It does this using the OpenID Connect (OIDC) protocol,
(IdP) that supports OIDC, streamlining the login process and enhancing security. which is widely supported by many popular IdPs.
This is generally the recommended authentication method when using Headplane in ## Getting Started
production environments as it provides the deepest integration with Headscale To set up Single Sign-On (SSO) with Headplane, there are several steps involved.
and allows for seamless user management. As a general recommendation, please read through the entire guide before
beginning the process as there are several important factors to consider.
## Configuring OIDC ### Requirements
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:
| Field | Description | ::: warning
|---------------------------|--------------------------------------------------| If you are also using OpenID Connect (OIDC) authentication with Headscale, it is
| **Client ID** | The client identifier provided by your IdP. | **fundamentally important** that both Headscale and Headplane are configured to
| **Client Secret** | The client secret provided by your IdP. | use the *exact same client* in your Identity Provider (IdP). This means that
| **Issuer URL** | The OIDC issuer URL given by your IdP. | both services should share the same client ID and secret.
::: tip This is necessary because Headplane relies on the user IDs provided by the IdP
If you are using a custom prefix other than `/admin` for the Headplane web UI, to match users with their equivalent Headscale users. If Headscale and Headplane
please ensure that you adjust the redirect URL accordingly when setting up are using different clients, the user IDs may not match up correctly, preventing
your OIDC client. a user from viewing their devices in Headplane.
::: :::
Before creating the client, configure Headplane to use a redirect URL that your You'll need the following things set up before proceeding:
IdP will accept. You'll need to set **`server.base_url`** to the public URL of your - A working Headplane installation that is already configured.
Headplane instance in your configuration file. For example, if your Headplane - An Identity Provider (IdP) that supports OAuth2 and OpenID Connect (OIDC).
instance runs on `https://headplane.example.com/admin`, set: - `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 ### Configuring the Client
server: You'll need to create a client in your Identity Provider (IdP) that Headplane
base_url: "https://headplane.example.com" 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 https://headplane.example.com/admin/auth/callback
``` ```
### Headscale API Key Once you have created the client in your IdP, make note of the following
Once you have created the client with your IdP, you'll need to generate an API information as you'll need it for the Headplane configuration:
key for Headplane to use when communicating with Headscale. You can do this by - Client ID
running `headscale apikeys create -e 1y` to create an API key that is valid for - Client Secret (if applicable)
one year (you can adjust the expiration as needed). Make sure to copy the - Issuer URL
generated API key as you will need it for the Headplane configuration.
### OIDC Configuration
### Headplane Configuration To enable OIDC authentication in Headplane, you'll need to add the necessary
Finally, you can configure Headplane to use OIDC by adding the following fields configuration options via the file or environment variables. See below:
to your Headplane configuration file:
```yaml ```yaml
oidc: oidc:
headscale_api_key: "<generated-api-key>"
issuer: "https://your-idp.com" issuer: "https://your-idp.com"
client_id: "your-client-id" client_id: "your-client-id"
client_secret: "your-client-secret" client_secret: "your-client-secret"
headscale_api_key: "<generated-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: # Those options should generally be sufficient, but you can also set these:
# authorization_endpoint: "" # authorization_endpoint: ""
@@ -82,10 +85,21 @@ oidc:
# baz: "qux" # 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 ### 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 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 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: to `true` in your Headplane configuration file:
```yaml ```yaml
@@ -93,9 +107,6 @@ oidc:
use_pkce: true 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 ## Troubleshooting
Some of the common issues you may encounter when configuring OIDC with Headplane Some of the common issues you may encounter when configuring OIDC with Headplane
include: include: