Privilege Guidelines

Privilege Guidelines

This document defines roles, permissions, and access control within Codex Web. Understanding these guidelines is essential for proper user management and security.

Role Hierarchy

Platform Admin (Highest Privilege)
    │
    ├─> Full platform access
    ├─> All admin operations
    └─> Unrestricted resource access

Group Admin (Group-Scoped)
    │
    ├─> Manage workspaces in assigned groups
    ├─> View group resources
    └─> Cannot modify group membership

Member (Basic Access)
    │
    ├─> Create own workspaces
    ├─> View own group information
    └─> Manage personal resources

Role Definitions

Platform Admin

Purpose: Full platform administration and management

Granted To:

• IT administrators
• DevOps engineers
• Platform operators
• System administrators

Access Level: FULL (unrestricted)

Key Capabilities:

• All user management operations
• Create, modify, and delete groups
• Access all workspaces across the platform
• View and manage all resources
• Configure system settings
• Access audit logs
• View platform-wide statistics

Group Admin

Purpose: Manage workspaces and resources within specific groups

Granted To:

• Team leads
• Project managers
• Senior developers managing team resources
• Department coordinators

Access Level: GROUP-SCOPED (limited to assigned groups)

Key Capabilities:

• Manage all workspaces in their group(s)
• View all group members
• Monitor group resource usage
• Start/stop/delete any workspace in group
• View workspace logs and metrics

Limitations:

• Cannot add/remove group members
• Cannot modify group quotas
• Cannot create new groups
• Cannot access other groups
• Cannot promote users to admin

Member

Purpose: Standard user access for development work

Granted To:

• Developers
• Analysts
• Contractors
• General users

Access Level: SELF-SCOPED (own resources only)

Key Capabilities:

• Create workspaces in assigned groups
• Manage own workspaces
• View group information
• Access group resources (within quota)
• Update personal profile

Limitations:

• Can only manage own workspaces
• Cannot delete others' workspaces
• Cannot modify group settings
• Cannot view others' workspace details
• Cannot add users to groups

Permission Matrix

User Management

Action	Member	Group Admin	Platform Admin
View own profile	✅	✅	✅
Edit own profile	✅	✅	✅
View other users' profiles	❌	⚠️ Group only	✅
Create users	❌	❌	✅
Delete users	❌	❌	✅
Enable/disable users	❌	❌	✅
Reset passwords	❌	❌	✅
Promote to admin	❌	❌	✅
Manage group membership	❌	❌	✅

Group Management

Action	Member	Group Admin	Platform Admin
View own groups	✅	✅	✅
View group members	✅	✅	✅
View group resources	✅	✅	✅
View all groups	❌	❌	✅
Create groups	❌	❌	✅
Delete groups	❌	❌	✅
Modify group quotas	❌	❌	✅
Add group members	❌	❌	✅
Remove group members	❌	❌	✅
Set group admin roles	❌	❌	✅

Workspace Management

Action	Member	Group Admin	Platform Admin
Create workspace	✅	✅	✅
View own workspaces	✅	✅	✅
View group workspaces	❌	⚠️ Group only	✅
View all workspaces	❌	❌	✅
Start/stop own workspace	✅	✅	✅
Start/stop group workspace	❌	⚠️ Group only	✅
Delete own workspace	✅	✅	✅
Delete group workspace	❌	⚠️ Group only	✅
Delete any workspace	❌	❌	✅
View workspace logs	⚠️ Own only	⚠️ Group only	✅
View workspace metrics	⚠️ Own only	⚠️ Group only	✅
Update workspace details	⚠️ Own only	⚠️ Group only	✅

System Operations

Action	Member	Group Admin	Platform Admin
View dashboard	✅	✅	✅
View platform stats	❌	❌	✅
Access admin panel	❌	❌	✅
View audit logs	❌	❌	✅
Modify system settings	❌	❌	✅
View cluster capacity	❌	❌	✅
Manage pricing config	❌	❌	✅

Legend:

• ✅ Full access
• ❌ No access
• ⚠️ Limited/scoped access

