feat(identity): enable field selector support for staff users

Pass field selectors from REST layer to backend provider to enable
staff users to query other users' identities and sessions. This is
required for the staff portal to view user identity provider links
and active sessions for support purposes.

Changes:
- Pass field selector from ListOptions to backend in useridentities
- Pass field selector from ListOptions to backend in sessions
- Update README documentation with field selector usage and security model
- Add test documentation for field selector authorization scenarios

Authorization model:
1. Milo RBAC: PolicyBinding grants access to identity resources
2. Backend authorization: Provider validates group membership
   - Regular users: Can only see their own data (no field selector)
   - Staff users: Can use field selectors to query other users
   - Groups: staff-users, fraud-manager (configured in Zitadel)

Security:
- Backward compatible: Regular users unaffected
- Defense in depth: Two layers of authorization
- Audit logging: All requests logged with user context
- Explicit deny: Non-staff users cannot use field selectors

This changes the previous 'self-scoped' design where field selectors
were intentionally ignored. The new behavior maintains self-scoped
access for regular users while enabling cross-user queries for staff.

Related: datum-cloud/staff-portal (staff user authorization)
Related: datum-cloud/auth-provider-zitadel (backend authorization)

Author: OscarLlamas6

internal/apiserver/identity/sessions/README.md

@@ -38,3 +38,30 @@ Naming & structure
 - internal/apiserver/identity/sessions/rest.go — REST storage
 - internal/apiserver/identity/sessions/dynamic.go — provider implementation
 
+Field Selector Support for Staff Users
+The Sessions API supports field selectors to enable staff users to query
+other users' active sessions. This is required for support and administrative
+purposes in the staff portal.
+
+Supported field selectors:
+- status.userUID=<user-id> — Query sessions for a specific user
+
+Authorization:
+- Regular users: Can only list their own sessions (field selectors are ignored)
+- Staff users: Can use field selectors to query other users' sessions
+  - Must be members of privileged groups in the identity provider (e.g., staff-users, fraud-manager)
+  - Authorization is enforced by the backend provider (auth-provider-zitadel)
+  - Requires appropriate PolicyBinding in Milo for RBAC
+
+Example usage:
+  # Regular user (sees only their own sessions)
+  kubectl get sessions
+
+  # Staff user (can query specific user's sessions)
+  kubectl get sessions --field-selector=status.userUID=<target-user-id>
+
+Security model:
+1. Milo RBAC: PolicyBinding grants access to sessions resource
+2. Backend authorization: Provider validates group membership for field selector usage
+3. Audit logging: All requests are logged with user context for compliance
+

internal/apiserver/identity/sessions/rest.go

@@ -49,8 +49,11 @@ func (r *REST) List(ctx context.Context, opts *metainternalversion.ListOptions)
 		groups = u.GetGroups()
 	}
 	logger.V(4).Info("Listing sessions", "username", username, "uid", uid, "groups", groups)
-	// ignore selectors; self-scoped list delegated to provider
+	// Pass field selector to backend provider for staff user queries
 	lo := metav1.ListOptions{}
+	if opts != nil && opts.FieldSelector != nil {
+		lo.FieldSelector = opts.FieldSelector.String()
+	}
 	res, err := r.backend.ListSessions(ctx, u, &lo)
 	if err != nil {
 		logger.Error(err, "List sessions failed")

internal/apiserver/identity/useridentities/README.md

@@ -38,6 +38,33 @@ Naming & structure
 - internal/apiserver/identity/useridentities/rest.go — REST storage
 - internal/apiserver/identity/useridentities/dynamic.go — provider implementation
 
+Field Selector Support for Staff Users
+The UserIdentities API supports field selectors to enable staff users to query
+other users' identity provider links. This is required for support and administrative
+purposes in the staff portal.
+
+Supported field selectors:
+- status.userUID=<user-id> — Query identities for a specific user
+
+Authorization:
+- Regular users: Can only list their own identities (field selectors are ignored)
+- Staff users: Can use field selectors to query other users' identities
+  - Must be members of privileged groups in the identity provider (e.g., staff-users, fraud-manager)
+  - Authorization is enforced by the backend provider (auth-provider-zitadel)
+  - Requires appropriate PolicyBinding in Milo for RBAC
+
+Example usage:
+  # Regular user (sees only their own identities)
+  kubectl get useridentities
+
+  # Staff user (can query specific user's identities)
+  kubectl get useridentities --field-selector=status.userUID=<target-user-id>
+
+Security model:
+1. Milo RBAC: PolicyBinding grants access to useridentities resource
+2. Backend authorization: Provider validates group membership for field selector usage
+3. Audit logging: All requests are logged with user context for compliance
+
 Read-only resource and admission webhook for deletion
 Unlike sessions, useridentities is a read-only resource. Users cannot create,
 update, or delete user identities through the Kubernetes API. Identity linking

internal/apiserver/identity/useridentities/rest.go

@@ -47,8 +47,11 @@ func (r *REST) List(ctx context.Context, opts *metainternalversion.ListOptions)
 		groups = u.GetGroups()
 	}
 	logger.V(4).Info("Listing user identities", "username", username, "uid", uid, "groups", groups)
