IAM-basierte API-Authentifizierung – Übersicht

Diese Seite gilt für Apigee, aber nicht für Apigee Hybrid.

Apigee unterstützt die IAM-basierte Authentifizierung und Autorisierung für API-Proxys. Bei dieser Lösung hängt der Zugriff auf die API-Aufruffunktion von mehreren Faktoren ab, z. B. davon, ob der Anfrageablauf die VerifyIAM-Richtlinie enthält und ob der API-Nutzer die erforderlichen Google Cloud IAM-Rollen oder Berechtigungen zum Aufrufen von Apigee APIs hat. Die Autorisierung kann für jeden Google Cloud-Rechtsinhaber gewährt werden und ist nicht auf einzelne Nutzer beschränkt.

IAM-basierte Zugriffssteuerung verwenden

In diesem Abschnitt wird der End-to-End-Prozess zum Einrichten der IAM-basierten Authentifizierung und Autorisierung beschrieben. Außerdem erfahren Sie, wie Anfragen nach der Einrichtung des Zugriffs ausgewertet werden und wie Sie den Zugriff für API-Nutzer widerrufen, die zuvor Zugriff hatten.

Zugriffsverwaltung hinzufügen

So richten Sie die Zugriffsverwaltung für einen API-Proxy ein:

  1. Fügen Sie die VerifyIAM-Richtlinie dem Apigee API-Proxy oder den Apigee API-Proxys als Teil des Anfrageablaufs hinzu.
  2. Der Cloud-Administrator für das Apigee-Projekt:
    1. Weisen dem Google Cloud-Hauptkonto des API-Nutzers auf Projektebene die IAM-Rolle deploymentInvoker (oder eine benutzerdefinierte Rolle mit der IAM-Berechtigung apigee.deployments.invoke) zu. Dadurch erhält der API-Nutzer Zugriff auf alle gehosteten APIs in der zugehörigen Apigee-Organisation.

      oder

    2. Mit der Aktion SetIamPolicy wird die Rolle oder Berechtigung dem Google Cloud-Prinzip des API-Nutzers bei einer bestimmten Bereitstellung oder iterativ bei mehreren Bereitstellungen gewährt. Verwenden Sie den List-Vorgang auf der Bereitstellungsressource, um alle Bereitstellungen in einer Umgebung aufzurufen, einschließlich API-Proxys und freigegebener Abläufe. Der Name der Bereitstellung ist der Name des API-Proxys oder des freigegebenen Ablaufs.
  3. Bitten Sie den API-Nutzer, ein Zugriffstoken zu generieren, das er in der Apigee API-Anfrage für die Berechtigungsprüfung weitergibt. Das generierte Token muss den Authentifizierungsbereich https://www.googleapis.com/auth/cloud-platform haben.

Administratorvorgänge

In diesem Abschnitt sind die Aktionen aufgeführt, die API-Administratoren (API-Produzenten) beim Verwalten von IAM-basierten Berechtigungen ausführen.

Die Dokumentation zu API-basierten Vorgängen, die beim Verwalten des IAM-basierten Zugriffs verwendet werden, finden Sie in der API-Referenzdokumentation für organizations.environments und organizations.environments.deployments. Dazu gehören die Vorgänge SetIamPolicy, GetIamPolicy, TestIamPermissions und GetDeployment.

In dieser Tabelle werden Vorgänge den erforderlichen Berechtigungen zugeordnet:

Admin-Vorgang Aktion Erforderliche IAM-Berechtigung IAM-Ressource, für die die Berechtigung erforderlich ist*
GetDeployment Informationen für eine Bereitstellung in einer Apigee-Umgebung abrufen apigee.deployments.get Google Cloud-Projekt oder Apigee-Umgebung
ListDeployments Deployments in einer Apigee-Umgebung auflisten apigee.deployments.list Projekt oder Apigee-Umgebung
SetIamPolicy Aufrufzugriff für API-Nutzer bei einer bestimmten API-Bereitstellung festlegen apigee.deployments.setIamPolicy Google Cloud-Projekt oder Apigee-Umgebung
GetIamPolicy Einstellungen für den Aufrufzugriff für eine API-Bereitstellung abrufen apigee.deployments.getIamPolicy Google Cloud-Projekt oder Apigee-Umgebung
TestIamPermissions Prüfen, ob der Nutzer, der diese API aufruft, die in der Nutzlast angegebene Berechtigung hat Keine IAM-Berechtigung erforderlich –
* Das Google Cloud-Projekt ist das Projekt, mit dem Apigee bereitgestellt wird. Apigee-Berechtigungen auf Umgebungsebene werden mit setIAMPolicy für die Umgebung festgelegt.