Access Control Rules

Group-Scoped Permissions

Group Admin Access:

A Group Admin can perform actions on a workspace IF:

(user.isAdmin == true) OR
(workspace.groupId IN user.groupMemberships WHERE role == "admin")

Example:

• User is Group Admin for grp_engineering

• Workspace belongs to grp_engineering

• Result: ✅ Can manage the workspace

• User is Group Admin for grp_engineering

• Workspace belongs to grp_marketing

• Result: ❌ Cannot access the workspace

Self-Scoped Permissions

Member Access:

A Member can perform actions on a workspace IF:

(workspace.userId == user.id) OR
(user.isAdmin == true) OR
(isGroupAdmin(user, workspace.groupId))

Example:

• User created the workspace

• Result: ✅ Can manage the workspace

• User didn't create the workspace

• User is not admin

• Result: ❌ Cannot manage the workspace

Group Membership Requirements

Workspace Creation:

User can create workspace in group IF:

(groupId IN user.groups) OR
(groupId IN user.groupMemberships.map(m => m.groupId)) OR
(user.isAdmin == true)

Example:

• User belongs to grp_engineering

• Trying to create workspace in grp_engineering

• Result: ✅ Allowed

• User doesn't belong to grp_marketing

• Trying to create workspace in grp_marketing

• Result: ❌ Denied

Role Assignment Guidelines

When to Grant Platform Admin

Appropriate Use Cases:

• Full-time IT administrators
• DevOps team members
• Platform operations staff
• System administrators

Approval Required:

• Manager approval
• Security team review
• Documented justification
• Regular access review

Security Considerations:

• Minimize number of platform admins (recommended: 2-4)
• Require MFA for all admins
• Regular audit of admin actions
• Document all admin accounts

Not Appropriate For:

• Temporary access needs → Use Group Admin
• Single-group management → Use Group Admin
• Development work → Use Member
• External contractors → Use Member

When to Grant Group Admin

Appropriate Use Cases:

• Team leads managing team workspaces
• Project managers overseeing projects
• Department coordinators
• Senior engineers managing junior developers

Approval Required:

• Team manager approval
• Documented need
• Limited to specific groups

Security Considerations:

• Grant per-group, not platform-wide
• Review group admin assignments quarterly
• Revoke when responsibility changes
• Document reason for assignment

Not Appropriate For:

• Users who only need own workspaces → Use Member
• Across-group management → Use Platform Admin
• Temporary projects → Use Member

When to Use Member Role

Appropriate Use Cases:

• Standard developers
• Analysts
• Contractors
• Temporary users
• External collaborators

Default Role:

• All new users start as Members
• Escalate only when needed
• Most users should remain Members

Privilege Escalation Process

Requesting Platform Admin Access

Process:

1. User submits formal request
2. Justification documented
3. Manager approves
4. Security team reviews
5. Platform admin grants access
6. Action logged in audit log

Required Documentation:

• Business justification
• Job responsibilities
• Duration of need
• Alternative approaches considered

Requesting Group Admin Access

Process:

1. User requests access to specific group
2. Group owner/manager approves
3. Platform admin grants group admin role
4. User notified of new permissions

Required Documentation:

• Which group(s) need access
• Why group admin role needed
• Expected duration

Revoking Elevated Privileges

Automatic Triggers:

• User changes roles
• User leaves organization
• Project completion
• End of defined access period

Manual Review:

• Quarterly access reviews
• Annual certification
• Incident investigation
• Policy violations

Security Best Practices

For Platform Admins

Account Security:

• Enable MFA
• Use strong, unique passwords
• Rotate credentials quarterly
• Never share credentials
• Use dedicated admin accounts (not personal)

Operational Security:

• Review audit logs weekly
• Investigate anomalies immediately
• Document all admin actions
• Follow change management procedures
• Test in dev/staging first

Access Management:

• Regular review of user access
• Quarterly audit of admin accounts
• Document all privilege grants
• Revoke access promptly
• Follow least privilege principle

