update changelog notes about oidc

Signed-off-by: Kristoffer Dalby <[email protected]>

CHANGELOG.md

@@ -2,8 +2,13 @@
 
 ## Next
 
+## 0.24.0 (2024-xx-xx)
+
 ### 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`).
@@ -22,32 +27,40 @@ 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.
 
-This issue _only_ affects Headscale installations which authenticate with OIDC.
-
 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.
 
-#### Migrating existing installations
-
 Headscale v0.23.0 and earlier never recorded the `iss` and `sub` fields, so all
 legacy (existing) OIDC accounts from _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.**
 
-Headscale v0.24.0 will ignore any `email` claim if the IdP does not provide an
-`email_verified` claim set to `true`.
-[What "verified" actually means is contextually dependent](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)
-– Headscale uses it as a signal that the contents of the `email` claim is
-reasonably trustworthy.
+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 uses can not log in anymore.
+
+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.
 
-Headscale v0.23.0 and earlier never checked the `email_verified` claim. This
-means even if an IdP explicitly indicated to Headscale that its `email` claim
-was untrustworthy, Headscale would have still accepted it.
+Please not 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.
+
+<details>
+
+<summary>What does automatic migration do?</summary>
 
 ##### What does automatic migration do?
 
@@ -74,16 +87,17 @@ 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. Mass updates would
-require Headscale implement a protocol like SCIM, which is **extremely**
-complicated and not available in all identity providers.
-
-Administrators could also attempt to migrate users manually by editing the
-database, using their own mapping rules with known-good data sources.
+_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`.
 
+</details>
+
+<details>
+
+<summary>What happens when automatic migration is disabled?</summary>
+
 ##### What happens when automatic migration is disabled?
 
 When automatic migration is disabled (`map_legacy_users: false`), Headscale will
@@ -98,6 +112,8 @@ 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.
 
+</details>
+
 Special thanks to @micolous for reviewing, proposing and working with us on
 these changes.