juanfont/headscale v0.24.0-beta.2 on GitHub

Security fix: OIDC changes in Headscale 0.24.0

The following issue only affects Headscale installations which authenticate
with OIDC.

Headscale v0.23.0 and earlier identified OIDC users by the "username" part of
their email address (when strip_email_domain: true, the default) or whole
email address (when strip_email_domain: false).

Depending on how Headscale and your Identity Provider (IdP) were configured,
only using the email claim could allow a malicious user with an IdP account to
take over another Headscale user's account, even when
strip_email_domain: false.

This would also cause a user to lose access to their Headscale account if they
changed their email address.

Headscale v0.24.0 now identifies OIDC users by the iss and sub claims.
These are guaranteed by the OIDC specification to be stable and unique,
even if a user changes email address. A well-designed IdP will typically set
sub to an opaque identifier like a UUID or numeric ID, which has no relation
to the user's name or email address.

Headscale v0.24.0 and later will also automatically update profile fields with
OIDC data on login. This means that users can change those details in your IdP,
and have it populate to Headscale automatically the next time they log in.
However, this may affect the way you reference users in policies.

Headscale v0.23.0 and earlier never recorded the iss and sub fields, so all
legacy (existing) OIDC accounts need to be migrated to be properly
secured.

What do I need to do to migrate?

Headscale v0.24.0 has an automatic migration feature, which is enabled by
default (map_legacy_users: true). This will be disabled by default in a
future version of Headscale – any unmigrated users will get new accounts.

The migration will mostly be done automatically, with one exception. If your
OIDC does not provide an email_verified claim, Headscale will ignore the
email. This means that either the administrator will have to mark the user
emails as verified, or ensure the users verify their emails. Any unverified
emails will be ignored, meaning that the users will get new accounts instead
of being migrated.

After this exception is ensured, make all users log into Headscale with their
account, and Headscale will automatically update the account record. This will
be transparent to the users.

When all users have logged in, you can disable the automatic migration by
setting map_legacy_users: false in your configuration file.

Please note that map_legacy_users will be set to false by default in v0.25.0
and the migration mechanism will be removed in v0.26.0.

What does automatic migration do?

When automatic migration is enabled (map_legacy_users: true), Headscale will
first match an OIDC account to a Headscale account by iss and sub, and then
fall back to matching OIDC users similarly to how Headscale v0.23.0 did:

If strip_email_domain: true (the default): the Headscale username matches
the "username" part of their email address.
If strip_email_domain: false: the Headscale username matches the whole
email address.

On migration, Headscale will change the account's username to their
preferred_username. This could break any ACLs or policies which are
configured to match by username.

Like with Headscale v0.23.0 and earlier, this migration only works for users who
haven't changed their email address since their last Headscale login.

A successful automated migration should otherwise be transparent to users.

Once a Headscale account has been migrated, it will be unavailable to be
matched by the legacy process. An OIDC login with a matching username, but
non-matching iss and sub will instead get a new Headscale account.

Because of the way OIDC works, Headscale's automated migration process can
only work when a user tries to log in after the update.

Legacy account migration should have no effect on new installations where all
users have a recorded sub and iss.

What happens when automatic migration is disabled?

When automatic migration is disabled (map_legacy_users: false), Headscale will
only try to match an OIDC account to a Headscale account by iss and sub.

If there is no match, it will get a new Headscale account – even if there was
a legacy account which could have matched and migrated.

We recommend new Headscale users explicitly disable automatic migration – but it
should otherwise have no effect if every account has a recorded iss and sub.

When automatic migration is disabled, the strip_email_domain setting will have
no effect.

Special thanks to @micolous for reviewing, proposing and working with us on
these changes.

Other OIDC changes

Headscale now uses
the standard OIDC claims
to populate and update user information every time they log in:

Headscale profile field	OIDC claim	Notes / examples
email address	`email`	Only used when `"email_verified": true`
display name	`name`	eg: `Sam Smith`
username	`preferred_username`	Varies depending on IdP and configuration, eg: `ssmith`, `ssmith@idp.example.com`, `\\example.com\ssmith`
profile picture	`picture`	URL to a profile picture or avatar

These should show up nicely in the Tailscale client.

This will also affect the way you
reference users in policies.

BREAKING

Remove dns.use_username_in_magic_dns configuration option
#2020,
#2279
- Having usernames in magic DNS is no longer possible.
Remove versions older than 1.56
#2149
- Clean up old code required by old versions
User gRPC/API #2261:
- If you depend on a Headscale Web UI, you should wait with this update until
  the UI have been updated to match the new API.
- GET /api/v1/user/{name} and GetUser have been removed in favour of ListUsers with an ID parameter
- RenameUser and DeleteUser now require an ID instead of a name.

Changes

Improved compatibilty of built-in DERP server with clients connecting over
WebSocket #2132
Allow nodes to use SSH agent forwarding
#2145
Fixed processing of fields in post request in MoveNode rpc
#2179
Added conversion of 'Hostname' to 'givenName' in a node with FQDN rules
applied #2198
Fixed updating of hostname and givenName when it is updated in HostInfo
#2199
Fixed missing stable-debug container tag
#2232
Loosened up server_url and base_domain check. It was overly strict in some
cases. #2248
CLI for managing users now accepts --identifier in addition to --name,
usage of --identifier is recommended
#2261
Add dns.extra_records_path configuration option #2262
Support client verify for DERP #2046

Changelog

e270169 Add -race Flag to GitHub Action and Fix Data Race in CreateTailscaleNodesInUser (#2038)
47b405d Changelog: support client verify for DERP
7d937c6 Correct macOS GUI connect guide because there's no ALT key on a mac (#2306)
3269cfd Mention reload and SIGHUP when editing the ACL policy file
0acb2b5 Misc doc updates
65304a0 Remove sealos documentation
bbc93a9 Set title for code listings
319ce67 Update DNS documentation for dns.extra_records_path
af4508b bump deps (#2308)
5345f19 fix issue where some oidc claim bools are sent as string (#2297)
ec8729b fix sighup issue with empty acl (#2296)
770f3dc fix tags not resolving to username if email is present (#2309)
ccc895b fixes to extra-record file watcher (#2298)
e00b9d9 flake.lock: Update (#2294)