diff --git a/config-example.yaml b/config-example.yaml index d109f64b..dbb08202 100644 --- a/config-example.yaml +++ b/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: diff --git a/docs/ref/oidc.md b/docs/ref/oidc.md index beb36ae0..f6ec1bcd 100644 --- a/docs/ref/oidc.md +++ b/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.