OIDC groups implementation

- Add Groups field to User struct with JSON storage
- Include GetGroups() and SetGroups() helper methods
- Extract groups from OIDC claims in FromClaim()
- Add database migration 202509161200 for groups column
- Update config-example.yaml with groups scope
- Add comprehensive documentation and testing

docs/ref/oidc.md

@@ -194,13 +194,64 @@ endpoint.
 | 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                                                                |
 | provider identifier | `iss`, `sub`         | A stable and unique identifier for a user, typically a combination of `iss` and `sub` OIDC claims |
-|                     | `groups`             | [Only used to filter for allowed groups](#authorize-users-with-filters)                           |
+| group membership    | `groups`             | Used for [access filtering](#authorize-users-with-filters) and stored for external integrations   |
+
+## Group Storage and Integration
+
+Starting with Headscale v0.24.0, OIDC group membership is automatically extracted from authentication claims and stored in the database. This enables external integrations (such as web interfaces) to implement role-based access control based on a user's group membership.
+
+### Group Storage
+- Groups are extracted from both ID tokens and UserInfo endpoint responses
+- Group membership is updated on every successful OIDC login
+- Groups are stored as JSON in the user database for external access
+- Multiple group claim formats are supported (`groups`, `roles`, provider-specific claims)
+
+### External Integration
+External applications can query user group membership for implementing role-based access control:
+
+```bash
+# View user groups via Headscale CLI
+headscale users list --output json
+
+# Example database query (for direct database access)
+SELECT name, email, groups FROM users WHERE provider = 'oidc';
+```
+
+### Scope Requirements
+To enable group storage, ensure your OIDC configuration includes the `groups` scope:
+
+```yaml
+oidc:
+  issuer: "https://sso.example.com"
+  client_id: "headscale"
+  client_secret: "generated-secret"
+  scope: ["openid", "profile", "email", "groups"]
+```
+
+### Headplane Integration
+When using [Headplane](https://github.com/tale/headplane) as a web interface for Headscale, OIDC groups enable automatic role-based access control:
+
+- **Automatic Role Assignment**: Users are assigned roles based on their OIDC group membership
+- **Zero-Trust Security**: New users receive minimal access until proper groups are assigned
+- **Dynamic Updates**: User roles update automatically on each login based on current group membership
+- **Configurable Mapping**: Organizations can customize which groups map to which roles
+
+Example Headplane role mapping configuration:
+```yaml
+role_mapping:
+  owner: ["ceo", "cto", "headscale-owner"]
+  admin: ["it-admin", "platform-admin"] 
+  network_admin: ["network-team", "devops"]
+  auditor: ["compliance", "audit-team"]
+```
+
+For detailed Headplane OIDC configuration, see the [Headplane documentation](https://github.com/tale/headplane/docs).
 
 ## Limitations
 
 - Support for OpenID Connect aims to be generic and vendor independent. It offers only limited support for quirks of
   specific identity providers.
-- OIDC groups cannot be used in ACLs.
+- OIDC groups cannot be directly used in Headscale ACLs (use external integrations for role-based access control).
 - The username provided by the identity provider needs to adhere to this pattern:
     - The username must be at least two characters long.
     - It must only contain letters, digits, hyphens, dots, underscores, and up to a single `@`.