Mit API-Tokens authentifizieren

Jede Anfrage an die REST-API enthält im Header Authorization Anmeldedaten. Dieser Artikel zeigt, wie Sie sie senden, was jede Art von Anmeldedaten erreichen kann und was zu tun ist, wenn eine Anfrage abgelehnt wird.

VoraussetzungenLink kopieren

• Beschaffen Sie Anmeldedaten. Erstellen Sie ein API-Token unter Identität & Zugriff › API-Tokens oder einen Schlüssel für ein Dienstkonto unter Identität & Zugriff › Dienstkonten. Siehe API-Token erstellen und Schlüssel verwalten.
• Um API-Tokens zu erstellen, benötigen Sie die Rolle Besitzer oder eine benutzerdefinierte Rolle, die API-Tokens verwalten kann. Die Rollen Mitwirkender und Leser können sie nur anzeigen.
• Speichern Sie das Secret, wenn es angezeigt wird. Das Secret wird nur einmal angezeigt.

Anmeldedaten auswählenLink kopieren

Verwenden Sie einen Dienstkontoschlüssel für Automatisierungen, die weiter funktionieren müssen, wenn Personen ausscheiden oder ihre Rollen wechseln. Die API-Tokens eines Benutzers werden widerrufen, wenn der Benutzer entfernt wird, und sie funktionieren nicht, solange das Konto des Benutzers deaktiviert ist.

Keine der beiden Arten von Anmeldedaten funktioniert mit OpenStack-Tools wie der openstack-CLI oder Terraform. Diese Tools verwenden ein OpenStack-Anwendungs-Credential. Siehe OpenStack-kompatible Tools.

Anmeldedaten sendenLink kopieren

Setzen Sie die Anmeldedaten bei jeder Anfrage nach Bearer in den Header Authorization. Um zu prüfen, ob sie funktionieren, lesen Sie Ihre eigene Identität:

curl "https://<api-host>/api/v1/account/whoami" \
  -H "Authorization: Bearer $PC_TOKEN"

• <api-host>: der Hostname der API.
• PC_TOKEN: eine Umgebungsvariable, die das API-Token oder den Dienstkontoschlüssel enthält.

Eine Antwort 200 OK listet die Mandanten, Abonnements und Projekte auf, die die Anmeldedaten erreichen können. Eine Antwort 401 Unauthorized bedeutet, dass die Anmeldedaten nicht gültig sind. Siehe Problembehandlung.

Halten Sie Anmeldedaten aus dem Quellcode und aus der Versionskontrolle heraus. Laden Sie sie aus einem Secrets-Speicher oder einer Umgebungsvariable, wie im Beispiel.

Token-BereicheLink kopieren

Ein API-Token wird durch zwei Dinge begrenzt: die Rolle des Benutzers, der es erstellt hat, und die Bereiche, die Sie dafür ausgewählt haben. Eine Anfrage wird nur durchgelassen, wenn beide sie erlauben. Zum Beispiel kann ein Token mit dem Bereich compute:write keine Instanzen erstellen, wenn sein Benutzer im Projekt die Rolle Leser hat. Ein write-Bereich schließt den passenden read-Bereich nicht ein: Wählen Sie beide, wenn das Token eine Ressource ändern und lesen soll.

Der Katalog hat 17 Bereiche: je einen read- und einen write-Bereich für jeden von acht Funktionsbereichen sowie audit:read.

Das Activity Log akzeptiert iam:read oder audit:read: Ein Token braucht nur eines von beiden.

Zum Löschen eines Abonnements oder eines Projekts sind iam:write und der Schreibbereich jedes Ressourcenbereichs nötig: compute:write, storage:write, network:write, loadbalancer:write, kubernetes:write und observability:write.

Zum Erstellen eines Abonnements sind iam:write und billing:write nötig, denn ein Abonnement ist ein Abrechnungskonto.

In der Konsole wählen Sie Bereiche aus, wenn Sie ein API-Token oder einen Dienstkontoschlüssel erstellen. In der API senden Sie sie beim Erstellen eines Tokens im Feld scopes.

Was ein API-Token nicht aufrufen kannLink kopieren

Ein Token kann jeden Bereich der API aufrufen, für den es den Bereich besitzt, einschließlich Änderungen in Identity & Access Management und in der Abrechnung. Diese Grenzen gelten für jedes Token:

• Nur in der Konsole. Manche Vorgänge akzeptieren nie ein Token. Siehe Vorgänge, die eine Konsolensitzung erfordern.
• Keine Anmeldedaten über dem Token. Ein Token kann ein Token oder einen Dienstkontoschlüssel nur mit Bereichen erstellen, die es selbst besitzt. Ein Bereich, den es nicht hat, wird mit 403 Forbidden und dem Grund TOKEN_SCOPE_MISSING abgelehnt.
• Keine Anmeldedaten, die das Token überdauern. Ein Token mit Ablaufdatum kann kein Token erstellen oder rotieren, das später oder nie abläuft. Ein Dienstkontoschlüssel, den ein solches Token erstellt, endet spätestens mit dem Token. Die Ablehnung ist 403 Forbidden mit dem Grund TOKEN_FENCE_EXCEEDED.
• Keine Anmeldedaten außerhalb der IP-Zulassungsliste des Tokens. Ein Token mit IP-Zulassungsliste kann nur Tokens erstellen oder rotieren, deren nicht leere Zulassungsliste innerhalb seiner eigenen liegt. Einen Dienstkontoschlüssel kann es nicht erstellen, weil ein Schlüssel keine Zulassungsliste hat. Die Ablehnung ist 403 Forbidden mit dem Grund TOKEN_FENCE_EXCEEDED.

