Como configurar a autenticação em aplicativos de produção de servidor para servidor

Neste guia, você verá como configurar a autenticação e a autorização para aplicativos de produção de servidor para servidor nas APIs do Google Cloud. A autenticação é o processo de determinar a identidade de um cliente. Autorização é ao processo de determinar quais permissões um cliente autenticado tem em um recurso específico. Ou seja, a autenticação identifica quem você é, e a autorização determina o que você pode fazer. Para mais informações sobre os métodos de autenticação compatíveis e como escolhê-los, consulte a Visão geral da autenticação.

O Google usa credenciais para identificar seu aplicativo para cota e faturamento. Suas credenciais também são usadas para autorizar o acesso às APIs, aos recursos e às funcionalidades do Google Cloud.

Como fornecer credenciais para um aplicativo

Como encontrar credenciais automaticamente

As bibliotecas de cliente do Google Cloud usam o serviço Application Default Credentials (ADC) como estratégia para localizar as credenciais de seu aplicativo. Quando o código usa uma biblioteca de cliente, as credenciais são verificadas pela estratégia na seguinte ordem:

  1. Primeiro, o ADC verifica se a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS está configurada. Caso esteja, o arquivo da conta de serviço apontado pela variável será usado. A próxima seção descreve como definir a variável de ambiente.

  2. Se a variável de ambiente não estiver configurada, o ADC usará a conta de serviço padrão fornecida pelo Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine e Cloud Functions para aplicativos executados nesses serviços.

  3. Caso o ADC não use nenhuma das credenciais acima, um erro é gerado.

O exemplo de código a seguir ilustra essa estratégia. O exemplo não especifica explicitamente as credenciais do aplicativo. No entanto, o ADC é capaz de localizar as credenciais implicitamente, desde que a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS esteja configurada ou o aplicativo esteja em execução no Compute Engine, GKE, App Engine ou Cloud Functions.

É necessário instalar a biblioteca de cliente do Cloud Storage para executar o exemplo a seguir.

C#

public object AuthImplicit(string projectId)
{
    // If you don't specify credentials when constructing the client, the
    // client library will look for credentials in the environment.
    var credential = GoogleCredential.GetApplicationDefault();
    var storage = StorageClient.Create(credential);
    // Make an authenticated API request.
    var buckets = storage.ListBuckets(projectId);
    foreach (var bucket in buckets)
    {
        Console.WriteLine(bucket.Name);
    }
    return null;
}

Go


// implicit uses Application Default Credentials to authenticate.
func implicit() {
	ctx := context.Background()

	// For API packages whose import path is starting with "cloud.google.com/go",
	// such as cloud.google.com/go/storage in this case, if there are no credentials
	// provided, the client library will look for credentials in the environment.
	storageClient, err := storage.NewClient(ctx)
	if err != nil {
		log.Fatal(err)
	}

	it := storageClient.Buckets(ctx, "project-id")
	for {
		bucketAttrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(bucketAttrs.Name)
	}

	// For packages whose import path is starting with "google.golang.org/api",
	// such as google.golang.org/api/cloudkms/v1, use NewService to create the client.
	kmsService, err := cloudkms.NewService(ctx)
	if err != nil {
		log.Fatal(err)
	}

	_ = kmsService
}

Java

static void authImplicit() {
  // If you don't specify credentials when constructing the client, the client library will
  // look for credentials via the environment variable GOOGLE_APPLICATION_CREDENTIALS.
  Storage storage = StorageOptions.getDefaultInstance().getService();

  System.out.println("Buckets:");
  Page<Bucket> buckets = storage.list();
  for (Bucket bucket : buckets.iterateAll()) {
    System.out.println(bucket.toString());
  }
}

Node.js

// Imports the Google Cloud client library.
const {Storage} = require('@google-cloud/storage');

