Zugriff für bereitgestellte Kundenservicemitarbeiter verwalten

Für verschiedene Zugriffsmodi sind verschiedene Authentifizierungsmethoden verfügbar:

Anwendungsfall Authentifizierungsmethode Diese Authentifizierungsmethode
Sie können direkt über einen Kundenservicemitarbeiter auf Datenquellen zugreifen. Dienstkonto Bereitstgestellte Kundenservicemitarbeiter haben Zugriff auf alle Ressourcen, auf die ihr Dienstkonto Zugriff hat.
Anfragen an Endpunkte mit API-Schlüsseln über einen Kundenservicemitarbeiter senden. API-Schlüssel Prüfen Sie, ob API-Schlüssel von der gewünschten API unterstützt werden, bevor Sie diese Authentifizierungsmethode verwenden.
Nutzerkonten, Registrierung, Anmeldung oder Autorisierung für die Endnutzer des Kunden verwalten OAuth-Client-ID Ihr Kundenservicemitarbeiter muss die Einwilligung des Nutzers einholen.

Rollen

Bots, die Sie in der Agent Engine bereitstellen, werden mit dem Dienstkonto des AI Platform Reasoning Engine-Dienst-Agents ausgeführt, das mit service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com übereinstimmt.

Das Dienstkonto hat die Rolle (roles/aiplatform.reasoningEngineServiceAgent) Vertex AI Reasoning Engine-Dienst-Agent, die die Standardberechtigungen für bereitgestellte Agenten gewährt. Eine vollständige Liste der Standardberechtigungen finden Sie in der IAM-Dokumentation.

Rollen eines bereitgestellten Agents auflisten

Console

  1. Rufen Sie die Seite IAM auf und markieren Sie das Kästchen „Von Google bereitgestellte Rollenzuweisungen einschließen“.

    IAM aufrufen

  2. Wählen Sie das Projekt aus, das Ihrem Google Cloud Projekt entspricht.

  3. Suchen Sie das Hauptkonto, das mit service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com übereinstimmt.

  4. Die Rollen des bereitgestellten Kundenservicemitarbeiters finden Sie in der Spalte Rolle.

gcloud

Installieren und initialisieren Sie zuerst die gcloud-Befehlszeile. Führen Sie dann den folgenden Befehl aus:

gcloud projects get-iam-policy PROJECT_ID_OR_NUMBER \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:PRINCIPAL" \
  --format="value(bindings.role)"

Dabei gilt:

  • PROJECT_ID_OR_NUMBER ist die ID oder Nummer Ihres Projekts.
  • PRINCIPAL basiert auf dem Dienstkonto, das beim Bereitstellen des Agents in der Agent Engine generiert wurde.

Weitere Informationen finden Sie in der IAM-Dokumentation und in der Referenz für die Befehlszeile.

Python

Installieren Sie zuerst die Clientbibliothek:

pip install google-api-python-client

Authentifizieren Sie sich und führen Sie den folgenden Befehl aus, um die Rollen eines bereitgestellten Agents aufzulisten:

from google.cloud import resourcemanager_v3
from google.iam.v1 import iam_policy_pb2

project_id = "PROJECT_ID"
principal = "PRINCIPAL"

crm_service = resourcemanager_v3.ProjectsClient()
policy = crm_service.get_iam_policy(iam_policy_pb2.GetIamPolicyRequest(
    resource=f"projects/{project_id}"
))
for binding in policy.bindings:
    for member in binding.members:
        if principal in member:
            print(binding.role)

Dabei basiert PRINCIPAL auf dem Dienstkonto, das beim Bereitstellen des Agents in der Agent Engine generiert wurde.

Rollen für einen bereitgestellten Agenten gewähren

  1. Rufen Sie die Seite IAM auf und markieren Sie das Kästchen „Von Google bereitgestellte Rollenzuweisungen einschließen“.

    IAM aufrufen

  2. Wählen Sie das Projekt aus, das Ihrem Google Cloud Projekt entspricht.

  3. Suchen Sie das Hauptkonto, das mit service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com übereinstimmt.

  4. Fügen Sie dem Hauptkonto die erforderlichen Rollen hinzu. Klicken Sie dazu auf die Schaltfläche „Bearbeiten“, fügen Sie die Rollen hinzu und klicken Sie dann auf die Schaltfläche „Speichern“.

