Autenticar cargas de trabalho nas APIs do Google Cloud usando contas de serviço

Nesta página, descrevemos como usar contas de serviço para permitir que aplicativos executados nas suas instâncias de máquina virtual (VM) sejam autenticados nas APIs do Google Cloud e autorizem o acesso a recursos.

Antes de usar contas de serviço na autenticação, verifique se a VM está configurada para usar uma conta de serviço. Para fazer isso, siga um destes procedimentos:

Antes de começar

  • Leia a visão geral das contas de serviço.
  • Configure a autenticação, caso ainda não tenha feito isso. A autenticação é o processo de verificação da sua identidade para acesso a serviços e APIs do Google Cloud. Para executar códigos ou amostras de um ambiente de desenvolvimento local, autentique-se no Compute Engine selecionando uma das seguintes opções:

    Para usar os exemplos Python desta página em um ambiente de desenvolvimento local, instale e inicialize o gcloud CLI e e configure o Application Default Credentials com suas credenciais de usuário.

    1. Install the Google Cloud CLI.

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

      gcloud init

    3. If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

    Confira mais informações em Set up authentication for a local development environment.

Visão geral

Depois de configurar uma instância de VM para execução com uma conta de serviço, o aplicativo em execução na instância da VM pode usar um dos seguintes métodos de autenticação:

Como autenticar aplicativos usando credenciais da conta de serviço

Depois de configurar uma instância para executar como uma conta de serviço, você poderá usar as credenciais da conta de serviço para autenticar aplicativos em execução na instância.

Como autenticar aplicativos com uma biblioteca de cliente

Bibliotecas de cliente podem usar Application Default Credentials para se autenticar com Google APIs e enviar solicitações a elas. O Application Default Credentials permite que os aplicativos consigam automaticamente credenciais de várias fontes para que você possa testar o aplicativo localmente e implementá-lo em uma instância do Compute Engine sem alterar o código do aplicativo.

Para ver informações sobre como configurar o Application Default Credentials, consulte Fornecer credenciais para credenciais padrão do aplicativo.

Neste exemplo, a Biblioteca de cliente Python é usada para autenticar e fazer uma solicitação à API do Cloud Storage para listar os buckets em um projeto. Este é o procedimento seguido:

  1. Consiga as credenciais de autenticação necessárias para a API do Cloud Storage e inicie o serviço do produto com o método build() e as credenciais.
  2. Liste os buckets no Cloud Storage.

Execute esta amostra em uma instância que tenha acesso para gerenciar buckets no Cloud Storage.

import argparse
from typing import List

from google.cloud import storage


def create_client() -> storage.Client:
    """
    Construct a client object for the Storage API using the
    application default credentials.

    Returns:
        Storage API client object.
    """
    # Construct the service object for interacting with the Cloud Storage API -
    # the 'storage' service, at version 'v1'.
    # Authentication is provided by application default credentials.
    # When running locally, these are available after running
    # `gcloud auth application-default login`. When running on Compute
    # Engine, these are available from the environment.
    return storage.Client()


def list_buckets(client: storage.Client, project_id: str) -> List[storage.Bucket]:
    """
    Retrieve bucket list of a project using provided client object.


    Args:
        client: Storage API client object.
        project_id: name of the project to list buckets from.

    Returns:
        List of Buckets found in the project.
    """
    buckets = client.list_buckets()
    return list(buckets)


def main(project_id: str) -> None:
    client = create_client()
    buckets = list_buckets(client, project_id)
    print(buckets)


if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
    )
    parser.add_argument("project_id", help="Your Google Cloud Project ID.")

    args = parser.parse_args()

    main(args.project_id)

Como autenticar aplicativos diretamente com tokens de acesso

Na maioria dos aplicativos, é possível autenticar usando o Application Default Credentials, que encontra credenciais e gerencia tokens para você. No entanto, se o aplicativo exigir que você forneça um token de acesso OAuth2, o Compute Engine permitirá que você receba um token de acesso do servidor de metadados para uso no aplicativo.

Há várias opções para conseguir e usar esses tokens de acesso para autenticar os aplicativos. Por exemplo, use o curl para criar uma solicitação simples ou utilize uma linguagem de programação como o Python para ter mais flexibilidade.

cURL

Para usar o curl para solicitar um token de acesso e enviar uma solicitação a uma API:

  1. Na instância em que o aplicativo é executado, consulte o servidor de metadados para conseguir um token de acesso executando o seguinte comando:

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

    A solicitação retorna uma resposta assim:

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

    Para solicitações de API, é necessário incluir o valor access_token, e não toda a resposta. Se você tiver o processador JSON da linha de comando jq instalado, poderá usar o seguinte comando para extrair o valor do token de acesso da resposta:

    $ ACCESS_TOKEN=`curl \
"http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \
-H "Metadata-Flavor: Google" | jq -r '.access_token'`

  2. Copie o valor da propriedade access_token da resposta e use-o para enviar solicitações para a API. Por exemplo, a solicitação a seguir imprime uma lista de instâncias no projeto a partir de uma determinada zona:

    $ curl https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances \
