Conéctate con una cuenta de IAM

En esta página, se explica el proceso para acceder a una instancia de AlloyDB para PostgreSQL con una cuenta preparada con Identity and Access Management (IAM). Se ilustra el proceso mostrando cómo realizar un acceso basado en IAM con el cliente de línea de comandos psql.

Para obtener una descripción general de la conexión a instancias de AlloyDB, consulta Descripción general de la conexión.

Antes de comenzar

Tu proyecto, clúster, instancias y cuentas de usuario de IAM requieren preparación antes de que puedas acceder a una instancia de AlloyDB con credenciales de IAM.

**Precaución:** Hay una cuota de acceso por minuto para cada instancia, que incluye accesos exitosos y no exitosos. Cuando se supera la cuota, los accesos no están disponibles por el momento. Recomendamos que evites accesos frecuentes y que restrinjas los accesos a través de las redes autorizadas.

Para obtener más información, consulta Administra la autenticación de IAM.

Autentica con un token de OAuth 2.0

Un usuario o una aplicación pueden autenticarse con una base de datos de AlloyDB siguiendo estos pasos:

1. Si aún no lo hiciste, autentícate en la gcloud CLI con el mismo usuario o cuenta de servicio con el que deseas acceder a tu instancia de AlloyDB.

2. Solicita un token de OAuth 2.0 a partir de Google Cloud con el gcloud auth print-access-token comando:

   gcloud auth print-access-token

   El Google Cloud imprime un token de OAuth 2.0 como resultado de este comando.

   Para mayor seguridad, puedes restringir el token para que se use solo con la autenticación de AlloyDB siguiendo estos pasos alternativos:

   1. Agrega el alloydb.login permiso a las credenciales de acceso de tu entorno actual con el gcloud auth application-default login comando, si aún no lo hiciste:

      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. Imprime un token de OAuth 2.0 restringido con el gcloud auth application-default print-access-token comando, que limita el token solo a la autenticación de AlloyDB:

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

   Precaución: Trata tu token de OAuth 2.0 como información sensible. Almacénalo de forma segura o no lo almacenes después de usarlo.

   El token de OAuth 2.0 te permite a ti, o a cualquier persona, realizar solicitudes autenticadas a Google Cloud en tu nombre. Trata el token con el mismo nivel de seguridad que una contraseña. Almacena el token de forma segura o evita almacenarlo. El ejemplo de uso de psql más adelante en esta página demuestra una forma de solicitar, usar y descartar un token de OAuth 2.0 en una sola acción.

3. Accede a una instancia de AlloyDB con técnicas estándar de PostgreSQL, usando estas credenciales:

   • Presenta el token de acceso que adquiriste en el paso anterior como tu contraseña.

   • Para una cuenta de usuario de IAM, el nombre de usuario de la base de datos es la dirección de correo electrónico completa de la cuenta.

   • Para una cuenta de servicio de IAM, el nombre de usuario de la base de datos es la dirección de correo electrónico de la cuenta sin el sufijo .gserviceaccount.com.

El siguiente comando psql muestra una forma de acceder a un usuario de IAM en la línea de comandos. Asigna el resultado de gcloud auth print-access-token a la variable de entorno PGPASSWORD, que psql usa posteriormente como contraseña de acceso a la base de datos.

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

Reemplaza lo siguiente:

• INSTANCE_ADDRESS: La dirección IP de la instancia de AlloyDB a la que te conectarás.

• USERNAME: Un identificador para el usuario de IAM con el que se autenticará la instancia.

  Para una cuenta de usuario de IAM, proporciona la dirección de correo electrónico completa de la cuenta de usuario. Por ejemplo, [e-mail].

  Para una cuenta de servicio de IAM, proporciona la dirección de la cuenta de servicio sin el sufijo .gserviceaccount.com. Por ejemplo, para especificar la cuenta de servicio [e-mail], usarías el valor [e-mail] aquí.

• DATABASE: El nombre de la base de datos a la que te conectarás.

Ten en cuenta que psql trunca las contraseñas ingresadas en la línea de comandos que tienen más de 100 caracteres. Para usar psql con un token de OAuth 2.0 como contraseña de acceso, debes configurar la variable de entorno PGPASSWORD como se muestra en este ejemplo, en lugar de pegarla de forma manual cuando se te solicite.

Autentica automáticamente

Para autenticar automáticamente a un usuario de AlloyDB basado en IAM sin necesidad de un token de OAuth 2.0, tienes dos opciones: el proxy de autenticación de AlloyDB y los conectores de lenguaje de AlloyDB.

La cuenta de IAM que usas para ejecutar el cliente proxy o los conectores de lenguaje debe ser la misma que agregaste como usuario de la base de datos. Por ejemplo, si ejecutas tu carga de trabajo con la cuenta de usuario de IAM [e-mail], puedes usar el cliente proxy o los conectores de lenguaje para autenticar automáticamente al usuario de la base de datos [e-mail] sin especificar un token de OAuth 2.0. En este ejemplo, la autenticación automática no funciona con ningún otro usuario de la base de datos, excepto [e-mail].

Proxy de autenticación

Para usar el proxy de autenticación, se requiere ejecutar el cliente del proxy de autenticación de AlloyDB con la marca --auto-iam-authn habilitada.

Para obtener más información sobre la ejecución del proxy de autenticación, consulta Conéctate con el proxy de autenticación de AlloyDB.

Conectores de lenguaje

Para usar los conectores de lenguaje, se requiere habilitar la autenticación de IAM de forma programática. Hay una opción correspondiente para cada lenguaje en Configura los conectores de lenguaje de AlloyDB.

Soluciona problemas de autenticación de IAM

Para determinar la causa de un intento de autenticación basado en IAM fallido, sigue estos pasos:

1. En la Google Cloud consola de, accede a la página Explorador de registros:

   Ir al Explorador de registros

2. En Tipo de recurso, haz clic en Instancia de AlloyDB.

3. En Gravedad, haz clic en Alerta.

   Si Alerta no es una opción, significa que no se registraron fallas de autenticación en el período seleccionado. Es posible que debas ajustar la ventana con los controles del Explorador de registros.

4. En Resultados de la consulta, verifica las entradas de registro en busca de uno de los siguientes mensajes:

   Request had invalid authentication credentials.

   El token de acceso no es válido.

   Caller does not have required permission to use project.

   El principal de IAM no tiene los roles de IAM necesarios o permisos. El mensaje de error completo especifica los roles o permisos que faltan.

   IAM principal does not match database user.

   El principal de IAM autenticado especificado por el token de acceso no coincide con el usuario de la base de datos al que deseas conectarte.

   Para ver el principal especificado por el token, ejecuta el siguiente comando:

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

   Reemplaza ACCESS_TOKEN por el token de acceso de OAuth 2.0.

   Request had insufficient scopes.

   El token de acceso no contiene el permiso alloydb.login ni el permiso cloud-platform. Se requiere al menos uno de estos permisos.

¿Qué sigue?

• Administra tu autenticación de IAM