Autorize a CLI gcloud

Normalmente, para aceder ao Trusted Cloud, tem de autorizar a CLI gcloud. Esta página demonstra as opções de autorização disponíveis e mostra-lhe como gerir as contas que usa para autorização. Se estiver a usar uma instância do Compute Engine ou o Cloud Shell, não tem de autorizar a CLI gcloud.

Tipos de contas

Para conceder autorização à CLI gcloud para aceder a Trusted Cloud, pode usar uma conta de utilizador ou uma conta de serviço.

Uma conta de utilizador é uma Trusted Cloud conta que permite aos utilizadores finais autenticarem-se na sua aplicação. Para os exemplos de utilização mais comuns, especialmente quando usa a CLI gcloud de forma interativa, a utilização de uma conta de utilizador é a melhor prática.

Uma conta de serviço é uma Trusted Cloud conta associada ao seu Trusted Cloud projeto e não a um utilizador específico. Pode usar a conta de serviço integrada disponível quando usa as funções do Cloud Run, o App Engine, o Compute Engine ou o Google Kubernetes Engine. Recomendamos uma conta de serviço para executar scripts da CLI gcloud em várias máquinas.

Escolha um tipo de autorização

Tem de autorizar a CLI gcloud a gerir recursos Trusted Cloud. A CLI Google Cloud e a Trusted Cloud usam o OAuth2 para autenticação e autorização.

Escolha um dos seguintes tipos de autorização:

Tipo Descrição
Conta de utilizador Recomendado se estiver a usar a CLI gcloud a partir da linha de comando ou se estiver a escrever scripts com a CLI gcloud para utilização numa única máquina.
Conta de serviço Recomendado se estiver a instalar e configurar a CLI gcloud como parte de um processo de implementação de máquinas em produção ou para utilização em instâncias de máquinas virtuais do Compute Engine onde todos os utilizadores têm acesso ao root.

Para mais informações sobre a autenticação e Trusted Cloud, consulte o artigo Vista geral da autenticação.

Autorize com uma conta de utilizador

Esta secção descreve como iniciar sessão na CLI gcloud através da Workforce Identity Federation.

Antes de iniciar sessão na CLI gcloud, tem de definir a propriedade core/universe_domain na sua configuração executando o seguinte comando:

gcloud config set universe_domain s3nsapis.fr

Início de sessão baseado no navegador da CLI gcloud

Para iniciar sessão na CLI gcloud através de um fluxo de início de sessão baseado no navegador, faça o seguinte:

  1. Crie um ficheiro de configuração de início de sessão.

    Para criar o ficheiro de configuração de início de sessão, execute o seguinte comando. Opcionalmente, pode ativar o ficheiro como predefinição para a CLI gcloud adicionando a flag --activate. Em seguida, pode executar o comando gcloud auth login sem especificar o caminho do ficheiro de configuração de cada vez. 

    gcloud iam workforce-pools create-login-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=LOGIN_CONFIG_FILE_PATH

    Substitua o seguinte:

    • WORKFORCE_POOL_ID: o ID do Workforce Pool
    • PROVIDER_ID: o ID do fornecedor
    • LOGIN_CONFIG_FILE_PATH: o caminho para um ficheiro de configuração que especifica, por exemplo, login.json

    O ficheiro contém os pontos finais usados pela CLI gcloud para ativar o fluxo de autenticação baseado no navegador e definir o público-alvo para o IdP que foi configurado no fornecedor do Workload Identity Pool. O ficheiro não contém informações confidenciais.

    O resultado tem um aspeto semelhante ao seguinte:

    {
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "auth_url": "https://auth.cloud.s3nscloud.fr/authorize",
  "token_url": "https://sts.s3nsapis.fr/v1/oauthtoken",
  "token_info_url": "https://sts.s3nsapis.fr/v1/introspect",
}

    Para impedir que o gcloud auth login use este ficheiro de configuração automaticamente, pode anular a definição executando o comando gcloud config unset auth/login_config_file.

  2. Inicie sessão através da autenticação baseada no navegador.

    Para autenticar através da autenticação de início de sessão baseada no navegador, pode usar um dos seguintes métodos:

    • Se usou a flag --activate quando criou o ficheiro de configuração ou se ativou o ficheiro de configuração com gcloud config set auth/login_config_file, a CLI gcloud usa o ficheiro de configuração automaticamente: 

      gcloud auth login

    • Para iniciar sessão especificando a localização do ficheiro de configuração, execute o seguinte comando: 

      gcloud auth login --login-config=LOGIN_CONFIG_FILE_PATH
    • Para usar uma variável de ambiente para especificar a localização do ficheiro de configuração, defina CLOUDSDK_AUTH_LOGIN_CONFIG_FILE para o caminho de configuração.

