Métodos de autenticación

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

LosGoogle Cloud servicios que se integran con Container Registry tienen permisos preconfigurados para acceder a los repositorios del mismo proyecto. No es necesario que configures la autenticación para estos servicios, pero debes verificar que los permisos estén configurados correctamente.

Antes de empezar

  1. Verifica que has habilitado la API Container Registry y que has instalado la CLI de gcloud. Para ver las instrucciones, consulta Habilitar e inhabilitar el servicio.

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

  3. Instala Docker si aún no lo has hecho. Docker está incluido en Cloud Shell.

  4. Docker requiere acceso con privilegios para interactuar con los registros. En Linux o Windows, añade el usuario que usas para ejecutar comandos de Docker al grupo de seguridad de Docker. Este paso no es necesario en macOS, 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 añadir 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 añadir un usuario desde la petición de comando del administrador, ejecuta el siguiente comando:

    net localgroup docker-users DOMAIN\USERNAME /add

    Dónde

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

    Cierra sesión y vuelve a iniciarla para que se apliquen los cambios en la pertenencia a grupos. Si usas una máquina virtual, es posible que tengas que reiniciarla para que los cambios en la suscripción surtan efecto.

Métodos de autenticación

Debe configurar los clientes de terceros que necesiten acceder a Container Registry.

Están disponibles los siguientes métodos de autenticación:

gcloud asistente de credenciales (recomendado)
Configura tus credenciales de Container Registry para usarlas con Docker directamente en gcloud. Utiliza este método siempre que sea posible para obtener acceso seguro y de corta duración a los recursos de tu proyecto. Esta opción solo es compatible con Docker 18.03 o versiones posteriores.
Asistente de credenciales independiente
Esta opción se usa principalmente para configurar tus credenciales para usarlas con Docker si no tienes la CLI de Google Cloud. Esta opción solo es compatible con las versiones de Docker 18.03 o posteriores.
Token de acceso
Las credenciales de aplicación predeterminadas proporcionan tokens de acceso de corta duración que una cuenta de servicio usa para acceder a tus Google Cloud recursos. Es la alternativa más segura a usar gcloud como ayuda para las credenciales.
Archivo de clave JSON

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

Cuando sea posible, utiliza un token de acceso u otro método de autenticación disponible para reducir el riesgo de acceso no autorizado a tus artefactos. Las claves de las cuentas de servicio suponen un riesgo para la seguridad si no se gestionan adecuadamente. Siempre que sea posible, deberías elegir una alternativa más segura a las claves de cuentas de servicio. Si debes autenticarte con una clave de cuenta de servicio, eres responsable de la seguridad de la clave privada y de otras operaciones descritas en las prácticas recomendadas para gestionar las claves de cuentas de servicio. Si no puedes crear una clave de cuenta de servicio, es posible que la creación de claves de cuenta de servicio esté inhabilitada en tu organización. Para obtener más información, consulta el artículo sobre gestionar recursos de organización seguros de forma predeterminada.

Si has obtenido la clave de cuenta de servicio de una fuente externa, debes validarla antes de usarla. Para obtener más información, consulta los requisitos de seguridad de las credenciales de fuentes externas.

Algunas herramientas o flujos de trabajo no ofrecen una buena compatibilidad con el uso de gcloud como auxiliar de credenciales. Si usas una de las opciones alternativas, asegúrate de que entiendes 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

El archivo tiene secciones independientes para los distintos métodos de autenticación:

credHelpers
Si usas el asistente de credenciales de Docker para la autenticación, Container Registry almacena los ajustes del asistente de credenciales en la sección credHelpers del archivo.
auths
Si usas Docker para iniciar sesión 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 has configurado un almacén de credenciales para gestionar tus credenciales, los ajustes del almacén de credenciales se encuentran en la sección credStore del archivo.

Cuando Docker se conecta a un registro, primero busca un asistente de credenciales asociado al host. Por lo tanto, si tu config.json incluye ajustes de Container Registry en las secciones credHelpers y auths, se ignorarán los ajustes de la sección auths.

Asistente de credenciales de gcloud

Te recomendamos que utilices este método siempre que 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. Inicia sesión en 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 las credenciales de la cuenta de servicio, ejecuta el siguiente comando:

      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. Puedes ver las cuentas de servicio que ya tienes 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 clave de la cuenta de servicio. Consulta la documentación de gestió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

    Tus credenciales se guardan en el directorio principal de tu usuario.

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

Asistente de credenciales independiente

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

