API-Keys & Authentifizierung¶

Übersicht¶

Die Polycrate API unterstützt mehrere Authentifizierungsmethoden für unterschiedliche Anwendungsfälle:

SSO / OIDC¶

Unterstützte Provider¶

Die Polycrate API unterstützt OpenID Connect (OIDC) mit:

• Keycloak (Standard)
• Azure AD / Entra ID
• Okta
• Google Workspace
• Andere OIDC-kompatible Provider

Login-Flow¶

┌─────────┐      ┌─────────────┐      ┌──────────────┐
│ Browser │─────▶│ Polycrate   │─────▶│ SSO Provider │
│         │      │   API       │      │ (Keycloak)   │
└─────────┘      └─────────────┘      └──────────────┘
     │                  ▲                    │
     │                  │                    │
     │           ┌──────┴──────┐            │
     │           │   Session   │            │
     │           │   erstellt  │            │
     │           └─────────────┘            │
     │                                       │
     └───────────────────────────────────────┘
              Redirect nach Login

Gruppen-Mapping¶

OIDC-Gruppen können automatisch auf Polycrate-Rollen gemappt werden:

Die Gruppennamen sind über Environment-Variablen konfigurierbar (nicht hardcoded):

Die Gruppennamen in der Tabelle oben sind Konventionen – in der Praxis muss der Wert in der Env-Variable mit den tatsächlichen Keycloak-Gruppennamen übereinstimmen.

Keycloak OIDC einrichten¶

Für den SSO-Login muss in Keycloak ein OIDC Client konfiguriert werden:

1. Client erstellen: Clients → Create client → Client ID (z. B. polycrate-api), Client authentication: ON (confidential), Standard flow: ON
2. Redirect URIs setzen: Valid redirect URIs: https://<polycrate-api-host>/*
3. Client Secret kopieren: Tab Credentials → Client Secret
4. Groups Scope erstellen: Client Scopes → Create → Name: groups, Mapper: Group Membership (Token Claim Name: groups, Full group path: OFF)
5. Scope zuweisen: Client → Client Scopes → Add groups als Default

Die OIDC-Konfiguration erfolgt über Environment-Variablen:

Die Scopes openid, email, profile und groups werden automatisch angefordert.

System API Keys¶

System API Keys sind Tokens für Dienste, die globalen Zugriff auf die Polycrate API benötigen – ohne Benutzerkontext. Typischer Anwendungsfall ist ein Customer Portal-Backend, das im Namen von Kunden Ressourcen verwaltet.

Berechtigungen¶

• Vollzugriff wie ein Super Admin (alle Organisationen, alle Ressourcen)
• Optional im read-Modus (nur lesende Zugriffe)
• Können Organization API Keys anlegen, auflisten und löschen

System API Key anlegen¶

1. Administration → System API Keys → + Neu
2. Namen vergeben und Zugriffsmodus wählen (read oder read_write)
3. Token wird genau einmal angezeigt – sofort sichern

Verwendung¶

curl https://api.acme.corp/api/v1/organizations/ \
  -H "Authorization: Bearer <system-api-key-token>"

Organization API Keys¶

Organization API Keys sind Tokens mit Org-Scope für Kunden oder Drittsysteme, die im Namen einer bestimmten Organisation handeln. Sie sehen und verwalten nur Ressourcen der eigenen Organisation.

Berechtigungen¶

• Zugriff auf alle Ressourcen der eigenen Organisation (DNS-Zonen, Buckets, Endpoints, Backups, …)
• Optional im read-Modus (nur lesende Zugriffe)
• Können durch System API Keys oder Administratoren angelegt werden

Organization API Key anlegen¶

Als Administrator (oder via System API Key):

POST /api/v1/organizations/{org-name}/api-keys/
{
  "name": "customer-portal-prod",
  "access_mode": "read_write"
}

In der Web-UI: Organisation öffnen → Tab API Keys → + Neu

Der Token wird einmalig in der Response zurückgegeben.

Verwendung¶

curl https://api.acme.corp/api/v1/domains/dnszones/ \
  -H "Authorization: Bearer <org-api-key-token>"

