This page explains the process of logging into an AlloyDB for PostgreSQL instance using
an account prepared with Identity and Access Management (IAM). It illustrates the process
by showing how to perform an IAM-based login using the psql
command-line client.
For an overview of connecting to AlloyDB instances, see Connection overview.
Before you begin
Your project, cluster, instances, and IAM user accounts all require preparation before you can log in to an AlloyDB instance using IAM credentials.
For more information, see Manage IAM authentication.
Authenticate with an OAuth 2.0 token
A user or an application can authenticate with an AlloyDB database by following these steps:
If you haven't already done so, authorize the Google Cloud CLI using the same user or service account that you want to log in to your AlloyDB instance with.
Request an OAuth 2.0 token from Google Cloud using the
gcloud auth print-access-token
command:gcloud auth print-access-token
The Google Cloud prints an OAuth 2.0 token as the output of this command.
For additional security, you can restrict the token for use with only AlloyDB authentication by following these alternative steps:
Add the
alloydb.login
scope to your current environment's access credentials using thegcloud auth application-default login
command, if you have not already done so: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
Print a restricted OAuth 2.0 token using the
gcloud auth application-default print-access-token
command, scoping the token only to AlloyDB authentication:gcloud auth application-default print-access-token –-scopes=https://www.googleapis.com/auth/alloydb.login
The OAuth 2.0 token lets you—or anyone—make authenticated requests to Google Cloud on your behalf. Treat the token with the same level of security as a password. Either store the token securely, or avoid storing it at all. The example use of
psql
later on this page demonstrates a way to request, use, and discard an OAuth 2.0 token in a single action.Log in to an AlloyDB instance with standard PostgreSQL techniques, using these credentials:
Present the access token you acquired in the previous step as your password.
For an IAM user account, the database username is the account's full email address.
For an IAM service account, the database username is the account's email address without the
.gserviceaccount.com
suffix.
The following psql
command demonstrates one way to log in to an
IAM user on the command line. It assigns the output of gcloud
auth print-access-token
to the PGPASSWORD
environment variable, which psql
subsequently uses as a database login password.
PGPASSWORD=$(gcloud auth print-access-token) psql \
-h INSTANCE_ADDRESS \
-U USERNAME \
-d DATABASE
Replace the following:
INSTANCE_ADDRESS
: The IP address of the AlloyDB instance to connect to.USERNAME
: An identifier for the IAM user to authenticate with the instance.For an IAM user account, supply the user account's full email address. For example,
kai@altostrat.com
.For an IAM service account, supply the service account's address without the
.gserviceaccount.com
suffix. For example, to specify the service accountmy-service@my-project.iam.gserviceaccount.com
, you would use the valuemy-service@my-project.iam
here.DATABASE
: The name of the database to connect to.
Note that psql
truncates passwords entered on the command line that are longer
than 100 characters. To use psql
with an OAuth 2.0 token as a login password,
you must set the PGPASSWORD
environment variable as demonstrated in this
example, rather than manually paste it when prompted.
Authenticate automatically using the AlloyDB Auth Proxy or AlloyDB Language Connectors
You can use the AlloyDB Auth Proxy or AlloyDB Language Connectors to automatically authenticate an IAM-based AlloyDB user, and connect to an instance without the need to provide an OAuth 2.0 token.
Using AlloyDB Auth Proxy requires running the AlloyDB Auth Proxy client with the
--auto-iam-authn
flag enabled, while AlloyDB Language Connectors require enabling
IAM authentication programmatically.
When using the Language Connectors, there is a corresponding option for each language. See Configure the AlloyDB Language Connectors for details.
The IAM account that you use to run the
proxy client or Language Connectors must be the same
account that you added as a database user. For example, if you run your workload
using the IAM user account kai@altostrat.com
, then you can use
the proxy client or Language Connectors to
automatically authenticate the kai@altostrat.com
database user without
specifying an OAuth 2.0 token. In this example, automatic authentication does
not work with any other database user except for kai@altostrat.com
.
For more information about running the Auth Proxy, see Connect using the AlloyDB Auth Proxy.
For more information about running the Language Connectors, see Connect using the AlloyDB Language Connectors.
Troubleshoot IAM authentication
To determine the cause of a failed IAM-based authentication attempt, follow these steps:
In the Google Cloud console, go to the Logs Explorer page:
Under Resource type, click AlloyDB instance.
Under Severity, click Alert.
If Alert is not an option, then there are no authentication failures logged within the selected time window. You may need to adjust the window using the Logs Explorer controls.
Under Query results, check the log entries for one of the following messages:
Request had invalid authentication credentials.
- The access token is invalid.
Caller does not have required permission to use project.
- The IAM principal doesn't have the necessary IAM roles or permissions. The full error message specifies the missing roles or permissions.
IAM principal does not match database user.
The authenticated IAM principal specified by the access token doesn't match the database user that you want to connect as.
To view the principal specified by the token, run the following command:
curl -H "Content-Type: application/x-www-form-urlencoded" -d "access_token=ACCESS_TOKEN" https://www.googleapis.com/oauth2/v1/tokeninfo
Replace
ACCESS_TOKEN
with the OAuth 2.0 access token.Request had insufficient scopes.
- The access token does not contain either the
alloydb.login
scope or thecloud-platform
scope. At least one of these scopes is required.