Métodos de autenticação

Esta página descreve como configurar um cliente de terceiro para autenticação com o Container Registry.

Os serviços do Google Cloud que se integram ao Container Registry são pré-configurados com permissões para acessar repositórios no mesmo projeto. Não é necessário configurar a autenticação para esses serviços, mas é necessário verificar se as permissões estão configuradas corretamente.

Antes de começar

  1. Verifique se você ativou a API Container Registry e instalou a CLI gcloud. Para instruções, consulte Como ativar e desativar o serviço.
  2. Verifique se a conta que você está usando para autenticação tem permissões para acessar o Container Registry. Recomendamos o uso de uma conta de serviço em vez de uma conta de usuário.

  3. Instale o Docker se ele ainda não estiver instalado. O Docker está incluído no Cloud Shell.

  4. O Docker requer acesso com privilégios para interagir com registros. No Linux ou no Windows, adicione o usuário utilizado para executar comandos do Docker no grupo de segurança do Docker. Esta etapa não é necessária no MacOS porque o Docker Desktop é executado em uma máquina virtual como o usuário raiz.

    Linux

    O grupo de segurança do Docker é chamado de docker. Para adicionar seu nome de usuário, execute o seguinte comando:

    sudo usermod -a -G docker ${USER}
    

    Windows

    O grupo de segurança do Docker é chamado de docker-users. Para adicionar um usuário a partir do prompt de comando do administrador, execute o seguinte comando:

    net localgroup docker-users DOMAIN\USERNAME /add
    

    Em que

    • DOMAIN é seu domínio do Windows.
    • USERNAME é seu nome de usuário.

    Saia e acesse novamente para a mudança de filiação ao grupo fazer efeito. Se estiver usando uma máquina virtual, talvez seja necessário reiniciar a máquina virtual para a mudança fazer efeito;

Métodos de autenticação

É preciso configurar qualquer cliente de terceiro que precise acessar o Container Registry.

Os seguintes métodos de autenticação estão disponíveis:

Auxiliar de credenciais gcloud (recomendado)
Configure suas credenciais do Container Registry para uso com o Docker diretamente no gcloud. Use esse método quando possível para acesso seguro e de curta duração aos recursos do projeto. Esta opção é compatível apenas com as versões 18.03 ou posteriores do Docker.
Auxiliar de credenciais independente
Esta opção é usada principalmente para configurar suas credenciais para uso com o Docker sem a CLI do Google Cloud. Esta opção é compatível apenas com as versões 18.03 ou posteriores do Docker.
Token de acesso
O Application Default Credentials fornece tokens de acesso de curta duração que uma conta de serviço usa para acessar seus recursos do Google Cloud. É a alternativa mais segura para usar gcloud como auxiliar de credencial.
Arquivo de chave JSON

Um par de chaves gerenciado pelo usuário que você pode usar como credencial para uma conta de serviço. Como a credencial é longa, é a opção menos segura de todos os métodos de autenticação disponíveis.

Quando possível, use um token de acesso ou outro método de autenticação disponível para reduzir o risco de acesso não autorizado aos seus artefatos. As chaves da conta de serviço são um risco de segurança quando não são gerenciadas corretamente. Sempre que possível, escolha uma alternativa mais segura para as chaves de conta de serviço. Caso seja necessário autenticar com uma chave de conta de serviço, você será responsável pela segurança da chave privada e por outras operações descritas em Práticas recomendadas para gerenciar chaves de contas de serviço. Se não for possível criar uma chave de conta de serviço, a criação pode ser desativada para sua organização. Para mais informações, consulte Gerenciar recursos da organização com segurança por padrão.

Algumas ferramentas ou fluxos de trabalho não fornecem um bom suporte para o uso de gcloud como um auxiliar de credencial. Se você usar uma das opções alternativas, compreenda as implicações de segurança.

Configurações de autenticação no arquivo de configuração do Docker

O Docker salva as definições de autenticação no arquivo de configuração config.json.

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

Há seções separadas no arquivo para diferentes métodos de autenticação:

credHelpers
Se você usar o auxiliar de credenciais do Docker para autenticação, o Container Registry vai armazenar as configurações do auxiliar de credenciais na seção credHelpers do arquivo.
auths
Se você usar o Docker para fazer login com um token ou chave de conta de serviço como sua senha, o Docker vai armazenar suas credenciais na seção auths do arquivo.
credStore
Se você configurou um armazenamento de credenciais para gerenciar suas credenciais, as configurações do armazenamento de credenciais estão em a seção credStore do arquivo.

