Métodos de autenticación

En esta página, se describe cómo configurar un cliente de terceros para autenticarse con Container Registry.

Los servicios de Google Cloud que se integran con Container Registry están preconfigurados con permisos para acceder a los repositorios en el mismo proyecto. No necesitas configurar la autenticación para estos servicios, pero debes verificar que los permisos estén configurados de forma adecuada.

Antes de comenzar

  1. Verifica que habilitaste la API de Container Registry y que instalaste gcloud CLI. Consulta la página Inhabilita y habilita servicios para obtener instrucciones.

  2. Verifica que la cuenta que usas para la autenticación tenga permisos a fin de acceder a Container Registry. Te recomendamos usar una cuenta de servicio en lugar de una de usuario.

  3. Instala Docker, si aún no se encuentra instalado. Docker está incluido en Cloud Shell.

  4. Docker necesita acceso con privilegios para interactuar con los registros. En Linux o Windows, agrega el usuario que usas para ejecutar comandos de Docker al grupo de seguridad de Docker. Este paso no es necesario en Mac OS, ya que Docker Desktop se ejecuta en una máquina virtual como usuario raíz.

    Linux

    El grupo de seguridad de Docker se llama docker. Para agregar tu nombre de usuario, ejecuta el siguiente comando:

    sudo usermod -a -G docker ${USER}

    Windows

    El grupo de seguridad de Docker se llama docker-users. Para agregar un usuario desde el símbolo del sistema del administrador, ejecuta el siguiente comando:

    net localgroup docker-users DOMAIN\USERNAME /add

    Donde

    • DOMAIN es tu dominio de Windows.
    • USERNAME es tu nombre de usuario.

    Sal de tu cuenta y vuelve a acceder para que se apliquen los cambios de membresía de grupo. Si utilizas una máquina virtual, es posible que tengas que reiniciarla para que se apliquen los cambios de membresía.

Métodos de autenticación

Debes configurar cualquier cliente de terceros que deba acceder a Container Registry.

Los siguientes métodos de autenticación están disponibles:

Auxiliar de credenciales de gcloud (recomendado)
Configura tus credenciales de Container Registry para usarlas con Docker directamente en gcloud. Usa este método cuando sea posible para un acceso seguro y de corta duración a los recursos de tu proyecto. Esta opción solo es compatible a partir de la versión 18.03 de Docker.
Auxiliar de credenciales independiente
Esta opción es principalmente para configurar tus credenciales y usarlas con Docker si Google Cloud CLI no existe. Esta opción solo es compatible a partir de la versión 18.03 de Docker.
Token de acceso
Las credenciales predeterminadas de la aplicación proporcionan tokens de acceso de corta duración que una cuenta de servicio usa para acceder a tus recursos de Google Cloud. Es la alternativa más segura para usar gcloud como auxiliar de credenciales.
Archivo de claves JSON

Un par de claves administrado por el usuario que puedes usar como credencial para una cuenta de servicio. Debido a que la credencial es de larga duración, es la opción menos segura de todos los métodos de autenticación disponibles.

Cuando sea posible, usa un token de acceso o cualquier otro método de autenticación disponible para reducir el riesgo de acceso no autorizado a tus artefactos. Las claves de cuenta de servicio son un riesgo de seguridad si no se administran de forma adecuada. Debes elegir una alternativa más segura a las claves de la cuenta de servicio siempre que sea posible. Si te debes autenticar con una clave de cuenta de servicio, eres responsable de la seguridad de la clave privada y de otras operaciones que se describen en Prácticas recomendadas para administrar claves de cuenta de servicio. Si no se te permite crear una clave de cuenta de servicio, es posible que la creación de claves de cuentas de servicio esté inhabilitada para tu organización. Para obtener más información, consulta Administra los recursos de la organización con seguridad de forma predeterminada.

Algunas herramientas o flujos de trabajo no proporcionan una buena asistencia para usar gcloud como auxiliar de credenciales. Si usas una de las opciones alternativas, asegúrate de comprender las implicaciones de seguridad.

