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:

• Para configurar a conta de serviço durante a criação da VM, consulte Criar uma VM que usa uma conta de serviço gerenciada pelo usuário.
• Para configurar a conta de serviço em uma VM atual, consulte Alterar a conta de serviço anexada.

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 da seguinte maneira.
  

  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:

• Para a maioria dos aplicativos, escolha uma das seguintes opções:
  • Use o Application Default Credentials e uma biblioteca de cliente
  • Use a Google Cloud CLI
• Para aplicativos que exigem um token de acesso OAuth2, solicite e use tokens de acesso diretamente do servidor de metadados

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.

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

• Autenticar cargas de trabalho em outras cargas de trabalho por mTLS.
• Saiba mais sobre Contas de serviço.
• Saiba mais sobre papéis e permissões do IAM do Compute Engine.
• Saiba mais sobre as práticas recomendadas para trabalhar com as contas de serviço.