Quando o Docker se conecta a um registro, ele verifica primeiro um auxiliar de credenciais associado ao host. Portanto, se o config.json incluir configurações do Container Registry nas seções credHelpers e auths, as configurações na seção auths serão ignoradas.

Auxiliar de credenciais do gcloud

É altamente recomendável que você use esse método quando possível. Ele permite o acesso seguro e de curta duração aos recursos do projeto.

Usar a CLI gcloud para configurar a autenticação no Cloud Shell ou em qualquer em que a Google Cloud CLI está instalada. O Cloud Shell inclui uma versão atual do Docker.

Para configurar a autenticação:

  1. Faça login no gcloud como o usuário que executará os comandos do Docker.

    • Para configurar a autenticação com credenciais de usuário, execute o seguinte comando:

      gcloud auth login
      
    • Para configurar a autenticação com credenciais da conta de serviço, execute o seguinte comando:

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

      Onde

  2. Configure o Docker com o seguinte comando:

    gcloud auth configure-docker
    

    Suas credenciais são salvas no diretório inicial do usuário.

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

Auxiliar de credenciais independente

O auxiliar de credenciais autônomo do Docker configura o Docker para autenticação para o Container Registry em um sistema em que CLI gcloud não está disponível.

As credenciais do Container Registry são fornecidas ao auxiliar de credenciais automaticamente ou a partir de uma localização especificada por meio da sinalização --token-source, Em seguida, elas são gravadas no arquivo de configuração do Docker. Assim, você pode usar a ferramenta de linha de comando do Docker, docker, para interagir diretamente com o Container Registry.

Para configurar a autenticação:

  1. Faça login na máquina como o usuário que executará os comandos do Docker.

  2. Faça o download de docker-credential-gcr versões do GitHub:

    Opcionalmente, você pode usar o utilitário de linha de comando curl. Exemplo:

    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. Configure o Docker com o seguinte comando:

    docker-credential-gcr configure-docker
    

    Suas credenciais são salvas no diretório inicial do usuário.

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

Consulte a documentação auxiliar de credenciais do Docker no GitHub para mais informações.

O Docker agora está configurado para autenticar com o Container Registry. Para enviar e extrair imagens, verifique se as permissões estão configuradas corretamente.

Token de acesso