gcloud

Installieren und initialisieren Sie zuerst die gcloud-Befehlszeile. Führen Sie dann den folgenden Befehl aus:

gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

Dabei gilt:

  • PRINCIPAL basiert auf dem Dienstkonto, das beim Bereitstellen des Agents in der Agent Engine generiert wurde.
  • ROLE_NAME ist der Name der Rolle, die Sie zuweisen möchten. Eine Liste der vordefinierten Rollen finden Sie unter Informationen zu Rollen.

Weitere Informationen finden Sie in der IAM-Dokumentation und in der Referenz für die Befehlszeile.

Python

Wir empfehlen nicht, eigenen Python-Code zu schreiben, um Rollen für bereitgestellte Kundenservicemitarbeiter zu gewähren oder zu widerrufen. Stattdessen empfehlen wir entweder die Google Cloud Console oder gcloud für einmalige Vorgänge oder Terraform für die programmatische Verwaltung der IAM-Zugriffssteuerung. Wenn Sie dies in Python tun möchten oder müssen, lesen Sie die Dokumentation zur IAM-Clientbibliothek.

Rollen für einen bereitgestellten Agenten widerrufen

  1. Rufen Sie die Seite IAM auf und markieren Sie das Kästchen „Von Google bereitgestellte Rollenzuweisungen einschließen“.

    IAM aufrufen

  2. Wählen Sie das Projekt aus, das Ihrem Google Cloud Projekt entspricht.

  3. Suchen Sie das Hauptkonto, das mit service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com übereinstimmt.

  4. Entziehen Sie dem Hauptkonto die Rollen. Klicken Sie dazu auf die Schaltfläche „Bearbeiten“, entfernen Sie die entsprechenden Rollen und klicken Sie dann auf die Schaltfläche „Speichern“.

gcloud

Installieren und initialisieren Sie zuerst die gcloud-Befehlszeile. Führen Sie dann den folgenden Befehl aus:

gcloud projects remove-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

Dabei gilt:

  • PRINCIPAL basiert auf dem Dienstkonto, das beim Bereitstellen des Agents in der Agent Engine generiert wurde.
  • ROLE_NAME ist der Name der Rolle, die Sie widerrufen möchten. Eine Liste der vordefinierten Rollen finden Sie unter Informationen zu Rollen.

Weitere Informationen finden Sie in der IAM-Dokumentation und in der Referenz für die Befehlszeile.

Python

Wir empfehlen nicht, eigenen Python-Code zu schreiben, um Rollen für bereitgestellte Kundenservicemitarbeiter zu gewähren oder zu widerrufen. Stattdessen empfehlen wir für einmalige Vorgänge entweder die Google Cloud Console oder gcloud oder Terraform, um die IAM-Zugriffssteuerung programmatisch zu verwalten. Wenn Sie dies in Python tun möchten oder müssen, lesen Sie die Dokumentation zur IAM-Clientbibliothek.

Secrets

Ein Secret enthält eine oder mehrere Secret-Versionen sowie Metadaten wie Labels und Replikationsinformationen. Die eigentliche Nutzlast eines Secrets wird in einer Secret-Version gespeichert. Secrets werden über Secret Manager auf Projektebene verwaltet und können für alle bereitgestellten Agenten freigegeben werden. Wenn Sie die einem Agenten zugewiesenen Secrets in Secret Manager auflisten möchten, können Sie Labels hinzufügen und zum Filtern verwenden.

Secret erstellen

Console

  1. Rufen Sie die Seite Secret Manager auf.

    Zu Secret Manager

  2. Klicken Sie auf der Seite Secret Manager auf Secret erstellen.

  3. Geben Sie im Feld Name einen Namen für das Secret ein, z. B. my-secret.

  4. Optional: Wenn Sie beim Erstellen des ersten Secrets auch eine Secret-Version hinzufügen möchten, geben Sie im Feld Secret-Wert einen Wert für das Secret ein (z. B. abcd1234).

  5. Klicken Sie auf Labels und dann auf Label hinzufügen.

  6. Geben Sie einen Schlüssel und den zugehörigen Wert ein, um ein Label zu erstellen.

  7. Klicken Sie auf Secret erstellen.

