Verbindung über ein IAM-Konto herstellen

Auf dieser Seite wird der Anmeldeprozess bei einer AlloyDB for PostgreSQL-Instanz mit einem Konto erläutert, das mit Identity and Access Management (IAM) vorbereitet wurde. Der Prozess wird anhand eines Beispiels veranschaulicht, in dem eine IAM-basierte Anmeldung mit dem Befehlszeilenclient psql durchgeführt wird.

Eine Übersicht über das Herstellen einer Verbindung zu AlloyDB-Instanzen finden Sie unter Verbindungsübersicht.

Hinweis

Ihr Projekt, Ihr Cluster, Ihre Instanzen und Ihre IAM-Nutzerkonten müssen alle vorbereitet werden, bevor Sie sich mit IAM-Anmeldedaten in einer AlloyDB-Instanz anmelden können.

Weitere Informationen finden Sie unter IAM-Authentifizierung verwalten.

Mit einem OAuth 2.0-Token authentifizieren

Ein Nutzer oder eine Anwendung kann sich mit den folgenden Schritten bei einer AlloyDB-Datenbank authentifizieren:

  1. Wenn Sie dies noch nicht getan haben, authentifizieren Sie sich für die gcloud CLI mit demselben Nutzer- oder Dienstkonto, mit dem Sie sich in Ihrer AlloyDB-Instanz anmelden möchten.

  2. Fordern Sie mit dem Befehl the gcloud auth print-access-token ein OAuth 2.0-Token von Google Cloud an:

    gcloud auth print-access-token

    Google Cloud gibt ein OAuth 2.0-Token als Ausgabe dieses Befehls aus.

    Für zusätzliche Sicherheit können Sie das Token so einschränken, dass es nur für die AlloyDB-Authentifizierung verwendet werden kann. Führen Sie dazu die folgenden Schritte aus:

    1. Fügen Sie den alloydb.login Bereich mit dem gcloud auth application-default login Befehl den Zugriffsanmeldedaten Ihrer aktuellen Umgebung hinzu, falls Sie dies noch nicht getan haben:

      gcloud auth application-default login --scopes=https://www.googleapis.com/auth/alloydb.login,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/userinfo.email,openid

    2. Geben Sie mit dem gcloud auth application-default print-access-token Befehl, ein eingeschränktes OAuth 2.0-Token aus, das nur für die AlloyDB-Authentifizierung gilt:

      gcloud auth application-default print-access-token --scopes=https://www.googleapis.com/auth/alloydb.login

    Mit dem OAuth 2.0-Token können Sie oder eine andere Person authentifizierte Anfragen an Google Cloud in Ihrem Namen stellen. Behandeln Sie das Token mit dem gleichen Niveau der Sicherheit wie ein Passwort. Speichern Sie das Token entweder sicher oder gar nicht. Das Beispiel für die Verwendung von psql weiter unten auf dieser Seite zeigt, wie Sie ein OAuth 2.0-Token in einer einzigen Aktion anfordern, verwenden und verwerfen.

  3. Melden Sie sich mit den Standardtechniken von PostgreSQL in einer AlloyDB-Instanz an. Verwenden Sie dazu die folgenden Anmeldedaten:

    • Geben Sie das im vorherigen Schritt abgerufene Zugriffstoken als Passwort an.

    • Bei einem IAM-Nutzerkonto ist der Datenbanknutzername die vollständige E-Mail-Adresse des Kontos.

    • Bei einem IAM-Dienstkonto ist der Datenbanknutzername die E-Mail-Adresse des Kontos ohne das Suffix .gserviceaccount.com.

Der folgende psql-Befehl zeigt eine Möglichkeit, sich in der Befehlszeile bei einem IAM-Nutzer anzumelden. Die Ausgabe von gcloud auth print-access-token wird der Umgebungsvariablen PGPASSWORD zugewiesen, die psql anschließend als Datenbankanmeldepasswort verwendet.

PGPASSWORD=$(gcloud auth print-access-token) psql \
  -h INSTANCE_ADDRESS \
  -U USERNAME \
  -d DATABASE

Ersetzen Sie Folgendes:

  • INSTANCE_ADDRESS: Die IP-Adresse der AlloyDB-Instanz, mit der eine Verbindung hergestellt werden soll.

  • USERNAME: Eine Kennung für den IAM-Nutzer, mit dem sich bei der Instanz authentifiziert werden soll.

    Geben Sie für ein IAM-Nutzerkonto die vollständige E-Mail-Adresse des Nutzerkontos an. Beispiel: kai@altostrat.com.

    Geben Sie für ein IAM-Dienstkonto die Adresse des Dienstkontos ohne das Suffix .gserviceaccount.com an. Wenn Sie beispielsweise das Dienstkonto my-service@my-project.iam.gserviceaccount.com angeben möchten, verwenden Sie hier den Wert my-service@my-project.iam

  • DATABASE: Der Name der Datenbank, zu der eine Verbindung hergestellt werden soll.