// Instantiates a client. If you don't specify credentials when constructing
// the client, the client library will look for credentials in the
// environment.
const storage = new Storage();
// Makes an authenticated API request.
async function listBuckets() {
  try {
    const results = await storage.getBuckets();

    const [buckets] = results;

    console.log('Buckets:');
    buckets.forEach((bucket) => {
      console.log(bucket.name);
    });
  } catch (err) {
    console.error('ERROR:', err);
  }
}
listBuckets();

PHP

// Imports the Cloud Storage client library.
use Google\Cloud\Storage\StorageClient;

function auth_cloud_implicit($projectId)
{
    $config = [
        'projectId' => $projectId,
    ];

    # If you don't specify credentials when constructing the client, the
    # client library will look for credentials in the environment.
    $storage = new StorageClient($config);

    # Make an authenticated API request (listing storage buckets)
    foreach ($storage->buckets() as $bucket) {
        printf('Bucket: %s' . PHP_EOL, $bucket->name());
    }
}

Python

def implicit():
    from google.cloud import storage

    # If you don't specify credentials when constructing the client, the
    # client library will look for credentials in the environment.
    storage_client = storage.Client()

    # Make an authenticated API request
    buckets = list(storage_client.list_buckets())
    print(buckets)

Ruby

# project_id = "Your Google Cloud project ID"

require "google/cloud/storage"

# If you don't specify credentials when constructing the client, the client
# library will look for credentials in the environment.
storage = Google::Cloud::Storage.new project: project_id

# Make an authenticated API request
storage.buckets.each do |bucket|
  puts bucket.name
end

Essa estratégia é útil para testes e experiências, mas pode dificultar a identificação das credenciais que seu aplicativo está usando. Recomendamos especificar explicitamente quais credenciais o aplicativo deve usar, conforme descrito na seção a seguir.

Como receber e fornecer credenciais da conta de serviço manualmente

Se você desenvolver o código localmente e implantar seu aplicativo no local ou em outra nuvem pública, será possível criar e receber manualmente as credenciais da conta de serviço.

Criar uma conta de serviço

As etapas a seguir descrevem como criar uma conta de serviço. No entanto, em vez de definir permissões de proprietário, restrinja o acesso às permissões, conforme descrito na seção de acesso restrito abaixo.

Console do Cloud

  1. No Console do Cloud, acesse a página Criar chave da conta de serviço.

    Acessar página "Criar chave da conta de serviço"
  2. Na lista Conta de serviço, selecione Nova conta de serviço.
  3. No campo Nome da conta de serviço, insira um nome.

  4. Na lista Papel, selecione Projeto > Proprietário.

    Observação: o campo Papel autoriza sua conta de serviço a acessar recursos. É possível visualizar e alterar esse campo mais tarde usando o Console do Cloud. Se você estiver desenvolvendo um aplicativo de produção, especifique permissões mais granulares do que Projeto > Proprietário. Para mais informações, consulte Como atribuir papéis a contas de serviço.
  5. Clique em Criar. O download de um arquivo JSON que contém a chave é feito no computador.

Linha de comando

É possível executar os seguintes comandos usando o SDK do Cloud na máquina local ou no Cloud Shell.

  1. Crie a conta de serviço. Substitua [NAME] por um nome para a conta de serviço. 

    gcloud iam service-accounts create [NAME]

  2. Conceda permissões à conta de serviço. Substitua [PROJECT_ID] pelo código do seu projeto. 

    gcloud projects add-iam-policy-binding [PROJECT_ID] --member "serviceAccount:[NAME]@[PROJECT_ID].iam.gserviceaccount.com" --role "roles/owner"
    Observação: o campo Papel autoriza a conta de serviço a acessar recursos. Se quiser visualizar e alterar esse campo mais tarde, use o Console do Cloud. Se você estiver desenvolvendo um aplicativo de produção, especifique permissões mais granulares do que Projeto > Proprietário. Para mais informações, consulte Como atribuir papéis a contas de serviço.

  3. Gere o arquivo de chave. Substitua [FILE_NAME] pelo nome do arquivo de chave. 

    gcloud iam service-accounts keys create [FILE_NAME].json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com

