Releases: juanfont/headscale
v0.25.1
v0.25.0
BREAKING
- Authentication flow has been rewritten
#2374 This change should be
transparent to users with the exception of some buxfixes that has been
discovered and was fixed as part of the rewrite. - Remove support for Tailscale clients older than 1.62 (Capability version 87)
#2405
Changes
oidc.map_legacy_users
is nowfalse
by default
#2350- Print Tailscale version instead of capability versions for outdated nodes
#2391 - Do not allow renaming of users from OIDC
#2393 - Change minimum hostname length to 2
#2393 - Fix migration error caused by nodes having invalid auth keys
#2412 - Pre auth keys belonging to a user are no longer deleted with the user
#2396 - Pre auth keys that are used by a node can no longer be deleted
#2396 - Rehaul HTTP errors, return better status code and errors to users
#2398
Changelog
- d5037c2 date in changelog
v0.25.0-beta.2
BREAKING
- Authentication flow has been rewritten
#2374 This change should be
transparent to users with the exception of some buxfixes that has been
discovered and was fixed as part of the rewrite. - Remove support for Tailscale clients older than 1.62 (Capability version 87)
#2405
Changes
oidc.map_legacy_users
is nowfalse
by default
#2350- Print Tailscale version instead of capability versions for outdated nodes
#2391 - Do not allow renaming of users from OIDC
#2393 - Change minimum hostname length to 2
#2393 - Fix migration error caused by nodes having invalid auth keys
#2412 - Pre auth keys belonging to a user are no longer deleted with the user
#2396 - Pre auth keys that are used by a node can no longer be deleted
#2396 - Rehaul HTTP errors, return better status code and errors to users
#2398
Changelog
v0.24.3
v0.25.0-beta.1
Help beta testing:
We would like to encourage users, and especially companies/organisations using headscale to join testing of every release.
Headscale is open source and it is maintained by a small group of volunteers. We need your help to ensure that the software is stable and secure.
The previous release had some issues that was only found after release, we would like to avoid that in the future. This could have been avoided if
companies and organisations had helped tested the release before it was released.
This release improves and fixes some long standing bugs in the authentication flow, we need help testing this release to ensure new bugs are not introduced.
The interesting things would be to test the following:
- Logging in and out with the same user (with all auth methods)
- Changing user with the same node
BREAKING
- Authentication flow has been rewritten
#2374 This change should be
transparent to users with the exception of some buxfixes that has been
discovered and was fixed as part of the rewrite. - Remove support for Tailscale clients older than 1.62 (Capability version 87)
#2405
Changes
oidc.map_legacy_users
is nowfalse
by default
#2350- Print Tailscale version instead of capability versions for outdated nodes
#2391 - Do not allow renaming of users from OIDC
#2393 - Change minimum hostname length to 2
#2393 - Pre auth keys belonging to a user are no longer deleted with the user
#2396 - Pre auth keys that are used by a node can no longer be deleted
#2396 - Rehaul HTTP errors, return better status code and errors to users
#2398
Changelog
- 8c09afe Headscale implements a single tailnet
- f12cb2e Headscale now updates the user profile
- 8076c94 Release docs 0.24 (#2349)
- f44b1d3 Remove routes without a node_id (#2386)
- 45752db Return better web errors to the user (#2398)
- d57a55c Rewrite authentication flow (#2374)
- 8b92c01 add 1.80 to capver and update deps (#2394)
- cd3b8e6 clean up handler methods, common logging (#2384)
- 2c279e0 create and rename usernames validated by new func (#2381)
- 9bd1438 do not allow preauth keys to be deleted if assigned to node (#2396)
- 9ae3570 drop versions older than 1.62 (#2405)
- d1dbe4e fix panic if derp update is 0 (#2368)
- 9e3f945 fix postgres migration issue with 0.24 (#2367)
- aa76980 flake.lock: Update (#2353)
- 97e5d95 flake.lock: Update (#2378)
- 9a7890d flake.lock: Update (#2402)
- e172c29 initial capver packet tracking version (#2391)
- 615ee5d make it harder to insert invalid routes (#2371)
- 1c7f3bc no edit of oidc users, minimum hostname length (#2393)
- c1f42cd relax user validation to allow emails, add tests from various oidc providers (#2364)
- 5b986ed set oidc.map_legacy_users false (#2350)
- 7ba6ad3 simplify findUserByToken in ACL, add missing testcases (#2388)
- 4c8e847 use dedicated registration ID for auth flow (#2337)
v0.24.2
v0.24.1
v0.24.0
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?
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?
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 , [email protected] , \\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}
andGetUser
have been removed in favour ofListUsers
with an ID parameterRenameUser
andDeleteUser
now require an ID instead of a name.
- If you depend on a Headscale Web UI, you should wait with this update until
Changes
- Improved compatibility 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
andbase_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
- Add PKCE Verifier for OIDC #2314
Changelog
- ede4f97 Fix typos
- fa641e3 Set CSRF cookies for OIDC (#2328)
- 1ab7b31 Update apple.md for latest version of iOS (#2321)
- 38aef77 allow @ and Log if OIDC username is not consider valid (#2340)
- b81420b feat: Add PKCE Verifier for OIDC (#2314)
- caad5c6 fix nil pointer deref (#2339)
- 9313e5b flake.lock: Update (#2313)
- f9bbfa5 flake.lock: Update (#2320)
- 41bad2b flake.lock: Update (#2324)
- 610597b flake.lock: Update (#2342)
- e88406e set changelog date (#2347)
- e4a3dcc use headscale server url as domain instead of base_domain (#2338)
v0.24.0-beta.2
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?
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?
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 , [email protected] , \\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}
andGetUser
have been removed in favour ofListUsers
with an ID parameterRenameUser
andDeleteUser
now require an ID instead of a name.
- If you depend on a Headscale Web UI, you should wait with this update until
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
andbase_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)
v0.24.0-beta.1
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?
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?
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 , [email protected] , \\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}
andGetUser
have been removed in favour ofListUsers
with an ID parameterRenameUser
andDeleteUser
now require an ID instead of a name.
- If you depend on a Headscale Web UI, you should wait with this update until
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
andbase_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
Changelog
- b6dc6eb #2140 Fixed reflection of hostname change (#2199)
- cc42fc3 #2177 Added conversion of 'Hostname' to 'givenName' in a node with FQDN rules applied (#2198)
- b3cda08 #2178 Fixed processing of fields in post request in MoveNode rpc (#2179)
- e367454 Add -it to docker exec (#2148)
- 75e7411 Add FAQ entry on which database to use
- 2345c38 Add a page for third-party tools (#2217)
- 1e61084 Add compatibility with only websocket-capable clients (#2132)
- 0602304 Add headplane
- 204a102 Add ouroboros to web ui list (#2154)
- 4445649 Add versioned documentation
- 380fcdb Add worker reading extra_records_path from file (#2271)
- 07b596d Allow nodes to use SSH agent forwarding (#2145)
- 7512e23 Bump deprecated github actions
- 24e7851 Changed all the html into go using go-elem (#2161)
- dc17b4d Documentation dependencies (#2252)
- 0089cea Feature tvos documentation (#2226)
- 0d3cf74 Fix README links to point to the stable version
- d2a86b1...