Para descontinuar a utilização do ficheiro de configuração de início de sessão, faça o seguinte:

  • Se usou a flag --activate quando criou o ficheiro de configuração ou se ativou o ficheiro de configuração com gcloud config set auth/login_config_file, tem de executar o seguinte comando para anular a definição: 

    gcloud config unset auth/login_config_file
  • Limpe a variável de ambiente CLOUDSDK_AUTH_LOGIN_CONFIG_FILE, se estiver definida.

Início de sessão sem interface da CLI gcloud

Para iniciar sessão na CLI gcloud através de um fluxo sem interface gráfica, faça o seguinte:

OIDC

  1. Inicie sessão de um utilizador na sua app de IdP e obtenha o token OIDC.

    Para informações sobre como obter o token, consulte a documentação OIDC do seu IdP.

  2. Guarde o token OIDC devolvido pelo IdP num local seguro na sua máquina local.

  3. Execute o seguinte comando para gerar um ficheiro de configuração:

    gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type="urn:ietf:params:oauth:token-type:id_token" \
    --credential-source-file="PATH_TO_OIDC_ID_TOKEN" \
    --workforce-pool-user-project="WORKFORCE_POOL_USER_PROJECT" \
    --output-file="config.json"

Substitua o seguinte:

  • WORKFORCE_POOL_ID: o ID do Workforce Pool
  • PROVIDER_ID: o ID do fornecedor
  • PATH_TO_OIDC_TOKEN: o caminho para o ficheiro de credenciais do IdP do OIDC
  • WORKFORCE_POOL_USER_PROJECT: o número do projeto associado ao projeto do utilizador dos conjuntos de trabalhadores

O principal tem de ter a autorização serviceusage.services.use neste projeto.

Quando executa o comando, produz um ficheiro de configuração do IdP do OIDC com um formato semelhante ao seguinte:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "file": "PATH_TO_OIDC_CREDENTIALS_FILE"
  }
}

SAML

  1. Fazer com que um utilizador inicie sessão na sua app de IdP e receber a declaração SAML.

    Para informações sobre como obter a declaração SAML do seu IdP, consulte a documentação SAML do IdP.

  2. Guarde a resposta SAML devolvida pelo IdP num local seguro na sua máquina local e, em seguida, armazene o caminho da seguinte forma:

    SAML_ASSERTION_PATH=SAML_ASSERTION_PATH

  3. Para gerar um ficheiro de configuração, execute o seguinte comando:

    gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type="urn:ietf:params:oauth:token-type:saml2" \
    --credential-source-file="SAML_ASSERTION_PATH"  \
    --workforce-pool-user-project="PROJECT_ID"  \
    --output-file="config.json"

    Substitua o seguinte:

    • WORKFORCE_PROVIDER_ID: o ID do fornecedor de força de trabalho que criou anteriormente neste guia.
    • WORKFORCE_POOL_ID: o ID do Workforce Pool que criou anteriormente neste guia.
    • SAML_ASSERTION_PATH: o caminho do ficheiro de declaração SAML.
    • PROJECT_ID: o ID do projeto

    O ficheiro de configuração gerado tem um aspeto semelhante ao seguinte:

    {
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "credential_source": {
    "file": "SAML_ASSERTION_PATH"
  },
  "workforce_pool_user_project": "PROJECT_ID"
}

Para iniciar sessão no gcloud através da troca de tokens, execute o seguinte comando:

gcloud auth login --cred-file="config.json"

gcloud, em seguida, troca de forma transparente as suas credenciais do IdP por tokens de acesso temporários Trusted Cloud , o que lhe permite fazer outras chamadas para gcloud Trusted Cloud.

O resultado é semelhante ao seguinte:

Authenticated with external account user credentials for:
[principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/USER_ID].

Para listar as contas com credenciais e a sua conta atualmente ativa, execute o seguinte comando:

gcloud auth list

Autorize com uma conta de serviço

O comando gcloud auth login pode autorizar o acesso com uma conta de serviço através de um ficheiro de credenciais armazenado no seu sistema de ficheiros local. Esta credencial pode ser uma credencial de utilizador com autorização para se fazer passar pela conta de serviço, um ficheiro de configuração de credenciais para a federação de identidades da carga de trabalho ou uma chave de conta de serviço.

Autorize uma conta de serviço através da simulação de conta de serviço

Para autorizar a CLI gcloud a usar credenciais de contas de serviço roubadas, faça o seguinte:

  1. Na Trusted Cloud consola, aceda à página Contas de serviço.

    Aceda a Contas de serviço

  2. Escolha uma conta existente ou crie uma nova clicando em Criar conta de serviço.

  3. Para receber a autorização de que precisa para se fazer passar por uma conta de serviço, peça ao seu administrador para lhe conceder a função IAM Criador de tokens de contas de serviço (roles/iam.serviceAccountTokenCreator) na conta de serviço. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

    Esta função predefinida contém a autorização iam.serviceAccounts.getAccessToken , que é necessária para usar a identidade de uma conta de serviço.

    Também pode obter esta autorização com funções personalizadas ou outras funções predefinidas.

  4. Autorize a CLI gcloud com a sua identidade de utilizador executando o comando gcloud auth login.

  5. Para configurar a CLI gcloud para usar a identidade e o acesso fornecidos por uma conta de serviço por predefinição, use o comando config da CLI gcloud:

    gcloud config set auth/impersonate_service_account SERVICE_ACCT_EMAIL

  6. Para deixar de usar as credenciais da conta de serviço roubadas por predefinição com a CLI gcloud, anule a definição da flag com o comando de configuração da CLI gcloud:

    gcloud config unset auth/impersonate_service_account

