Menghubungkan menggunakan akun IAM

Halaman ini menjelaskan proses login ke instance AlloyDB untuk PostgreSQL menggunakan akun yang disiapkan dengan Identity and Access Management (IAM). Halaman ini mengilustrasikan proses dengan menunjukkan cara melakukan login berbasis IAM menggunakan klien command line psql.

Untuk mengetahui ringkasan tentang 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.

Perhatian: Ada kuota login per menit untuk setiap instance, yang mencakup login yang berhasil dan gagal. Jika kuota terlampaui, login akan tidak tersedia untuk sementara. Sebaiknya hindari login yang terlalu sering dan batasi login menggunakan jaringan yang diizinkan.

Untuk mengetahui informasi selengkapnya, lihat Mengelola autentikasi IAM.

Melakukan autentikasi dengan token OAuth 2.0

Pengguna atau aplikasi dapat melakukan autentikasi dengan database AlloyDB dengan mengikuti langkah-langkah berikut:

1. Jika belum melakukannya, lakukan autentikasi untuk gcloud CLI menggunakan pengguna atau akun layanan yang sama dengan yang ingin Anda gunakan untuk login ke instance AlloyDB.

2. Minta token OAuth 2.0 dari Google Cloud menggunakan perintah gcloud auth print-access-token:

   gcloud auth print-access-token

   Google Cloud Mencetak token OAuth 2.0 sebagai output dari perintah ini.

   Untuk keamanan tambahan, Anda dapat membatasi token untuk digunakan hanya dengan autentikasi AlloyDB dengan mengikuti langkah-langkah alternatif berikut:

   1. Tambahkan cakupan alloydb.login ke kredensial akses lingkungan saat ini menggunakan perintah gcloud auth application-default login command, jika Anda belum melakukannya:

      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. Cetak token OAuth 2.0 yang dibatasi menggunakan perintah gcloud auth application-default print-access-token, yang mencakup token hanya untuk autentikasi AlloyDB:

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

   Perhatian: Perlakukan token OAuth 2.0 sebagai informasi sensitif. Simpan token dengan aman, atau jangan simpan sama sekali setelah digunakan.

   Token OAuth 2.0 memungkinkan Anda—atau siapa pun—membuat permintaan yang diautentikasi ke Google Cloud atas nama Anda. Perlakukan token dengan tingkat keamanan yang sama seperti sandi. Simpan token dengan aman, atau hindari menyimpannya sama sekali. Contoh penggunaan psql di halaman ini menunjukkan cara meminta, menggunakan, dan menghapus token OAuth 2.0 dalam satu tindakan.

3. 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 ..

Perintah psql berikut menunjukkan salah satu cara untuk login ke pengguna IAM di command line. Perintah ini menetapkan output gcloud auth print-access-token ke variabel lingkungan PGPASSWORD, yang psql kemudian digunakan sebagai sandi login database.

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

Ganti kode berikut:

• INSTANCE_ADDRESS: Alamat IP instance AlloyDB yang akan terhubung.

• USERNAME: ID untuk pengguna IAM yang akan diautentikasi dengan instance.

  Untuk akun pengguna IAM, berikan alamat email lengkap akun pengguna. Misalnya, [e-mail].

  Untuk akun layanan IAM, berikan alamat akun layanan tanpa akhiran .. Misalnya, untuk menentukan akun layanan my-service@my-project., Anda akan menggunakan nilai [e-mail] di sini.

• DATABASE: Nama database yang akan terhubung.

Perhatikan bahwa psql memangkas sandi yang dimasukkan di command line yang lebih panjang 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 Konektor Bahasa harus merupakan akun yang sama dengan yang Anda tambahkan sebagai pengguna database. Misalnya, jika Anda menjalankan workload menggunakan akun pengguna IAM [e-mail], Anda dapat menggunakan klien proxy atau Konektor Bahasa untuk mengautentikasi pengguna database [e-mail] secara otomatis tanpa menentukan token OAuth 2.0. Dalam contoh ini, autentikasi otomatis tidak berfungsi dengan pengguna database lain kecuali [e-mail].

Proxy Auth

Penggunaan Proxy Auth mengharuskan Anda menjalankan klien Proxy Auth AlloyDB dengan flag --auto-iam-authn diaktifkan.

Untuk mengetahui informasi selengkapnya tentang cara menjalankan Proxy Auth, lihat Menghubungkan menggunakan Proxy Auth AlloyDB.

Konektor Bahasa

Penggunaan Konektor Bahasa mengharuskan Anda mengaktifkan autentikasi IAM secara terprogram. Ada opsi yang sesuai untuk setiap bahasa di Mengonfigurasi Konektor Bahasa AlloyDB.

Memecahkan masalah autentikasi IAM

Untuk menentukan penyebab upaya autentikasi berbasis IAM yang gagal, ikuti langkah-langkah berikut:

1. Di Google Cloud konsol, buka halaman Logs Explorer:

   Buka Logs Explorer

2. Di bagian Jenis resource, klik Instance AlloyDB.

3. Di bagian Severity, klik Alert.

   Jika Alert bukan opsi, berarti tidak ada kegagalan autentikasi yang dicatat dalam log dalam jangka waktu yang dipilih. Anda mungkin perlu menyesuaikan jangka waktu menggunakan kontrol Logs Explorer.

4. Di bagian Hasil kueri, periksa entri log untuk salah satu pesan berikut:

   Request had invalid authentication credentials.

   Token akses tidak valid.

   Caller does not have required permission to use project.

   Principal IAM tidak memiliki peran IAM yang diperlukan atau izin. Pesan error lengkap menentukan peran atau izin yang tidak ada.

   IAM principal does not match database user.

   Principal IAM yang diautentikasi yang ditentukan oleh token akses tidak cocok dengan pengguna database yang ingin Anda hubungkan.

   Untuk melihat principal yang ditentukan oleh token, jalankan perintah berikut:

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

   Ganti ACCESS_TOKEN dengan token akses OAuth 2.0.

   Request had insufficient scopes.

   Token akses tidak berisi cakupan alloydb.login atau cakupan cloud-platform. Setidaknya salah satu cakupan ini diperlukan.

Langkah berikutnya

• Mengelola autentikasi IAM