From efd83da14e71a5cffee54d41edb86694ab14642d Mon Sep 17 00:00:00 2001 From: Florian Preinstorfer Date: Fri, 20 Mar 2026 19:34:12 +0100 Subject: [PATCH] Explicitly mention that a headscale username should *not* end with @ See: #3149 --- docs/ref/oidc.md | 6 ++++-- docs/ref/registration.md | 7 +++++-- docs/usage/getting-started.md | 4 +++- 3 files changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/ref/oidc.md b/docs/ref/oidc.md index 8684764a..cdbbebc2 100644 --- a/docs/ref/oidc.md +++ b/docs/ref/oidc.md @@ -191,8 +191,10 @@ You may refer to users in the Headscale policy via: !!! note "A user identifier in the policy must contain a single `@`" The Headscale policy requires a single `@` to reference a user. If the username or provider identifier doesn't - already contain a single `@`, it needs to be appended at the end. For example: the username `ssmith` has to be - written as `ssmith@` to be correctly identified as user within the policy. + already contain a single `@`, it needs to be appended at the end. For example: the Headscale username `ssmith` has + to be written as `ssmith@` to be correctly identified as user within the policy. + + Ensure that the Headscale username itself does not end with `@`. !!! warning "Email address or username might be updated by users" diff --git a/docs/ref/registration.md b/docs/ref/registration.md index 17cf4894..9f51de88 100644 --- a/docs/ref/registration.md +++ b/docs/ref/registration.md @@ -33,7 +33,8 @@ node can be approved with: - [Headscale API](api.md) - Or delegated to an identity provider via [OpenID Connect](oidc.md) -Web authentication relies on the presence of a Headscale user. Use the `headscale users` command to create a new user: +Web authentication relies on the presence of a Headscale user. Use the `headscale users` command to create a new +user[^1]: ```console headscale users create @@ -98,7 +99,7 @@ Its best suited for automation. === "Personal devices" - A personal node is always assigned to a Headscale user. Use the `headscale users` command to create a new user: + A personal node is always assigned to a Headscale user. Use the `headscale users` command to create a new user[^1]: ```console headscale users create @@ -139,3 +140,5 @@ Its best suited for automation. The registration of a tagged node is complete and it should be listed as "online" in the output of `headscale nodes list`. The "User" column displays `tagged-devices` as the owner of the node. See the "Tags" column for the list of assigned tags. + +[^1]: [Ensure that the Headscale username does not end with `@`.](oidc.md#reference-a-user-in-the-policy) diff --git a/docs/usage/getting-started.md b/docs/usage/getting-started.md index 5eb11226..3171c348 100644 --- a/docs/usage/getting-started.md +++ b/docs/usage/getting-started.md @@ -61,7 +61,7 @@ options, run: ## Manage headscale users In headscale, a node (also known as machine or device) is [typically assigned to a headscale -user](../ref/registration.md#identity-model). Such a headscale user may have many nodes assigned to them and can be +user](../ref/registration.md#identity-model). Such a headscale user[^1] may have many nodes assigned to them and can be managed with the `headscale users` command. Invoke the built-in help for more information: `headscale users --help`. ### Create a headscale user @@ -149,3 +149,5 @@ The command returns the preauthkey on success which is used to connect a node to ```shell tailscale up --login-server --authkey ``` + +[^1]: [Ensure that the Headscale username does not end with `@`.](../ref/oidc.md#reference-a-user-in-the-policy)