For Group Admins

Responsible Management:

• Only manage workspaces when needed
• Communicate with workspace owners
• Document major changes
• Don't abuse access
• Report security concerns

Resource Management:

• Monitor group resources
• Communicate with team about limits
• Clean up unused workspaces with owner consent
• Plan capacity needs

For All Users

Account Hygiene:

• Use strong passwords
• Don't share credentials
• Log out when done
• Report suspicious activity
• Follow security policies

Workspace Security:

• Don't commit secrets
• Use appropriate access controls
• Secure workspace passwords
• Delete when no longer needed

Compliance and Auditing

Audit Logging

Logged Actions:

• User creation/deletion
• Role changes
• Group membership changes
• Admin privilege grants
• Workspace deletions
• System setting changes

Audit Log Contents:

{
  "id": "audit_abc123",
  "userId": "usr_admin1",
  "username": "admin@example.com",
  "action": "promote_user_to_admin",
  "resource": "user:usr_target",
  "details": {
    "promotedUser": "developer@example.com",
    "reason": "DevOps team member"
  },
  "timestamp": "2024-12-03T10:00:00Z",
  "success": true
}

Retention:

• Logs retained for 90 days (minimum)
• Compliance may require longer
• Export for long-term storage
• Regular backup of audit data

Access Reviews

Quarterly Reviews:

• List all Platform Admins
• Verify business need
• Confirm manager approval
• Update documentation

Annual Certification:

• All elevated privileges reviewed
• Managers certify access
• Revoke unnecessary access
• Document review results

Compliance Requirements

SOC 2 / ISO 27001:

• Documented access control policy
• Regular access reviews
• Audit logging enabled
• Least privilege enforced

GDPR:

• Document who has access to user data
• Justify admin access
• Track data access in logs
• Support data deletion requests

Troubleshooting

User Can't Perform Expected Action

Debug Steps:

1. Check user's role:

   GET /api/admin/users/{userId}

2. Verify group membership:
   • Check groups array
   • Check groupMemberships array
3. Confirm group admin role:
   • Check role in groupMemberships
4. Verify resource ownership:
   • Check workspace userId

Common Issues:

• User in group but wrong role
• Workspace in different group
• User removed from group
• Admin privileges revoked

Workspace Access Denied

Check:

• Is user member of workspace's group?
• Does user own the workspace?
• Is user group admin for that group?
• Is user platform admin?

Resolution:

• Add user to group if appropriate
• Grant group admin role if needed
• Escalate to platform admin if required

Admin Operations Failing

Verify:

• User has platform admin status (isAdmin: true)
• Token is valid and not expired
• User is not trying to demote self
• Target resources exist

Role Transition Examples

Example 1: Developer Promotion to Team Lead

Before:

• Role: Member
• Groups: grp_engineering (member)
• Can: Manage own workspaces

Change:

# Promote to group admin
POST /api/admin/users/{userId}/groups/grp_engineering/promote

After:

• Role: Member + Group Admin
• Groups: grp_engineering (admin)
• Can: Manage all workspaces in engineering group

Example 2: IT Staff Promotion

Before:

• Role: Member
• Groups: grp_it (member)
• Can: Manage own workspaces

Change:

# Promote to platform admin
POST /api/admin/users/{userId}/promote

After:

• Role: Platform Admin
• Groups: grp_it (member)
• Can: Full platform access

Example 3: Contractor Offboarding

Before:

• Role: Member
• Groups: grp_project_a (member), grp_project_b (member)
• Can: Manage own workspaces

Change:

# Remove from groups
DELETE /api/admin/users/{userId}/groups/grp_project_a
DELETE /api/admin/users/{userId}/groups/grp_project_b

# Disable account
POST /api/admin/users/{userId}/disable

After:

• Role: Member (disabled)
• Groups: (none)
• Can: Nothing (account disabled)

Next Steps

• User Account Management - Managing user accounts
• Group Management - Creating and managing groups
• Workspace Administration - Admin workspace operations

---

← User Account Management | Group Management →