Como fornecer credenciais de conta de serviço

Depois de criar uma conta de serviço, existem duas opções para fornecer as credenciais ao seu aplicativo. Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS explicitamente ou passe o caminho para a chave da conta de serviço no código.

Como configurar a variável de ambiente

Forneça credenciais de autenticação ao código do aplicativo definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS. Substitua [PATH] pelo caminho do arquivo JSON que contém sua chave da conta de serviço. Essa variável só se aplica à sessão de shell atual. Assim, se você abrir uma nova sessão, precisará definir a variável novamente.

Linux ou macOS

export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

Exemplo:

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/my-key.json"

Windows

Com o PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

Exemplo:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\my-key.json"

Com prompt de comando:

set GOOGLE_APPLICATION_CREDENTIALS=[PATH]

Depois de concluir as etapas anteriores, o ADC consegue determinar suas credenciais implicitamente, conforme descrito na seção acima, Como fornecer credenciais para seu aplicativo. Recomendamos essa abordagem porque requer menos códigos. Além disso, o uso da variável de ambiente torna seu código mais portátil, porque será possível executar o mesmo código em vários ambientes com contas de serviço diferentes.

Como passar o caminho para a chave da conta de serviço no código

Outra opção seria apontar explicitamente para o arquivo da conta de serviço no código, conforme mostrado no exemplo de código a seguir.

É necessário instalar a biblioteca de cliente do Cloud Storage para executar o exemplo a seguir.

C#

        // Some APIs, like Storage, accept a credential in their Create()
        // method.
        public object AuthExplicit(string projectId, string jsonPath)
        {
            // Explicitly use service account credentials by specifying
            // the private key file.
            var credential = GoogleCredential.FromFile(jsonPath);
            var storage = StorageClient.Create(credential);
            // Make an authenticated API request.
            var buckets = storage.ListBuckets(projectId);
            foreach (var bucket in buckets)
            {
                Console.WriteLine(bucket.Name);
            }
            return null;
        }
        // Other APIs, like Language, accept a channel in their Create()
        // method.
        public object AuthExplicit(string projectId, string jsonPath)
        {
            LanguageServiceClientBuilder builder = new LanguageServiceClientBuilder
            {
                CredentialsPath = jsonPath
            };

            LanguageServiceClient client = builder.Build();
            AnalyzeSentiment(client);
            return 0;
        }

Go


// explicit reads credentials from the specified path.
func explicit(jsonPath, projectID string) {
	ctx := context.Background()
	client, err := storage.NewClient(ctx, option.WithCredentialsFile(jsonPath))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Buckets:")
	it := client.Buckets(ctx, projectID)
	for {
		battrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(battrs.Name)
	}
}

Java

static void authExplicit(String jsonPath) throws IOException {
  // You can specify a credential file by providing a path to GoogleCredentials.
  // Otherwise credentials are read from the GOOGLE_APPLICATION_CREDENTIALS environment variable.
  GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream(jsonPath))
        .createScoped(Lists.newArrayList("https://www.googleapis.com/auth/cloud-platform"));
  Storage storage = StorageOptions.newBuilder().setCredentials(credentials).build().getService();

  System.out.println("Buckets:");
  Page<Bucket> buckets = storage.list();
  for (Bucket bucket : buckets.iterateAll()) {
    System.out.println(bucket.toString());
  }
}

Node.js

// Imports the Google Cloud client library.
const {Storage} = require('@google-cloud/storage');

// Instantiates a client. Explicitly use service account credentials by
// specifying the private key file. All clients in google-cloud-node have this
// helper, see https://github.com/GoogleCloudPlatform/google-cloud-node/blob/master/docs/authentication.md
// const projectId = 'project-id'
// const keyFilename = '/path/to/keyfile.json'
const storage = new Storage({projectId, keyFilename});