El asistente de credenciales obtiene tus credenciales de Container Registry (automáticamente o desde una ubicación especificada con su marca --token-source) y, a continuación, las escribe en el archivo de configuración de Docker. De esta forma, 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. Inicia sesión en el equipo con la cuenta del usuario que ejecutará los comandos de Docker.

  2. Descarga docker-credential-gcr desde Versiones de GitHub:

    También puedes usar la utilidad de línea de comandos 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

    Tus credenciales se guardan en el directorio principal de tu usuario.

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

Para obtener más información, consulta la documentación independiente del asistente de credenciales de Docker en GitHub.

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

Token de acceso

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

  1. Crea una cuenta de servicio que interactúe con Container Registry.

    Consola

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

      Ir a la página Crear cuenta de servicio

    2. Selecciona el proyecto que quieras usar.

    3. En el campo Nombre de cuenta de servicio, escribe un nombre.

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

    5. Haz clic en Crear.

    6. Haz clic en el campo Selecciona un rol. En Todos los roles, selecciona un rol de Cloud Storage adecuado en función de los permisos que quieras conceder a la cuenta de servicio.

    7. Haz clic en Listo.

    gcloud

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

    1. Crea la cuenta de servicio. Sustituye NAME por el nombre de la cuenta de servicio.

      gcloud iam service-accounts create NAME

    2. Asigna un rol a la cuenta de servicio. Sustituye PROJECT_ID por el ID de tu proyecto y ROLE por el rol de Cloud Storage adecuado para la cuenta de servicio. Este rol se aplica a todos los repositorios del proyecto. Puedes cambiar el rol más adelante y también puedes asignar 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.

    Consola

    1. En la Google Cloud consola, 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 de la cuenta de servicio que quieras usar.

    3. Haz clic en Teclas.

    4. Haz clic en Añadir clave y, a continuación, en Crear clave.

    5. Haz clic en Crear. Se descargará en tu ordenador un archivo JSON que contiene tu 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 la CLI de Google Cloud 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 iniciar sesión en la CLI de Google Cloud como 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 clave de la cuenta de servicio. Consulta la documentación de gestión de identidades y accesos para obtener información sobre cómo crear una clave.

  4. Verifica que los permisos estén configurados correctamente para la cuenta de servicio. Si utilizas la cuenta de servicio de Compute Engine, debes configurar correctamente tanto los permisos como los ámbitos de acceso.

  5. Obtén un token de acceso para la cuenta de servicio. Como el token tiene una validez breve, solicítelo menos de una hora antes de usarlo para conectarse con 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.

    .

Ahora Docker está autenticado con Container Registry.

Archivo de clave 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 OAuth, una clave de cuenta de servicio no caduca.

Cualquier persona que tenga acceso a una clave privada válida de una cuenta de servicio podrá acceder a los recursos a través de esa cuenta. Por ejemplo, algunas cuentas de servicio creadas automáticamente por Google Cloud, como la cuenta de servicio de Container Registry, tienen asignado el rol de lectura y escritura Editor del proyecto principal. La cuenta de servicio predeterminada de Compute Engine está configurada con acceso de solo lectura al almacenamiento 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 ha descargado la clave.

Sigue estas directrices para limitar el acceso a tus imágenes de contenedor:

Para crear una cuenta de servicio y una clave de cuenta de servicio que solo se puedan usar con repositorios de Container Registry, sigue estos pasos:

  1. Crea una cuenta de servicio que interactúe con Container Registry.

    Consola

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

      Ir a la página Crear cuenta de servicio

    2. Selecciona el proyecto que quieras usar.

    3. En el campo Nombre de cuenta de servicio, escribe un nombre.

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

    5. Haz clic en Crear.

    6. Haz clic en el campo Selecciona un rol. En Todos los roles, selecciona un rol de Cloud Storage adecuado para la cuenta de servicio.

    7. Haz clic en Listo.

    gcloud

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

    1. Crea la cuenta de servicio. Sustituye NAME por el nombre de la cuenta de servicio.

      gcloud iam service-accounts create NAME

    2. Asigna un rol a la cuenta de servicio. Sustituye PROJECT_ID por el ID de tu proyecto y ROLE por 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.

    Consola

    1. En la Google Cloud consola, 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 de la cuenta de servicio que quieras usar.

    3. Haz clic en Teclas.

    4. Haz clic en Añadir clave y, a continuación, en Crear clave.

    5. Haz clic en Crear. Se descargará en tu ordenador un archivo JSON que contiene tu 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 la CLI de Google Cloud 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 correctamente para la cuenta de servicio. Si utilizas la cuenta de servicio de Compute Engine, debes configurar correctamente tanto los permisos como los ámbitos de acceso.

  4. Usa la clave de la cuenta de servicio como contraseña para autenticarte en Docker.

    Linux o 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

    Haz los cambios siguientes:

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

Ahora Docker está autenticado con Container Registry.