headplane/examples/enterprise-configurations.md

# Enterprise Configuration Examples

This document provides complete configuration examples for deploying Headscale and Headplane with OIDC role mapping in various enterprise environments.

## Corporate IT Environment

### Scenario
- Large corporate environment with IT department hierarchy
- Azure AD as identity provider
- Role-based access control based on organizational structure

### Headscale Configuration
```yaml
# /etc/headscale/config.yaml
server_url: "https://headscale.corp.example.com"
listen_addr: "0.0.0.0:8080"
metrics_listen_addr: "0.0.0.0:9090"
grpc_listen_addr: "0.0.0.0:50443"

# Corporate IP ranges
prefixes:
  v4: 10.100.0.0/16
  v6: fd00:corp::/48

database:
  type: postgres
  postgres:
    host: postgres.internal
    port: 5432
    name: headscale
    user: headscale
    pass: "${DB_PASSWORD}"
    ssl: require

# Azure AD OIDC configuration
oidc:
  issuer: "https://login.microsoftonline.com/your-tenant-id/v2.0"
  client_id: "headscale-client-id"
  client_secret: "${AZURE_CLIENT_SECRET}"
  scope: ["openid", "profile", "email", "groups"]
  extra_params:
    domain_hint: "corp.example.com"
    prompt: "select_account"
  
  # Corporate security requirements
  expiry: 30d
  use_expiry_from_token: false
  
  # Allow only corporate domain
  allowed_domains:
    - "corp.example.com"

# DNS configuration for corporate network
dns:
  override_local_dns: true
  nameservers:
    global: ["10.1.1.10", "10.1.1.11"]  # Corporate DNS
  domains:
    - "corp.example.com"
    - "internal.corp.example.com"
  magic_dns: true
  base_domain: vpn.corp.example.com

# Security hardening
disable_check_updates: true
ephemeral_node_inactivity_timeout: 8h

policy:
  mode: file
  path: "/etc/headscale/corporate-acl.hujson"

log:
  format: json
  level: info
```

### Headplane Configuration
```yaml
# /etc/headplane/config.yaml
headscale:
  url: "https://headscale.corp.example.com"
  api_key: "${HEADSCALE_API_KEY}"

server:
  port: 3000
  cookie_secret: "${COOKIE_SECRET}"

oidc:
  enabled: true
  issuer_url: "https://login.microsoftonline.com/your-tenant-id/v2.0"
  client_id: "headplane-client-id"
  client_secret: "${AZURE_CLIENT_SECRET}"
  scope: "openid profile email groups"
  redirect_uri: "https://headplane.corp.example.com/admin/oidc/callback"
  headscale_api_key: "${HEADSCALE_API_KEY}"
  
  extra_params:
    domain_hint: "corp.example.com"
    prompt: "select_account"

  # Corporate role mapping
  role_mapping:
    owner: ["Global Administrators", "IT Directors"]
    admin: ["IT Administrators", "System Administrators"]
    network_admin: ["Network Team", "Infrastructure Admins"]
    it_admin: ["Help Desk", "Desktop Support", "IT Staff"]
    auditor: ["Compliance Team", "Security Auditors"]

integration:
  provider: "kubernetes"

log:
  level: "info"
  format: "json"
```

## Healthcare Organization

### Scenario
- Healthcare provider with HIPAA compliance requirements
- Keycloak as identity provider
- Role-based access with audit trails

