AlloyDB 인증 프록시는 로컬 환경에서 로컬 클라이언트를 실행하여 작동합니다. 애플리케이션은 데이터베이스에서 사용하는 표준 데이터베이스 프로토콜을 사용하여 AlloyDB 인증 프록시와 통신합니다.
AlloyDB 인증 프록시는 보안 터널 (TLS 1.3, 256비트 AES 암호화)을 사용하여 서버에서 실행 중인 컴패니언 프로세스와 통신합니다. AlloyDB 인증 프록시를 통해 설정된 각 연결은 AlloyDB 인스턴스에 대한 하나의 연결을 만듭니다.
애플리케이션에서 AlloyDB 인증 프록시에 연결할 때 애플리케이션과 대상 AlloyDB 인스턴스 간의 기존 연결을 사용할 수 있는지 여부를 확인합니다.
연결이 없으면 AlloyDB Admin API를 호출하여 임시 SSL 인증서를 가져오고 사용하여 AlloyDB에 연결합니다.
임시 SSL 인증서는 24시간 후에 만료됩니다. AlloyDB 인증 프록시는 이러한 인증서가 만료되기 전에 새로 고칩니다.
AlloyDB 인증 프록시는 HTTPS를 사용하여 도메인 이름 alloydb.googleapis.com를 통해 API를 호출합니다. 따라서 클라이언트 머신에서 포트 443 (HTTPS)으로 나가는 모든 TCP 연결이 방화벽에 의해 허용되어야 합니다.
AlloyDB 인증 프록시는 모든 포트에서 리슨할 수 있지만 포트 5433에서만 AlloyDB 인스턴스에 대한 발신 또는 이그레스 연결을 만듭니다. 클라이언트 호스트에 아웃바운드 방화벽이 있는 경우 AlloyDB 인스턴스의 IP 주소에서 포트 5433으로의 연결을 허용해야 합니다. 클라이언트 호스트는 모든 IP 주소에 대한 표준 HTTPS 포트인 포트 443에 대한 연결도 허용해야 합니다.
AlloyDB 인증 프록시가 IAM 주 구성원을 승인하는 방법
클라이언트의 AlloyDB 인스턴스 연결을 승인하기 위해 인증 프록시 클라이언트는 클라이언트에서 IAM 주 구성원 사용자 인증 정보를 사용하여 Google Cloud 에 인증한 다음 IAM 주 구성원에 Cloud AlloyDB 클라이언트 (roles/alloydb.client) 및 서비스 사용량 소비자(roles/serviceusage.serviceUsageConsumer) IAM 역할이 있는지 확인합니다.
클라이언트에서 IAM 사용자 인증 정보를 찾기 위해 인증 프록시 클라이언트는 다음 각 항목을 확인하고 첫 번째로 발견된 항목을 사용하여 Google Cloud에 대한 인증을 시도합니다.
--credentials-file 플래그로 제공된 사용자 인증 정보
서비스 계정을 사용하여 연결된 JSON 키 파일을 만들어 다운로드하고 인증 프록시 클라이언트를 시작할 때 --credentials-file 플래그를 해당 파일 경로로 설정합니다.
서비스 계정에는 AlloyDB 인스턴스의 Cloud AlloyDB 클라이언트(roles/alloydb.client) 및 서비스 사용량 소비자(roles/serviceusage.serviceUsageConsumer) IAM 역할이 있어야 합니다.
명령줄에서 이 옵션을 사용하려면 --credentials-file 플래그가 JSON 사용자 인증 정보 파일의 경로와 파일 이름으로 설정된 alloydb-auth-proxy 명령어를 호출합니다. 경로는 절대적이거나 현재 작업 디렉터리를 기준으로 할 수 있습니다.
--token 플래그로 제공된 사용자 인증 정보
액세스 토큰을 만들고--token 플래그와 함께 alloydb-auth-proxy 명령어를 호출하여 OAuth 2.0 액세스 토큰으로 설정합니다.
환경 변수로 제공된 사용자 인증 정보
이 옵션은 --credentials-file 플래그를 사용하는 대신 GOOGLE_APPLICATION_CREDENTIALS 환경 변수에 설정한 JSON 사용자 인증 정보 파일을 지정한다는 점을 제외하면 --credentials-file 플래그를 사용하는 것과 유사합니다.
인증된 Google Cloud CLI 클라이언트의 사용자 인증 정보
gcloud CLI를 설치하고 개인 계정으로 인증한 경우 --gcloud-auth 플래그를 사용 설정하면 인증 프록시 클라이언트에서 동일한 계정 사용자 인증 정보를 사용할 수 있습니다. 이 방법은 특히 개발 환경을 준비하고 실행하는 데 유용합니다.
gcloud auth login에 선택된 계정이 없으면 인증 프록시 클라이언트는 gcloud
auth application-default login에 선택된 계정을 확인합니다. --gcloud-auth 플래그를 사용 설정하지 않으면 기본 동작입니다.
Compute Engine 인스턴스 관련 사용자 인증 정보
Compute Engine 인스턴스에서 AlloyDB에 연결하는 경우 인증 프록시 클라이언트는 Compute Engine 인스턴스와 연결된 서비스 계정을 사용할 수 있습니다.
서비스 계정에 AlloyDB 인스턴스의 Cloud AlloyDB 클라이언트(roles/alloydb.client) 및 서비스 사용량 소비자(roles/serviceusage.serviceUsageConsumer) ID 및 액세스 관리 (IAM) 역할이 있는 경우 인증 프록시 클라이언트가 인증에 성공합니다.
Compute Engine 인스턴스가 AlloyDB 인스턴스와 동일한 프로젝트에 있는 경우 Compute Engine 인스턴스의 기본 서비스 계정에는 AlloyDB를 인증하는 데 필요한 권한이 있습니다.
두 인스턴스가 서로 다른 프로젝트에 있는 경우 Compute Engine 인스턴스의 서비스 계정을 AlloyDB 인스턴스가 포함된 프로젝트에 추가해야 합니다.
환경의 기본 서비스 계정
인증 프록시 클라이언트가 앞에서 설명한 위치에서 사용자 인증 정보를 찾을 수 없는 경우 서비스 계정으로 인증에 설명된 로직을 따릅니다.
일부 환경(예: Compute Engine, App Engine 등)은 애플리케이션이 기본적으로 인증하는 데 사용할 수 있는 기본 서비스 계정을 제공합니다. 기본 서비스 계정을 사용하는 경우 Cloud AlloyDB 클라이언트(roles/alloydb.client) 및 서비스 사용량 소비자(roles/serviceusage.serviceUsageConsumer) IAM 역할이 있어야 합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-05(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)."]]
