Benutzerdefinierte Zielgruppen (Dienste)

Auf dieser Seite wird beschrieben, wie Sie benutzerdefinierte Zielgruppen für die Autorisierung verwenden.

Clients, die einen durch Identity and Access Management geschützten Cloud Run-Dienst aufrufen, müssen ein gültiges ID-Token bereitstellen, das eine Zielgruppenanforderung enthält, die der *.run.app-URL des empfangenden Dienstes entspricht. Für Kunden, die diese URL nicht kennen, können Sie einen benutzerdefinierten Zielgruppenwert verwenden.

Informationen zu benutzerdefinierten Zielgruppen

Cloud Run bietet eine Aufruferrolle (roles/run.invoker), um die Zugriffssteuerung mit IAM zu unterstützen. Die IAM-Zugriffssteuerung verwendet von Google signierte ID-Tokens, die als JSON-Webtokens (JWTs) verpackt sind. Der Inhalt dieser Tokens entspricht einem OIDC-Standard.

Im Token wird ein Zielgruppenfeld codiert, um das Ziel anzugeben, das das Token verwenden kann. Dadurch wird das Risiko eines Wiederholungsangriffs begrenzt, bei dem ein abgefangenes Token, das für die Verwendung mit einem Dienst bestimmt ist, bei einem anderen Dienst wiedergegeben wird

Konventionsgemäß ist die Zielgruppe die vollständige URL des Zieldienstes. Standardmäßig wird in Cloud Run dies die von Google generierte URL für einen Dienst sein, der auf run.app endet.

Ein Cloud Run-Dienst kann sich jedoch hinter einer anderen URL als der standardmäßig generierten URL befinden, wie in den folgenden Szenarien:

Bei Verwendung einer benutzerdefinierten Domain, um einen Dienst zu erreichen, den der Client nicht über die von Google generierte URL kennt.
Wenn Sie mehrere Dienste hinter einem Load-Balancer bereitstellen, kann ein Client nicht voraussehen, welcher regionale Dienst eine Anfrage erreicht. Von Google generierte URLs für Dienste sind regionsspezifisch, auch wenn der Dienstname identisch ist.

In diesen Szenarien müssen Sie einen Dienst so konfigurieren, dass benutzerdefinierte Zielgruppenwerte akzeptiert werden, die zusätzliche Ziele zulassen, die einem Client bekannt sind. Die von Google generierte Standard-URL bleibt immer als akzeptierter Zielgruppenwert.

Benutzerdefinierte Zielgruppen festlegen und aktualisieren

Das Festlegen benutzerdefinierter Zielgruppen für Cloud Run erfolgt auf Dienstebene und gilt für alle Bereitstellungsüberarbeitungen, ähnlich wie bei der IAM-Autorisierung.

Sie können mehrere benutzerdefinierte Zielgruppen festlegen, solange die JSON-Codierung der Zielgruppen als Stringliste 32.768 Zeichen nicht überschreitet.

Jede Konfigurationsänderung führt zur Erstellung einer neuen Überarbeitung. Für nachfolgende Überarbeitungen gilt automatisch dieselbe Konfigurationseinstellung, sofern Sie sie nicht explizit aktualisieren.

Befehlszeile

Mit dem folgenden Befehl können Sie benutzerdefinierte Zielgruppen für einen Dienst festlegen:

gcloud run services update SERVICE --add-custom-audiences=AUDIENCE

Ersetzen

SERVICE durch den Namen Ihres Cloud Run-Dienstes
AUDIENCE durch einen String für die benutzerdefinierte Zielgruppe, die Sie unterstützen möchten, z. B. myservice oder https://myservice.example.com

Sie können alle benutzerdefinierten Zielgruppen mit dem folgenden Befehl aus einem Dienst entfernen:

gcloud run services update SERVICE --clear-custom-audiences

YAML

Sie können vorhandene Dienstkonfigurationen mit dem Befehl gcloud run services describe --format export herunterladen und aufrufen, was bereinigte Ergebnisse im YAML-Format liefert. Anschließend können Sie die unten beschriebenen Felder ändern und die geänderte YAML-Datei mit dem Befehl gcloud run services replace hochladen. Achten Sie darauf, dass Sie die Felder nur wie dokumentiert ändern.

So rufen Sie die Konfiguration auf und laden sie herunter:

gcloud run services describe SERVICE --format export > service.yaml

Legen Sie die Annotation run.googleapis.com/custom-audiences in den Dienstmetadaten fest (nicht in den template-Metadaten):googledata/devsite/site-cloud/en/run/docs/authenticating/service-to-service.md
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  annotations:
    run.googleapis.com/custom-audiences: '["AUDIENCE"]'
spec:
  template:
    ...
```
Ersetzen
- SERVICE durch den Namen Ihres Cloud Run-Dienstes
- AUDIENCE durch einen String für die benutzerdefinierte Zielgruppe, die Sie unterstützen möchten, z. B. myservice oder https://myservice.example.com
Beachten Sie, dass der Wert des Attributs ein JSON-Array von Strings in Anführungszeichen ist, sodass sowohl doppelte als auch einfache Anführungszeichen verwendet werden müssen.
Ersetzen Sie den Dienst mit dem folgenden Befehl durch die neue Konfiguration:
```
gcloud run services replace service.yaml
```

Benutzerdefinierte Zielgruppen prüfen

Rufen Sie ein ID-Token für ein Dienstkonto ab, das eine IAM-Berechtigung zum Aufrufen des Dienstes hat. Beachten Sie die Verwendung der benutzerdefinierten Zielgruppe AUDIENCE.
```
export TOKEN=$(gcloud auth print-identity-token --impersonate-service-account SERVICE_ACCOUNT_EMAIL --audiences='AUDIENCE')
```
Ersetzen Sie:
- SERVICE_ACCOUNT_EMAIL: die E-Mail-Adresse des Dienstkontos endet mit .iam.gserviceaccount.com.
- AUDIENCE durch den benutzerdefinierten Zielgruppenwert, den Sie für den Dienst festgelegt haben.
Endpunkt des Dienstes mit diesem ID-Token aufrufen
```
curl -H "Authorization: Bearer ${TOKEN}" ENDPOINT
```
Ersetzen Sie ENDPOINT durch den Endpunkt, um Ihren Dienst zu erreichen, z. B. die benutzerdefinierte Domain oder die URL .run.app.
Bestätigen Sie, dass die Anfrage autorisiert ist und Sie die erwartete Antwort Ihres Dienstes sehen.