-	// ignore selectors; self-scoped list delegated to provider
+	// Pass field selector to backend provider for staff user queries
 	lo := metav1.ListOptions{}
+	if opts != nil && opts.FieldSelector != nil {
+		lo.FieldSelector = opts.FieldSelector.String()
+	}
 	res, err := r.backend.ListUserIdentities(ctx, u, &lo)
 	if err != nil {
 		logger.Error(err, "List user identities failed")

test/identity/field-selector-authorization/README.md

@@ -0,0 +1,121 @@
+# Field Selector Authorization Tests
+
+This test suite validates that field selector authorization works correctly for
+UserIdentities and Sessions resources in the Identity API.
+
+## Test Scenarios
+
+### 1. Regular User - Self-Scoped Access (Default Behavior)
+**Given:** A regular user without staff privileges
+**When:** User lists useridentities without field selector
+**Then:** User sees only their own identity provider links
+
+**When:** User attempts to use field selector for another user
+**Then:** Request is rejected with 403 Forbidden error
+
+### 2. Staff User - Cross-User Access with Field Selector
+**Given:** A user in the staff-users group
+**When:** User lists useridentities with field selector for another user
+**Then:** User successfully retrieves the target user's identity provider links
+
+### 3. Field Selector Validation
+**Given:** Any authenticated user
+**When:** User provides invalid field selector (e.g., metadata.name)
+**Then:** Request is rejected with appropriate error message
+
+## Authorization Model
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. Milo RBAC Check                                          │
+│    - PolicyBinding grants access to useridentities resource │
+│    - Required for both regular and staff users              │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 2. Field Selector Passed to Backend                         │
+│    - Milo passes field selector to auth-provider-zitadel    │
+│    - No validation at Milo layer                            │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 3. Backend Authorization (auth-provider-zitadel)            │
+│    - If no field selector: use authenticated user's UID     │
+│    - If field selector with different UID:                  │
+│      → Check user groups (staff-users, fraud-manager)       │
+│      → Allow if staff, deny if not                          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Required Setup
+
+### PolicyBindings
+```yaml
+# Grant staff-users access to useridentities
+apiVersion: iam.miloapis.com/v1alpha1
+kind: PolicyBinding
+metadata:
+  name: staff-useridentities-viewer
+  namespace: milo-system
+spec:
+  resourceSelector:
+    resourceKind:
+      apiGroup: identity.miloapis.com
+      kind: UserIdentity
+  roleRef:
+    name: identity-user-session-viewer
+    namespace: milo-system
+  subjects:
+  - kind: Group
+    name: staff-users
+    namespace: milo-system
+    uid: <staff-users-group-uid>
+```
+
+### Zitadel Configuration
+- Create group: `staff-users`
+- Assign users to group via project roles
+- Configure JWT claims to include groups
+
+## Manual Testing
+
+### Test 1: Regular User Cannot Use Field Selector
+```bash
+# As regular user
+kubectl get useridentities --field-selector=status.userUID=<other-user-id>
+
+# Expected: 403 Forbidden
+# Error: "only staff users can query other users' identities"
+```
+
+### Test 2: Staff User Can Use Field Selector
+```bash
+# As staff user (member of staff-users group)
+kubectl get useridentities --field-selector=status.userUID=<target-user-id>
+
+# Expected: 200 OK
+# Response: List of target user's identity provider links
+```
+
+### Test 3: Regular User Can See Own Data
+```bash
+# As regular user
+kubectl get useridentities
+
+# Expected: 200 OK
+# Response: List of own identity provider links
+```
+
+## Security Considerations
+
+1. **Defense in Depth**: Two layers of authorization (Milo RBAC + Backend groups)
+2. **Audit Logging**: All requests logged with user context
+3. **Principle of Least Privilege**: Regular users cannot access others' data
+4. **Explicit Deny**: Field selector attempts by non-staff users are explicitly denied
+
+## Future Enhancements
+
+- [ ] Add automated E2E tests using Chainsaw
+- [ ] Add rate limiting for staff user queries
+- [ ] Add metrics for field selector usage
+- [ ] Consider adding SubjectAccessReview checks in Milo layer