Autenticar para usar REST

Nesta página, descrevemos como autenticar ao fazer uma solicitação REST para uma API do Google.

Para mais informações sobre como autenticar usando bibliotecas de cliente do Google, consulte Autenticar usando bibliotecas de cliente.

Antes de começar

Para executar as amostras nesta página, siga estas etapas:

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command: 

    gcloud init

  3. Enable the Cloud Resource Manager and Identity and Access Management (IAM) APIs: 

    gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

Se você não quiser usar a CLI gcloud, pule estas etapas e use a identidade temporária de conta de serviço ou o servidor de metadados para gerar um token.

Tipos de credenciais

É possível usar os seguintes tipos de credenciais para autenticar uma chamada REST:

  • Suas credenciais da gcloud CLI.

    Essa abordagem é a maneira mais fácil e segura de fornecer credenciais para um método REST em um ambiente de desenvolvimento local. Se a conta de usuário tiver as permissões de gerenciamento de identidade e acesso (IAM) necessárias para o método que você quer chamar, essa é a abordagem preferencial.

    As credenciais da gcloud não são iguais às fornecidas ao ADC pela CLI gcloud. Para mais informações, consulte Configuração de autenticação da gcloud CLI e configuração do ADC.

  • Credenciais fornecidas ao Application Default Credentials (ADC).

    Esse método é a opção preferida para autenticar uma chamada REST em um ambiente de produção, porque o ADC encontra credenciais do recurso em que o código está sendo executado, tal como uma máquina virtual do Compute Engine. Você também pode usar o ADC para autenticação em um ambiente de desenvolvimento local. Nesse cenário, a CLI da gcloud cria um arquivo que contém suas credenciais no sistema de arquivos local.

  • As credenciais fornecidas ao representar uma conta de serviço.

    Esse método requer mais configuração. Se você quiser usar suas credenciais atuais para conseguir credenciais de curta duração para outra conta de serviço, como testar com uma conta de serviço localmente ou solicitar privilégios temporários, use essa abordagem.

  • As credenciais retornadas pelo servidor de metadados.

    Esse método funciona apenas em ambientes com acesso a um servidor de metadados. As credenciais retornadas pelo servidor de metadados são as mesmas que seriam encontradas pelo Application Default Credentials usando a conta de serviço anexada, mas você solicita o token de acesso explicitamente. ao servidor de metadados e fornece a ele a solicitação REST. Consultar as credenciais no servidor de metadados requer uma solicitação GET HTTP. Esse método não depende da CLI do Google Cloud.

Credenciais da CLI gcloud

Para executar o exemplo abaixo, você precisa da permissão resourcemanager.projects.get no projeto. A permissão resourcemanager.projects.get está incluída em vários papéis, por exemplo, o papel de navegador (roles/browser).

  1. Use o comando gcloud auth print-access-token para inserir um token de acesso gerado por suas credenciais de usuário.

    O exemplo a seguir recebe detalhes do projeto especificado. É possível usar o mesmo padrão em qualquer solicitação REST.

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

    • PROJECT_ID: o nome ou ID do projeto do Google Cloud.

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

    curl

    Execute o seguinte comando: 

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

    PowerShell

    execute o seguinte comando: 

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

    Os detalhes do projeto são retornados.

Para APIs que exigem um projeto de cota, é preciso definir um explicitamente para a solicitação. Para mais informações, consulte Definir o projeto de cota com uma solicitação REST nesta página.

Application Default Credentials

Para executar o exemplo abaixo, o principal associado às credenciais fornecidas ao ADC precisa da permissão resourcemanager.projects.get no projeto. A permissão resourcemanager.projects.get está incluída em vários papéis, por exemplo, o papel de navegador (roles/browser).

  1. Forneça credenciais para o ADC.

    Se você estiver executando em um recurso de computação do Google Cloud, não forneça suas credenciais de usuário ao ADC. Em vez disso, use a conta de serviço anexada para fornecer credenciais. Para mais informações, consulte Serviços que aceitam a anexação de uma conta de serviço.

  2. Use o comando gcloud auth application-default print-access-token para inserir o token de acesso retornado pelo ADC na sua solicitação REST.

    O exemplo a seguir recebe detalhes do projeto especificado. É possível usar o mesmo padrão em qualquer solicitação REST.

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

    • PROJECT_ID: o nome ou ID do projeto do Google Cloud.

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

    curl

    Execute o seguinte comando: 

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
         "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

    PowerShell

    execute o seguinte comando: 

    $cred = gcloud auth application-default print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

    Os detalhes do projeto são retornados.

    Se a sua solicitação retornar uma mensagem de erro informando que as credenciais do usuário final não são compatíveis com essa API, consulte Definir o projeto de cota com uma solicitação REST nesta página.

Conta de serviço representada

