Zugangsdaten für eine Integration wählen
Diese Seite ist für Integrationsentwickler und Administratoren, die entscheiden müssen, wie ein anderes System Exponential gegenüber nachweist, wer es ist. Jedes Zugangsdatum in Exponential steht für einen Benutzer, und eine damit gestellte Anfrage kann nie mehr, als die Rollen dieses Benutzers erlauben. Die Wahl betrifft, wer dieser Benutzer ist, wie lange das Zugangsdatum gilt und wie es widerrufen wird.
Inhalt
- Die Zugangsdaten
- Welches für welche Aufgabe
- Grenzen, die immer gelten
- Zugangsdaten aufbewahren und rotieren
- Checkliste
Die Zugangsdaten
| Zugangsdatum | Sieht aus wie | Gesendet als | Funktioniert für | Erzeugt von | Endet |
|---|---|---|---|---|---|
| OAuth-2.0-Zugriffstoken | 40 hexadezimale Zeichen | Authorization: Bearer <token> oder Authorization: OAuth <token> | REST-API (/api/...) | Einer App, nachdem der Benutzer sie unter oauth/authorize zugelassen hat; Token von POST /api/auth/v1/oauth/token | Nach rest.ini [OAuthSettings] TokenTTL (3600 Sekunden); mit dem Refresh-Token erneuert |
| Persönlicher API-Schlüssel | expk_ + 12 + _ + 40 Zeichen | Nur Authorization: Bearer expk_... (in der Adresse abgelehnt) | REST-API | Dem Benutzer unter Mein Konto > API-Zugang (/apikey/list), mit apikey/create | Widerrufen, abgelaufen (MaxExpiryDays, Standard 365) oder Eigentümer deaktiviert |
expservices-Token | expt_ + 48 hexadezimale Zeichen | Authorization: Bearer <token> oder X-Exp-Token: <token> | Dienste unter /ezjscore/call/exp... | Dem Benutzer mit expsession::tokenCreate | Widerrufen (expsession::tokenRevoke), abgelaufen oder Eigentümer deaktiviert |
| HTTP-Basic-Authentifizierung | Login und Passwort | Authorization: Basic ... | REST-API, wenn rest.ini [Authentication] AuthenticationStyle=ezpRestBasicAuthStyle; WebDAV | Dem Benutzerkonto | Wenn sich das Passwort ändert |
| Anmeldung per Sitzung | Sitzungscookie plus Formular-Token | Cookie und ezxform_token | expservices- und ezjscore-Aufrufe aus einem Browser oder einem Skript, das sich anmeldet | user/login | Ende der Sitzung |
Die REST-Schicht löst einen persönlichen API-Schlüssel in expApiKeyAuthFilter
(kernel/private/rest/classes/auth/apikey_auth_filter.php) für beide Authentifizierungsarten des Kernels auf;
Schlüssel funktionieren also, ob die Website OAuth oder Basic-Authentifizierung verwendet.
Welches für welche Aufgabe
| Aufgabe | Verwenden Sie | Warum |
|---|---|---|
| Ein Skript oder Server Ihres Unternehmens, der über REST Inhalte liest oder veröffentlicht | Einen persönlichen API-Schlüssel eines Dienstkontos | Ein Schlüssel pro Programm, mit Geltungsbereich (read, publish, edit, remove), einzeln widerrufbar, protokolliert |
| Eine App, bei der sich viele Menschen anmelden und als sie selbst handeln | Eine OAuth-Anwendung | Jeder Benutzer lässt die App zu; das Token handelt als dieser Benutzer |
Ein Skript, das expservices aufruft (Caches, Inhaltsjobs, Benutzer, ...) | Ein expservices-Token eines Dienstkontos | Für Schreibzugriffe ist kein Formular-Token nötig; widerrufbar |
| Eine Browserseite auf derselben Website | Die Sitzung | Sie ist bereits da; Schreibzugriffe tragen den Formular-Token |
| Ein Desktop-Werkzeug, das Inhalte als Laufwerk einbindet | Basic-Authentifizierung über HTTPS (WebDAV) | WebDAV-Clients sprechen sie |
| Ein älterer Client, der nur Basic-Authentifizierung kennt | Basic-Authentifizierung über HTTPS, mit einem eigenen Konto | Letzter Ausweg: Das Passwort öffnet jede Seite, die das Konto öffnen darf |
Hinweis Ein Passwort ist das weitreichendste Zugangsdatum: Es meldet überall an, wo das Konto hindarf, und eine Änderung bricht jedes Programm auf einmal. Bevorzugen Sie einen Schlüssel oder ein Token, wann immer die Schnittstelle es annimmt (Persönliche API-Schlüssel).
Grenzen, die immer gelten
- Nie mehr als der Benutzer. Jeder REST-Lese- und Schreibzugriff fragt über
expRestContentPermissiondie Richtlinien des Benutzers ab; jederexpservices-Dienst deklariert seinen Zugriff und prüft ihn. Der Geltungsbereich eines Schlüssels wird bei jeder Anfrage erneut gegen die aktuellen Richtlinien des Eigentümers geprüft. - Ratenlimit für Schlüssel.
rest.ini [ApiKeySettings] RateLimitPerMinute=120pro Schlüssel, in APCu gezählt; über dem Limit lautet die Antwort429mitRetry-After. - Schlüssel nur im Header. Ein Schlüssel in
oauth_token,access_tokenoderapi_keyder Adresse oder des Inhalts wird ohne Nachschlagen abgelehnt. - HTTPS.
rest.ini [Authentication] RequireHTTPSkann einfaches HTTP für die REST-API ablehnen; liefern Sie jede API trotzdem über HTTPS aus. - Proxys. Wenn ein Proxy oder Apache mit PHP-FPM den Header
Authorizationverwirft, scheitern Schlüssel und Token mit 401. Reichen Sie den Header durch (CGIPassAuth On) oder verwenden Sie fürexpservicesX-Exp-Token.
Zugangsdaten aufbewahren und rotieren
| Tun Sie | Tun Sie nicht |
|---|---|
| Schlüssel und Token im Geheimnisspeicher oder in Umgebungsvariablen des aufrufenden Systems halten | Sie in Git, in ein Template, in eine URL oder in ein gemeinsam genutztes Skript legen |
| Ein Zugangsdatum pro Programm und pro Umgebung anlegen | Einen Schlüssel zwischen Test und Produktion teilen |
| Rotieren, indem Sie zuerst den neuen Schlüssel anlegen, umstellen, Zuletzt benutzt prüfen und dann den alten widerrufen | Zuerst widerrufen und das Programm danach reparieren |
Ihrem Secret-Scanner die Präfixe expk_ und expt_ beibringen | Schlüssel in Tickets oder Chats einfügen |
| Sofort widerrufen, wenn ein Zugangsdatum gesehen worden sein könnte | Warten, bis es abläuft |
Jedes Anlegen, Widerrufen, die erste Nutzung und jede Ablehnung eines Schlüssels wird im Audit-Protokoll als
access.apikey.* festgehalten; expservices-Token als access.expservices.token.*:
php bin/php/console exp:audit tail --channel=access --name='access.apikey.*' --lines=20 --allow-root-userCheckliste
- To do: Ein Dienstkonto pro Integration, mit einer engen Rolle (wie).
- To do: Die Art des Zugangsdatums pro Datenfluss gewählt und in die Schnittstellenspezifikation geschrieben.
- To do: Geltungsbereiche auf das beschränkt, was der Fluss braucht (eine lesende Integration bekommt nur
read). - To do: Ablaufdatum gesetzt und ein Rotationstermin im Betriebskalender.
- To do: Das Zugangsdatum außerhalb von Git aufbewahrt; sein Ort im Runbook genannt.
- To do: Die Audit-Ereignisse nach dem ersten Lauf geprüft.
Verwandte Seiten
- Persönliche API-Schlüssel für Integrationen
- OAuth-Anwendungen für Integrationen
- Entfernte Dienste mit expservices
- OAuth und API-Schlüssel für App-Ersteller
- Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.
Werden Sie Exponential-Partner
Partner teilen ihre Informationen, stellen Mittel bereit, geben Beiträge zurück und entwickeln die Produkte mit uns, und so wächst Exponential. Eine Partner-Website und ein Dashboard sind für Mitte 2027 geplant: Werden Sie noch heute Partner, damit wir schneller wachsen und neue Funktionen früher liefern.