Proxy Auth memberikan keuntungan berikut dibandingkan dengan menghubungkan klien langsung ke database AlloyDB:
Otorisasi koneksi berbasis IAM (AuthZ): Proxy Auth menggunakan
kredensial dan izin akun utama Identity and Access Management (IAM) untuk memberi otorisasi koneksi ke
instance AlloyDB.
Komunikasi terenkripsi yang aman: Proxy Auth secara otomatis
membuat, menggunakan, dan mempertahankan koneksi TLS 1.3
menggunakan cipher AES 256-bit
antara klien Anda dan instance AlloyDB untuk memverifikasi identitas klien
dan server serta mengenkripsi traffic data.
Untuk mengetahui informasi selengkapnya tentang cara menghubungkan ke instance AlloyDB, lihat Ringkasan koneksi.
Cara kerja Proxy Auth AlloyDB
Proxy Auth AlloyDB bekerja dengan menjalankan klien lokal
di lingkungan lokal. Aplikasi Anda berkomunikasi dengan Proxy Auth AlloyDB
menggunakan protokol database standar yang digunakan oleh database Anda.
Proxy Auth AlloyDB menggunakan tunnel yang aman (TLS 1.3,
cipher AES 256-bit) untuk
berkomunikasi dengan proses pendampingnya
yang berjalan di server. Setiap koneksi yang dibuat melalui Proxy Auth AlloyDB membuat
satu koneksi ke instance AlloyDB.
Saat terhubung ke Proxy Auth AlloyDB, aplikasi akan memeriksa apakah koneksi
antara aplikasi tersebut dan instance AlloyDB target telah tersedia.
Jika tidak tersedia, maka koneksi akan memanggil AlloyDB Admin API untuk mendapatkan
sertifikat SSL sementara dan menggunakannya untuk terhubung ke AlloyDB.
Masa berlaku sertifikat SSL sementara akan habis dalam waktu 24 jam. Proxy Auth AlloyDB memperbarui
sertifikat-sertifikat tersebut sebelum masa berlakunya habis.
Proxy Auth AlloyDB memanggil API melalui nama domain alloydb.googleapis.com menggunakan HTTPS. Akibatnya, semua koneksi TCP keluar pada port 443 (HTTPS) dari
mesin klien harus diizinkan oleh firewall Anda.
Meskipun dapat memproses port apa pun, Proxy Auth AlloyDB membuat koneksi keluar
ke instance AlloyDB Anda hanya pada port 5433. Jika host klien Anda memiliki firewall keluar, firewall tersebut harus mengizinkan koneksi ke port 5433 di alamat IP instance AlloyDB Anda. Host klien juga harus mengizinkan koneksi ke port 443, yang merupakan port HTTPS standar, ke semua alamat IP.
Cara Proxy Auth AlloyDB mengizinkan principal IAM
Untuk mengizinkan koneksi klien ke instance AlloyDB, klien Proxy Auth melakukan autentikasi ke Google Cloud menggunakan kredensial akun utama IAM di klien, lalu memvalidasi bahwa akun utama IAM memiliki peran IAM Klien Cloud AlloyDB (roles/alloydb.client) dan Konsumen Penggunaan Layanan (roles/serviceusage.serviceUsageConsumer).
Untuk menemukan kredensial IAM di klien, klien Proxy Auth memeriksa
setiap item berikut, menggunakan item pertama yang
ditemukan untuk mencoba autentikasi ke Google Cloud:
Kredensial yang disediakan oleh flag --credentials-file
Gunakan akun layanan untuk
membuat dan mendownload file kunci JSON terkait, lalu tetapkan
flag --credentials-file ke jalur file saat Anda memulai
klien Proxy Auth.
Akun layanan harus memiliki peran IAM Cloud AlloyDB Client
(roles/alloydb.client) dan Service Usage Consumer
(roles/serviceusage.serviceUsageConsumer)
untuk instance AlloyDB.
Untuk menggunakan opsi ini pada command line, panggil perintah alloydb-auth-proxy dengan
flag --credentials-file yang ditetapkan ke nama file dan jalur file kredensial
JSON. Jalur tersebut dapat bersifat absolut atau relatif sesuai direktori kerja saat ini.
Kredensial yang disediakan oleh tanda --token
Buat
token akses dan panggil perintah alloydb-auth-proxy dengan flag
--token yang ditetapkan ke token akses OAuth 2.0.
Kredensial yang disediakan oleh variabel lingkungan
Opsi ini mirip dengan menggunakan flag --credentials-file, kecuali Anda menentukan
file kredensial JSON yang ditetapkan dalam GOOGLE_APPLICATION_CREDENTIALS variabel
lingkungan, bukan menggunakan flag --credentials-file.
Kredensial dari klien Google Cloud CLI yang diautentikasi
Jika Anda telah menginstal gcloud CLI
dan melakukan autentikasi dengan akun pribadi, klien Proxy Auth
dapat menggunakan kredensial akun yang sama jika Anda mengaktifkan
flag --gcloud-auth. Metode ini sangat membantu untuk
mendapatkan lingkungan pengembangan dan menjalankannya.
Jika tidak ada akun yang dipilih untuk gcloud auth login, klien
Proxy Auth akan memeriksa akun yang dipilih untuk gcloud
auth application-default login. Ini adalah perilaku default jika Anda
tidak mengaktifkan tanda --gcloud-auth.
Kredensial yang terkait dengan instance Compute Engine
Jika Anda terhubung ke AlloyDB dari instance Compute Engine, klien
Proxy Auth dapat menggunakan akun layanan yang terkait dengan instance Compute Engine.
Jika akun layanan memiliki peran Identity and Access Management (IAM) Cloud AlloyDB Client (roles/alloydb.client) dan Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) untuk instance AlloyDB, klien Auth Proxy akan berhasil diautentikasi.
Jika instance Compute Engine berada dalam project yang sama dengan instance
AlloyDB, akun layanan default untuk instance Compute Engine memiliki
izin yang diperlukan untuk mengautentikasi AlloyDB.
Jika kedua instance berada di project yang berbeda, Anda harus menambahkan akun layanan instance Compute Engine ke project yang berisi instance AlloyDB.
Akun layanan default lingkungan
Jika klien Auth Proxy tidak dapat menemukan kredensial di tempat mana pun yang telah dibahas sebelumnya, klien tersebut
mengikuti logika yang didokumentasikan dalam
Mengautentikasi sebagai akun layanan.
Beberapa lingkungan (seperti Compute Engine, App Engine, dan lainnya) menyediakan
akun layanan default yang dapat digunakan oleh aplikasi untuk melakukan autentikasi secara default. Jika
Anda menggunakan akun layanan default, akun tersebut harus memiliki peran IAM Cloud AlloyDB Client
(roles/alloydb.client) dan Service Usage Consumer
(roles/serviceusage.serviceUsageConsumer).
Untuk mengetahui informasi selengkapnya tentang pendekatan Google Cloud terhadap autentikasi, lihat
Ringkasan autentikasi.
[[["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\u003eThe AlloyDB Auth Proxy enables secure, encrypted connections to AlloyDB databases using IAM-based authorization.\u003c/p\u003e\n"],["\u003cp\u003eIt provides advantages over direct connections by using IAM credentials for authorization and establishing TLS 1.3 encrypted connections with a 256-bit AES cipher.\u003c/p\u003e\n"],["\u003cp\u003eThe Auth Proxy runs a local client that communicates with the application using standard database protocols and establishes connections to AlloyDB via secure tunnels.\u003c/p\u003e\n"],["\u003cp\u003eThe Auth Proxy automatically manages and refreshes ephemeral SSL certificates, which expire every 24 hours.\u003c/p\u003e\n"],["\u003cp\u003eThe AlloyDB Auth Proxy supports various methods for locating IAM credentials, including service account JSON key files, OAuth 2.0 access tokens, environment variables, gcloud CLI credentials, and Compute Engine instance credentials.\u003c/p\u003e\n"]]],[],null,["# About the AlloyDB Auth Proxy\n\nThis page provides an overview of the AlloyDB Auth Proxy, a connector that lets you\nmake authorized, encrypted connections to AlloyDB\ndatabases.\n\nFor a step-by-step guide to using the Auth Proxy, see [Connect using the AlloyDB Auth Proxy](/alloydb/docs/auth-proxy/connect).\n\nBenefits of using the AlloyDB Auth Proxy\n----------------------------------------\n\nThe Auth Proxy provides these advantages over connecting clients directly to\nAlloyDB databases:\n\n- **IAM-based connection authorization (AuthZ):** The Auth Proxy uses\n the credentials and permissions of an Identity and Access Management (IAM) principal to authorize connections to\n AlloyDB instances.\n\n- **Secure, encrypted communication:** The Auth Proxy automatically\n creates, uses, and maintains a TLS 1.3 connection\n using a 256-bit AES cipher\n between your client and an AlloyDB instance to verify client\n and server identities and encrypt data traffic.\n\nFor more information about to connecting to AlloyDB instances,\nsee [Connection overview](/alloydb/docs/connection-overview).\n\nHow the AlloyDB Auth Proxy works\n--------------------------------\n\nThe AlloyDB Auth Proxy works by having a local client running\nin the local environment. Your application communicates with the AlloyDB Auth Proxy\nwith the standard database protocol used by your database.\n\nThe AlloyDB Auth Proxy uses a secure tunnel (TLS 1.3,\n256-bit AES cipher) to\ncommunicate with its companion process\nrunning on the server. Each connection established through the AlloyDB Auth Proxy creates\none connection to the AlloyDB instance.\n\nWhen an application connects to the AlloyDB Auth Proxy, it checks whether an existing\nconnection between it and the target AlloyDB instance is available.\nIf a connection does not exist, it calls AlloyDB Admin APIs to obtain\nan ephemeral SSL certificate and uses it to connect to AlloyDB.\nEphemeral SSL certificates expire in 24 hours. The AlloyDB Auth Proxy refreshes\nthese certificates before they expire.\n\nThe AlloyDB Auth Proxy calls APIs through the domain name `alloydb.googleapis.com`\nusing HTTPS. As a result, all egress TCP connections on port 443 (HTTPS) from\nthe client machine must be allowed by your firewall.\n\nWhile the AlloyDB Auth Proxy can listen on any port, it creates outgoing or egress\nconnections to your AlloyDB instance only on port 5433. If your client\nhost has an outbound firewall, it must allow connections to port 5433 on your\nAlloyDB instance's IP address. The client host must also allow\nconnections to port 443, which is the standard HTTPS port, to all IP addresses.\n\nHow the AlloyDB Auth Proxy authorizes IAM principals\n----------------------------------------------------\n\nTo authorize a client's connection to an AlloyDB instance, the\nAuth Proxy client authenticates to Google Cloud using IAM principal\ncredentials on the client, and then validates that the IAM principal has the\nCloud AlloyDB Client (`roles/alloydb.client`) and Service Usage Consumer\n(`roles/serviceusage.serviceUsageConsumer`) IAM roles.\n\nTo locate the IAM credentials on the client, the Auth Proxy client checks\nfor each of the following items, using the first one it\nfinds to attempt authentication to Google Cloud:\n\n1. **Credentials supplied by the --credentials-file flag**\n\n Use a [service account](/alloydb/docs/auth-proxy/best-practices#using-a-service-account) to\n create and download the associated JSON key file, and set the\n `--credentials-file` flag to the path of the file when you start\n the Auth Proxy client.\n The service account must have the Cloud AlloyDB Client\n (`roles/alloydb.client`) and Service Usage Consumer\n (`roles/serviceusage.serviceUsageConsumer`)\n IAM roles for the AlloyDB instance.\n\n To use this option on the command-line, invoke the `alloydb-auth-proxy` command with\n the `--credentials-file` flag set to the path and filename of a JSON credential\n file. The path can be absolute, or relative to the current working directory.\n2. **Credentials supplied by the --token flag**\n\n [Create an\n access token](https://developers.google.com/oauthplayground/) and invoke the `alloydb-auth-proxy` command with the\n `--token` flag set to an OAuth 2.0 access token.\n3. **Credentials supplied by an environment variable**\n\n This option is similar to using the `--credentials-file` flag, except you specify\n the JSON credential file you set in the `GOOGLE_APPLICATION_CREDENTIALS` environment\n variable instead of using the `--credentials-file` flag.\n4. **Credentials from an authenticated Google Cloud CLI client**\n\n If you installed the [gcloud CLI](/sdk/gcloud)\n and have authenticated with your personal account, the Auth Proxy client\n can use the same account credentials if you enable the\n `--gcloud-auth` flag. This method is especially helpful for\n getting a development environment up and running.\n | To enable the Auth Proxy client to use your gcloud CLI credentials, use the `gcloud auth login` command to authenticate the gcloud CLI. To determine your current gcloud CLI credentials, use the `gcloud auth list` command.\n\n If no account was selected for `gcloud auth login`, the\n Auth Proxy client checks for an account that was selected for `gcloud\n auth application-default login`. This is the default behavior when you\n don't enable the `--gcloud-auth` flag.\n5. **Credentials associated with the Compute Engine instance**\n\n If you are connecting to AlloyDB from a Compute Engine instance, the\n Auth Proxy client can use the service account associated with the Compute Engine instance.\n If the service account has the Cloud AlloyDB Client\n (`roles/alloydb.client`) and Service Usage Consumer\n (`roles/serviceusage.serviceUsageConsumer`)\n Identity and Access Management (IAM) roles for the AlloyDB instance, the Auth Proxy client\n authenticates successfully.\n\n If the Compute Engine instance is in the same project as the AlloyDB\n instance, the default service account for the Compute Engine instance has the\n necessary permissions for authenticating the AlloyDB.\n If the two instances are in different projects, you must add the Compute Engine\n instance's service account to the project containing the AlloyDB\n instance.\n6. **Environment's default service account**\n\n If the Auth Proxy client cannot find credentials in any of the places covered earlier, it\n follows the logic documented in\n [Authenticating as a service account](/docs/authentication/production).\n Some environment (such as Compute Engine, App Engine, and others) provide a\n default service account that your application can use to authenticate by default. If\n you use a default service account, it must have the Cloud AlloyDB Client\n (`roles/alloydb.client`) and Service Usage Consumer\n (`roles/serviceusage.serviceUsageConsumer`) IAM roles.\n\n For more information about Google Cloud's approach to authentication, see\n [Authentication overview](/docs/authentication).\n\nWhat's next\n-----------\n\n- [Connect using the AlloyDB Auth Proxy](/alloydb/docs/auth-proxy/connect).\n- [Explore the Google Cloud GitHub repository for the AlloyDB Auth Proxy](https://github.com/GoogleCloudPlatform/alloydb-auth-proxy)."]]
