feat(auth): support deriving roles from the IDP

Closes HP-352.

docs/NixOS-options.md

@@ -252,6 +252,15 @@ _Type:_ boolean
 
 _Default:_ `false`
 
+## settings.oidc.default_role
+
+_Description:_ Role assigned to newly created OIDC users after the first owner is bootstrapped.
+The owner role is reserved for the first-login bootstrap.
+
+_Type:_ one of "admin", "network_admin", "it_admin", "auditor", "viewer", "member"
+
+_Default:_ `"member"`
+
 ## settings.oidc.headscale_api_key_path
 
 _Description:_ DEPRECATED: Use `headscale.api_key_path` instead.
@@ -284,6 +293,17 @@ _Default:_ `""`
 
 _Example:_ `"https://headscale.example.com/admin/oidc/callback"`
 
+## settings.oidc.role_claim
+
+_Description:_ Optional OIDC claim containing the Headplane role to assign to newly created users.
+A valid role claim takes precedence over default_role.
+
+_Type:_ null or string
+
+_Default:_ `null`
+
+_Example:_ `"headplane_role"`
+
 ## settings.oidc.token_endpoint_auth_method
 
 _Description:_ The token endpoint authentication method.

docs/features/sso.md

@@ -74,6 +74,8 @@ oidc:
   # userinfo_endpoint: ""
   # scope: "openid email profile"
   # subject_claims: ["open_id", "email"]
+  # default_role: "member"
+  # role_claim: "headplane_role"
   # allow_weak_rsa_keys: false
   # extra_params:
   #  foo: "bar"
@@ -226,6 +228,40 @@ role. All subsequent users are assigned the **Member** role (no access) by
 default. An owner or admin must then assign them an appropriate role through
 the Users page.
 
+### Automatic Role Assignment
+
+You can change the role assigned to newly created OIDC users with
+`oidc.default_role`:
+
+```yaml
+oidc:
+  # Valid values: admin, network_admin, it_admin, auditor, viewer, member
+  default_role: "viewer"
+```
+
+This is useful when Headscale already restricts who can authenticate by domain,
+group, or user. For example, if Headscale only allows `@example.com` users to
+sign in and all of those users should be able to view Headplane, set
+`default_role: "viewer"`.
+
+For per-user roles from your IdP, configure `oidc.role_claim` with the OIDC
+claim that contains a Headplane role:
+
+```yaml
+oidc:
+  role_claim: "headplane_role"
+```
+
+The claim may be a string, such as `"admin"`, or an array containing one of the
+valid roles. This lets providers such as Keycloak map groups or client roles to
+a final Headplane role before login. When both `role_claim` and `default_role`
+are configured, a valid role claim takes precedence for new users.
+
+Automatic role assignment only applies when Headplane creates a user for the
+first time. It does not overwrite roles that were already assigned in Headplane.
+The **Owner** role is reserved for the first-login bootstrap and cannot be
+granted by `default_role` or `role_claim`.
+
 ### API Key Sessions
 
 Users who sign in with a Headscale API key (instead of OIDC) are treated as