From 0f12e414a67ad1afc846c189336890723e88a7a6 Mon Sep 17 00:00:00 2001 From: Stefan Bethke Date: Fri, 27 Feb 2026 09:48:43 +0100 Subject: [PATCH] Explain one approach to update OIDC provider info See #3112 --- docs/ref/oidc.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/ref/oidc.md b/docs/ref/oidc.md index c7ef2d70..fe0e8c40 100644 --- a/docs/ref/oidc.md +++ b/docs/ref/oidc.md @@ -370,3 +370,9 @@ oidc: Groups for the [allowed groups filter](#authorize-users-with-filters) need to be specified with their group ID(UUID) instead of the group name. + +## Switching OIDC providers + +Headscale only supports a single OIDC provider in its configuration, but it does store the provider identifier of each user. When switching providers, this might lead to issues with existing users: all user details (name, email, groups) might be identical with the new provider, but the identifier will differ. Headscale will be unable to create a new user as the name and email will already be in use for the existing users. + +At this time, you will need to manually update the `provider_identifier` column in the `users` table for each user with the appropriate value for the new provider. The identifier is built from the `iss` and `sub` claims of the OIDC ID token, for example `https://id.example.com/12340987`.