Laufzeitzugriffsprüfung

Wenn der API-Nutzer versucht, auf eine API mit IAM-basierter Zugriffssteuerung zuzugreifen, wird geprüft, ob er das erforderliche Zugriffstoken und die entsprechende Rolle oder Berechtigung auf Projekt- oder Bereitstellungsebene hat. Ist dies der Fall, darf der Zugriff auf den Proxy fortgesetzt werden. Andernfalls werden sie blockiert.

Zugriff entfernen

Zugriff auf Projektebene entfernen:Wenn der Cloud-Administrator des Apigee-Projekts den Zugriff für einen API-Nutzer entfernen möchte, der auf Projektebene verwaltet wird, widerruft er die IAM-Rolle deploymentInvoker (oder die benutzerdefinierte Rolle mit der IAM-Berechtigung apigee.deployments.invoke) für das Google Cloud-Hauptkonto des API-Nutzers für das Google Cloud-Projekt.

Wenn der Zugriff für einzelne Bereitstellungen mit setIamPolicy gewährt wurde,entfernen Sie die Rolle oder Berechtigung mit einem anderen setIamPolicy-Vorgang aus den Bereitstellungen.

Merkmale und Einschränkungen der IAM-basierten Zugriffssteuerung

Beachten Sie die folgenden Eigenschaften und Einschränkungen bei der Verwendung von IAM-basierter Authentifizierung und Autorisierung:

  • Die Richtlinienausführung mit VerifyIAM dauert in der Regel etwa 10 Millisekunden. Bei einigen Aufrufen kann es jedoch zu einer Ausführungslatenz von etwa 50 ms kommen. Insbesondere in der Region asia-east2 kann die durchschnittliche Latenz auf 50 ms ansteigen und einige Aufrufe können etwa 100 ms dauern.

    Diese Latenzwerte sind keine Garantie.
  • Die Einbeziehung der VerifyIAM-Richtlinie für einen Proxy ist nur eine Bestätigung/Nichtbestätigung. Die spezifischen Rollen und Berechtigungen des API-Nutzers werden in späteren Prozessen im Anfrage- oder Antwortablauf nicht berücksichtigt.
  • Da eine Autorisierungsüberprüfung nur bei der Ausführung der VerifyIAM-Richtlinie erfolgt, sollte VerifyIAM die erste Richtlinie im Anfrageablauf sein, nach den Richtlinien zur Verkehrsverwaltung.
  • Wenn die Berechtigungsbestätigung erfolgreich ist oder der API-Produzent die VerifyIAM-Richtlinie so gekennzeichnet hat, dass bei Fehlern fortgefahren wird, werden die anderen Richtlinien (falls vorhanden) im Anfrageablauf fortgesetzt, bis der Zielserver erreicht wird. Wenn die Berechtigungsprüfung fehlschlägt und der API-Produzent die Richtlinie nicht so markiert hat, dass bei Fehlern fortgefahren wird, erhält der Nutzer eine Fehlermeldung.
  • Wenn Sie den Aufrufzugriff (apigee.deployments.invoke) auf Umgebungsebene hinzufügen, wird der Aufrufzugriff nicht auf alle API-Bereitstellungen innerhalb der Umgebung übertragen.
  • IAM-Bedingungen werden für die Bereitstellungsressource nicht unterstützt und können nicht verwendet werden, um den Aufrufzugriff zu steuern. Weitere Informationen finden Sie unter Apigee IAM Conditions zu Richtlinien hinzufügen.
  • Die IAM-basierte Zugriffssteuerung unterstützt maximal 1.500 Rollenbindungen innerhalb einer einzelnen Richtlinie und unterliegt anderen Einschränkungen. Weitere Informationen finden Sie unter IAM-Kontingente und ‑Limits.
  • Bei der IAM-basierten Zugriffssteuerung kann es zu Verzögerungen bei der IAM-Weitergabe kommen.
  • Der Versuch, andere apigee.deployments-Vorgänge wie apigee.deployments.delete über die setIAMPolicy auf Bereitstellungsebene zu verwalten, ist nicht effektiv, führt aber auch nicht zu einem Fehler. Nur apigee.deployements.invoke ist wirksam.
  • Der Zugriff auf eine Bereitstellung wird gelöscht, wenn der entsprechende Proxy aus der Umgebung entfernt oder gelöscht wird. Bei einer Neubereitstellung muss der Zugriff neu hinzugefügt werden.
  • Die IAM-basierte Authentifizierung und Autorisierung ist im Hybridmodus derzeit nicht verfügbar.

