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). En él, 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 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 antes de 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.

Autentícate con un token de OAuth 2.0

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

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

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

    gcloud auth print-access-token

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

    Para mayor seguridad, puedes restringir el uso del token solo a 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 alcance del 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 por completo. 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 y 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.

    • 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.

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: Es la dirección IP de la instancia de AlloyDB a la que se conectará.

  • USERNAME: Es un identificador del usuario de IAM con el que se autenticará en la instancia.

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

    En el caso de 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, usarías 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 superan los 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 manualmente cuando se te solicite.

Autenticación automática

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 kai@altostrat.com, puedes usar el cliente proxy o los conectores de lenguaje para autenticar automáticamente el 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.

Proxy de autenticación

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

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.

Conectores de lenguaje

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

Soluciona problemas de autenticación de IAM

Para determinar la causa de un intento fallido de autenticación basada en IAM, 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 errores 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.
    La principal de IAM no tiene los roles de IAM o los permisos necesarios. El mensaje de error completo especifica los roles o permisos faltantes.
    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 la entidad principal especificada 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?