// Makes an authenticated API request.
async function listBuckets() {
  try {
    const [buckets] = await storage.getBuckets();

    console.log('Buckets:');
    buckets.forEach((bucket) => {
      console.log(bucket.name);
    });
  } catch (err) {
    console.error('ERROR:', err);
  }
}
listBuckets();

PHP

namespace Google\Cloud\Samples\Auth;

// Imports the Cloud Storage client library.
use Google\Cloud\Storage\StorageClient;

function auth_cloud_explicit($projectId, $serviceAccountPath)
{
    # Explicitly use service account credentials by specifying the private key
    # file.
    $config = [
        'keyFilePath' => $serviceAccountPath,
        'projectId' => $projectId,
    ];
    $storage = new StorageClient($config);

    # Make an authenticated API request (listing storage buckets)
    foreach ($storage->buckets() as $bucket) {
        printf('Bucket: %s' . PHP_EOL, $bucket->name());
    }
}

Python

def explicit():
    from google.cloud import storage

    # Explicitly use service account credentials by specifying the private key
    # file.
    storage_client = storage.Client.from_service_account_json(
        'service_account.json')

    # Make an authenticated API request
    buckets = list(storage_client.list_buckets())
    print(buckets)

Ruby

# project_id = "Your Google Cloud project ID"
# key_file   = "path/to/service-account.json"
require "google/cloud/storage"

# Explicitly use service account credentials by specifying the private key
# file.
storage = Google::Cloud::Storage.new project: project_id, keyfile: key_file

# Make an authenticated API request
storage.buckets.each do |bucket|
  puts bucket.name
end

Como receber credenciais no Compute Engine, no Kubernetes Engine, no ambiente flexível do App Engine e no Cloud Functions

Se o aplicativo for executado no Compute Engine, no GKE, no ambiente flexível do App Engine ou Cloud Functions, não será necessário criar sua própria conta de serviço. O Compute Engine inclui uma conta de serviço padrão criada automaticamente. Além disso, é possível atribuir uma conta de serviço diferente, por instância, se necessário. Quando você cria uma nova instância, ela é ativada automaticamente para ser executada como a conta padrão e com um conjunto de permissões de autorização padrão. Para mais informações, consulte a seção Conta do serviço padrão do Compute Engine.

Depois que você configura uma conta de serviço, o ADC consegue encontrar suas credenciais implicitamente sem que o código precise ser alterado, conforme descrito na seção acima. Para usar credenciais específicas do Compute Engine, faça-o explicitamente, conforme o código abaixo.

É necessário instalar a biblioteca de cliente do Cloud Storage para executar o exemplo a seguir.

C#

        // Some APIs, like Storage, accept a credential in their Create()
        // method.
        public object AuthExplicitComputeEngine(string projectId)
        {
            // Explicitly request service account credentials from the compute
            // engine instance.
            GoogleCredential credential =
                GoogleCredential.FromComputeCredential();
            var storage = StorageClient.Create(credential);
            // Make an authenticated API request.
            var buckets = storage.ListBuckets(projectId);
            foreach (var bucket in buckets)
            {
                Console.WriteLine(bucket.Name);
            }
            return null;
        }
        // Other APIs, like Language, accept a channel in their Create()
        // method.
        public object AuthExplicitComputeEngine(string projectId)
        {
            LanguageServiceClientBuilder builder = new LanguageServiceClientBuilder
            {
                ChannelCredentials = GoogleCredential
                .FromComputeCredential()
                .ToChannelCredentials()
            };

            LanguageServiceClient client = builder.Build();
            AnalyzeSentiment(client);
            return 0;
        }

Go


// explicitDefault finds the default credentials.
//
// It is very uncommon to need to explicitly get the default credentials in Go.
// Most of the time, client libraries can use Application Default Credentials
// without having to pass the credentials in directly. See implicit above.
func explicitDefault(projectID string) {
	ctx := context.Background()

	creds, err := google.FindDefaultCredentials(ctx, storage.ScopeReadOnly)
	if err != nil {
		log.Fatal(err)
	}
	client, err := storage.NewClient(ctx, option.WithCredentials(creds))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Buckets:")
	it := client.Buckets(ctx, projectID)
	for {
		battrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(battrs.Name)
	}
}

