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

docker-dev/keycloak-config/realm-export.json

@@ -0,0 +1,188 @@
+{
+  "id": "headscale",
+  "realm": "headscale",
+  "displayName": "Headscale OIDC Test Realm",
+  "enabled": true,
+  "sslRequired": "external",
+  "registrationAllowed": false,
+  "loginWithEmailAllowed": true,
+  "duplicateEmailsAllowed": false,
+  "resetPasswordAllowed": true,
+  "editUsernameAllowed": true,
+  "bruteForceProtected": true,
+  "groups": [
+    {
+      "id": "headscale-owner",
+      "name": "headscale-owner",
+      "path": "/headscale-owner"
+    },
+    {
+      "id": "headscale-admin", 
+      "name": "headscale-admin",
+      "path": "/headscale-admin"
+    },
+    {
+      "id": "headscale-network",
+      "name": "headscale-network", 
+      "path": "/headscale-network"
+    },
+    {
+      "id": "headscale-it",
+      "name": "headscale-it",
+      "path": "/headscale-it"
+    },
+    {
+      "id": "headscale-audit", 
+      "name": "headscale-audit",
+      "path": "/headscale-audit"
+    },
+    {
+      "id": "headscale-member",
+      "name": "headscale-member",
+      "path": "/headscale-member"
+    }
+  ],
+  "users": [
+    {
+      "username": "owner@example.com",
+      "enabled": true,
+      "email": "owner@example.com",
+      "firstName": "Owner",
+      "lastName": "User", 
+      "credentials": [
+        {
+          "type": "password",
+          "value": "password123",
+          "temporary": false
+        }
+      ],
+      "groups": ["/headscale-owner"]
+    },
+    {
+      "username": "admin@example.com",
+      "enabled": true,
+      "email": "admin@example.com", 
+      "firstName": "Admin",
+      "lastName": "User",
+      "credentials": [
+        {
+          "type": "password",
+          "value": "password123",
+          "temporary": false
+        }
+      ],
+      "groups": ["/headscale-admin"]
+    },
+    {
+      "username": "network@example.com",
+      "enabled": true,
+      "email": "network@example.com",
+      "firstName": "Network",
+      "lastName": "Admin",
+      "credentials": [
+        {
+          "type": "password", 
+          "value": "password123",
+          "temporary": false
+        }
+      ],
+      "groups": ["/headscale-network"]
+    },
+    {
+      "username": "auditor@example.com",
+      "enabled": true,
+      "email": "auditor@example.com",
+      "firstName": "Auditor", 
+      "lastName": "User",
+      "credentials": [
+        {
+          "type": "password",
+          "value": "password123", 
+          "temporary": false
+        }
+      ],
+      "groups": ["/headscale-audit"]
+    },
+    {
+      "username": "member@example.com",
+      "enabled": true,
+      "email": "member@example.com",
+      "firstName": "Member",
+      "lastName": "User",
+      "credentials": [
+        {
+          "type": "password",
+          "value": "password123",
+          "temporary": false
+        }
+      ],
+      "groups": ["/headscale-member"]
+    }
+  ],
+  "clients": [
+    {
+      "clientId": "headscale-client",
+      "name": "Headscale OIDC Client",
+      "enabled": true,
+      "clientAuthenticatorType": "client-secret",
+      "secret": "your-client-secret",
+      "redirectUris": ["http://localhost:8180/oidc/callback"],
+      "webOrigins": ["http://localhost:8180"],
+      "standardFlowEnabled": true,
+      "implicitFlowEnabled": false,
+      "directAccessGrantsEnabled": false,
+      "serviceAccountsEnabled": false,
+      "publicClient": false,
+      "frontchannelLogout": true,
+      "protocol": "openid-connect",
+      "fullScopeAllowed": true,
+      "protocolMappers": [
+        {
+          "name": "groups",
+          "protocol": "openid-connect", 
+          "protocolMapper": "oidc-group-membership-mapper",
+          "consentRequired": false,
+          "config": {
+            "full.path": "false",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "claim.name": "groups",
+            "userinfo.token.claim": "true"
+          }
+        }
+      ]
+    },
+    {
+      "clientId": "headplane-client",
+      "name": "Headplane OIDC Client",
+      "enabled": true,
+      "clientAuthenticatorType": "client-secret",
+      "secret": "headplane-client-secret",
+      "redirectUris": ["http://localhost:3000/admin/oidc/callback"],
+      "webOrigins": ["http://localhost:3000"],
+      "standardFlowEnabled": true,
+      "implicitFlowEnabled": false,
+      "directAccessGrantsEnabled": false,
+      "serviceAccountsEnabled": false,
+      "publicClient": false,
+      "frontchannelLogout": true,
+      "protocol": "openid-connect",
+      "fullScopeAllowed": true,
+      "protocolMappers": [
+        {
+          "name": "groups",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-group-membership-mapper",
+          "consentRequired": false,
+          "config": {
+            "full.path": "false",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "claim.name": "groups",
+            "userinfo.token.claim": "true"
+          }
+        }
+      ]
+    }
+  ]
+}