feat(auth): support deriving roles from the IDP

Closes HP-352.

config.example.yaml

@@ -290,6 +290,19 @@ integration:
 #     - "open_id"
 #     - "email"
 #
+#   # Role assigned to new OIDC users after the first owner is bootstrapped.
+#   # This is useful with Headscale's OIDC allowed_domains / allowed_groups
+#   # restrictions when every permitted SSO user should receive the same
+#   # Headplane permissions. Valid values: admin, network_admin, it_admin,
+#   # auditor, viewer, member. The owner role is only granted to the first user.
+#   default_role: "member"
+#
+#   # Optional OIDC claim to read a Headplane role from when creating a new user.
+#   # This can be a string claim, or an array claim containing one of the valid
+#   # roles above. If present and valid, it takes precedence over default_role.
+#   # Configure your IdP to map groups or client roles into this claim.
+#   role_claim: "headplane_role"
+#
 #   # Allow ID token verification with legacy RSA keys smaller than 2048 bits.
 #   # This is disabled by default because it lowers token verification security and
 #   # should only be used as a temporary compatibility workaround.