Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
Auf dieser Seite wird beschrieben, wie Sie sich mit einem Konto, das mit Identity and Access Management (IAM) vorbereitet wurde, in einer AlloyDB for PostgreSQL-Instanz anmelden. Darin wird der Prozess veranschaulicht, indem gezeigt wird, wie eine IAM-basierte Anmeldung mit dem psql-Befehlszeilenclient durchgeführt wird.
Eine Übersicht über das Herstellen einer Verbindung zu AlloyDB-Instanzen finden Sie unter Verbindungsübersicht.
Hinweise
Für Ihr Projekt, Ihren Cluster, Ihre Instanzen und Ihre IAM-Nutzerkonten sind Vorbereitungen erforderlich, bevor Sie sich mit IAM-Anmeldedaten in einer AlloyDB-Instanz anmelden können.
Der Befehl Google Cloud gibt ein OAuth 2.0-Token aus.
Für zusätzliche Sicherheit können Sie das Token auf die Verwendung mit der AlloyDB-Authentifizierung beschränken. Folgen Sie dazu dieser alternativen Anleitung:
Mit dem OAuth 2.0-Token können Sie oder andere authentifizierte Anfragen an Google Cloud in Ihrem Namen stellen. Behandeln Sie das Token mit demselben Sicherheitsniveau wie ein Passwort. Speichern Sie das Token entweder sicher oder vermeiden Sie es, es überhaupt zu speichern. Im Beispiel für die Verwendung von psql weiter unten auf dieser Seite wird gezeigt, wie ein OAuth 2.0-Token in einem einzigen Vorgang angefordert, verwendet und verworfen werden kann.
Melden Sie sich mit den folgenden Anmeldedaten bei einer AlloyDB-Instanz an:
Geben Sie das im vorherigen Schritt abgerufene Zugriffstoken als Passwort an.
Bei einem IAM-Nutzerkonto ist der Datenbank-Nutzername die vollständige E-Mail-Adresse des Kontos.
Bei einem IAM-Dienstkonto ist der Datenbank-Nutzername die E-Mail-Adresse des Kontos ohne das Suffix .gserviceaccount.com.
Der folgende psql-Befehl zeigt eine Möglichkeit, sich über die Befehlszeile bei einem IAM-Nutzer anzumelden. Die Ausgabe von gcloud
auth print-access-token wird der Umgebungsvariable PGPASSWORD zugewiesen, die psql später als Datenbankanmeldepasswort verwendet.
INSTANCE_ADDRESS: Die IP-Adresse der AlloyDB-Instanz, zu der eine Verbindung hergestellt werden soll.
USERNAME: Eine Kennung für den IAM-Nutzer, mit dem die Authentifizierung bei der Instanz erfolgt.
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 Language 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 Language 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 für den Datenbanknutzer kai@altostrat.com.
Auth-Proxy
Für die Verwendung des Auth-Proxys muss der AlloyDB Auth-Proxy-Client mit dem Flag --auto-iam-authn ausgeführt werden.
Für die Verwendung von Language Connectors ist die programmatische Aktivierung der IAM-Authentifizierung erforderlich. Für jede Sprache gibt es eine entsprechende Option unter AlloyDB Language Connectors konfigurieren.
Probleme mit der IAM-Authentifizierung beheben
So ermitteln Sie die Ursache eines fehlgeschlagenen IAM-basierten Authentifizierungsversuchs:
Rufen Sie in der Google Cloud Console die Seite „Log-Explorer“ auf:
Klicken Sie unter Ressourcentyp auf AlloyDB-Instanz.
Klicken Sie unter Schweregrad auf Benachrichtigung.
Wenn Warnung keine Option ist, wurden im ausgewählten Zeitraum keine Authentifizierungsfehler protokolliert. Möglicherweise müssen Sie das Fenster mit den Steuerelementen des Log-Explorers anpassen.
Sehen Sie sich unter Abfrageergebnisse die Logeinträge an und suchen Sie nach einer der folgenden Meldungen:
Request had invalid authentication credentials.
Das Zugriffstoken ist ungültig.
Caller does not have required permission to use project.
Dem IAM-Hauptkonto fehlen 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 sich verbinden möchten.
Führen Sie den folgenden Befehl aus, um den vom Token angegebenen Prinzipal aufzurufen:
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-08-25 (UTC)."],[[["\u003cp\u003eThis guide outlines how to log in to an AlloyDB for PostgreSQL instance using Identity and Access Management (IAM) credentials, primarily through the \u003ccode\u003epsql\u003c/code\u003e command-line client.\u003c/p\u003e\n"],["\u003cp\u003eAuthentication with an OAuth 2.0 token requires authorizing the Google Cloud CLI and obtaining a token, which is then used as the password for database access, with the username being the IAM user's email address or the service account's email without the suffix.\u003c/p\u003e\n"],["\u003cp\u003eThe document details how to authenticate using the \u003ccode\u003epsql\u003c/code\u003e command by assigning the OAuth token to the \u003ccode\u003ePGPASSWORD\u003c/code\u003e environment variable, ensuring correct syntax for IAM user or service accounts.\u003c/p\u003e\n"],["\u003cp\u003eAlloyDB Auth Proxy and Language Connectors can be used to automate IAM authentication, eliminating the need to manually provide an OAuth 2.0 token, but requiring the use of the same IAM account for the workload and database user.\u003c/p\u003e\n"],["\u003cp\u003eTroubleshooting steps are provided to resolve IAM authentication failures, including checking logs for specific error messages and verifying access token validity, permissions, principal matching, and required scopes.\u003c/p\u003e\n"]]],[],null,["# Connect using an IAM account\n\nThis page explains the process of logging into an AlloyDB for PostgreSQL instance using\nan account prepared with Identity and Access Management (IAM). It illustrates the process\nby showing how to perform an IAM-based login using the `psql`\ncommand-line client.\n\nFor an overview of connecting to AlloyDB instances, see\n[Connection overview](/alloydb/docs/connection-overview).\n\nBefore you begin\n----------------\n\nYour project, cluster, instances, and IAM user accounts all\nrequire preparation before you can log in to an AlloyDB instance\nusing IAM credentials.\n\nFor more information, see [Manage IAM\nauthentication](/alloydb/docs/manage-iam-authn).\n\nAuthenticate with an OAuth 2.0 token\n------------------------------------\n\nA user or an application can authenticate with an AlloyDB database\nby following these steps:\n\n1. If you haven't already done so, [authorize the\n Google Cloud CLI](https://cloud.google.com/sdk/docs/authorizing) using the\n same user or service account that you want to log in to your\n AlloyDB instance with.\n\n2. Request an OAuth 2.0 token from Google Cloud using [the\n `gcloud auth print-access-token`\n command](/sdk/gcloud/reference/auth/print-access-token):\n\n gcloud auth print-access-token\n\n The Google Cloud prints an OAuth 2.0 token as the output of this\n command.\n\n For additional security, you can restrict the token for use with only\n AlloyDB authentication by following these alternative steps:\n 1. Add the\n `alloydb.login` scope to your current environment's access credentials using [the\n `gcloud auth application-default login`\n command](/sdk/gcloud/reference/auth/application-default/login), if you have not already done so:\n\n 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\n\n 2. Print a restricted OAuth 2.0 token using [the `gcloud auth application-default print-access-token`\n command](/sdk/gcloud/reference/auth/application-default/print-access-token),\n scoping the token only to AlloyDB authentication:\n\n gcloud auth application-default print-access-token ---scopes=https://www.googleapis.com/auth/alloydb.login\n\n | **Caution:** Treat your OAuth 2.0 token as sensitive information. Either store it securely, or don't store it at all after use.\n\n The OAuth 2.0 token lets you---or anyone---make authenticated requests to\n Google Cloud on your behalf. Treat the token with the same level\n of security as a password. Either store the token securely, or avoid\n storing it at all. The example use of `psql` later on this page\n demonstrates a way to request, use, and discard an OAuth 2.0 token in a\n single action.\n3. Log in to an AlloyDB instance with standard PostgreSQL\n techniques, using these credentials:\n\n - Present the access token you acquired in the previous step as your\n password.\n\n - For an IAM user account, the database username is the\n account's full email address.\n\n - For an IAM service account, the database username is the\n account's email address without the `.gserviceaccount.com` suffix.\n\nThe following `psql` command demonstrates one way to log in to an\nIAM user on the command line. It assigns the output of `gcloud\nauth print-access-token` to the `PGPASSWORD` environment variable, which `psql`\nsubsequently uses as a database login password. \n\n PGPASSWORD=$(gcloud auth print-access-token) psql \\\n -h \u003cvar translate=\"no\"\u003eINSTANCE_ADDRESS\u003c/var\u003e \\\n -U \u003cvar translate=\"no\"\u003eUSERNAME\u003c/var\u003e \\\n -d \u003cvar translate=\"no\"\u003eDATABASE\u003c/var\u003e\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eINSTANCE_ADDRESS\u003c/var\u003e: The IP address of the\n AlloyDB instance to connect to.\n\n- \u003cvar translate=\"no\"\u003eUSERNAME\u003c/var\u003e: An identifier for the IAM user\n to authenticate with the instance.\n\n For an IAM user account, supply the user account's full email\n address. For example, `kai@altostrat.com`.\n\n For an IAM service account, supply the service account's\n address *without* the `.gserviceaccount.com` suffix. For example, to specify\n the service account `my-service@my-project.iam.gserviceaccount.com`, you\n would use the value `my-service@my-project.iam` here.\n- \u003cvar translate=\"no\"\u003eDATABASE\u003c/var\u003e: The name of the database to connect to.\n\nNote that `psql` truncates passwords entered on the command line that are longer\nthan 100 characters. To use `psql` with an OAuth 2.0 token as a login password,\nyou must set the `PGPASSWORD` environment variable as demonstrated in this\nexample, rather than manually paste it when prompted.\n\nAuthenticate automatically\n--------------------------\n\nTo automatically authenticate an IAM-based AlloyDB\nuser without the need for an OAuth 2.0 token, you have two options:\n[AlloyDB Auth Proxy](/alloydb/docs/auth-proxy/connect) and\n[AlloyDB Language Connectors](/alloydb/docs/connect-language-connectors).\n\nThe IAM account that you use to run the\nproxy client or Language Connectors must be the same\naccount that you added as a database user. For example, if you run your workload\nusing the IAM user account `kai@altostrat.com`, then you can use\nthe proxy client or Language Connectors to\nautomatically authenticate the `kai@altostrat.com` database user without\nspecifying an OAuth 2.0 token. In this example, automatic authentication does\nnot work with any other database user except for `kai@altostrat.com`. \n\n### Auth Proxy\n\nUsing Auth Proxy requires running the AlloyDB Auth Proxy client with the\n`--auto-iam-authn` flag enabled.\n\nFor more information about running the Auth Proxy, see\n[Connect using the AlloyDB Auth Proxy](/alloydb/docs/auth-proxy/connect).\n\n### Language Connectors\n\nUsing Language Connectors requires enabling IAM\nauthentication programmatically. There is a corresponding option for each\nlanguage on\n[Configure the AlloyDB Language Connectors](/alloydb/docs/connect-language-connectors#configure-connectors).\n\nTroubleshoot IAM authentication\n-------------------------------\n\nTo determine the cause of a failed IAM-based authentication\nattempt, follow these steps:\n\n1. In the Google Cloud console, go to the Logs Explorer page:\n\n [Go to Logs Explorer](https://console.cloud.google.com/logs/query)\n2. Under **Resource type** , click **AlloyDB instance**.\n\n3. Under **Severity** , click **Alert**.\n\n If **Alert** is not an option, then there are no authentication failures logged within the\n selected time window. You may need to adjust the window using the\n Logs Explorer controls.\n4. Under **Query results**, check the log entries for one of the following messages:\n\n `Request had invalid authentication credentials.`\n : The access token is invalid.\n\n `Caller does not have required permission to use project.`\n : The IAM principal doesn't have [the necessary IAM roles](/alloydb/docs/manage-iam-authn#role) or permissions.\n The full error message specifies the missing roles or permissions.\n\n `IAM principal does not match database user.`\n\n : The authenticated IAM principal specified by the access token doesn't match the database user that you want to connect as.\n\n To view the principal specified by the token, run the following command: \n\n ```\n curl -H \"Content-Type: application/x-www-form-urlencoded\" -d \"access_token=ACCESS_TOKEN\" https://www.googleapis.com/oauth2/v1/tokeninfo\n ```\n\n Replace \u003cvar translate=\"no\"\u003eACCESS_TOKEN\u003c/var\u003e with the OAuth 2.0 access token.\n\n `Request had insufficient scopes.`\n : The access token does not contain either the `alloydb.login` scope or the `cloud-platform` scope. At least one of these scopes is required.\n\nWhat's next\n-----------\n\n- [Manage your IAM authentication](/alloydb/docs/database-users/manage-iam-auth)"]]