Beispiele

Dieser Abschnitt enthält Beispiele für die Erteilung und den Widerruf von IAM-basiertem Zugriff auf APIs. In diesen Beispielen wird davon ausgegangen, dass VerifyIAM dem entsprechenden API-Proxy bereits hinzugefügt wurde.

In diesen Beispielen wird entweder die Cloud Console oder gcloud (siehe Abbildung) verwendet, um Rollen oder Berechtigungen für das Google Cloud-Principal des API-Nutzers zu verwalten. $Project in den Beispielen ist das Google Cloud-Projekt.

Nutzerzugriff auf das Aufrufen aller APIs in einer Apigee-Organisation gewähren und widerrufen

Wenn Sie Zugriff gewähren möchten, fügen Sie die Rolle deploymentInvoker hinzu:

gcloud projects add-iam-policy-binding {$Project} --member={$user} --role='roles/apigee.deploymentInvoker'

Entfernen Sie die Rolle deploymentInvoker, um den Zugriff zu widerrufen:

gcloud projects remove-iam-policy-binding {$Project} --member={$user} --role='roles/apigee.deploymentInvoker'

Nutzerzugriff auf bestimmte Bereitstellungen innerhalb einer Umgebung gewähren und widerrufen

So fügen Sie einer bestimmten Bereitstellung die Rolle „Invoker“ für einen Nutzer hinzu:

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:setIamPolicy' \
    --header 'Authorization: Bearer $TOKEN ' \
    --header 'Content-Type: application/json' \
    --data '{"policy":{"bindings":[{"members":["user:$user"],"role":"roles/apigee.deploymentInvoker"}]}}'

Eine Erfolgsmeldung sollte in etwa so aussehen:

  {
    "version": 1,
    "etag": "BwYT8i40Vwo=",
    "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:$user"
        ]
      }
    ]
  }

So prüfen Sie, ob das hinzugefügte Richtlinienobjekt korrekt gespeichert wurde (optional):

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:getIamPolicy' \
  --header 'Authorization: Bearer $TOKEN'

Sie sollten eine Erfolgsmeldung wie die oben gezeigte sehen.

Damit der Nutzer prüfen kann, ob er auf die angegebene Bereitstellung zugreifen kann (d. h., ob die Berechtigung apigee.deployments.invoke für den angegebenen Nutzer in einer bestimmten Bereitstellung festgelegt ist), bitten Sie ihn, diese Anfrage mit dem zuvor generierten Zugriffstoken zu senden:

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:testIamPermissions' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"permissions":["apigee.deployments.invoke"]}'

Die Antwort muss die Berechtigung apigee.deployments.invoke für den Nutzer enthalten.

Wenn Sie den Zugriff auf eine bestimmte Bereitstellung widerrufen möchten, entfernen Sie die Rolle deploymentInvoker. Rufen Sie zuerst das Richtlinienobjekt ab, das derzeit mit der Bereitstellung verknüpft ist: 

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:getIamPolicy' \
  --header 'Authorization: Bearer $TOKEN'

Die Erfolgsantwort sollte in etwa so aussehen: Möglicherweise werden auch andere Verknüpfungen angezeigt.

{
  "version": 1,
  "etag": "BwYT8i40Vwo=",
  "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:$user"
        ]
      }
    ]
  }

So entfernen Sie die Bindung:

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:setIamPolicy' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{}'

Hinweis: Wenn Sie eine leere Payload angeben, wird der Zugriff für alle Nutzer entfernt. Das ist in diesem Beispiel jedoch angemessen, da wir nur einen Nutzer mit Zugriff haben. Wenn Sie den Nutzerzugriff in einer Situation entfernen, in der der Zugriff für andere Nutzer fortgesetzt werden soll, geben Sie in der Nutzlast die Nutzer an, die weiterhin Zugriff haben sollen, genau wie beim Festlegen des ursprünglichen Zugriffs für diese Nutzer.

Prüfen Sie, ob die Bindung entfernt wurde. Dazu muss die Berechtigung apigee.deployments.invoke für den Nutzer in der Bereitstellung nicht vorhanden sein:

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:testIamPermissions' \
  --header 'Authorization: Bearer $USER_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"permissions":["apigee.deployments.invoke"]}'

Wenn kein Nutzer die Berechtigung hat, sollte eine leere Ausgabe zurückgegeben werden.