이 페이지에서는 Identity and Access Management (IAM)로 준비된 계정을 사용하여 PostgreSQL용 AlloyDB 인스턴스에 로그인하는 프로세스를 설명합니다. psql 명령줄 클라이언트를 사용하여 IAM 기반 로그인을 실행하는 방법을 보여주면서 프로세스를 설명합니다.
OAuth 2.0 토큰을 사용하면 본인 또는 다른 사람이 본인을 대신하여 Google Cloud 에 인증된 요청을 할 수 있습니다. 토큰을 비밀번호와 동일한 수준의 보안으로 취급합니다. 토큰을 안전하게 저장하거나 아예 저장하지 마세요. 이 페이지의 뒷부분에 나오는 psql의 사용 예에서는 단일 작업으로 OAuth 2.0 토큰을 요청하고 사용하고 삭제하는 방법을 보여줍니다.
다음 사용자 인증 정보를 사용하여 표준 PostgreSQL 기법으로 AlloyDB 인스턴스에 로그인합니다.
이전 단계에서 획득한 액세스 토큰을 비밀번호로 제시합니다.
IAM 사용자 계정의 경우 데이터베이스 사용자 이름은 계정의 전체 이메일 주소입니다.
IAM 서비스 계정의 경우 데이터베이스 사용자 이름은 .gserviceaccount.com 서픽스가 없는 계정의 이메일 주소입니다.
다음 psql 명령어는 명령줄에서 IAM 사용자로 로그인하는 한 가지 방법을 보여줍니다. gcloud
auth print-access-token의 출력을 PGPASSWORD 환경 변수에 할당합니다. PGPASSWORD 환경 변수는 psql에서 데이터베이스 로그인 비밀번호로 사용됩니다.
IAM 사용자 계정의 경우 사용자 계정의 전체 이메일 주소를 제공합니다. 예를 들면 kai@altostrat.com입니다.
IAM 서비스 계정의 경우 .gserviceaccount.com 서픽스를 제외한 서비스 계정의 주소를 제공합니다. 예를 들어 서비스 계정 my-service@my-project.iam.gserviceaccount.com을 지정하려면 여기에 my-service@my-project.iam 값을 사용합니다.
DATABASE: 연결할 데이터베이스의 이름입니다.
psql는 명령줄에 입력된 비밀번호가 100자를 초과하는 경우 이를 자릅니다. OAuth 2.0 토큰을 로그인 비밀번호로 사용하여 psql를 사용하려면 메시지가 표시될 때 수동으로 붙여넣는 대신 이 예에 표시된 대로 PGPASSWORD 환경 변수를 설정해야 합니다.
프록시 클라이언트 또는 Language Connector를 실행하는 데 사용하는 IAM 계정은 데이터베이스 사용자로 추가한 계정과 동일해야 합니다. 예를 들어 IAM 사용자 계정 kai@altostrat.com를 사용하여 워크로드를 실행하는 경우 프록시 클라이언트 또는 언어 커넥터를 사용하여 OAuth 2.0 토큰을 지정하지 않고 kai@altostrat.com 데이터베이스 사용자를 자동으로 인증할 수 있습니다. 이 예에서는 kai@altostrat.com를 제외한 다른 데이터베이스 사용자와는 자동 인증이 작동하지 않습니다.
인증 프록시
인증 프록시를 사용하려면 --auto-iam-authn 플래그가 사용 설정된 AlloyDB 인증 프록시 클라이언트를 실행해야 합니다.
[[["이해하기 쉬움","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-04(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)"]]