Bereiche von DienstkontoschlüsselnLink kopieren

Auch ein Dienstkontoschlüssel hat Bereiche und durchläuft zusätzlich zu den Rollen seines Dienstkontos dieselbe Bereichsprüfung wie ein API-Token. Beim Erstellen eines Schlüssels wählen Sie seine Bereiche aus dem Katalog ohne iam:write. Ein Schlüssel, der ohne Bereiche erstellt wird, erhält alle Bereiche außer iam:write. Eine Anfrage, die iam:write verlangt, wird mit 422 Unprocessable Entity abgelehnt.

Bei jedem Vorgang, der iam:write erfordert, wird ein Schlüssel mit 403 Forbidden und dem Code INTERACTIVE_SESSION_REQUIRED abgelehnt, welche Bereiche er auch hat. Beispiele sind das Einladen von Benutzern, das Gewähren von Rollen und das Erstellen von Tokens oder Schlüsseln. Führen Sie diese Änderungen in der Konsole oder mit einem API-Token aus, das iam:write hat.

Wo Anmeldedaten geltenLink kopieren

• Ein Mandant. Anmeldedaten funktionieren nur in dem Mandanten, in dem sie erstellt wurden. Eine Anfrage für ein Projekt eines anderen Mandanten gibt 404 Not Found zurück, als gäbe es das Projekt nicht.
• Jedes Projekt dieses Mandanten. Ein API-Token ist nicht an das Projekt gebunden, in dem Sie es erstellt haben. Es funktioniert in jedem Projekt des Mandanten, in dem sein Benutzer eine Rolle hat.
• IP-Zulassungsliste. Wenn Sie für ein Token eine IP-Zulassungsliste festlegen, werden Anfragen von anderen Adressen mit 401 Unauthorized abgelehnt.
• Ablauf und Widerruf. Ein abgelaufenes oder widerrufenes Token wird mit 401 Unauthorized abgelehnt. Die Plattform prüft jede Bearer-Anfrage gegen den aktuellen Status des Tokens, sodass der Widerruf eines Tokens bei seiner nächsten Anfrage wirksam wird.
• Lebensdauer. Beim Erstellen eines Tokens legen Sie den Ablauf auf 30, 60 oder 90 Tage, ein eigenes Datum oder keinen Ablauf fest. Ein eigenes Datum darf höchstens 365 Tage nach heute (UTC) liegen. Ein späteres Datum wird mit 422 Unprocessable Entity und dem Grund token_lifetime_exceeds_maximum abgelehnt.
• Rotation. Wenn Sie ein API-Token rotieren, funktioniert das vorherige Geheimnis noch 24 Stunden lang, damit Sie es in Ihren Clients ersetzen können. Siehe API-Token rotieren.
• Idempotenzschlüssel. Mit einem API-Token oder einem Dienstkontoschlüssel muss eine Anfrage mit POST, die eine Ressource erstellt und mit 202 Accepted antwortet, z. B. das Erstellen einer Instanz oder eines Volumes, einen Header Idempotency-Key enthalten. Ohne ihn wird die Anfrage mit 400 Bad Request und dem Code IDEMPOTENCY_KEY_REQUIRED abgelehnt. Bei anderen Schreibzugriffen ist der Header optional, aber eine Wiederholung ohne ihn kann die Änderung erneut anwenden. Siehe Idempotente Anfragen.
• Ratenlimits. Alle Anmeldedaten haben ein eigenes Ratenlimit, und jeder Mandant hat eines über alle seine Anmeldedaten zusammen. Antworten enthalten X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset, die Anzahl der Sekunden, bis das Limit zurückgesetzt wird. Eine Anfrage über dem Limit erhält 429 Too Many Requests mit dem Code RATE_LIMITED und einem Header Retry-After. Siehe Ratenbegrenzung.

Vorgänge, die eine Konsolensitzung erfordernLink kopieren

Diese Vorgänge erfordern eine angemeldete Konsolensitzung mit einer aktuellen Zwei-Faktor-Bestätigung:

• Erstellen eines OpenStack-Credentials.
• Rotieren eines OpenStack-Credentials.
• Ein- oder Ausschalten des OpenStack-API-Zugriffs der Organisation.

Mit einem API-Token oder einem Dienstkontoschlüssel werden sie mit 403 Forbidden und dem Code INTERACTIVE_SESSION_REQUIRED abgelehnt. Siehe Step-up-Bestätigung.

ProblembehandlungLink kopieren

Eine Antwort 403 Forbidden mit dem Code FORBIDDEN kann details.reason enthalten, das angibt, warum die Anfrage abgelehnt wurde. Eine Ablehnung durch das API-Gateway hat keine details. Die Tabelle führt beide Fälle auf.

Alle Fehlercodes finden Sie unter Fehler.

Zugehöriger InhaltLink kopieren

• Dienstkonten und API-Tokens
• Bereiche, URLs und Anfrageformat
• Fehler
• Bewährte Sicherheitsmethoden