-H "Authorization":"Bearer ACCESS_TOKEN"

    Substitua:

    • PROJECT_ID: o ID do projeto para essa solicitação.
    • ZONE: a zona da lista de VMs.
    • ACCESS_TOKEN: o valor do token de acesso que você recebeu na etapa anterior.

    Para informações sobre os parâmetros que podem ser definidos na solicitação, consulte a documentação Parâmetros do sistema.

Python

Veja neste exemplo como solicitar um token para acessar a API Cloud Storage em um aplicativo Python. Este é o procedimento seguido:

  1. Solicite um token de acesso do servidor de metadados.
  2. Extraia o token de acesso da resposta do servidor.
  3. Use o token de acesso para fazer uma solicitação ao Cloud Storage.
  4. Se a solicitação for bem-sucedida, o script imprimirá a resposta.

import argparse

import requests


METADATA_URL = "http://metadata.google.internal/computeMetadata/v1/"
METADATA_HEADERS = {"Metadata-Flavor": "Google"}
SERVICE_ACCOUNT = "default"


def get_access_token() -> str:
    """
    Retrieves access token from the metadata server.

    Returns:
        The access token.
    """
    url = f"{METADATA_URL}instance/service-accounts/{SERVICE_ACCOUNT}/token"

    # Request an access token from the metadata server.
    r = requests.get(url, headers=METADATA_HEADERS)
    r.raise_for_status()

    # Extract the access token from the response.
    access_token = r.json()["access_token"]

    return access_token


def list_buckets(project_id: str, access_token: str) -> dict:
    """
    Calls Storage API to retrieve a list of buckets.

    Args:
        project_id: name of the project to list buckets from.
        access_token: access token to authenticate with.

    Returns:
        Response from the API.
    """
    url = "https://www.googleapis.com/storage/v1/b"
    params = {"project": project_id}
    headers = {"Authorization": f"Bearer {access_token}"}

    r = requests.get(url, params=params, headers=headers)
    r.raise_for_status()

    return r.json()


def main(project_id: str) -> None:
    """
    Retrieves access token from metadata server and uses it to list
    buckets in a project.

    Args:
        project_id: name of the project to list buckets from.
    """
    access_token = get_access_token()
    buckets = list_buckets(project_id, access_token)
    print(buckets)


if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
    )
    parser.add_argument("project_id", help="Your Google Cloud project ID.")

    args = parser.parse_args()

    main(args.project_id)

Os tokens de acesso expiram depois de um período curto. O servidor de metadados armazena em cache os tokens de acesso até que tenham cinco minutos de tempo restante antes que eles expirem. Se os tokens não puderem ser armazenados em cache, as solicitações que excederem 50 consultas por segundo poderão ter limitação de taxa. Os aplicativos precisam ter um token de acesso válido para que as chamadas de API sejam bem-sucedidas.

Como autenticar ferramentas em uma instância usando uma conta de serviço

Alguns aplicativos podem usar comandos da gcloud CLI, que são incluídos por padrão na maioria das imagens do Compute Engine. A gcloud CLI reconhece automaticamente a conta de serviço de uma instância e as permissões relevantes concedidas à conta de serviço. Especificamente, se você conceder os papéis corretos à conta de serviço, será possível usar a gcloud CLI a partir das instâncias e sem precisar utilizar gcloud auth login.

Esse reconhecimento da conta de serviço acontece automaticamente e se aplica somente à gcloud CLI incluída na instância. Se você criar novas ferramentas ou adicionar ferramentas personalizadas, precisará autorizar o aplicativo usando uma biblioteca de cliente ou usando tokens de acesso diretamente no aplicativo.

Para aproveitar o reconhecimento automático da conta de serviço, conceda os papéis do IAM apropriados à conta de serviço e anexe-a à instância. Por exemplo, se você conceder o papel roles/storage.objectAdmin a uma conta de serviço, a gcloud CLI poderá gerenciar e acessar objetos do Cloud Storage automaticamente.

Da mesma forma, se você ativar roles/compute.instanceAdmin.v1 na conta de serviço, a ferramenta gcloud compute poderá gerenciar instâncias automaticamente.

A seguir

Faça um teste

Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho do Compute Engine em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

Faça uma avaliação gratuita do Compute Engine