Configuración de autenticación en el archivo de configuración de Docker

Docker guarda la configuración de autenticación en el archivo de configuración config.json.

  • Linux: ~/.docker/config.json
  • Windows: %USERPROFILE%\.docker\config.json

En el archivo, hay secciones separadas para los diferentes métodos de autenticación:

credHelpers
Si usas el auxiliar de credenciales de Docker para la autenticación, Container Registry almacena la configuración del auxiliar de credenciales en la sección credHelpers del archivo.
auths
Si usas Docker para acceder con un token o una clave de cuenta de servicio como contraseña, Docker almacena tus credenciales en la sección auths del archivo.
credStore
Si configuraste un almacén de credenciales para administrar tus credenciales, la configuración del almacén de credenciales se encuentra en la sección credStore del archivo.

Cuando Docker se conecta a un registro, primero busca un auxiliar de credenciales asociado con el host. Por lo tanto, si tu config.json incluye la configuración del Container Registry en las secciones credHelpers y auths, se ignora la configuración de la sección auths.

Auxiliar de credenciales de gcloud

Te recomendamos que utilices este método cuando sea posible. Proporciona acceso seguro y de corta duración a los recursos de tu proyecto.

Usa gcloud CLI para configurar la autenticación en Cloud Shell o en cualquier entorno en el que esté instalada Google Cloud CLI. Cloud Shell incluye una versión actual de Docker.

