Autenticar com a API Cloud Workstations

Neste documento, descrevemos como autenticar para o Cloud Workstations de maneira programática. O modo de autenticação no Cloud Workstations depende da interface usada para acessar a API e do ambiente em que o código está em execução.

Se você não conhece a API Cloud Workstations, leia as seções a seguir primeiro:

Para mais informações sobre a Google Cloud autenticação, consulte os métodos de autenticação.

Acesso à API

O Cloud Workstations oferece suporte ao acesso programático. É possível acessar a API das seguintes maneiras:

Bibliotecas de cliente

As bibliotecas de cliente do Cloud Workstations oferecem suporte de linguagem de alto nível para autenticação programática no Cloud Workstations. Para autenticar chamadas às Google Cloud APIs do, as bibliotecas de cliente oferecem suporte ao Application Default Credentials (ADC); as bibliotecas procuram credenciais em um conjunto de locais definidos e as usam para autenticar solicitações à API. Com o ADC, é possível disponibilizar credenciais ao aplicativo em uma variedade de ambientes, como de desenvolvimento ou produção local, sem precisar modificar o código do aplicativo.

Google Cloud CLI

Ao usar a gcloud CLI para acessar o Cloud Workstations, você faz login na gcloud CLI com uma conta de usuário que fornece as credenciais usadas pelos comandos da gcloud CLI.

Se as políticas de segurança da sua organização impedirem que as contas de usuário tenham as permissões necessárias é possível usar a identidade temporária de conta de serviço.

Para mais informações, consulte Autenticar-se para usar a CLI gcloud. Para mais informações sobre como usar a CLI gcloud com o Cloud Workstations, consulte Estações de trabalho do gcloud.

REST

É possível autenticar-se na API Cloud Workstations usando as credenciais da gcloud CLI ou usando Application Default Credentials. Para mais informações sobre a autenticação para solicitações REST, consulte Autenticar-se usando REST. Para informações sobre os tipos de credenciais, consulte gcloud credenciais da CLI e do ADC.

Configurar a autenticação do Cloud Workstations

A configuração da autenticação depende do ambiente em que o código está sendo executado.

As opções a seguir para configuração da autenticação são as mais usadas. Para mais opções e informações sobre autenticação, consulte Métodos de autenticação.

Antes de seguir estas instruções, conclua a configuração básica do Cloud Workstations, conforme descrito em Antes de começar.

Para um ambiente de desenvolvimento local

É possível configurar credenciais para um ambiente de desenvolvimento local das seguintes maneiras:

Bibliotecas de cliente ou ferramentas de terceiros

Configure Application Default Credentials (ADC) no ambiente local:

  1. Instale a Google Cloud CLI. Após a instalação, inicialize a Google Cloud CLI executando o seguinte comando: 

    gcloud init

    Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

  2. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário: 

    gcloud auth application-default login

    Não é necessário fazer isso se você estiver usando o Cloud Shell.

    Se um erro de autenticação for retornado e você estiver usando um provedor de identidade (IdP) externo, confirme se você fez login na gcloud CLI com sua identidade federada.

    Uma tela de login é exibida. Após o login, suas credenciais são armazenadas no arquivo de credenciais local usado pelo ADC.

Para saber como trabalhar com o ADC em um ambiente local, consulte Configurar o ADC para um ambiente de desenvolvimento local.

Solicitações REST usando a linha de comando

Ao fazer uma solicitação REST usando a linha de comando, use as credenciais da CLI gcloud incluindo gcloud auth print-access-token como parte do comando que envia a solicitação.

No exemplo a seguir, listamos as contas de serviço do projeto especificado. É possível usar o mesmo padrão em qualquer solicitação REST.

Antes de usar os dados da solicitação, faça as seguintes substituições:

  • PROJECT_ID: o ID do projeto do Google Cloud .

Para enviar a solicitação, expanda uma destas opções:

 

Para saber como autenticar-se usando REST e gRPC, consulte Autenticar-se para usar REST. Para mais informações sobre a diferença entre as credenciais locais do ADC e as credenciais da gcloud CLI, consulte gcloud Configuração da autenticação da CLI e configuração do ADC.

identidade temporária de conta de serviço.

Na maioria dos casos, é possível usar as credenciais de usuário para se autenticar em um ambiente de desenvolvimento local. Se isso não for viável ou for preciso testar as permissões atribuídas a uma conta de serviço, use a identidade temporária de conta de serviço. Você precisa ter a iam.serviceAccounts.getAccessToken permissão, que é incluída no papel do IAM de Criador de tokens da conta de serviço (roles/iam.serviceAccountTokenCreator).

