headplane/role-mapping-examples.yaml

# Headplane OIDC Role Mapping Configuration Examples
# Copy and customize these examples for your organization

# Example 1: Basic Corporate Structure
basic_corporate:
  role_mapping:
    owner: ["ceo", "cto", "founder"]
    admin: ["it-admin", "platform-admin", "devops-lead"]
    network_admin: ["network-team", "infrastructure"]
    it_admin: ["helpdesk", "support-team", "it-staff"]
    auditor: ["compliance", "audit-team", "security"]

# Example 2: Healthcare Organization
healthcare:
  role_mapping:
    owner: ["chief-information-officer", "it-director"]
    admin: ["hipaa-admin", "system-admin"]
    network_admin: ["network-ops", "infrastructure-team"]
    it_admin: ["clinical-it", "medical-devices"]
    auditor: ["hipaa-compliance", "privacy-officer"]

# Example 3: Financial Services
financial:
  role_mapping:
    owner: ["risk-management", "compliance-officer"]
    admin: ["fintech-admin", "platform-ops"]
    network_admin: ["trading-infrastructure", "market-data"]
    it_admin: ["client-support", "operations"]
    auditor: ["regulatory-compliance", "sox-audit"]

# Example 4: Educational Institution
education:
  role_mapping:
    owner: ["dean-technology", "it-director"]
    admin: ["campus-it", "student-systems"]
    network_admin: ["network-services", "infrastructure"]
    it_admin: ["faculty-support", "classroom-tech"]
    auditor: ["ferpa-compliance", "data-governance"]

# Example 5: Multi-Tenant SaaS
saas_multi_tenant:
  role_mapping:
    owner: ["tenant-admin", "account-owner"]
    admin: ["tenant-manager", "org-admin"]
    network_admin: ["network-manager", "infrastructure-admin"]
    it_admin: ["support-agent", "customer-success"]
    auditor: ["compliance-viewer", "read-only-admin"]

# Example 6: Government/Military
government:
  role_mapping:
    owner: ["system-administrator", "security-control-assessor"]
    admin: ["isso", "issm", "system-admin"]  # Information System Security Officer/Manager
    network_admin: ["network-administrator", "communications"]
    it_admin: ["user-administrator", "help-desk"]
    auditor: ["compliance-auditor", "inspector-general"]

# Example 7: Startup/Small Company
startup:
  role_mapping:
    owner: ["founder", "cto", "tech-lead"]
    admin: ["senior-engineer", "devops"]
    network_admin: ["infrastructure", "platform"]
    it_admin: ["engineer", "developer"]
    auditor: ["security-champion", "compliance"]

# Example 8: Manufacturing
manufacturing:
  role_mapping:
    owner: ["plant-manager", "it-manager"]
    admin: ["automation-engineer", "control-systems"]
    network_admin: ["industrial-network", "scada-admin"]
    it_admin: ["manufacturing-it", "maintenance"]
    auditor: ["quality-assurance", "safety-inspector"]

# Example 9: Azure AD Integration
azure_ad:
  role_mapping:
    owner: ["Headscale Owners", "Global Administrators"]
    admin: ["Headscale Admins", "Application Administrators"]
    network_admin: ["Network Administrators", "Infrastructure Team"]
    it_admin: ["Helpdesk Operators", "User Administrators"]
    auditor: ["Security Readers", "Compliance Managers"]

# Example 10: Okta Groups
okta:
  role_mapping:
    owner: ["Headscale_Owners", "IT_Directors"]
    admin: ["Headscale_Admins", "System_Administrators"]
    network_admin: ["Network_Team", "DevOps_Engineers"]
    it_admin: ["Support_Staff", "Technical_Support"]
    auditor: ["Audit_Team", "Security_Analysts"]

# Advanced Configuration Options
advanced_config:
  # Case sensitivity (default: false)
  case_sensitive: false
  
  # Group prefix stripping (removes common prefixes)
  strip_prefixes:
    - "CORP_"
    - "AD_"
    - "headscale-"
  
  # Group suffix stripping (removes common suffixes)
  strip_suffixes:
    - "_GROUP"
    - "_ROLE"
  
  # Fallback role for unmatched groups (default: member)
  fallback_role: "member"
  
  # Log role assignments for audit
  audit_logging: true
  
  # Allow multiple group matches (highest privilege wins)
  multiple_groups: true

# Role Capability Reference
role_capabilities:
  owner:
    - "All capabilities including system ownership"
    - "Can modify other users' roles"
    - "Full administrative access"
  
  admin:
    - "Administrative access to all features"
    - "Cannot modify owner accounts"
    - "User and machine management"
  
  network_admin:
    - "Network configuration and routing"
    - "DNS and subnet management"
    - "Read access to users and machines"
  
  it_admin:
    - "Machine and user management"
    - "Support operations"
    - "Limited network access"
  
  auditor:
    - "Read-only access to all features"
    - "Audit trail and compliance viewing"
    - "No modification capabilities"
  
  member:
    - "No UI access (zero capabilities)"
    - "Can only use client software"
    - "Requires manual role assignment"

# Testing Configuration
test_users:
  # Use these test accounts to verify role mapping
  - email: "owner@company.com"
    groups: ["cto"]
    expected_role: "owner"
  
  - email: "admin@company.com" 
    groups: ["it-admin"]
    expected_role: "admin"
  
  - email: "network@company.com"
    groups: ["network-team"]
    expected_role: "network_admin"
  
  - email: "support@company.com"
    groups: ["helpdesk"]
    expected_role: "it_admin"
  
  - email: "auditor@company.com"
    groups: ["compliance"]
    expected_role: "auditor"

# Migration Strategy
migration_approach:
  # Phase 1: Deploy with all users as 'member'
  # Phase 2: Test role mapping with select users
  # Phase 3: Enable role mapping for all users
  # Phase 4: Remove manual role assignments
  
  steps:
    1. "Deploy OIDC role mapping with feature flag disabled"
    2. "Configure group mappings for your organization"
    3. "Test with pilot users in each role category"
    4. "Enable role mapping for production"
    5. "Monitor and adjust mappings as needed"