Zscaler Integration einrichten¶

TCM365 unterstützt seit v2.0.0 die vollständige Integration mit Zscaler Internet Access (ZIA) und Zscaler Private Access (ZPA) über das VendorAdapter Pattern. Dieser Guide erklaert die Einrichtung der API Credentials, Rate Limits und den Verbindungstest.

Übersicht¶

TCM365 Backend
  │
  ├── ZscalerZiaClient ──► ZIA API (cloud.zscaler.net)
  │     ├── Cookie-Auth (28 min TTL)
  │     ├── 12 Endpoint-Gruppen
  │     └── Rate Limit: 80 read/10s, 10 write/10s
  │
  └── ZscalerZpaClient ──► ZPA API (config.private.zscaler.com)
        ├── OAuth 2.0 Client Credentials
        ├── 9 Endpoint-Gruppen
        └── Rate Limit: 15 req/10s

Unterstützte Funktionen¶

Voraussetzungen¶

Bevor Sie beginnen, stellen Sie sicher:

• Zugang zur Zscaler Admin Console (ZIA und/oder ZPA)
• API-Zugriff ist für Ihren Zscaler Account aktiviert
• Ein dedizierter API-Admin-Account (empfohlen, kein persoenlicher Account)
• TCM365 läuft und Sie haben einen SUPER_ADMIN oder TENANT_ADMIN Account

ZIA Credentials einrichten¶

Schritt 1: ZIA API Key beschaffen¶

1. Melden Sie sich an der ZIA Admin Console an
2. Navigieren Sie zu Administration > API Key Management
3. Kopieren Sie den API Key

Schritt 2: Admin Credentials vorbereiten¶

Notieren Sie die folgenden Informationen:

Schritt 3: In TCM365 konfigurieren¶

curl -X POST http://localhost:8000/api/v1/tenants/vendor \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "zscaler",
    "name": "Zscaler Production",
    "zia_cloud": "zscalertwo.net",
    "zia_api_key": "abc123def456...",
    "zia_admin_username": "zia-api@example.com",
    "zia_admin_password": "your-password"
  }'

ZIA Authentifizierung im Detail¶

Die ZIA API verwendet Cookie-basierte Authentifizierung:

1. TCM365 sendet eine Authentifizierungsanfrage mit API Key + Username + obfuskiertem Passwort
2. ZIA gibt ein Session Cookie zurück
3. Das Cookie hat eine TTL von 28 Minuten
4. Die ZscalerAuthFactory verwaltet die automatische Token-Erneuerung

Login Request → ZIA API → Session Cookie (28 min TTL)
                              │
                              ▼
              ZscalerZiaClient verwendet Cookie für alle API Aufrufe
                              │
                              ▼
              Automatische Erneuerung vor Ablauf

ZPA Credentials einrichten¶

Schritt 1: OAuth Client erstellen¶

1. Melden Sie sich an der ZPA Admin Console an
2. Navigieren Sie zu Administration > API Keys
3. Erstellen Sie einen neuen API Client:
   • Client Type: Service
   • Enabled: Ja
4. Notieren Sie Client ID und Client Secret

Schritt 2: Customer ID beschaffen¶

1. In der ZPA Admin Console unter Administration > Company Profile
2. Kopieren Sie die Customer ID (auch "Company ID" genannt)

Schritt 3: Credentials zusammenfassen¶

Schritt 4: In TCM365 konfigurieren¶

Erweitern Sie den bestehenden Zscaler Tenant um ZPA Credentials:

curl -X PATCH http://localhost:8000/api/v1/tenants/vendor/<tenant-id> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "zpa_customer_id": "123456789",
    "zpa_client_id": "aBcDeFgHiJkLmN...",
    "zpa_client_secret": "your-client-secret",
    "zpa_cloud": "config.private.zscaler.com"
  }'

ZPA Authentifizierung im Detail¶

Die ZPA API verwendet OAuth 2.0 Client Credentials:

1. TCM365 fordert ein Access Token mit Client ID + Client Secret an
2. ZPA gibt ein Bearer Token zurück
3. Die ZscalerAuthFactory erneuert das Token 5 Minuten vor Ablauf (Pre-Expiry Buffer)

Rate Limits¶

Die Zscaler APIs haben strikte Rate Limits, die von der ZscalerRateLimiter Klasse in TCM365 automatisch eingehalten werden:

ZIA Rate Limits¶

ZPA Rate Limits¶

Rate Limiter Verhalten¶

Die ZscalerRateLimiter implementiert ein Sliding-Window Verfahren:

• Requests werden in einem Zeitfenster gezaehlt
• Bei Erreichen des Limits werden weitere Requests verzögert (nicht abgelehnt)
• Die Verzögerung wird automatisch berechnet bis das Fenster zurückgesetzt wird
• Retry-Logik bei 429 Too Many Requests Antworten

Zscaler Resource Types¶

ZIA Resource Types (12 Gruppen)¶

ZPA Resource Types (9 Gruppen)¶

Zscaler Baseline Templates¶

TCM365 beinhaltet 4 Zscaler-spezifische Baseline Templates:

Credential-Speicherung¶

Alle Zscaler Credentials werden verschlüsselt in der Datenbank gespeichert:

In Produktionsumgebungen wird die Azure Key Vault SecretBackend verwendet. Im Entwicklungsmodus wird LocalAES mit dem APP_SECRET_KEY genutzt.

Troubleshooting¶

ZIA Authentifizierung schlägt fehl¶

Ursache: Falscher API Key oder ungueltige Admin Credentials.

Lösung:

1. API Key in der ZIA Admin Console verifizieren
2. Admin Account ist nicht gesperrt prüfen
3. Cloud Instanz ist korrekt verifizieren (z.B. zscalertwo.net statt zscaler.net)

ZPA Token Request schlägt fehl¶

Ursache: Ungueltiger Client ID/Secret oder deaktivierter API Client.

Lösung:

1. API Client ist in der ZPA Console als "Enabled" markiert verifizieren
2. Client Secret wurde korrekt kopiert (keine Leerzeichen am Anfang/Ende)
3. Customer ID stimmt mit dem ZPA Account ueberein

Rate Limit Warnungen in Logs¶

Symptome: Warnmeldungen über Rate Limiting in den Backend Logs.

Lösung: Dies ist normales Verhalten. Der ZscalerRateLimiter verzögert Requests automatisch. Bei haefigen Warnungen den Snapshot-Intervall reduzieren.

Leere Snapshot-Daten für einzelne Resource Types¶

Ursache: Der API Account hat keine Berechtigung für diesen Resource Type.

Lösung: Admin-Berechtigungen des API Accounts in der Zscaler Console prüfen. Der Account benötigt mindestens Lesezugriff auf alle zu erfassenden Resource Types.