Configure a CLI gcloud para usar a identidade temporária de conta de serviço com o gcloud config set comando: 

gcloud config set auth/impersonate_service_account SERVICE_ACCT_EMAIL

Em algumas linguagens, é possível usar a identidade temporária de conta de serviço para criar um arquivo local do ADC para ser usado pelas bibliotecas de cliente. Essa abordagem só é aceita nas bibliotecas de cliente Go, Java, Node.js e Python. Não há suporte a ela em outras linguagens. Para configurar um arquivo local do ADC com a identidade temporária de conta de serviço, use a flag --impersonate-service-account com o comando gcloud auth application-default login: 

gcloud auth application-default login --impersonate-service-account=SERVICE_ACCT_EMAIL

Para mais informações sobre a identidade temporária de conta de serviço, consulte Usar a identidade temporária de conta de serviço.

No Google Cloud

Para autenticar uma carga de trabalho em execução no Google Cloud, use as credenciais da conta de serviço anexada ao recurso de computação em que o código está sendo executado, como uma instância de máquina virtual (VM) do Compute Engine. Essa abordagem é o método de autenticação preferencial para códigos em execução em um recurso de computação do Google Cloud .

Para a maioria dos serviços, você precisa anexar a conta de serviço ao criar o recurso que vai executar o código. Não é possível adicionar ou substituir essa conta de serviço mais tarde. O Compute Engine é uma exceção. Ele permite anexar uma conta de serviço a uma instância de VM a qualquer momento.

Use a CLI gcloud para criar uma conta de serviço e anexá-la ao seu recurso:

  1. Instale a Google Cloud CLI. Após a instalação, inicialize a Google Cloud CLI executando o seguinte comando: 

    gcloud init

    Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

  2. Configure a autenticação:

    1. Verifique se você tem o papel do IAM de Criador de contas de serviço (roles/iam.serviceAccountCreator) e o papel de administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin). Saiba como conceder papéis.

    2. Crie a conta de serviço: 

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Substitua SERVICE_ACCOUNT_NAME por um nome para a conta de serviço.

    3. Para conceder acesso ao projeto e aos recursos, conceda um papel à conta de serviço: 

      gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

      Substitua:

      • SERVICE_ACCOUNT_NAME: o nome da conta de serviço.
      • PROJECT_ID: o ID do projeto em que você criou a conta de serviço
      • ROLE: o papel a ser concedido
    4. Para conceder outro papel à conta de serviço, execute o comando que você fez na etapa anterior.

    5. Conceda o papel necessário ao principal que vai anexar a conta de serviço a outros recursos. 

      gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

      Substitua:

      • SERVICE_ACCOUNT_NAME: o nome da conta de serviço.
      • PROJECT_ID: o ID do projeto em que você criou a conta de serviço
      • USER_EMAIL: o endereço de e-mail de uma Conta do Google

  3. Crie o recurso que vai executar o código e anexe a conta de serviço a esse recurso. Por exemplo, se você usar o Compute Engine:

    Crie uma instância do Compute Engine. Configure a instância da seguinte maneira:
    • Substitua INSTANCE_NAME pelo nome de instância que quiser usar.
    • Defina a flag --zone com a zona em que a instância será criada.
    • Defina a flag --service-account com o endereço de e-mail da conta de serviço que você criou. 
    gcloud compute instances create INSTANCE_NAME --zone=ZONE --service-account=SERVICE_ACCOUNT_EMAIL

Para mais informações sobre a autenticação nas APIs do Google, consulte Métodos de autenticação.

No local ou em outro provedor de nuvem

O método preferencial para configurar a autenticação de fora do Google Cloud é usar a federação de identidade da carga de trabalho. Para mais informações, consulte Configurar o ADC para um ambiente local ou outro provedor de nuvem na documentação de autenticação.

Controle de acesso para o Cloud Workstations

Depois de se autenticar no Cloud Workstations, você precisa ter autorização para acessar Google Cloud recursos. O Cloud Workstations usa Identity and Access Management (IAM) para autorização.

Para mais informações sobre os papéis do Cloud Workstations, consulte Controle de acesso com o IAM. Para mais informações sobre o IAM e a autorização, consulte Visão geral do IAM.

A seguir