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

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Esta página descreve como usar contas de serviço para permitir que aplicativos em execução nas instâncias de máquina virtual (VM) se autentiquem Google Cloud APIs e autorizar o acesso aos recursos.

Para usar contas de serviço para autenticação, primeiro você deve garantir que sua VM esteja configurada para usar uma conta de serviço. Para fazer isso, execute um dos seguintes procedimentos:

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

Antes de começar

• Revise a visão geral das contas de serviço .
• Se ainda não o fez, configure a autenticação. Autenticação é o processo pelo qual sua identidade é verificada para acesso a Google Cloud serviços e APIs. Para executar códigos ou amostras em um ambiente de desenvolvimento local, você pode se autenticar 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. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

     gcloud init

  4. 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.

     If an authentication error is returned, confirm that you have configured the gcloud CLI to use Workforce Identity Federation.

  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 usando uma conta de serviço, um aplicativo em execução na instância de VM poderá usar um dos seguintes métodos de autenticação:

• Para a maioria dos aplicativos, escolha um dos seguintes:
  • Use credenciais padrão do aplicativo e uma biblioteca de cliente
  • Usar a CLI do Google Cloud
• Para aplicativos que exigem um token de acesso OAuth2, solicite e use tokens de acesso diretamente do servidor de metadados

Autenticação de aplicativos usando credenciais de conta de serviço

Depois de configurar uma instância para execução 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.

Autenticando aplicativos com uma biblioteca cliente

As bibliotecas cliente podem usar credenciais padrão do aplicativo para autenticar com APIs do Google e enviar solicitações para essas APIs. As credenciais padrão do aplicativo permitem que os aplicativos obtenham credenciais automaticamente de várias fontes para que você possa testar seu aplicativo localmente e implantá-lo em uma instância do Compute Engine sem alterar o código do aplicativo.

Para obter informações sobre como configurar credenciais padrão do aplicativo, consulte Fornecer credenciais para credenciais padrão do aplicativo .

Este exemplo usa a biblioteca cliente Python para autenticar e fazer uma solicitação à API Cloud Storage para listar os buckets em um projeto. O exemplo usa o seguinte procedimento:

1. Obtenha as credenciais de autenticação necessárias para a API Cloud Storage e inicialize o serviço Cloud Storage com o método build() e as credenciais.
2. Liste intervalos no Cloud Storage.

Você pode executar este exemplo 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)

Autenticando aplicativos diretamente com tokens de acesso

Para a maioria dos aplicativos, você pode autenticar usando Application Default Credentials , que localiza credenciais e gerencia tokens para você. No entanto, se seu 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 em seu aplicativo.

Existem diversas opções para obter e usar esses tokens de acesso para autenticar suas aplicações. Por exemplo, você pode usar curl para criar uma solicitação simples ou usar uma linguagem de programação como Python para obter 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 após um curto período de tempo. O servidor de metadados armazena em cache os tokens de acesso até que tenham 5 minutos restantes antes de expirarem. Se os tokens não puderem ser armazenados em cache, as solicitações que excederem 50 consultas por segundo poderão ter taxa limitada. Seus aplicativos devem ter um token de acesso válido para que suas 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 CLI gcloud, que é incluída por padrão na maioria das imagens do Compute Engine. A CLI gcloud 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, poderá usar a CLI gcloud nas suas instâncias sem precisar usar gcloud auth login .

Esse reconhecimento da conta de serviço acontece automaticamente e se aplica somente à CLI gcloud incluída na instância. Se você criar novas ferramentas ou adicionar ferramentas personalizadas, deverá autorizar seu aplicativo usando uma biblioteca cliente ou usando tokens de acesso diretamente em seu 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 conta de serviço à instância . Por exemplo, se você conceder a uma conta de serviço o papel roles/storage.objectAdmin , a CLI gcloud poderá gerenciar e acessar automaticamente objetos do Cloud Storage.

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

O que vem a seguir

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