Document ports in use

Ref: #1767

CHANGELOG.md

@@ -67,6 +67,12 @@ systemctl start headscale
   [#2625](https://github.com/juanfont/headscale/pull/2625)
 - Don't crash if config file is missing
   [#2656](https://github.com/juanfont/headscale/pull/2656)
+- Adds `/robots.txt` endpoint to avoid crawlers
+  [#2643](https://github.com/juanfont/headscale/pull/2643)
+- OIDC: Use group claim from UserInfo
+  [#2663](https://github.com/juanfont/headscale/pull/2663)
+- OIDC: Update user with claims from UserInfo *before* comparing with allowed
+  groups, email and domain [#2663](https://github.com/juanfont/headscale/pull/2663)
 
 ## 0.26.1 (2025-06-06)
 

cmd/headscale/cli/nodes.go

@@ -539,19 +539,25 @@ be assigned to nodes.`,
 		output, _ := cmd.Flags().GetString("output")
 
 		confirm := false
-		prompt := &survey.Confirm{
-			Message: "Are you sure that you want to assign/remove IPs to/from nodes?",
+
+		force, _ := cmd.Flags().GetBool("force")
+		if !force {
+			prompt := &survey.Confirm{
+				Message: "Are you sure that you want to assign/remove IPs to/from nodes?",
+			}
+			err = survey.AskOne(prompt, &confirm)
+			if err != nil {
+				return
+			}
 		}
-		err = survey.AskOne(prompt, &confirm)
-		if err != nil {
-			return
-		}
-		if confirm {
+
+
+		if confirm || force {
 			ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 			defer cancel()
 			defer conn.Close()
 
-			changes, err := client.BackfillNodeIPs(ctx, &v1.BackfillNodeIPsRequest{Confirmed: confirm})
+			changes, err := client.BackfillNodeIPs(ctx, &v1.BackfillNodeIPsRequest{Confirmed: confirm || force })
 			if err != nil {
 				ErrorOutput(
 					err,

docs/setup/requirements.md

@@ -4,11 +4,35 @@ Headscale should just work as long as the following requirements are met:
 
 - A server with a public IP address for headscale. A dual-stack setup with a public IPv4 and a public IPv6 address is
   recommended.
-- Headscale is served via HTTPS on port 443[^1].
+- Headscale is served via HTTPS on port 443[^1] and [may use additional ports](#ports-in-use).
 - A reasonably modern Linux or BSD based operating system.
 - A dedicated local user account to run headscale.
 - A little bit of command line knowledge to configure and operate headscale.
 
+## Ports in use
+
+The ports in use vary with the intended scenario and enabled features. Some of the listed ports may be changed via the
+[configuration file](../ref/configuration.md) but we recommend to stick with the default values.
+
+- tcp/80
+    - Expose publicly: yes
+    - HTTP, used by Let's Encrypt to verify ownership via the HTTP-01 challenge.
+    - Only required if the built-in Let's Enrypt client with the HTTP-01 challenge is used. See [TLS](../ref/tls.md) for
+      details.
+- tcp/443
+    - Expose publicly: yes
+    - HTTPS, required to make Headscale available to Tailscale clients[^1]
+    - Required if the built-in DERP server is enabled
+- udp/3478
+    - Expose publicly: yes
+    - STUN, required if the built-in DERP server is enabled
+- tcp/50443
+    - Expose publicly: yes
+    - Only required if the gRPC interface is used to [remote-control Headscale](../ref/remote-cli.md).
+- tcp/9090
+    - Expose publicly: no
+    - [Metrics and debug endpoint](../ref/debug.md#metrics-and-debug-endpoint)
+
 ## Assumptions
 
 The headscale documentation and the provided examples are written with a few assumptions in mind:

hscontrol/app.go

@@ -449,6 +449,7 @@ func (h *Headscale) createRouter(grpcMux *grpcRuntime.ServeMux) *mux.Router {
 	router.HandleFunc(ts2021UpgradePath, h.NoiseUpgradeHandler).
 		Methods(http.MethodPost, http.MethodGet)
 
+	router.HandleFunc("/robots.txt", h.RobotsHandler).Methods(http.MethodGet)
 	router.HandleFunc("/health", h.HealthHandler).Methods(http.MethodGet)
 	router.HandleFunc("/key", h.KeyHandler).Methods(http.MethodGet)
 	router.HandleFunc("/register/{registration_id}", h.authProvider.RegisterHandler).

hscontrol/handlers.go

@@ -180,6 +180,21 @@ func (h *Headscale) HealthHandler(
 	respond(nil)
 }
 
+func (h *Headscale) RobotsHandler(
+	writer http.ResponseWriter,
+	req *http.Request,
+) {
+	writer.Header().Set("Content-Type", "text/plain")
+	writer.WriteHeader(http.StatusOK)
+	_, err := writer.Write([]byte("User-agent: *\nDisallow: /"))
+	if err != nil {
+		log.Error().
+			Caller().
+			Err(err).
+			Msg("Failed to write response")
+	}
+}
+
 var codeStyleRegisterWebAPI = styles.Props{
 	styles.Display:         "block",
 	styles.Padding:         "20px",

hscontrol/oidc.go

@@ -254,6 +254,35 @@ func (a *AuthProviderOIDC) OIDCCallbackHandler(
 		return
 	}
 
+	// Fetch user information (email, groups, name, etc) from the userinfo endpoint
+	// https://openid.net/specs/openid-connect-core-1_0.html#UserInfo
+	var userinfo *oidc.UserInfo
+	userinfo, err = a.oidcProvider.UserInfo(req.Context(), oauth2.StaticTokenSource(oauth2Token))
+	if err != nil {
+		util.LogErr(err, "could not get userinfo; only using claims from id token")
+	}
+
+	// The oidc.UserInfo type only decodes some fields (Subject, Profile, Email, EmailVerified).
+	// We are interested in other fields too (e.g. groups are required for allowedGroups) so we
+	// decode into our own OIDCUserInfo type using the underlying claims struct.
+	var userinfo2 types.OIDCUserInfo
+	if userinfo != nil && userinfo.Claims(&userinfo2) == nil && userinfo2.Sub == claims.Sub {
+		// Update the user with the userinfo claims (with id token claims as fallback).
+		// TODO(kradalby): there might be more interesting fields here that we have not found yet.
+		claims.Email = cmp.Or(userinfo2.Email, claims.Email)
+		claims.EmailVerified = cmp.Or(userinfo2.EmailVerified, claims.EmailVerified)
+		claims.Username = cmp.Or(userinfo2.PreferredUsername, claims.Username)
+		claims.Name = cmp.Or(userinfo2.Name, claims.Name)
+		claims.ProfilePictureURL = cmp.Or(userinfo2.Picture, claims.ProfilePictureURL)
+		if userinfo2.Groups != nil {
+			claims.Groups = userinfo2.Groups
+		}
+	} else {
+		util.LogErr(err, "could not get userinfo; only using claims from id token")
+	}
+
+	// The user claims are now updated from the the userinfo endpoint so we can verify the user a
+	// against allowed emails, email domains, and groups.
 	if err := validateOIDCAllowedDomains(a.cfg.AllowedDomains, &claims); err != nil {
 		httpError(writer, err)
 		return
@@ -269,30 +298,6 @@ func (a *AuthProviderOIDC) OIDCCallbackHandler(
 		return
 	}
 
-	var userinfo *oidc.UserInfo
-	userinfo, err = a.oidcProvider.UserInfo(req.Context(), oauth2.StaticTokenSource(oauth2Token))
-	if err != nil {
-		util.LogErr(err, "could not get userinfo; only checking claim")
-	}
-
-	// If the userinfo is available, we can check if the subject matches the
-	// claims, then use some of the userinfo fields to update the user.
-	// https://openid.net/specs/openid-connect-core-1_0.html#UserInfo
-	if userinfo != nil && userinfo.Subject == claims.Sub {
-		claims.Email = cmp.Or(claims.Email, userinfo.Email)
-		claims.EmailVerified = cmp.Or(claims.EmailVerified, types.FlexibleBoolean(userinfo.EmailVerified))
-
-		// The userinfo has some extra fields that we can use to update the user but they are only
-		// available in the underlying claims struct.
-		// TODO(kradalby): there might be more interesting fields here that we have not found yet.
-		var userinfo2 types.OIDCUserInfo
-		if err := userinfo.Claims(&userinfo2); err == nil {
-			claims.Username = cmp.Or(claims.Username, userinfo2.PreferredUsername)
-			claims.Name = cmp.Or(claims.Name, userinfo2.Name)
-			claims.ProfilePictureURL = cmp.Or(claims.ProfilePictureURL, userinfo2.Picture)
-		}
-	}
-
 	user, policyChanged, err := a.createOrUpdateUserFromClaim(&claims)
 	if err != nil {
 		log.Error().

hscontrol/types/users.go

@@ -310,6 +310,7 @@ type OIDCUserInfo struct {
 	PreferredUsername string          `json:"preferred_username"`
 	Email             string          `json:"email"`
 	EmailVerified     FlexibleBoolean `json:"email_verified,omitempty"`
+	Groups            []string        `json:"groups"`
 	Picture           string          `json:"picture"`
 }