Headscale

Dieser Leitfaden erklärt, wie man die Single Sign-On (SSO)-Authentifizierung zwischen SmartLink und Headscale mithilfe von OpenID Connect konfiguriert. Headscale ist eine Open-Source-Implementierung des Tailscale-Steuerungsservers.

Voraussetzungen

• Headscale Version 0.22.0 oder höher
• Administratorzugriff auf den Headscale-Server
• Anwendung in SmartLink mit OpenID Connect konfiguriert
• Gültiges SSL-Zertifikat für Headscale (für OIDC erforderlich)

Überblick

Headscale unterstützt die Authentifizierung über OpenID Connect, was es Benutzern ermöglicht, sich mit SmartLink anstelle von vorab generierten Authentifizierungsschlüsseln anzumelden.

Konfiguration in SmartLink

1. Anwendung erstellen

1. Melden Sie sich als Administrator bei SmartLink an
2. Gehen Sie zu Anwendungen → Hinzufügen
3. Erstellen Sie eine neue Anwendung:
   • Name: Headscale
   • URL: https://headscale.example.com
   • Beschreibung: Headscale-Steuerungsserver
   • Symbol: Verwenden Sie das Tailscale-Symbol oder ein benutzerdefiniertes Symbol

2. OpenID Connect konfigurieren

1. Im Tab Authentifizierung
2. Wählen Sie OpenID Connect als Authentifizierungstyp
3. Notieren Sie die folgenden Informationen:
   • Client-ID: headscale-xxxxxx
   • Client-Geheimnis: secret-xxxxxx
   • Issuer-URL: https://votre-smartlink.link.vaultys.org/api/oidc/[appid]
   • App-ID: [appid] (eindeutige Kennung der Anwendung in SmartLink)

3. Weiterleitungs-URLs konfigurieren

Fügen Sie die Callback-URL unter Zugelassene Weiterleitungs-URLs hinzu:

https://headscale.example.com/oidc/callback

Hinweis: Die [appid] wird automatisch generiert, wenn die Anwendung in SmartLink erstellt wird.

4. Bereiche konfigurieren

Erforderliche Bereiche:

• openid
• Profil
• E-Mail
• Gruppen (optional, für gruppenbasierte ACLs)

Headscale-Konfiguration

1. Konfiguration der config.yaml-Datei

Bearbeiten Sie die Headscale-Konfigurationsdatei (normalerweise /etc/headscale/config.yaml):

# Serverkonfiguration
server_url: https://headscale.example.com
listen_addr: 0.0.0.0:8080
metrics_listen_addr: 0.0.0.0:9090

# Datenbankkonfiguration
db_type: sqlite3
db_path: /var/lib/headscale/db.sqlite

# OIDC-Konfiguration
oidc:
  # OIDC aktivieren
  enabled: true
  
  # URL des SmartLink-Issuers
  issuer: "https://votre-smartlink.link.vaultys.org/api/oidc/[appid]"
  
  # Client-ID und Geheimnis von SmartLink
  client_id: "headscale-xxxxxx"
  client_secret: "secret-xxxxxx"
  
  # Zu beantragende Bereiche
  scope:
    - openid
    - profile
    - email
    - groups
  
  # Claims zum Zuordnen von Benutzerinformationen
  claims:
    # Claim für die E-Mail (Benutzerkennung)
    email: email
    # Claim für den Anzeigenamen
    name: name
    # Claim für Gruppen (optional)
    groups: groups
    
  # Zulässige E-Mail-Domains
  allowed_domains:
    - example.com
    
  # Zulässige Gruppen (optional)
  allowed_groups:
    - admins
    - developers
    - users
    
  # Benutzer automatisch erstellen
  auto_create_users: true
  
  # Gültigkeitsdauer des Authentifizierungstokens
  expiry: 180d
  
  # Verwenden des Ablaufs des OIDC-Tokens
  use_expiry_from_token: false

# Konfiguration von Namespaces/Benutzern
ip_prefixes:
  - 100.64.0.0/10
  - fd7a:115c:a1e0::/48

# DNS-Konfiguration
dns_config:
  nameservers:
    - 1.1.1.1
    - 8.8.8.8
  domains: []
  magic_dns: true
  base_domain: example.com

2. Konfiguration mit Umgebungsvariablen

Alternativ können Sie Umgebungsvariablen verwenden:

export HEADSCALE_OIDC_ENABLED=true
export HEADSCALE_OIDC_ISSUER="https://votre-smartlink.link.vaultys.org"
export HEADSCALE_OIDC_CLIENT_ID="headscale-xxxxxx"
export HEADSCALE_OIDC_CLIENT_SECRET="secret-xxxxxx"
export HEADSCALE_OIDC_ALLOWED_DOMAINS="example.com"

3. Starten mit Docker

Wenn Sie Docker verwenden, hier ist ein Beispiel für docker-compose.yml:

version: '3.8'

services:
  headscale:
    image: headscale/headscale:latest
    container_name: headscale
    volumes:
      - ./config:/etc/headscale
      - ./data:/var/lib/headscale
    ports:
      - "8080:8080"
      - "9090:9090"
    environment:
      - HEADSCALE_OIDC_ENABLED=true
      - HEADSCALE_OIDC_ISSUER=https://votre-smartlink.link.vaultys.org
      - HEADSCALE_OIDC_CLIENT_ID=headscale-xxxxxx
      - HEADSCALE_OIDC_CLIENT_SECRET=secret-xxxxxx
    command: headscale serve
    restart: unless-stopped

4. Konfiguration des Reverse-Proxys (Nginx)

Beispielkonfiguration für Headscale mit SSL in Nginx:

server {
    listen 443 ssl http2;
    server_name headscale.example.com;

    ssl_certificate /etc/letsencrypt/live/headscale.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/headscale.example.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_redirect http:// https://;
        proxy_buffering off;
    }
}

Konfiguration von ACLs mit Gruppen

1. Struktur von gruppenbasierten ACLs

Erstellen Sie eine Datei acls.yaml oder acls.hujson:

groups:
  group:admins:
    - user1@example.com
  group:developers:
    - user2@example.com

acls:
  - action: accept
    src:
      - group:admins
    dst:
      - "*:*"
  
  - action: accept
    src:
      - group:developers
    dst:
      - tag:dev:*
      - tag:staging:*

tagOwners:
  tag:prod:
    - group:admins
  tag:dev:
    - group:developers
  tag:staging:
    - group:developers

2. Anwendung der ACLs

# ACLs anwenden
headscale acls set acls.yaml

# ACLs überprüfen
headscale acls show

Clientkonfiguration

1. Installation des Tailscale-Clients

# Linux
curl -fsSL https://tailscale.com/install.sh | sh

# macOS
brew install tailscale

# Windows
# Herunterladen von https://tailscale.com/download

2. Verbindung mit OIDC

# Verbindung zum Headscale-Server mit OIDC
tailscale up --login-server https://headscale.example.com

# Der Browser öffnet sich automatisch zur Authentifizierung
# Sie werden zu SmartLink weitergeleitet, um sich anzumelden

3. Überprüfung der Verbindung

# Status überprüfen
tailscale status

# Verbundene Peers anzeigen
tailscale status --peers

# Zugeordnete IP überprüfen
tailscale ip

Konfigurationstest

1. Test der OIDC-Authentifizierung

1. Führen Sie auf einem Client aus:

   tailscale up --login-server https://headscale.example.com
2. Der Browser öffnet sich auf der Authentifizierungsseite
3. Klicken Sie auf "Mit OIDC anmelden"
4. Sie werden zu SmartLink weitergeleitet
5. Melden Sie sich mit Ihren SmartLink-Anmeldeinformationen an
6. Nach der Authentifizierung werden Sie zu Headscale weitergeleitet
7. Der Tailscale-Client sollte automatisch eine Verbindung herstellen

2. Überprüfung in Headscale

# Benutzer auflisten
headscale users list

# Maschinen auflisten
headscale machines list

# Details eines Benutzers anzeigen
headscale users show utilisateur@example.com

# Routen anzeigen
headscale routes list

3. Konnektivitätstest

# Ping an eine andere Maschine
ping 100.64.0.2

# Test mit MagicDNS-Hostname
ping machine-name.example.com.beta.tailscale.net

Fehlerbehebung

Fehler "OIDC-Authentifizierung fehlgeschlagen"

Problem: Die OIDC-Authentifizierung schlägt fehl

Lösung:

1. Überprüfen Sie die Headscale-Protokolle:

   journalctl -u headscale -f
2. Überprüfen Sie die Issuer-URL in der Konfiguration
3. Testen Sie die OIDC-Entdeckung mit Ihrer App-ID:

   curl https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration

Fehler "Ungültige Client-Anmeldeinformationen"

Problem: Die OIDC-Anmeldeinformationen sind ungültig

Lösung:

1. Überprüfen Sie die Client-ID und das Geheimnis in SmartLink
2. Stellen Sie sicher, dass keine Leerzeichen oder versteckten Zeichen vorhanden sind
3. Starten Sie Headscale nach der Konfigurationsänderung neu

Benutzer erstellt, kann sich jedoch nicht anmelden

Problem: Der Benutzer existiert in Headscale, aber die Anmeldung schlägt fehl

Lösung:

1. Überprüfen Sie, ob die E-Mail-Domain in allowed_domains enthalten ist
2. Wenn Sie allowed_groups verwenden, überprüfen Sie die Gruppen des Benutzers
3. Überprüfen Sie die ACLs, wenn diese konfiguriert sind
4. Versuchen Sie, den Benutzer erneut zu authentifizieren:

   headscale preauthkeys create --user utilisateur@example.com

Gruppen werden nicht synchronisiert

Problem: Die SmartLink-Gruppen sind in Headscale nicht sichtbar

Lösung:

1. Stellen Sie sicher, dass der Bereich groups in SmartLink aktiviert ist
2. Testen Sie den UserInfo-Endpunkt:

   curl -H "Authorization: Bearer TOKEN" https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/userinfo
3. Überprüfen Sie den Gruppen-Claim in der Headscale-Konfiguration
4. Die Gruppen sollten ein Array von Zeichenfolgen sein

SSL/TLS-Fehler

Problem: Zertifikatfehler bei der OIDC-Verbindung

Lösung:

1. Headscale erfordert HTTPS mit einem gültigen Zertifikat
2. Verwenden Sie keine selbstsignierten Zertifikate
3. Überprüfen Sie die Zertifikatskette:

   openssl s_client -connect headscale.example.com:443 -showcerts

Sicherheit

Empfehlungen

1. Zwingendes HTTPS: Headscale erfordert HTTPS für OIDC
2. Firewall: Beschränken Sie den Zugriff auf den Headscale-Port (8080)
3. Datenbank: Verwenden Sie PostgreSQL in der Produktion
4. Geheimnisse: Speichern Sie Geheimnisse sicher
5. Überwachung: Überwachen Sie Protokolle und Metriken

Schlüsselrotation

# Generieren eines neuen Knotenschlüssels
headscale nodes key rotate --id NODE_ID

# Maschine widerrufen
headscale machines delete --id MACHINE_ID

Sicherung

# SQLite-Datenbank sichern
sqlite3 /var/lib/headscale/db.sqlite ".backup /backup/headscale.db"

# Konfiguration sichern
cp -r /etc/headscale /backup/headscale-config

# Mit PostgreSQL
pg_dump headscale > /backup/headscale.sql

Erweiterte Konfiguration

Multi-User-Modus mit Namespaces

# In config.yaml
oidc:
  # Einen Namespace pro Benutzer erstellen
  create_namespace_for_user: true
  
  # Namespace-Format
  namespace_format: "{email}"
  
  # Oder einen spezifischen Claim verwenden
  namespace_claim: "department"

Integration mit Kubernetes

Bereitstellung von Headscale in Kubernetes:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: headscale
spec:
  replicas: 1
  selector:
    matchLabels:
      app: headscale
  template:
    metadata:
      labels:
        app: headscale
    spec:
      containers:
      - name: headscale
        image: headscale/headscale:latest
        ports:
        - containerPort: 8080
        env:
        - name: HEADSCALE_OIDC_ENABLED
          value: "true"
        - name: HEADSCALE_OIDC_ISSUER
          value: "https://votre-smartlink.example.com"
        - name: HEADSCALE_OIDC_CLIENT_ID
          valueFrom:
            secretKeyRef:
              name: headscale-oidc
              key: client-id
        - name: HEADSCALE_OIDC_CLIENT_SECRET
          valueFrom:
            secretKeyRef:
              name: headscale-oidc
              key: client-secret
        volumeMounts:
        - name: config
          mountPath: /etc/headscale
        - name: data
          mountPath: /var/lib/headscale
      volumes:
      - name: config
        configMap:
          name: headscale-config
      - name: data
        persistentVolumeClaim:
          claimName: headscale-data

Überwachung mit Prometheus

Headscale stellt Metriken auf Port 9090 bereit:

# prometheus.yml
scrape_configs:
  - job_name: 'headscale'
    static_configs:
      - targets: ['headscale.example.com:9090']

Ressourcen

• Headscale-Dokumentation
• GitHub Headscale
• Headscale-Forum