### Headscale Configuration
```yaml
# /etc/headscale/config.yaml
server_url: "https://vpn.healthcorp.com"
listen_addr: "0.0.0.0:8080"

# Healthcare network segmentation
prefixes:
  v4: 172.20.0.0/16
  v6: fd20:health::/48

database:
  type: postgres
  postgres:
    host: postgres-primary.internal
    port: 5432
    name: headscale_prod
    user: headscale
    pass: "${DB_PASSWORD}"
    ssl: require

# Keycloak OIDC configuration
oidc:
  issuer: "https://auth.healthcorp.com/realms/healthcare"
  client_id: "headscale-vpn"
  client_secret: "${KEYCLOAK_CLIENT_SECRET}"
  scope: ["openid", "profile", "email", "groups"]
  
  # HIPAA compliance - shorter session times
  expiry: 12h
  use_expiry_from_token: false
  
  # Restrict to healthcare domain
  allowed_domains:
    - "healthcorp.com"
  
  # Additional HIPAA compliance groups
  allowed_groups:
    - "healthcare-staff"
    - "clinical-users"
    - "administrative-users"

# Healthcare DNS requirements
dns:
  override_local_dns: true
  nameservers:
    global: ["172.16.1.10", "172.16.1.11"]
  domains:
    - "healthcorp.com"
    - "emr.internal"
    - "clinical.internal"
  magic_dns: true
  base_domain: secure.healthcorp.com

# HIPAA audit requirements
log:
  format: json
  level: info

policy:
  mode: file
  path: "/etc/headscale/hipaa-acl.hujson"
```

### Headplane Configuration
```yaml
# /etc/headplane/config.yaml
headscale:
  url: "https://vpn.healthcorp.com"
  api_key: "${HEADSCALE_API_KEY}"

oidc:
  enabled: true
  issuer_url: "https://auth.healthcorp.com/realms/healthcare"
  client_id: "headplane-admin"
  client_secret: "${KEYCLOAK_CLIENT_SECRET}"
  scope: "openid profile email groups"
  redirect_uri: "https://admin.healthcorp.com/admin/oidc/callback"
  headscale_api_key: "${HEADSCALE_API_KEY}"

  # Healthcare role mapping
  role_mapping:
    owner: ["chief-information-officer", "security-officer"]
    admin: ["hipaa-admin", "it-admin"]
    network_admin: ["clinical-infrastructure", "network-ops"]
    it_admin: ["medical-devices", "clinical-support"]
    auditor: ["hipaa-compliance", "privacy-officer", "audit-team"]

# HIPAA audit logging
log:
  level: "info"
  format: "json"
  
# Disable features not needed in healthcare
integration:
  agent:
    enabled: false  # Reduce attack surface
```

## Financial Services

### Scenario
- Financial institution with SOX compliance
- Okta as identity provider
- High security requirements with audit trails

### Headscale Configuration
```yaml
# /etc/headscale/config.yaml
server_url: "https://secure-vpn.finserv.com"
listen_addr: "0.0.0.0:8080"

# Financial services network
prefixes:
  v4: 192.168.0.0/16
  v6: fd30:finserv::/48

database:
  type: postgres
  postgres:
    host: postgres-cluster.internal
    port: 5432
    name: headscale_production
    user: headscale_user
    pass: "${DATABASE_PASSWORD}"
    ssl: require

# Okta OIDC configuration
oidc:
  issuer: "https://finserv.okta.com/oauth2/default"
  client_id: "0oa1234567890abcdef"
  client_secret: "${OKTA_CLIENT_SECRET}"
  scope: ["openid", "profile", "email", "groups"]
  
  # Financial compliance - short sessions
  expiry: 8h
  use_expiry_from_token: false
  
  # Strict domain controls
  allowed_domains:
    - "finserv.com"
  
  # Financial compliance groups
  allowed_groups:
    - "trading-floor"
    - "compliance-team" 
    - "risk-management"
    - "technology-staff"

# Financial network DNS
dns:
  override_local_dns: true
  nameservers:
    global: ["10.10.10.10", "10.10.10.11"]
  domains:
    - "finserv.com"
    - "trading.internal"
    - "compliance.internal"
  magic_dns: true
  base_domain: vpn.finserv.com

# SOX compliance logging
log:
  format: json
  level: debug  # Enhanced logging for compliance

policy:
  mode: file
  path: "/etc/headscale/sox-compliance-acl.hujson"
```