Java

static void authCompute() {
  // Explicitly request service account credentials from the compute engine instance.
  GoogleCredentials credentials = ComputeEngineCredentials.create();
  Storage storage = StorageOptions.newBuilder().setCredentials(credentials).build().getService();

  System.out.println("Buckets:");
  Page<Bucket> buckets = storage.list();
  for (Bucket bucket : buckets.iterateAll()) {
    System.out.println(bucket.toString());
  }
}

Node.js

'use strict';

const {auth, Compute} = require('google-auth-library');

/**
 * This example directly instantiates a Compute client to acquire credentials.
 * Generally, you wouldn't directly create this class, rather call the
 * `auth.getClient()` method to automatically obtain credentials.
 */
async function main() {
  const client = new Compute({
    // Specifying the serviceAccountEmail is optional. It will use the default
    // service account if one is not defined.
    serviceAccountEmail: 'some-service-account@example.com',
  });
  const projectId = await auth.getProjectId();
  const url = `https://dns.googleapis.com/dns/v1/projects/${projectId}`;
  const res = await client.request({url});
  console.log(res.data);
}

main().catch(console.error);

PHP

namespace Google\Cloud\Samples\Auth;

// Imports GCECredentials and the Cloud Storage client library.
use Google\Auth\Credentials\GCECredentials;
use Google\Cloud\Storage\StorageClient;

function auth_cloud_explicit_compute_engine($projectId)
{
    $gceCredentials = new GCECredentials();
    $config = [
        'projectId' => $projectId,
        'credentialsFetcher' => $gceCredentials,
    ];
    $storage = new StorageClient($config);

    # Make an authenticated API request (listing storage buckets)
    foreach ($storage->buckets() as $bucket) {
        printf('Bucket: %s' . PHP_EOL, $bucket->name());
    }
}

Python

def explicit_compute_engine(project):
    from google.auth import compute_engine
    from google.cloud import storage

    # Explicitly use Compute Engine credentials. These credentials are
    # available on Compute Engine, App Engine Flexible, and Container Engine.
    credentials = compute_engine.Credentials()

    # Create the client using the credentials and specifying a project ID.
    storage_client = storage.Client(credentials=credentials, project=project)

    # Make an authenticated API request
    buckets = list(storage_client.list_buckets())
    print(buckets)

Ruby

require "googleauth"
require "google/cloud/env"
require "google/cloud/storage"

# Explicitly use Compute Engine credentials and a project ID to create a new
# Cloud Storage client. These credentials are available on Compute Engine,
# App Engine Flexible, and Container Engine.
storage = Google::Cloud::Storage.new project: Google::Cloud.env.project_id,
                                     keyfile: Google::Auth::GCECredentials.new

# Make an authenticated API request
storage.buckets.each do |bucket|
  puts bucket.name
end

Como receber credenciais no ambiente padrão do App Engine

Quando o aplicativo for executado no ambiente padrão do App Engine, use a API App Identity do App Engine para receber as credenciais.

Depois que você configura uma conta de serviço, o ADC consegue encontrar suas credenciais implicitamente sem que o código precise ser alterado, conforme descrito na seção acima. Para usar credenciais específicas do App Engine, faça-o explicitamente, conforme o código abaixo.

É necessário instalar a biblioteca de cliente do Cloud Storage para executar o exemplo a seguir.

PHP

namespace Google\Cloud\Samples\Auth;

// Imports AppIdentityCredentials and the Cloud Storage client library.
use Google\Auth\Credentials\AppIdentityCredentials;
use Google\Cloud\Storage\StorageClient;