Para configurar la autenticación, sigue estos pasos:

  1. Accede a gcloud como el usuario que ejecutará los comandos de Docker.

    • Para configurar la autenticación con credenciales de usuario, ejecuta el siguiente comando:

      gcloud auth login

    • Para configurar la autenticación con credenciales de cuenta de servicio, ejecuta el siguiente comando:

      gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE

      Donde

      • ACCOUNT es el nombre de la cuenta de servicio en el formato [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com. Puedes ver las cuentas de servicio existentes en la página Cuentas de servicio de la consola de Google Cloud o con el comando gcloud iam service-accounts list.
      • KEY-FILE es el archivo de claves de la cuenta de servicio. Consulta la documentación de la administración de identidades y accesos (IAM) para obtener información sobre cómo crear una clave.

  2. Configura Docker con el siguiente comando:

    gcloud auth configure-docker

    Las credenciales se guardan en el directorio de inicio del usuario.

    • Linux: $HOME/.docker/config.json
    • Windows: %USERPROFILE%/.docker/config.json

Auxiliar de credenciales independiente

El auxiliar de credenciales de Docker independiente configura Docker para autenticar en Container Registry en un sistema en el que gcloud CLI no está disponible.

El auxiliar de credenciales recupera tus credenciales de Container Registry, ya sea automáticamente o desde una ubicación especificada mediante la marca --token-source. Luego, las escribe en el archivo de configuración de Docker. De esta manera, puedes usar la herramienta de línea de comandos de Docker, docker, para interactuar directamente con Container Registry.

Para configurar la autenticación, sigue estos pasos:

  1. Accede a la máquina como el usuario que ejecutará los comandos de Docker.

  2. Descarga docker-credential-gcr de las versiones de GitHub:

    También puedes usar la utilidad de línea de comandos de curl. Por ejemplo:

    VERSION=2.1.23
OS=linux  # or "darwin" for OSX, "windows" for Windows.
ARCH=amd64  # or "386" for 32-bit OSs, "arm64" for ARM 64.

curl -fsSL "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \
| tar xz docker-credential-gcr \
&& chmod +x docker-credential-gcr && sudo mv docker-credential-gcr /usr/bin/

  3. Configura Docker con el siguiente comando:

    docker-credential-gcr configure-docker

    Las credenciales se guardan en el directorio de inicio del usuario.

    • Linux: $HOME/.docker/config.json
    • Windows: %USERPROFILE%/.docker/config.json

Consulta la documentación del auxiliar de credenciales de Docker independiente en GitHub para obtener más información.

Docker ahora está configurado para autenticarse con Container Registry. Para enviar y extraer imágenes, asegúrate de que los permisos estén configurados de forma correcta.

Token de acceso

Puedes generar un token de acceso de OAuth de corta duración para autenticarte con el Container Registry. Dado que el token es válido por 60 minutos, debes solicitarlo menos de una hora antes de usarlo para conectarte a Container Registry.

  1. Crea una cuenta de servicio nueva que interactuará con Container Registry.

    Console

    1. En la consola de Google Cloud, ve a la página Crear cuenta de servicio.

      Ve a la página Crear cuenta de servicio

    2. Selecciona el proyecto que deseas usar.

    3. Ingresa un nombre en el campo Nombre de cuenta de servicio.

    4. Opcional: en el campo Descripción de la cuenta de servicio, ingresa una descripción.

    5. Haga clic en Crear.

    6. Haz clic en el campo Seleccionar una función. En Todos los roles, selecciona un rol de Cloud Storage adecuado según los permisos que deseas otorgar a la cuenta de servicio.

    7. Haz clic en Listo.

    gcloud

    Puedes ejecutar los siguientes comandos con Google Cloud CLI en tu máquina local o en Cloud Shell.

    1. Cree la cuenta de servicio. Reemplaza NAME por un nombre para la cuenta de servicio.

      gcloud iam service-accounts create NAME

    2. Otorga un rol a la cuenta de servicio. Reemplaza PROJECT_ID con el ID de tu proyecto y ROLE con el rol de Cloud Storage adecuado para la cuenta de servicio. Esta función se aplica a todos los repositorios del proyecto. Puedes cambiar el rol más adelante y también puedes otorgar diferentes roles a la cuenta de servicio en repositorios específicos.

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"

  2. Obtén una clave para la cuenta de servicio que interactuará con Container Registry.

    Console

    1. En la consola de Google Cloud, ve a la página Cuentas de servicio.

      Ir a la página Cuentas de servicio

    2. Haz clic en la dirección de correo electrónico de la cuenta de servicio que deseas usar.

    3. Haga clic en Claves.

    4. Haz clic en Agregar clave -> Crear nueva clave.

    5. Haz clic en Crear. Se descargará a tu computadora un archivo JSON con la clave.

      En las instrucciones de esta página, se usa el nombre de archivo keyfile.json para este archivo de claves.

    6. Haz clic en Cerrar.

    gcloud

    Puedes ejecutar el siguiente comando con Google Cloud CLI en tu máquina local o en Cloud Shell.

    En las instrucciones de esta página, se usa el nombre de archivo keyfile.json para el archivo de claves.

    gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com

  3. Ejecuta el siguiente comando para acceder a Google Cloud CLI como una cuenta de servicio.

    gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE

    Dónde

    • ACCOUNT es el nombre de la cuenta de servicio en el formato [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com.
    • KEY-FILE es el archivo de claves de la cuenta de servicio. Consulta la documentación de IAM para obtener información sobre la creación de una clave.

  4. Verifica que los permisos estén configurados de forma correcta para la cuenta de servicio. Si usas la cuenta de servicio de Compute Engine, debes configurar de forma correcta los permisos y los permisos de acceso.

  5. Obtén un token de acceso para la cuenta de servicio. Dado que el token es de corta duración, solicítalo menos de una hora antes de usarlo para conectarte a Container Registry.

    Ejecuta el siguiente comando:

    Linux

    gcloud auth print-access-token | docker login -u oauth2accesstoken \
    --password-stdin https://HOSTNAME

    Windows

    gcloud auth print-access-token |
    docker login -u oauth2accesstoken --password-stdin https://HOSTNAME

    donde HOSTNAME es gcr.io, us.gcr.io, eu.gcr.io o asia.gcr.io.

Docker ahora está autenticado con Container Registry.

Archivo de claves JSON

Una clave de cuenta de servicio es un par de claves de larga duración que puedes usar como credencial para una cuenta de servicio. A diferencia del token de acceso de OAuth, una clave de cuenta de servicio no vence.

Cualquier persona que tenga acceso a una clave privada válida para una cuenta de servicio podrá acceder a los recursos a través de la cuenta de servicio. Por ejemplo, a algunas cuentas de servicio creadas automáticamente por Google Cloud, como la cuenta de servicio de Container Registry, se les otorga la función de lectura y escritura Editor para el proyecto principal. La cuenta de servicio predeterminada de Compute Engine está configurada con acceso de solo lectura al almacenamiento dentro del mismo proyecto.

Además, el ciclo de vida del acceso de la clave a la cuenta de servicio (y, por lo tanto, a los datos a los que tiene acceso la cuenta de servicio) es independiente del ciclo de vida del usuario que descargó la clave.

Usa las siguientes pautas para limitar el acceso a tus imágenes de contenedor:

A fin de crear una cuenta de servicio y una clave de cuenta de servicio nueva para usar solo con los repositorios de Container Registry, sigue estos pasos:

  1. Crea una cuenta de servicio nueva que interactuará con Container Registry.

    Console

    1. En la consola de Google Cloud, ve a la página Crear cuenta de servicio.

      Ve a la página Crear cuenta de servicio

    2. Selecciona el proyecto que deseas usar.

    3. Ingresa un nombre en el campo Nombre de cuenta de servicio.

    4. Opcional: en el campo Descripción de la cuenta de servicio, ingresa una descripción.

    5. Haga clic en Crear.

    6. Haz clic en el campo Seleccionar una función. En Todas las funciones, selecciona un rol de Cloud Storage apropiado para la cuenta de servicio.

    7. Haz clic en Listo.

    gcloud

    Puedes ejecutar los siguientes comandos con Google Cloud CLI en tu máquina local o en Cloud Shell.

    1. Cree la cuenta de servicio. Reemplaza NAME por un nombre para la cuenta de servicio.

      gcloud iam service-accounts create NAME

    2. Otorga un rol a la cuenta de servicio. Reemplaza PROJECT_ID con el ID de tu proyecto y ROLE con el rol de Cloud Storage adecuado para la cuenta de servicio.

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"

  2. Obtén una clave para la cuenta de servicio que interactuará con Container Registry.

    Console

    1. En la consola de Google Cloud, ve a la página Cuentas de servicio.

      Ir a la página Cuentas de servicio

    2. Haz clic en la dirección de correo electrónico de la cuenta de servicio que deseas usar.

    3. Haga clic en Claves.

    4. Haz clic en Agregar clave -> Crear nueva clave.

    5. Haz clic en Crear. Se descargará a tu computadora un archivo JSON con la clave.

      En las instrucciones de esta página, se usa el nombre de archivo keyfile.json para este archivo de claves.

    6. Haz clic en Cerrar.

    gcloud

    Puedes ejecutar el siguiente comando con Google Cloud CLI en tu máquina local o en Cloud Shell.

    En las instrucciones de esta página, se usa el nombre de archivo keyfile.json para el archivo de claves.

    gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com

  3. Verifica que los permisos estén configurados de forma correcta para la cuenta de servicio. Si usas la cuenta de servicio de Compute Engine, debes configurar de forma correcta los permisos y los permisos de acceso.

  4. Usa la clave de la cuenta de servicio como contraseña a fin de autenticarte con Docker.

    Linux/macOS

    cat KEY-FILE | docker login -u _json_key --password-stdin \
https://HOSTNAME

    Windows

    Get-Content KEY-FILE |
docker login -u _json_key --password-stdin https://HOSTNAME

    Reemplaza lo siguiente:

    • KEY-FILE es el nombre del archivo de claves de la cuenta de servicio en formato JSON.
    • HOSTNAME es gcr.io, us.gcr.io, eu.gcr.io o asia.gcr.io.

Docker ahora está autenticado con Container Registry.