Der Zugriff ist automatisch auf die eigene Organisation beschränkt – Cross-Tenant-Zugriffe werden mit 403 abgelehnt.

User API-Keys¶

Was sind User API-Keys?¶

User API-Keys sind langlebige Tokens für programmatischen Zugriff als angemeldeter Benutzer. Sie haben dieselben Rechte wie der Benutzer, der sie erstellt hat.

User API-Key erstellen¶

1. Öffnen Sie Profil → API-Keys
2. Klicken Sie + Neuer API-Key
3. Geben Sie einen Namen ein (z.B. "MacBook Pro", "CI/CD Pipeline")
4. Optional: Ablaufdatum setzen
5. Wichtig: Token wird nur einmal angezeigt – sofort kopieren!

API-Key verwenden¶

# ~/.polycrate/polycrate.yml
api:
  enabled: true
  url: https://hub.polycrate.io
  api_key: poly_abc123def456...

curl -X GET https://hub.polycrate.io/api/v1/workspaces/ \
  -H "Authorization: Bearer poly_abc123def456..."

import requests

headers = {
    "Authorization": "Bearer poly_abc123def456..."
}

response = requests.get(
    "https://hub.polycrate.io/api/v1/workspaces/",
    headers=headers
)

User API-Key-Eigenschaften¶

User API-Key widerrufen¶

1. Öffnen Sie Profil → API-Keys
2. Finden Sie den zu widerrufenden Key
3. Klicken Sie Löschen
4. Bestätigen Sie die Aktion

Agent-Tokens¶

Was sind Agent-Tokens?¶

Agent-Tokens sind spezielle Tokens für Polycrate Monitoring Agents. Sie haben eingeschränkte Berechtigungen:

• ✅ Endpoints abrufen
• ✅ Check-Ergebnisse melden
• ✅ Agent-Status aktualisieren
• ❌ Konfiguration ändern
• ❌ Auf andere Ressourcen zugreifen

Agent-Token erstellen¶

1. Öffnen Sie Monitoring → Agents
2. Klicken Sie + Neuer Agent
3. Geben Sie einen Namen und Standort ein
4. Agent-Token wird generiert

Agent-Token verwenden¶

polycrate api agent --agent-token "agt_xyz789..."

Berechtigungsmodell¶

Rollen-Hierarchie¶

Super Admin
    │ Alle Rechte im System
    │
    ▼
Org Admin
    │ Alle Rechte in einer Organisation
    │
    ▼
Workspace Admin
    │ Alle Rechte in einem Workspace
    │
    ▼
User
    │ Lesen + Schreiben (eingeschränkt)
    │
    ▼
Viewer
    │ Nur Lesen

Standard-Berechtigungen¶

Sicherheits-Best-Practices¶

API-Key-Management¶

1. Separate Keys pro Anwendungsfall
2. Einen für lokale Entwicklung
3. Einen für CI/CD

4. Einen pro Automatisierungs-Script

5. Ablaufdaten setzen

6. CI/CD-Keys: 90 Tage
7. Entwickler-Keys: 365 Tage

8. Temporäre Keys: 7 Tage

9. Regelmäßige Rotation

10. Kritische Keys alle 90 Tage
11. Alle Keys mindestens jährlich

Secret-Storage¶

export POLYCRATE_API_KEY="poly_abc123..."
polycrate run my-block install

# AWS Secrets Manager
export POLYCRATE_API_KEY=$(aws secretsmanager get-secret-value \
  --secret-id polycrate/api-key --query SecretString --output text)

# GitHub Actions
- name: Run Polycrate
  env:
    POLYCRATE_API_KEY: ${{ secrets.POLYCRATE_API_KEY }}
  run: polycrate run my-block deploy

Niemals tun¶

• ❌ API-Keys in Git committen
• ❌ Keys in Logs ausgeben
• ❌ Keys in öffentlichen Kanälen teilen
• ❌ Einen Key für alles verwenden
• ❌ Keys ohne Ablaufdatum für CI/CD

Audit-Logging¶

Alle Authentifizierungs-Events werden geloggt:

Logs sind unter Administration → Audit Logs einsehbar.