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.

API-Keys¶

Was sind API-Keys?¶

API-Keys sind langlebige Tokens für programmatischen Zugriff. Sie werden vom Benutzer erstellt und können jederzeit widerrufen werden.

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
)

API-Key-Eigenschaften¶

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.