gcloud

Installieren und initialisieren Sie zuerst die gcloud-Befehlszeile. Führen Sie dann die folgenden Befehle aus:

gcloud secrets create SECRET_ID --replication-policy="automatic"
gcloud secrets versions add SECRET_ID --data-file="FILE_PATH"

Dabei gilt:

  • SECRET_ID ist die ID des Geheimnisses oder die voll qualifizierte Kennzeichnung für das Geheimnis.
  • FILE_PATH ist der vollständige Pfad (einschließlich Dateiname) zur Datei mit den Versionsdetails.

Weitere Informationen finden Sie in der Secret Manager-Dokumentation zum Erstellen eines Secrets und einer Secret-Version oder in der Befehlszeilenreferenz zum Erstellen eines Secrets und einer Secret-Version.

Python

Installieren Sie zuerst die Clientbibliothek:

pip install google-cloud-secret-manager

Authentifizieren Sie sich und führen Sie dann den folgenden Befehl aus:

from google.cloud import secretmanager
import google_crc32c

client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
    "parent": "projects/PROJECT_ID",
    "secret_id": "SECRET_ID",
    "secret": {  # google.cloud.secretmanager_v1.types.Secret
        # Required. The replication policy cannot be changed after the Secret has been created.
        "replication": {"automatic": {}},
        # Optional. Labels to associate with the secret.
        "labels": {"type": "api_key", "provider": "anthropic"},
        # Optional. The secret's time-to-live in seconds with format (e.g.,
        # "900s" for 15 minutes). If specified, the secret versions will be
        # automatically deleted upon reaching the end of the TTL period.
        "ttl": "TTL",
    },
})

anthropic_api_key = "API_KEY"  # The secret to be stored.
payload_bytes = anthropic_api_key.encode("UTF-8")
# Optional. Calculate payload checksum.
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)

version = client.add_secret_version(request={
    "parent": secret.name,
    "payload": {
        "data": payload_bytes,
        "data_crc32c": int(crc32c.hexdigest(), 16),  # Optional.
    },
})
print(f"Added secret version: {version.name}")

Secret abrufen

Console

  1. Rufen Sie die Seite Secret Manager auf.

    Zu Secret Manager

  2. Klicken Sie auf der Seite Secret Manager auf den Namen eines zu beschreibenden Secrets.

  3. Auf der Seite Secret-Detail werden Informationen zum Secret aufgelistet.

gcloud

Installieren und initialisieren Sie zuerst die gcloud-Befehlszeile. Führen Sie dann den folgenden Befehl aus:

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID

Dabei gilt:

  • VERSION_ID ist die ID der Secret-Version.
  • SECRET_ID ist die ID des Geheimnisses oder die voll qualifizierte Kennzeichnung für das Geheimnis.

Weitere Informationen finden Sie in der Secret Manager-Dokumentation oder in der Referenz zur Befehlszeile.

Python

Installieren Sie zuerst die Clientbibliothek:

pip install google-cloud-secret-manager

Authentifizieren Sie sich und führen Sie dann den folgenden Befehl aus:

from google.cloud import secretmanager

client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.get_secret(request={"name": name})

Secrets auflisten

Console

  1. Rufen Sie die Seite Secret Manager auf.

    Zu Secret Manager

  2. Klicken Sie in der Tabelle „Secrets“ in das Feld Filter.

  3. Wählen Sie ein Filterattribut und den entsprechenden Wert aus, z. B. Location:asia-east1.

  4. Die Tabelle wird automatisch anhand der eingegebenen Werte gefiltert.

  5. Optional: Wenn Sie Secret-Versionen filtern möchten, wählen Sie ein Secret aus, um auf die zugehörigen Versionen zuzugreifen, und verwenden Sie dann die Option Filter in der Tabelle Versionen.

gcloud

Installieren und initialisieren Sie zuerst die gcloud-Befehlszeile.