### Headplane Configuration
```yaml
# /etc/headplane/config.yaml
headscale:
  url: "https://secure-vpn.finserv.com"
  api_key: "${HEADSCALE_API_KEY}"

oidc:
  enabled: true
  issuer_url: "https://finserv.okta.com/oauth2/default"
  client_id: "0oa9876543210fedcba"
  client_secret: "${OKTA_CLIENT_SECRET}"
  scope: "openid profile email groups"
  redirect_uri: "https://vpn-admin.finserv.com/admin/oidc/callback"
  headscale_api_key: "${HEADSCALE_API_KEY}"

  # Financial services role mapping
  role_mapping:
    owner: ["risk-management", "compliance-officer"]
    admin: ["fintech-admin", "trading-systems"]
    network_admin: ["market-data", "trading-infrastructure"]
    it_admin: ["client-support", "operations"]
    auditor: ["sox-audit", "regulatory-compliance"]

# SOX compliance audit logging
log:
  level: "debug"
  format: "json"

integration:
  provider: "kubernetes"
```

## Government/Defense

### Scenario
- Government agency with security clearance levels
- ADFS as identity provider
- Multi-level security (MLS) requirements

### Headscale Configuration
```yaml
# /etc/headscale/config.yaml
server_url: "https://secure.agency.gov"
listen_addr: "0.0.0.0:8080"

# Government network classification
prefixes:
  v4: 10.0.0.0/8
  v6: fd40:gov::/48

database:
  type: postgres
  postgres:
    host: postgres-ha.internal.gov
    port: 5432
    name: headscale_classified
    user: headscale_svc
    pass: "${CLASSIFIED_DB_PASSWORD}"
    ssl: require

# ADFS OIDC configuration
oidc:
  issuer: "https://adfs.agency.gov/adfs"
  client_id: "headscale-government"
  client_secret: "${ADFS_CLIENT_SECRET}"
  scope: ["openid", "profile", "email", "groups"]
  
  # Government security requirements
  expiry: 4h  # Short sessions for classified access
  use_expiry_from_token: false
  
  # Restrict to government personnel
  allowed_domains:
    - "agency.gov"
  
  # Security clearance groups
  allowed_groups:
    - "top-secret-clearance"
    - "secret-clearance"
    - "confidential-clearance"
    - "government-personnel"

# Government DNS
dns:
  override_local_dns: true
  nameservers:
    global: ["192.168.1.10", "192.168.1.11"]  # Classified DNS
  domains:
    - "agency.gov"
    - "classified.internal"
    - "unclassified.internal"
  magic_dns: true
  base_domain: vpn.agency.gov

# Government audit requirements
log:
  format: json
  level: trace  # Maximum logging for security

policy:
  mode: file
  path: "/etc/headscale/government-acl.hujson"
```

### Headplane Configuration
```yaml
# /etc/headplane/config.yaml
headscale:
  url: "https://secure.agency.gov"
  api_key: "${HEADSCALE_API_KEY}"

oidc:
  enabled: true
  issuer_url: "https://adfs.agency.gov/adfs"
  client_id: "headplane-government"
  client_secret: "${ADFS_CLIENT_SECRET}"
  scope: "openid profile email groups"
  redirect_uri: "https://admin.agency.gov/admin/oidc/callback"
  headscale_api_key: "${HEADSCALE_API_KEY}"

  # Government role mapping based on clearance levels
  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"]

# Government security logging
log:
  level: "trace"
  format: "json"

integration:
  provider: "docker"
```

## Multi-Tenant SaaS

### Scenario
- SaaS provider offering VPN services to multiple customers
- Auth0 as identity provider
- Tenant isolation and role mapping

### Headscale Configuration
```yaml
# /etc/headscale/config.yaml
server_url: "https://vpn.saasprovider.com"
listen_addr: "0.0.0.0:8080"

# Multi-tenant IP allocation
prefixes:
  v4: 100.64.0.0/10
  v6: fd50:saas::/32
  
ip_allocation: random  # Better for multi-tenant

database:
  type: postgres
  postgres:
    host: postgres-cluster.saasprovider.com
    port: 5432
    name: headscale_multitenant
    user: headscale
    pass: "${DATABASE_PASSWORD}"
    ssl: require

# Auth0 OIDC configuration
oidc:
  issuer: "https://saasprovider.auth0.com/"
  client_id: "auth0-client-id"
  client_secret: "${AUTH0_CLIENT_SECRET}"
  scope: ["openid", "profile", "email", "groups"]
  
  # SaaS tenant management
  expiry: 24h
  use_expiry_from_token: false
  
  # No domain restrictions for multi-tenant
  allowed_domains: []
  allowed_groups: []

# Multi-tenant DNS
dns:
  override_local_dns: false  # Let tenants manage their own DNS
  nameservers:
    global: ["1.1.1.1", "8.8.8.8"]
  magic_dns: true
  base_domain: tenant.vpn.saasprovider.com

log:
  format: json
  level: info

policy:
  mode: database  # Dynamic policies for multi-tenant
```