A maneira mais simples de falsificar uma conta de serviço para gerar um token de acesso é usando a CLI gcloud. No entanto, se você precisar gerar o token programaticamente ou não quiser usar a CLI gcloud, use a usurpação de identidade para gerar um token de curta duração.

Para mais informações sobre como representar uma conta de serviço, consulte Usar representação de conta de serviço.

  1. Revise as permissões necessárias.

    • O principal que você quer usar para realizar a representação precisa ter a permissão iam.serviceAccounts.getAccessToken na conta de serviço representada, também chamada de conta de serviço com privilégios. A permissão iam.serviceAccounts.getAccessToken está incluída no papel de criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator). Se você estiver usando sua conta de usuário, adicione essa permissão mesmo que tenha o papel de proprietário (roles/owner) no projeto. Para mais informações, consulte Como definir as permissões necessárias.

  2. Identifique ou crie a conta de serviço com privilégios: a conta de serviço que você representará.

    A conta de serviço com privilégios precisa ter as permissões necessárias para fazer a chamada do método da API.

gcloud

  1. Use o comando gcloud auth print-access-token com a sinalização --impersonate-service-account para inserir um token de acesso na conta de serviço com privilégios na solicitação REST.

O exemplo a seguir recebe detalhes do projeto especificado. É possível usar o mesmo padrão em qualquer solicitação REST.

Para executar este exemplo, a conta de serviço que você representa precisa da permissão resourcemanager.projects.get. A permissão resourcemanager.projects.get está incluída em vários papéis, por exemplo, o papel de navegador (roles/browser).

Faça as seguintes substituições:

  • PRIV_SA: clique no endereço de e-mail da conta de serviço com privilégios. Por exemplo, my-sa@my-project.iam.gserviceaccount.com.

  • PROJECT_ID: o nome ou ID do projeto do Google Cloud.

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account=PRIV_SA)" \
    "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

Token de curta duração

Para gerar um token de curta duração usando a representação de conta de serviço, siga as instruções em Criar um token de acesso de curta duração.

Servidor de metadados

Para receber um token de acesso do servidor de metadados, faça a chamada REST usando um dos serviços que têm acesso a um servidor:

Use uma ferramenta de linha de comando, como curl, para receber um token de acesso e inseri-lo na solicitação REST.

  1. Consulte um token de acesso no servidor de metadados:

    curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \
    -H "Metadata-Flavor: Google"

    O pedido retorna uma resposta semelhante ao exemplo a seguir:

    {
      "access_token":"ya29.AHES6ZRN3-HlhAPya30GnW_bHSb_QtAi85nHq39HE3C2LTrCARA",
      "expires_in":3599,
      "token_type":"Bearer"
 }

  2. Insira o token de acesso na solicitação REST, fazendo as seguintes substituições:

    • ACCESS_TOKEN: o token de acesso retornado na etapa anterior.
    • PROJECT_ID: o nome ou ID do projeto do Google Cloud.
    curl -X GET \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

Definir o projeto de cota com uma solicitação REST

Para chamar algumas APIs com credenciais de usuário, também é ciso definir o projeto que será faturado pelo uso e usado para rastrear a cota. Se a chamada de API retornar uma mensagem de erro informando que as credenciais do usuário não são compatíveis ou que o projeto de cota não está definido, é necessário definir explicitamente o projeto de cota para a solicitação. Para definir o projeto de cota, inclua o cabeçalho x-goog-user-project na solicitação.

Para saber mais sobre quando você pode encontrar esse problema, consulte Credenciais do usuário que não funcionam.

Você precisa ter a permissão do IAM serviceusage.services.use para que um projeto possa designá-lo como seu projeto de faturamento. A permissão serviceusage.services.use está incluída no papel de IAM de consumidor do Service Usage. Se você não tiver a permissão serviceusage.services.use para nenhum projeto, entre em contato com o administrador de segurança ou um proprietário do projeto que possa conceder a você o papel Consumidor do Service Usage no projeto.

O exemplo a seguir usa a API Cloud Translation para traduzir a palavra "hello" para o espanhol. A API Cloud Translation precisa ser especificada por um projeto de cota. Para executar o exemplo, crie um arquivo chamado request.json com o conteúdo do corpo da solicitação.

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

  • PROJECT_ID: o ID ou o nome do projeto do Google Cloud a ser usado como projeto de faturamento.

Corpo JSON da solicitação:

{
  "q": "hello",
  "source": "en",
  "target": "es"
}

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

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://translation.googleapis.com/language/translate/v2"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://translation.googleapis.com/language/translate/v2" | Select-Object -Expand Content

A solicitação de tradução foi concluída. Você pode testar o comando sem o cabeçalho x-goog-user-project para ver o que acontece quando você não especifica o projeto de faturamento.

A seguir