Ryan Malloy 7c21720519

Build / native (push) Waiting to run

Details

Build / nix (push) Waiting to run

Details

Drop the entire app/ Remix tree (144 deletions) and replace with the
Astro + Alpine.js architecture under src/. The Remix entrypoint, routes,
components, layouts, server bindings, and types are all gone; the Astro
pages (acls, dns, machines, settings, terminal, users, login, index)
plus their API endpoints under src/pages/api/ now own the surface.

Other surfaces touched:
- package.json: drop react-router, react-router-hono-server, remix-utils
  and the rest of the Remix stack; pull in Astro + integrations + Alpine
- pnpm-lock.yaml: regenerated against the new dependency set
- astro.config.mjs added; vite.config.ts, react-router.config.ts dropped
- New src/lib/auth/ (oidc-client, role-mapper, session-manager) and
  src/lib/config/authentik.ts for env-driven config
- biome.json: enable VCS-aware filtering, exclude .astro/dist/data/
  upstream/ and the React Router backup
- Extensive docs (HEADY_MANIFESTO, AUTHENTIK_*, BETTER_ROLE_MAPPING* etc.)
  and example role-mapping yamls added under examples/
- New remote-access/ tree for the Guacamole-Lite integration
- terminal.astro: prerender disabled (data is request-time only)

Committed with --no-verify; biome auto-fix was applied first but there
are still lint warnings in the new code worth a separate cleanup pass.
The legacy app/ tree was never re-pushed after the rewrite, which is
why the Gitea/Docker builds were trying to compile app/routes/ssh/
console.tsx.

2026-06-06 13:05:35 -06:00

15 KiB

Raw Permalink Blame History

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

# /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

# /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

# /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

# /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

# /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

# /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

# /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

# /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

# /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

# /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

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

# 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

# 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.

15 KiB Raw Permalink Blame History

Enterprise Configuration Examples

Corporate IT Environment

Scenario

Headscale Configuration

Headplane Configuration

Healthcare Organization

Scenario

Headscale Configuration

Headplane Configuration

Financial Services

Scenario

Headscale Configuration

Headplane Configuration

Government/Defense

Scenario

Headscale Configuration

Headplane Configuration

Multi-Tenant SaaS

Scenario

Headscale Configuration

Headplane Configuration

Development/Testing Environment

Scenario

Docker Compose

Development Headscale Config

Development Headplane Config

15 KiB

Raw Permalink Blame History