Führen Sie den folgenden Befehl aus, um alle Secrets eines Projekts aufzulisten:

gcloud secrets list --filter="FILTER"

Dabei ist FILTER ein String (z.B. name:asecret OR name:bsecret) oder ein regulärer Ausdruck (z.B. name ~ "secret_ab.*").

Führen Sie den folgenden Befehl aus, um alle Versionen eines Secrets aufzulisten:

gcloud secrets versions list SECRET_ID

Dabei ist SECRET_ID die ID des Geheimnisses oder die voll qualifizierte Kennzeichnung für das Geheimnis.

Weitere Informationen finden Sie in der Secret Manager-Dokumentation zum Filtern von Secrets und zum Auflisten von Secret-Versionen oder in der Befehlszeilenreferenz zum Auflisten von Secrets bzw. Secret-Versionen.

Python

Installieren Sie zuerst die Clientbibliothek:

pip install google-cloud-secret-manager

Authentifizieren Sie sich und führen Sie dann den folgenden Befehl aus:

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
for secret in client.list_secrets(request={
    "parent": "projects/PROJECT_ID",
    "filter": "FILTER", # e.g. "labels.provider=anthropic"
}):
    print(f"Found secret: {secret.name}")

Secret aktualisieren

Console

  1. Rufen Sie die Seite Secret Manager auf.

    Zu Secret Manager

  2. Klicken Sie auf der Seite Secret Manager auf das Kästchen neben dem Namen des Secrets.

  3. Wenn das Infofeld geschlossen ist, klicken Sie auf Infofeld ansehen, um es einzublenden.

  4. Wählen Sie im Infofeld den Tab Labels aus.

  5. Klicken Sie auf Label hinzufügen und geben Sie einen Schlüssel und einen Wert für das Label ein.

  6. Klicken Sie auf Speichern.

gcloud

Installieren und initialisieren Sie zuerst die gcloud-Befehlszeile. Führen Sie dann den folgenden Befehl aus:

gcloud secrets update SECRET_ID --update-labels=KEY=VALUE

Dabei gilt:

  • SECRET_ID ist die ID des Geheimnisses oder die voll qualifizierte Kennzeichnung für das Geheimnis.
  • KEY ist der Labelschlüssel und
  • VALUE ist der entsprechende Wert des Labels.

Weitere Informationen finden Sie in der Secret Manager-Dokumentation oder in der Referenz für die Befehlszeile.

Python

Installieren Sie zuerst die Clientbibliothek:

pip install google-cloud-secret-manager

Authentifizieren Sie sich und führen Sie dann den folgenden Befehl aus:

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.update_secret(request={
    "secret": {
        "name": name,
        "labels": {"type": "api_key", "provider": "anthropic"}, # updated labels
    },
    "update_mask": {"paths": ["labels"]},
})
print(f"Updated secret: {response.name}")

Secret löschen

Console

  1. Rufen Sie die Seite Secret Manager auf.

    Zu Secret Manager

  2. Klicken Sie auf der Seite Secret Manager in der Spalte Aktionen für das Secret auf Mehr anzeigen.

  3. Wählen Sie im Menü die Option Löschen aus.

  4. Geben Sie im Dialogfeld Secret löschen den Namen des Secrets ein.

  5. Klicken Sie auf die Schaltfläche Secret löschen.

gcloud

Installieren und initialisieren Sie zuerst die gcloud-Befehlszeile.

Führen Sie den folgenden Befehl aus, um eine Secret-Version zu löschen:

gcloud secrets versions destroy VERSION_ID --secret=SECRET_ID

Dabei gilt:

  • VERSION_ID ist der Ressourcenname der Secret-Version.
  • SECRET_ID ist die ID des Geheimnisses oder die voll qualifizierte Kennzeichnung für das Geheimnis.

Führen Sie den folgenden Befehl aus, um ein Secret und alle zugehörigen Versionen zu löschen:

gcloud secrets delete SECRET_ID

wobei SECRET_ID die ID des Geheimnisses oder die voll qualifizierte Kennzeichnung für das Geheimnis ist.

