Einleitung
Auf dieser Seite wird beschrieben, wie Sie die Service Control API v2 für die Zugangssteuerung für verwaltete Dienste verwenden, die in Service Infrastructure eingebunden sind. Sie richtet sich an Dienstersteller, die ihre Dienste umfassend in Google Cloud integrieren möchten.
Service Infrastructure ist eine grundlegende Plattform, mit der Entwickler APIs und Dienste erstellen, verwalten, sichern und nutzen können. Sie verwendet ein einfaches, allgemeines Dienstnutzungsmodell: Ein Verbraucher nutzt einen von einem Ersteller verwalteten Dienst. Alle Google APIs und Google Cloud APIs verwenden dieses Modell, da sie auch auf Service Infrastructure basieren.
Wenn ein Client auf einen Dienst zugreift, erfordern alle am Zugriff beteiligten Entitäten normalerweise eine Status- und Richtlinienprüfung, einschließlich Verbraucher, Dienst, Ersteller, Nutzer, Anwendung und Ressourcen. Bei Service Infrastructure bezeichnet dieses Verfahren die sogenannte Zugriffssteuerung. Dazu gehört die Authentifizierung, Autorisierung, Auditing, Ratenbegrenzung und mehr.
Service Control API Version 2
Die Service Control API v2 bietet eine einfache services.check
-Methode, die Zugriffssteuerung für alle in Service Infrastructure integrierten Dienste ermöglicht.
Bei dieser Methode können Sie folgende Aktionen in einem einzigen Methodenaufruf durchführen:
- Statusprüfung
- Missbrauchsstatus
- Abrechnungsstatus
- Nutzerstatus
- Dienststatus
- Aktivieren von Diensten
- Authentifizierung
- Google OAuth-Zugriffstoken
- Vom Google-Dienstkonto signiertes JWT
- Autorisierung
- Audit
- Cloud-Audit-Logs. Das Audit-Log ist dem Dienst "externalaudit.googleapis.com" zugeordnet.
Wenn ein Dienst die Service Control API aufruft, ist der Ersteller gleichzeitig ein Nutzer der Service Control API. Daher führt die Methode services.check
auch eine Zugriffskontrolle für den Aufruf der Service Control API durch.
Damit ein Dienst die Service Control API aufrufen kann, müssen Sie die Service Control API für das Erstellerprojekt aktivieren und über die entsprechenden Berechtigungen für den Dienst verfügen. Weitere Informationen finden Sie unter Erste Schritte mit Cloud APIs und Zugriffssteuerung mit Service Control.
Anfrageattribute
Wenn ein Client auf einen Dienst zugreift, muss der Dienst den Zugriff in eine oder mehrere API-Anfragen zusammenfassen, die mit der Zugriffskontrolle überprüft werden können. In den meisten Fällen handelt es sich bei solchen Zugriffen um echte API-Anfragen. In anderen Fällen kann der Zugriff komplizierte Datenimportaufträge oder SQL-Abfragen darstellen und der Dienst muss den Zugriff anhand einer Reihe von virtuellen API-Anfragen modellieren und für jede Anfrage eine Zugriffskontrolle durchführen.
Wenn Sie die Zugriffssteuerung mithilfe der Service Control API ausführen möchten, muss der Dienst die Methode services.check
mit den erforderlichen Anfrageattributen aufrufen. In der folgenden Tabelle sind die Attribute aufgeführt, die für die Zugangssteuerung erforderlich sind.
Die vollständige Spezifikation finden Sie unter AttributeContext
.
Attribut | Beschreibung | Beispiel |
---|---|---|
origin.ip |
Die IP-Adresse des Aufrufers. | "1.2.3.4" |
api.service |
Der API-Dienstname. | "endpointsapis.appspot.com" |
api.operation |
Der API-Methodenname. | "google.example.hello.v1.HelloService.GetHello" |
api.version |
Der API-Versionsstring. | "v1" |
api.protocol |
Der API-Protokollname. | "https" |
request.id |
Eine eindeutige Anfrage-ID. | "123e4567-e89b-12d3-a456-426655440000" |
request.time |
Der Zeitpunkt der Anfrage. | "2019-07-31T05:20:00Z" |
request.method |
Der Name der HTTP-Methode. | "POST" |
request.scheme |
Das URL-Schema | "https" |
request.host |
Der HTTP-Host-Header | "endpointsapis.appspot.com" |
request.path |
Der URL-Pfad | "/v1/hello" |
request.headers |
Die HTTP-Anfrageheader. Die erforderlichen Header sind "Authorization", "User-Agent", "Origin", "Referer". | |
resource.name |
Der Name der Zielressource. | „projects/123/topics/news-feed” |
Ressourcenattribute
Wenn ein Client auf einen Dienst zugreift, kann der Zugriff eine oder mehrere Ressourcen innerhalb des Dienstes umfassen, z. B. das Lesen eines Objekts oder das Erstellen einer VM-Instanz. Der Dienst kann die Service Infrastructure-Steuerung für die Zugriffssteuerung auf Ressourcen verwenden, die von IAM und Cloud-Audit-Logs unterstützt werden. Wenn Ihr Dienst keine Zugriffssteuerung benötigt, können Sie diesen Abschnitt überspringen.
Für die Zugriffskontrolle muss ein Dienst Ressourcenattribute zusammen mit den Anfrageattributen an die Methode services.check
übergeben.
Die folgende Tabelle zeigt die für die Zugriffskontrolle erforderlichen Ressourcenattribute.
Attribut | Beschreibung | Beispiel |
---|---|---|
name |
Der Ressourcenname | "projects/123/locations/global/instances/instance-1" |
type |
Der Ressourcentyp. Das Format ist "{service}/{Kind}". | "endpointsapis.appspot.com/Instance" |
permission |
Die Ressourcenberechtigung. Das Format ist "{service}/{kinds}.{verb}". | "endpointsapis.appspot.com/instances.get" |
Für mehr Leistung und Effizienz können Sie mit der Methode services.check
mehrere Berechtigungen für eine einzelne Ressource in einem Aufruf prüfen.
Zugriffskontrolle durchführen
Sobald Sie Ihre Dienstkonfiguration für die Service Management API bereitgestellt haben und Ihr Dienst bereit ist, Anfragen von Clients zu bearbeiten, können Sie services.check
für Ihren bereitgestellten Dienst aufrufen. Sie sollten services.check
aufrufen, um die Zugriffskontrolle durchzuführen, wenn Ihr Dienst eine Anfrage erhält.
Um die Zugriffskontrolle zügig auszuprobieren, können Sie mit dem Befehl gcurl
die Methode services.check
aufrufen. Die Schritte zur Ersteinrichtung werden unter Erste Schritte mit der Service Control API erläutert.
Das folgende Beispiel zeigt, wie Sie mit dem Befehl gcurl
services.check
über HTTP aufrufen.
gcurl -d '{ "service_config_id": "latest", "attributes": { "origin": { "ip": "1.2.3.4" }, "api": { "service": "endpointsapis.appspot.com", "operation": "google.example.hello.v1.HelloService.GetHello", "version": "v1", "protocol": "https" } }, "request": { "id": "123e4567-e89b-12d3-a456-426655440000", "time": "2019-07-31T05:20:00Z", "scheme": "https", "host": "endpointsapis.appspot.com" "headers": { "authorization": "Bearer xxx", "user-agent": "curl/1.0" } }, "resources": [ ] }' https://servicecontrol.googleapis.com/v2/services/endpointsapis.appspot.com:check { }
Die Antwort der Methode services.check
gibt an, ob die Zugangssteuerung bestanden wurde. Bei erfolgreicher Prüfung sollte die Antwort leer sein. Wenn sie fehlschlägt, enthält der status
in der Antwort Fehlerinformationen, die der Dienst an den Client zurückgeben soll. Der Dienst muss die Fehlerinformationen häufig in sein eigenes Format übersetzen. Der Dienst kann die Informationen auch für Logging und Monitoring verwenden.
Für Produktionsdienste sollten Sie eine der von Google bereitgestellten Clientbibliotheken verwenden, um die Service Control API aufzurufen. Diese Bibliotheken bieten eine hohe Nutzerfreundlichkeit und verarbeiten gängige Funktionen wie die Authentifizierung automatisch. Weitere Informationen erhalten Sie unter Erläuterung der Clientbibliotheken.