Autorize uma conta de serviço através da federação de identidades da carga de trabalho

Para autorizar a CLI gcloud com uma conta de serviço através de credenciais externas da federação de identidades da carga de trabalho, faça o seguinte:

  1. Na Trusted Cloud consola, aceda à página Contas de serviço.

    Aceda a Contas de serviço

  2. Escolha uma conta existente ou crie uma nova clicando em Criar conta de serviço.

  3. Crie um ficheiro de configuração de credenciais para a federação de identidade da carga de trabalho seguindo as instruções do seu Fornecedor de identidade suportado.

  4. Para ativar a sua conta de serviço, execute o comando gcloud auth login com a flag --cred-file:

    gcloud auth login --cred-file=CONFIGURATION_FILE

    Substitua CONFIGURATION_FILE pelo caminho para um ficheiro de configuração de credenciais para a federação de identidade da carga de trabalho.

Autorize uma conta de serviço através de uma chave de conta de serviço

Para autorizar a CLI gcloud com uma conta de serviço através de uma chave da conta de serviço, faça o seguinte:

  1. Na Trusted Cloud consola, aceda à página Contas de serviço.

    Aceda a Contas de serviço

  2. Escolha uma conta existente ou crie uma nova clicando em Criar conta de serviço.

  3. Para criar chaves de contas de serviço, consulte as instruções do IAM para criar uma chave de conta de serviço.

  4. Para ativar a sua conta de serviço, execute o comando gcloud auth login com a flag --cred-file:

    gcloud auth login --cred-file=KEY_FILE

    Substitua KEY_FILE pelo caminho para um ficheiro de chave de conta de serviço.

Listar contas

Para listar as contas cujas credenciais estão armazenadas no sistema local, execute o comando gcloud auth list:

gcloud auth list

A CLI gcloud lista as contas e mostra qual está ativa:

Credentialed accounts:
 - user-1@gmail.com (active)
 - user-2@gmail.com

Mude a conta ativa

Para mudar a conta ativa, execute o comando gcloud config set:

gcloud config set account ACCOUNT

em que [ACCOUNT] é o endereço de email completo da conta.

Também pode alternar entre contas criando uma configuração separada que especifique a conta diferente e alternando entre configurações:

gcloud config configurations activate CONFIGURATION

Se quiser mudar a conta usada pela CLI gcloud por invocação, substitua a conta ativa usando a flag --account.

Defina a duração da sessão autorizada

Enquanto administrador, pode controlar durante quanto tempo diferentes utilizadores podem aceder à CLI gcloud sem terem de se autenticar novamente. Por exemplo, pode forçar os utilizadores com privilégios elevados a autenticarem-se novamente com mais frequência do que os utilizadores normais.

Para mais informações, consulte o artigo Defina a duração da sessão para os Trusted Cloud serviços.

Revogue as credenciais de uma conta

Pode revogar as credenciais quando quiser impedir o acesso da CLI gcloud por uma conta específica. Não precisa de revogar as credenciais para alternar entre contas.

Para revogar credenciais, execute o comando gcloud auth revoke:

gcloud auth revoke ACCOUNT

Para revogar todo o acesso para a CLI gcloud para todas as máquinas, remova a CLI gcloud da lista de apps que têm acesso à sua conta.

Trabalhe com ficheiros de credenciais

Encontre os seus ficheiros de credenciais

Para encontrar a localização dos ficheiros de credenciais, execute o seguinte comando gcloud info:

gcloud info

A CLI gcloud imprime informações sobre a sua instalação. Os ficheiros de credenciais são armazenados no diretório de configuração do utilizador:

User Config Directory: [/home/USERNAME/.config/gcloud]

Configure as Credenciais padrão da aplicação

A CLI gcloud oferece suporte para a gestão de credenciais predefinidas da aplicação (ADC) com o grupo de comandos gcloud auth application-default. Para disponibilizar as credenciais do utilizador ao ADC, execute o seguinte comando: gcloud auth application-default login

gcloud auth application-default login

Estas credenciais não são usadas pela CLI gcloud. Para mais formas de configurar as ADC, consulte o artigo Configure as Credenciais padrão da aplicação.

unset GOOGLE_APPLICATION_CREDENTIALS
gcloud config unset auth/impersonate_service_account
gcloud auth application-default login

O que se segue?