Tetap teratur dengan koleksi
Simpan dan kategorikan konten berdasarkan preferensi Anda.
Halaman ini menjelaskan proses login ke instance AlloyDB for PostgreSQL menggunakan
akun yang disiapkan dengan Identity and Access Management (IAM). Bagian ini menggambarkan proses
dengan menunjukkan cara melakukan login berbasis IAM menggunakan klien command line psql.
Untuk mengetahui ringkasan cara menghubungkan ke instance AlloyDB, lihat
Ringkasan koneksi.
Sebelum memulai
Project, cluster, instance, dan akun pengguna IAM Anda memerlukan persiapan sebelum Anda dapat login ke instance AlloyDB menggunakan kredensial IAM.
Pengguna atau aplikasi dapat melakukan autentikasi dengan database AlloyDB
dengan mengikuti langkah-langkah berikut:
Jika belum melakukannya, beri otorisasi
Google Cloud CLI menggunakan
akun pengguna atau akun layanan yang sama dengan yang ingin Anda gunakan untuk login ke instance AlloyDB.
Google Cloud mencetak token OAuth 2.0 sebagai output perintah
ini.
Untuk keamanan tambahan, Anda dapat membatasi token agar hanya digunakan dengan
autentikasi AlloyDB dengan mengikuti langkah-langkah alternatif berikut:
Token OAuth 2.0 memungkinkan Anda—atau siapa pun—membuat permintaan terautentikasi ke
Google Cloud atas nama Anda. Perlakukan token dengan tingkat
keamanan yang sama seperti sandi. Simpan token dengan aman, atau hindari
penyimpanannya sama sekali. Contoh penggunaan psql di halaman ini
menunjukkan cara meminta, menggunakan, dan menghapus token OAuth 2.0 dalam
satu tindakan.
Login ke instance AlloyDB dengan teknik PostgreSQL
standar, menggunakan kredensial berikut:
Berikan token akses yang Anda peroleh pada langkah sebelumnya sebagai
sandi Anda.
Untuk akun pengguna IAM, nama pengguna database adalah
alamat email lengkap akun.
Untuk akun layanan IAM, nama pengguna database adalah
alamat email akun tanpa akhiran .gserviceaccount.com.
Perintah psql berikut menunjukkan salah satu cara untuk login ke pengguna IAM di command line. Tindakan ini menetapkan output gcloud
auth print-access-token ke variabel lingkungan PGPASSWORD, yang selanjutnya digunakan psql
sebagai sandi login database.
INSTANCE_ADDRESS: Alamat IP instance AlloyDB yang akan dihubungkan.
USERNAME: ID untuk pengguna IAM
yang akan diautentikasi dengan instance.
Untuk akun pengguna IAM, berikan alamat email lengkap akun pengguna. Misalnya, kai@altostrat.com.
Untuk akun layanan IAM, berikan alamat
akun layanan tanpa akhiran .gserviceaccount.com. Misalnya, untuk menentukan
akun layanan my-service@my-project.iam.gserviceaccount.com, Anda
akan menggunakan nilai my-service@my-project.iam di sini.
DATABASE: Nama database yang akan dihubungkan.
Perhatikan bahwa psql akan memangkas sandi yang dimasukkan di command line yang panjangnya lebih dari 100 karakter. Untuk menggunakan psql dengan token OAuth 2.0 sebagai sandi login,
Anda harus menetapkan variabel lingkungan PGPASSWORD seperti yang ditunjukkan dalam
contoh ini, bukan menempelkannya secara manual saat diminta.
Melakukan autentikasi secara otomatis
Untuk mengautentikasi pengguna AlloyDB berbasis IAM secara otomatis tanpa memerlukan token OAuth 2.0, Anda memiliki dua opsi:
Proxy Auth AlloyDB dan
Konektor Bahasa AlloyDB.
Akun IAM yang Anda gunakan untuk menjalankan
klien proxy atau Language Connector harus sama dengan
akun yang Anda tambahkan sebagai pengguna database. Misalnya, jika Anda menjalankan workload
menggunakan akun pengguna IAM kai@altostrat.com, Anda dapat menggunakan
klien proxy atau Language Connector untuk
mengautentikasi pengguna database kai@altostrat.com secara otomatis tanpa
menentukan token OAuth 2.0. Dalam contoh ini, autentikasi otomatis tidak berfungsi dengan pengguna database lain kecuali kai@altostrat.com.
Proxy Auth
Penggunaan Proxy Auth memerlukan eksekusi klien Proxy Auth AlloyDB dengan mengaktifkan flag --auto-iam-authn.
Penggunaan Language Connector memerlukan pengaktifan autentikasi IAM secara terprogram. Ada opsi yang sesuai untuk setiap bahasa di Mengonfigurasi Konektor Bahasa AlloyDB.
Memecahkan masalah autentikasi IAM
Untuk mengetahui penyebab kegagalan upaya autentikasi berbasis IAM, ikuti langkah-langkah berikut:
Di konsol Google Cloud , buka halaman Logs Explorer:
Jika Peringatan tidak tersedia, berarti tidak ada kegagalan autentikasi yang dicatat dalam jangka waktu yang dipilih. Anda mungkin perlu menyesuaikan jendela menggunakan
kontrol Logs Explorer.
Di bagian Query results, periksa entri log untuk menemukan salah satu pesan berikut:
Request had invalid authentication credentials.
Token akses tidak valid.
Caller does not have required permission to use project.
[[["Mudah dipahami","easyToUnderstand","thumb-up"],["Memecahkan masalah saya","solvedMyProblem","thumb-up"],["Lainnya","otherUp","thumb-up"]],[["Sulit dipahami","hardToUnderstand","thumb-down"],["Informasi atau kode contoh salah","incorrectInformationOrSampleCode","thumb-down"],["Informasi/contoh yang saya butuhkan tidak ada","missingTheInformationSamplesINeed","thumb-down"],["Masalah terjemahan","translationIssue","thumb-down"],["Lainnya","otherDown","thumb-down"]],["Terakhir diperbarui pada 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)"]]