### Headplane Configuration
```yaml
# /etc/headplane/config.yaml
headscale:
  url: "https://vpn.saasprovider.com"
  api_key: "${HEADSCALE_API_KEY}"

oidc:
  enabled: true
  issuer_url: "https://saasprovider.auth0.com/"
  client_id: "headplane-saas-client"
  client_secret: "${AUTH0_CLIENT_SECRET}"
  scope: "openid profile email groups"
  redirect_uri: "https://admin.saasprovider.com/admin/oidc/callback"
  headscale_api_key: "${HEADSCALE_API_KEY}"

  # Multi-tenant role mapping
  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"]

# SaaS monitoring
log:
  level: "info"
  format: "json"

integration:
  provider: "kubernetes"
```

## Development/Testing Environment

### Scenario
- Development environment for testing OIDC role mapping
- Local Keycloak instance
- Simplified configuration for development

### Docker Compose
```yaml
version: '3.8'
services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: password
    volumes:
      - postgres_data:/var/lib/postgresql/data

  keycloak:
    image: quay.io/keycloak/keycloak:23.0
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: password
      KC_HOSTNAME_STRICT: false
      KC_HOSTNAME_STRICT_HTTPS: false
    ports:
      - "8280:8080"
    depends_on:
      - postgres
    command: start-dev

  headscale:
    image: headscale/headscale:latest
    command: serve
    volumes:
      - ./config/headscale-dev.yaml:/etc/headscale/config.yaml
      - headscale_data:/var/lib/headscale
    ports:
      - "8180:8080"
    depends_on:
      - keycloak

  headplane:
    image: ghcr.io/tale/headplane:latest
    volumes:
      - ./config/headplane-dev.yaml:/etc/headplane/config.yaml
    ports:
      - "3000:3000"
    depends_on:
      - headscale

volumes:
  postgres_data:
  headscale_data:
```

### Development Headscale Config
```yaml
# config/headscale-dev.yaml
server_url: "http://localhost:8180"
listen_addr: "0.0.0.0:8080"

prefixes:
  v4: 100.64.0.0/10
  v6: fd7a:115c:a1e0::/48

database:
  type: sqlite
  sqlite:
    path: /var/lib/headscale/db.sqlite

oidc:
  issuer: "http://keycloak:8080/realms/development"
  client_id: "headscale-dev"
  client_secret: "dev-client-secret"
  scope: ["openid", "profile", "email", "groups"]
  expiry: 30d

dns:
  magic_dns: true
  base_domain: headscale.local

log:
  level: debug
```

### Development Headplane Config
```yaml
# config/headplane-dev.yaml
headscale:
  url: "http://headscale:8080"
  api_key: "dev-api-key"

oidc:
  enabled: true
  issuer_url: "http://localhost:8280/realms/development"
  client_id: "headplane-dev"
  client_secret: "dev-client-secret"
  scope: "openid profile email groups"
  redirect_uri: "http://localhost:3000/admin/oidc/callback"
  headscale_api_key: "dev-api-key"

  # Development role mapping
  role_mapping:
    owner: ["developer", "admin"]
    admin: ["senior-dev", "team-lead"]
    network_admin: ["devops", "infrastructure"]
    it_admin: ["junior-dev", "intern"]
    auditor: ["qa", "tester"]

log:
  level: debug
```

This collection of configuration examples provides templates for deploying OIDC role mapping in various enterprise environments, from high-security government installations to multi-tenant SaaS platforms.