Weitere Informationen finden Sie in der Secret Manager-Dokumentation zum Löschen eines Secrets und zum Vernichten einer Secret-Version oder in der Befehlszeilenreferenz zum Löschen eines Secrets und zum Vernichten einer Secret-Version.

Python

Installieren Sie zuerst die Clientbibliothek:

pip install google-cloud-secret-manager

Authentifizieren Sie sich und führen Sie den folgenden Befehl aus:

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
client.delete_secret(request={"name": name})

OAuth-Clients und ‑Anmeldedaten

Eine Client-ID wird zur Identifizierung eines einzelnen Kundenservicemitarbeiters bei den OAuth-Servern von Google verwendet. Wenn Ihr Bot auf mehreren Plattformen ausgeführt wird, erfordert jede eine eigene Client-ID. So integrieren Sie einen OAuth-basierten Agenten:

  1. Erstellen Sie einen OAuth-Client und Anmeldedaten.

  2. Speichern Sie die Client-ID und das Secret in Secret Manager. Weitere Informationen finden Sie unter Secret erstellen.

  3. Während der Entwicklung auf das Secret in Ihrem Agenten zugreifen

OAuth-Client-Anmeldedaten erstellen

  1. Rufen Sie in der Google Cloud Console die Seite Google Auth Platform > Clients auf.

    Gehen Sie zu „Google Auth Platform“ > „Clients“.

  2. (Bei Bedarf) Wenn auf dem Bildschirm „Google Auth Platform noch nicht konfiguriert“ angezeigt wird, klicken Sie auf Jetzt starten und füllen Sie die Projektkonfigurationen aus. Sie können sie später aktualisieren. Weitere Informationen zur Produktionsbereitschaft finden Sie unter Einhaltung der OAuth 2.0-Richtlinien.

  3. Klicken Sie auf Create client (Client erstellen).

  4. Legen Sie für Application type (Anwendungstyp) den Wert Web application fest.

  5. Legen Sie den Namen des OAuth-Clients auf OAUTH_CLIENT_DISPLAY_NAME fest.

  6. Fügen Sie unter Autorisierte Weiterleitungs-URIs den URI für REDIRECT_URI hinzu.

  7. Klicken Sie unter „Clientschlüssel“ auf die Schaltfläche „JSON herunterladen“. Es wird eine client_secret.json-Datei mit folgendem Inhalt heruntergeladen:

{'web': {
    'client_id': "CLIENT_ID",
    'client_secret': "CLIENT_SECRET",
    'project_id': "PROJECT_ID",
    'redirect_uris': [REDIRECT_URIs],
    'auth_uri': 'https://accounts.google.com/o/oauth2/auth',
    'token_uri': 'https://www.googleapis.com/oauth2/v3/token',
    'auth_provider_x509_cert_url': 'https://www.googleapis.com/oauth2/v1/certs',
    'javascript_origins': "JAVASCRIPT_ORIGINS",  # Optional.
}}
  1. Speichern Sie die Client-ID und das Secret beispielsweise in Secret Manager.
from google.cloud import secretmanager
import google_crc32c
import json

client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
    "parent": "projects/PROJECT_ID",
    "secret_id": "OAUTH_SECRET_ID", # e.g. "oauth-client-demo"
    "secret": {
        "labels": {"type": "oauth_client"},
        "replication": {"automatic": {}},
    },
})

payload_bytes = json.dumps(cred).encode("UTF-8")
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)

client.add_secret_version(request={
    "parent": secret.name,
    "payload": {
        "data": payload_bytes,
        "data_crc32c": int(crc32c.hexdigest(), 16),
    },
})

OAuth-Clients auflisten

  1. Rufen Sie in der Google Cloud Console die Seite Google Auth Platform > Clients auf.

    Gehen Sie zu „Google Auth Platform“ > „Clients“.

  2. Dort werden Ihre OAuth-Clientanmeldedaten aufgeführt.

OAuth-Client löschen

  1. Rufen Sie in der Google Cloud Console die Seite Google Auth Platform > Clients auf.

    Gehen Sie zu „Google Auth Platform“ > „Clients“.

  2. Wählen Sie die zu löschenden OAuth-Client-Anmeldedaten aus und klicken Sie auf „Löschen“.