function auth_cloud_explicit_app_engine($projectId)
{
    # Learn more about scopes at https://cloud.google.com/storage/docs/authentication#oauth-scopes
    $scope = 'https://www.googleapis.com/auth/devstorage.read_only';
    $gaeCredentials = new AppIdentityCredentials($scope);
    $config = [
        'projectId' => $projectId,
        'credentialsFetcher' => $gaeCredentials,
    ];
    $storage = new StorageClient($config);

    # Make an authenticated API request (listing storage buckets)
    foreach ($storage->buckets() as $bucket) {
        printf('Bucket: %s' . PHP_EOL, $bucket->name());
    }
}

Go


// explicitDefault finds the default credentials.
//
// It is very uncommon to need to explicitly get the default credentials in Go.
// Most of the time, client libraries can use Application Default Credentials
// without having to pass the credentials in directly. See implicit above.
func explicitDefault(projectID string) {
	ctx := context.Background()

	creds, err := google.FindDefaultCredentials(ctx, storage.ScopeReadOnly)
	if err != nil {
		log.Fatal(err)
	}
	client, err := storage.NewClient(ctx, option.WithCredentials(creds))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Buckets:")
	it := client.Buckets(ctx, projectID)
	for {
		battrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(battrs.Name)
	}
}

Java

static void authAppEngineStandard() throws IOException {
  // Explicitly request service account credentials from the app engine standard instance.
  GoogleCredentials credentials = AppEngineCredentials.getApplicationDefault();
  Storage storage = StorageOptions.newBuilder().setCredentials(credentials).build().getService();

  System.out.println("Buckets:");
  Page<Bucket> buckets = storage.list();
  for (Bucket bucket : buckets.iterateAll()) {
    System.out.println(bucket.toString());
  }
}

Python

def explicit_app_engine(project):
    from google.auth import app_engine
    import googleapiclient.discovery

    # Explicitly use App Engine credentials. These credentials are
    # only available when running on App Engine Standard.
    credentials = app_engine.Credentials()

    # Explicitly pass the credentials to the client library.
    storage_client = googleapiclient.discovery.build(
        'storage', 'v1', credentials=credentials)

    # Make an authenticated API request
    buckets = storage_client.buckets().list(project=project).execute()
    print(buckets)

Como restringir o acesso

Conceda ao aplicativo apenas as permissões de autorização necessárias para que ele interaja com os recursos, funcionalidades ou APIs do Google Cloud pertinentes. O Google Cloud usa o Cloud Identity and Access Management (Cloud IAM) para controle de acesso. Ao criar uma conta de serviço, é possível escolher um papel do IAM para limitar o acesso. O tutorial Primeiros passos na autenticação instrui a escolher o papel Owner quando você criar uma conta de serviço. É possível alterar esse valor a qualquer momento. Para ver mais informações, consulte Como atribuir papéis a contas de serviço.

Práticas recomendadas para o gerenciamento de credenciais

As credenciais fornecem acesso a dados confidenciais. As práticas a seguir ajudam você a proteger o acesso a esses recursos.

  • Não incorpore chaves secretas relacionadas à autenticação no código-fonte, como chaves de API, tokens OAuth e credenciais da conta de serviço. Use uma variável de ambiente que aponte para as credenciais fora do código-fonte do aplicativo, como o Cloud Key Management Service.

  • Use credenciais diferentes em contextos distintos como ambientes de teste e de produção.

  • Transfira credenciais apenas por meio de HTTPS para evitar a interceptação das suas credenciais por terceiros. Jamais transfira em texto simples ou como parte do URL.

  • Nunca incorpore credenciais de longa duração ao aplicativo do lado do cliente. Por exemplo, não incorpore credenciais de conta de serviço em um aplicativo para dispositivos móveis. Os aplicativos do lado do cliente podem ser examinados e as credenciais podem ser facilmente encontradas e usadas por terceiros.

  • Revogue um token quando ele não for mais necessário.

Como resolver problemas de erros na API

Saiba mais sobre como resolver problemas de solicitações de API em Erros das APIs do Cloud.

A seguir