É possível gerar um token de acesso OAuth de curta duração para autenticar com Container Registry. Como o token é válido por 60 minutos, você deve solicitá-lo menos de uma hora antes de usá-lo para se conectar com Container Registry.

  1. Crie uma conta de serviço que vai interagir com o Container Registry.

    Console

    1. No Console do Google Cloud, acesse a página Criar conta de serviço.

      Acesse a página "Criar conta de serviço"

    2. Selecione o projeto desejado.

    3. No campo Nome da conta de serviço, insira um nome.

    4. Opcional: no campo Descrição da conta de serviço, digite uma descrição.

    5. Clique em Criar.

    6. Clique no campo Selecionar um papel. Em Todas as funções, selecione uma apropriado Papel do Cloud Storage com base nas permissões que você quer conceder à conta de serviço.

    7. Clique em Concluído.

    gcloud

    É possível executar os comandos a seguir usando a Google Cloud CLI na sua máquina local. ou no Cloud Shell.

    1. Crie a conta de serviço. Substitua NAME por um nome para a conta de serviço.

      gcloud iam service-accounts create NAME
    2. Conceda um papel à conta de serviço. Substitua PROJECT_ID pelo ID do projeto e ROLE pelo papel do Cloud Storage apropriado para a conta de serviço. Essa função se aplica a todos os repositórios no projeto. Você pode mudar o papel mais tarde e também conceder papéis diferentes à conta de serviço em repositórios específicos.

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"
  2. Obtenha uma chave para a conta de serviço que interage com o Container Registry.

    Console

    1. No Console do Google Cloud, acesse a página Contas de serviço.

      Acesse a página Contas de serviço

    2. Clique no endereço de e-mail da conta de serviço que você quer usar.

    3. Clique em Chaves.

    4. Clique em Adicionar chave e, depois, em Criar nova chave.

    5. Clique em Criar. O download de um arquivo JSON que contém sua chave é feito no computador.

      As instruções nesta página usam o nome de arquivo keyfile.json para este arquivo de chave.

    6. Clique em Fechar.

    gcloud

    É possível executar o comando a seguir usando a CLI do Google Cloud na sua máquina local ou no Cloud Shell.

    As instruções nesta página usam o nome de arquivo keyfile.json para o arquivo de chave.

    gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com
  3. Execute o comando a seguir para fazer login na Google Cloud CLI como um serviço do Compute Engine.

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

    Onde

    • ACCOUNT é o nome da conta de serviço no formato [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com.
    • KEY-FILE é o arquivo de chave da conta de serviço. Consulte a documentação do IAM para informações sobre como criar uma chave.
  4. Verifique se as permissões estão configuradas corretamente para a conta de serviço. Se você estiver usando a conta de serviço do Compute Engine, precisará configurar corretamente as permissões e os escopos de acesso.

  5. Obtenha um token de acesso para a conta de serviço. Como o token tem vida curta, solicite menos de uma hora antes de usá-lo para se conectar ao Container Registry.

    Execute este 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
    

    em que HOSTNAME é gcr.io, us.gcr.io, eu.gcr.io ou asia.gcr.io.

O Docker agora está autenticado com o Container Registry.

Arquivo de chave JSON

Uma chave de conta de serviço é um par de chaves de longa duração que você pode usar como credencial para uma conta de serviço. Ao contrário do token de acesso do OAuth, uma chave de conta de serviço não expira.

Qualquer pessoa que tenha acesso a uma chave privada válida para uma conta de serviço poderá acessar recursos por meio da conta de serviço. Por exemplo, algumas contas de serviço criadas automaticamente pelo Google Cloud, como a conta de serviço do Container Registry, recebem o papel de leitura/gravação Editor do projeto pai. A conta de serviço padrão do Compute Engine é configurada com acesso somente leitura ao armazenamento dentro do mesmo projeto.

Além disso, o ciclo de vida do acesso da chave à conta de serviço não depende do ciclo de vida do usuário que fez o download da chave.

Use as seguintes diretrizes para limitar o acesso às imagens do seu contêiner:

Para criar uma nova conta de serviço e uma chave de conta de serviço para uso apenas com repositórios do Container Registry:

  1. Crie uma nova conta de serviço que vai interagir com o Container Registry.

    Console

    1. No Console do Google Cloud, acesse a página Criar conta de serviço.

      Acesse a página "Criar conta de serviço"

    2. Selecione o projeto desejado.

    3. No campo Nome da conta de serviço, insira um nome.

    4. Opcional: no campo Descrição da conta de serviço, digite uma descrição.

    5. Clique em Criar.

    6. Clique no campo Selecionar um papel. Em Todos os papéis, selecione um papel do Cloud Storage adequado para a conta de serviço.

    7. Clique em Concluído.

    gcloud

    É possível executar os comandos a seguir usando a Google Cloud CLI na sua máquina local. ou no Cloud Shell.

    1. Crie a conta de serviço. Substitua NAME por um nome para a conta de serviço.

      gcloud iam service-accounts create NAME
    2. Atribua um papel à conta de serviço. Substituir PROJECT_ID por ID do projeto e ROLE com os Papel do Cloud Storage para conta de serviço.

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"
  2. Obtenha uma chave para a conta de serviço que interage com o Container Registry.

    Console

    1. No Console do Google Cloud, acesse a página Contas de serviço.

      Acesse a página Contas de serviço

    2. Clique no endereço de e-mail da conta de serviço que você quer usar.

    3. Clique em Chaves.

    4. Clique em Adicionar chave e, depois, em Criar nova chave.

    5. Clique em Criar. O download de um arquivo JSON que contém sua chave é feito no computador.

      As instruções nesta página usam o nome de arquivo keyfile.json para este arquivo de chave.

    6. Clique em Fechar.

    gcloud

    É possível executar o comando a seguir usando a CLI do Google Cloud na sua máquina local ou no Cloud Shell.

    As instruções nesta página usam o nome de arquivo keyfile.json para a chave .

    gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com
  3. Verifique se as permissões estão configuradas corretamente para a conta de serviço. Se você estiver usando a conta de serviço do Compute Engine, precisará configurar corretamente as permissões e os escopos de acesso.

  4. Use a chave da conta de serviço como sua senha para autenticar com o 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
    

    Substitua:

    • KEY-FILE é o nome do arquivo de chave da conta de serviço no formato JSON.
    • HOSTNAME é gcr.io, us.gcr.io, eu.gcr.io ou asia.gcr.io.

O Docker agora está autenticado com o Container Registry.