Conéctate con una cuenta de IAM

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

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

Antes de comenzar

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

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

Cómo autenticar con un token de OAuth 2.0

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

  1. Si aún no lo hiciste, autoriza Google Cloud CLI con el mismo usuario o la misma cuenta de servicio con la que deseas acceder a tu instancia de AlloyDB.

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

    gcloud auth print-access-token

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

    Para obtener seguridad adicional, puedes restringir el token para usarlo solo con la autenticación de AlloyDB. Para ello, sigue estos pasos alternativos:

    1. Agrega el alcance alloydb.login a las credenciales de acceso de tu entorno actual con el comando gcloud auth application-default login, 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 comando gcloud auth application-default print-access-token y 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

    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 que se muestra 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 con estas credenciales:

    • Presenta el token de acceso que adquiriste en el paso anterior como 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.

    • En el caso de 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.

En el siguiente comando psql, se 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 luego usa 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 quieres conectar.

  • USERNAME: Es un identificador para que el usuario de IAM se autentique con 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, kai@altostrat.com.

    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 my-service@my-project.iam.gserviceaccount.com, debes usar el valor my-service@my-project.iam 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.

Realiza la autenticación automáticamente con el proxy de autenticación de AlloyDB o los conectores de lenguaje de AlloyDB

Puedes usar el proxy de autenticación de AlloyDB o los conectores de lenguaje de AlloyDB para autenticar automáticamente un usuario de AlloyDB basado en IAM y conectarte a una instancia sin necesidad de proporcionar un token de OAuth 2.0.

Para usar el proxy de autenticación de AlloyDB, debes ejecutar el cliente de proxy de autenticación de AlloyDB con la marca --auto-iam-authn habilitada, mientras que los conectores de lenguaje de AlloyDB requieren habilitar la autenticación de IAM de forma programática.

Cuando usas los conectores de idioma, hay una opción correspondiente para cada idioma. Consulta Configura los conectores de lenguaje de AlloyDB para obtener más detalles.

La cuenta de IAM que usas para ejecutar el cliente de 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 kai@altostrat.com, puedes usar el cliente de proxy o los conectores de lenguaje para autenticar automáticamente al usuario de la base de datos kai@altostrat.com 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 kai@altostrat.com.

Para obtener más información sobre cómo ejecutar el proxy de autenticación, consulta Conéctate con el proxy de autenticación de AlloyDB.

Para obtener más información sobre cómo ejecutar los conectores de lenguaje, consulta Cómo conectarse con 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 que falló, sigue estos pasos:

  1. En la consola de Google Cloud, ve 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 durante 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 ni los 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 que especifica el token de acceso no coincide con el usuario de la base de datos con el 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 cloud-platform. Se requiere al menos uno de estos permisos.