Dienst-Identitäten für Integrationen

Gilt für die CoCoCo-Plattform v1.0.0-rc.31. Jeder Schritt unten wurde auf dieser Version ausgeführt.

Eine Integration sollte nie unter dem Konto eines Menschen laufen. Sonst werden ihre Schreibvorgänge dieser Person zugeschrieben, sie hört auf zu funktionieren, wenn die Person das Unternehmen verlässt, und sie besitzt alle Rechte, die diese Person zufällig hat.

Dafür gibt es in CoCoCo Dienstkonten. Eines richtig einzurichten sind vier Schritte — und der zweite ist der, den alle überspringen.

1. Das Dienstkonto anlegen

Legen Sie für die Integration einen Benutzer der Art BOT an. Der Name sollte sagen, was das Konto tut, nicht wer es eingerichtet hat: MIS-Import, Versand-Sync, Telemetrie Presse 1.

Eine Identität pro Integration, nicht eine für alles. Es kostet nichts und zahlt sich beim ersten Mal aus, wenn Sie wissen müssen, welches System einen Datensatz geschrieben hat — oder genau eine Verbindung sperren wollen.

2. Eine Policy geben — ein frisches Konto hat keinerlei Rechte

Das ist der Schritt, der überrascht: Ein neu angelegtes Dienstkonto kann gar nichts. Es ist keine abgespeckte Version eines Administrators, sondern startet mit einer leeren Rechtemenge. Jeder Aufruf, der ein Recht braucht, wird abgelehnt, bis eine Policy zugewiesen ist. Nur Fragen zum Konto selbst werden noch beantwortet: myEffectivePermissions liefert eine leere Liste.

Also: eine Policy anlegen, die genau die Aktionen auflistet, die die Integration ausführt, und sie dem Konto zuweisen. Für einen MIS-Import, der Aufträge liest und Rückmeldungen schreibt, ist das etwa:

customer:read, customer:list, customer:write
order:read, order:list, order:write
job:read, job:list, job:write
operation:read, operation:list, operation:write
progressPoint:write

Sonst nichts — keine Löschrechte, keine Konfiguration, keine Benutzerverwaltung. Beginnen Sie mit dem, was die Integration heute tut, und ergänzen Sie, wenn sie wächst; das ist deutlich leichter, als eine zu breite Policy später zu beschneiden.

3. Ein Token ausstellen — und einmal kopieren

Erstellen Sie ein API-Token im Namen des Dienstkontos, nicht auf Ihrem eigenen. Der Tokenwert wird genau einmal zurückgegeben und ist danach nie wieder lesbar. Legen Sie ihn dort ab, wo Ihre Integration ihre Geheimnisse hält, bevor Sie die Antwort schließen.

Geht es verloren, erstellen Sie ein zweites Token und widerrufen das erste.

4. Nachprüfen, was das Konto wirklich bekommen hat

Vertrauen Sie nicht dem Policy-Dokument — rufen Sie myEffectivePermissions mit dem Token des Kontos aus Schritt 3 auf und vergleichen Sie das Ergebnis mit Ihrer Liste.

Damit fallen die zwei Fehler auf, die sonst unsichtbar bleiben: eine Anweisung, die angenommen wurde und nichts gewährt, und ein Recht, von dem Sie annahmen, es sei in einem anderen enthalten. Zwei Minuten hier ersparen einen Nachmittag mit Autorisierungsfehlern, die wie Programmfehler aussehen.

Läuft die Integration innerhalb der Plattform als Integration mit Timern, braucht sie kein Token: Die Instanz läuft unter dem Dienstkonto, an das sie gebunden ist (botUserId). Dieses Konto braucht trotzdem seine Policy aus Schritt 2 — weisen Sie sie zu, bevor Sie die Instanz starten. Tokens sind für Code außerhalb — einen Job auf eigener Hardware, eine Middleware, ein Skript auf Ihrem Server.

Gute Praxis

Tun	Warum
Ein Konto pro Integration	Nachvollziehbarkeit, und das Sperren des einen bricht das andere nicht
Nach der Funktion benennen	MIS-Import, nicht api-user-2
Minimale Rechte, mitwachsend	Die Policy dokumentiert, was die Integration darf
Mit myEffectivePermissions prüfen	Es zeigt, was wirklich gilt, nicht was im Dokument steht
Token in den Secret-Store	Es wird einmal gezeigt und ist ein vollwertiger Zugang

Wie es weitergeht

• IAM verstehen: Policies, Berechtigungen und Rollen — das Modell dahinter
• Eine IAM-Policy erstellen und Eine Policy einem Benutzer zuweisen — die Mechanik
• Berechtigungsfehler diagnostizieren — wenn ein Aufruf trotzdem abgelehnt wird
• API-Tokens erstellen und verwalten — Token-Handhabung im Detail