Beachten Sie, dass psql Passwörter, die in der Befehlszeile eingegeben werden und länger als 100 Zeichen sind, abschneidet. Wenn Sie psql mit einem OAuth 2.0-Token als Anmeldepasswort verwenden möchten, müssen Sie die Umgebungsvariable PGPASSWORD wie in diesem Beispiel gezeigt festlegen, anstatt sie bei Aufforderung manuell einzufügen.

Automatisch authentifizieren

Wenn Sie einen IAM-basierten AlloyDB Nutzer automatisch authentifizieren möchten, ohne dass ein OAuth 2.0-Token erforderlich ist, haben Sie zwei Möglichkeiten: AlloyDB Auth-Proxy und AlloyDB-Sprach-Connectors.

Das IAM-Konto, mit dem Sie den Proxy-Client oder die Sprach-Connectors ausführen, muss dasselbe Konto sein, das Sie als Datenbanknutzer hinzugefügt haben. Wenn Sie Ihre Arbeitslast beispielsweise mit dem IAM-Nutzerkonto kai@altostrat.com ausführen, können Sie den Proxy-Client oder die Sprach-Connectors verwenden, um den Datenbanknutzer kai@altostrat.com automatisch zu authentifizieren, ohne ein OAuth 2.0-Token anzugeben. In diesem Beispiel funktioniert die automatische Authentifizierung nur mit dem Datenbanknutzer kai@altostrat.com.

Auth-Proxy

Wenn Sie den Auth-Proxy verwenden möchten, müssen Sie den AlloyDB Auth-Proxy-Client mit dem aktivierten Flag --auto-iam-authn ausführen.

Weitere Informationen zum Ausführen des Auth-Proxys finden Sie unter Verbindung mit dem AlloyDB Auth-Proxy herstellen.

Sprach-Connectors

Wenn Sie Sprach-Connectors verwenden möchten, müssen Sie die IAM-Authentifizierung programmatisch aktivieren. Auf der Seite AlloyDB-Sprach-Connectors konfigurierenfinden Sie für jede Sprache eine entsprechende Option.

IAM-Authentifizierung beheben

So ermitteln Sie die Ursache für einen fehlgeschlagenen IAM-basierten Authentifizierungsversuch:

  1. Rufen Sie in der Google Cloud Console die Seite „Log-Explorer“ auf:

    Zum Log-Explorer

  2. Klicken Sie unter Ressourcentyp auf AlloyDB-Instanz.

  3. Klicken Sie unter Schweregrad auf Warnung.

    Wenn Warnung keine Option ist, wurden im ausgewählten Zeitraum keine Authentifizierungsfehler protokolliert. Möglicherweise müssen Sie den Zeitraum mit den Steuerelementen des Log-Explorers anpassen.

  4. Suchen Sie unter Abfrageergebnisse in den Logeinträgen nach einer der folgenden Nachrichten:

    Request had invalid authentication credentials.
    Das Zugriffstoken ist ungültig.
    Caller does not have required permission to use project.
    Das IAM-Hauptkonto hat nicht die erforderlichen IAM-Rollen oder ‑Berechtigungen. In der vollständigen Fehlermeldung werden die fehlenden Rollen oder Berechtigungen angegeben.
    IAM principal does not match database user.

    Das authentifizierte IAM-Hauptkonto, das durch das Zugriffstoken angegeben wird, stimmt nicht mit dem Datenbanknutzer überein, als der Sie eine Verbindung herstellen möchten.

    Führen Sie den folgenden Befehl aus, um das durch das Token angegebene Hauptkonto aufzurufen:

    curl -H "Content-Type: application/x-www-form-urlencoded" -d "access_token=ACCESS_TOKEN" https://www.googleapis.com/oauth2/v1/tokeninfo

    Ersetzen Sie ACCESS_TOKEN durch das OAuth 2.0-Zugriffstoken.

    Request had insufficient scopes.
    Das Zugriffstoken enthält weder den Bereich alloydb.login noch den Bereich cloud-platform. Mindestens einer dieser Bereiche ist erforderlich.

Nächste Schritte