Document oidc.email_verification_required

config-example.yaml

@@ -362,6 +362,12 @@ unix_socket_permission: "0770"
 #   # required "openid" scope.
 #   scope: ["openid", "profile", "email"]
 #
+#   # Only verified email addresses are synchronized to the user profile by
+#   # default. Unverified emails may be allowed in case an identity provider
+#   # does not send the "email_verified: true" claim or email verification is
+#   # not required.
+#   email_verified_required: true
+#
 #   # Provide custom key/value pairs which get sent to the identity provider's
 #   # authorization endpoint.
 #   extra_params:

docs/ref/oidc.md

@@ -77,6 +77,7 @@ are configured, a user needs to pass all of them.
 
     * Check the email domain of each authenticating user against the list of allowed domains and only authorize users
       whose email domain matches `example.com`.
+    * A verified email address is required [unless email verification is disabled](#control-email-verification).
     * Access allowed: `alice@example.com`
     * Access denied: `bob@example.net`
 
@@ -93,6 +94,7 @@ are configured, a user needs to pass all of them.
 
     * Check the email address of each authenticating user against the list of allowed email addresses and only authorize
       users whose email is part of the `allowed_users` list.
+    * A verified email address is required [unless email verification is disabled](#control-email-verification).
     * Access allowed: `alice@example.com`, `bob@example.net`
     * Access denied: `mallory@example.net`
 
@@ -123,6 +125,23 @@ are configured, a user needs to pass all of them.
         - "headscale_users"
     ```
 
+### Control email verification
+
+Headscale uses the `email` claim from the identity provider to synchronize the email address to its user profile. By
+default, a user's email address is only synchronized when the identity provider reports the email address as verified
+via the `email_verified: true` claim.
+
+Unverified emails may be allowed in case an identity provider does not send the `email_verified` claim or email
+verification is not required. In that case, a user's email address is always synchronized to the user profile.
+
+```yaml hl_lines="5"
+oidc:
+  issuer: "https://sso.example.com"
+  client_id: "headscale"
+  client_secret: "generated-secret"
+  email_verified_required: false
+```
+
 ### Customize node expiration
 
 The node expiration is the amount of time a node is authenticated with OpenID Connect until it expires and needs to
@@ -189,7 +208,7 @@ endpoint.
 
 | Headscale profile   | OIDC claim           | Notes / examples                                                                                  |
 | ------------------- | -------------------- | ------------------------------------------------------------------------------------------------- |
-| email address       | `email`              | Only used when `email_verified: true`                                                             |
+| email address       | `email`              | Only verified emails are synchronized, unless `email_verified_required: false` is configured      |
 | display name        | `name`               | eg: `Sam Smith`                                                                                   |
 | username            | `preferred_username` | Depends on identity provider, eg: `ssmith`, `ssmith@idp.example.com`, `\\example.com\ssmith`      |
 | profile picture     | `picture`            | URL to a profile picture or avatar                                                                |
@@ -205,8 +224,6 @@ endpoint.
     - The username must be at least two characters long.
     - It must only contain letters, digits, hyphens, dots, underscores, and up to a single `@`.
     - The username must start with a letter.
-- A user's email address is only synchronized to the local user profile when the identity provider marks the email
-  address as verified (`email_verified: true`).
 
 Please see the [GitHub label "OIDC"](https://github.com/juanfont/headscale/labels/OIDC) for OIDC related issues.