Autenticar para usar bibliotecas de cliente

Nesta página, descrevemos como usar bibliotecas de cliente para acessar as APIs do Google.

As bibliotecas de cliente facilitam o acesso a APIsGoogle Cloud usando uma linguagem com suporte. É possível usar as APIs Google Cloud diretamente fazendo solicitações brutas ao servidor, mas as bibliotecas de cliente oferecem simplificações que reduzem significativamente a quantidade de código que você precisa escrever. Isso é especialmente verdadeiro para a autenticação, porque as bibliotecas de cliente oferecem suporte a Application Default Credentials (ADC).

Se você aceitar configurações de credenciais (JSON, arquivos ou streams) de uma origem externa (por exemplo, um cliente), consulte os requisitos de segurança ao usar configurações de credenciais de uma origem externa.

Usar o Application Default Credentials com as bibliotecas de clientes

Para usar o Application Default Credentials para autenticar um aplicativo, primeiro configure o ADC para o ambiente em que o aplicativo está em execução. Quando você usa a biblioteca de cliente para criar um cliente, essa biblioteca verifica e usa automaticamente as credenciais fornecidas ao ADC para autenticação nas APIs usadas pelo seu código. Seu aplicativo não precisa autenticar ou gerenciar tokens explicitamente. esses requisitos são gerenciados automaticamente pelas bibliotecas de autenticação.

Para um ambiente de desenvolvimento local, é possível configurar o ADC com suas credenciais de usuário ou com representação de conta de serviço usando a gcloud CLI. Para ambientes de produção, configure o ADC anexando uma conta de serviço.

Exemplo de criação de cliente

As amostras de código a seguir criam um cliente para o serviço do Cloud Storage. É provável que seu código precise de clientes diferentes. Estas amostras servem apenas para mostrar como criar um cliente e usá-lo sem qualquer código para autenticar explicitamente.

Antes de executar os exemplos a seguir, é preciso concluir as etapas a seguir:

• Configurar o ADC para seu ambiente
• Instale a biblioteca de cliente do Cloud Storage

Go

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/storage"
	"google.golang.org/api/iterator"
)

// authenticateImplicitWithAdc uses Application Default Credentials
// to automatically find credentials and authenticate.
func authenticateImplicitWithAdc(w io.Writer, projectId string) error {
	// projectId := "your_project_id"

	ctx := context.Background()

	// NOTE: Replace the client created below with the client required for your application.
	// Note that the credentials are not specified when constructing the client.
	// The client library finds your credentials using ADC.
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	it := client.Buckets(ctx, projectId)
	for {
		bucketAttrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Bucket: %v\n", bucketAttrs.Name)
	}

	fmt.Fprintf(w, "Listed all storage buckets.\n")

	return nil
}

Java

import com.google.api.gax.paging.Page;
import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.io.IOException;

public class AuthenticateImplicitWithAdc {

  public static void main(String[] args) throws IOException {
    // TODO(Developer):
    //  1. Before running this sample,
    //  set up Application Default Credentials as described in
    //  https://cloud.google.com/docs/authentication/external/set-up-adc
    //  2. Replace the project variable below.
    //  3. Make sure you have the necessary permission to list storage buckets
    //  "storage.buckets.list"
    String projectId = "your-google-cloud-project-id";
    authenticateImplicitWithAdc(projectId);
  }

  // When interacting with Google Cloud Client libraries, the library can auto-detect the
  // credentials to use.
  public static void authenticateImplicitWithAdc(String project) throws IOException {

    // *NOTE*: Replace the client created below with the client required for your application.
    // Note that the credentials are not specified when constructing the client.
    // Hence, the client library will look for credentials using ADC.
    //
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    Storage storage = StorageOptions.newBuilder().setProjectId(project).build().getService();

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

Node.js

/**
 * TODO(developer):
 *  1. Uncomment and replace these variables before running the sample.
 *  2. Set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
 *  3. Make sure you have the necessary permission to list storage buckets "storage.buckets.list"
 *    (https://cloud.google.com/storage/docs/access-control/iam-permissions#bucket_permissions)
 */
// const projectId = 'YOUR_PROJECT_ID';

const {Storage} = require('@google-cloud/storage');

async function authenticateImplicitWithAdc() {
  // This snippet demonstrates how to list buckets.
  // NOTE: Replace the client created below with the client required for your application.
  // Note that the credentials are not specified when constructing the client.
  // The client library finds your credentials using ADC.
  const storage = new Storage({
    projectId,
  });
  const [buckets] = await storage.getBuckets();
  console.log('Buckets:');

  for (const bucket of buckets) {
    console.log(`- ${bucket.name}`);
  }

  console.log('Listed all storage buckets.');
}

authenticateImplicitWithAdc();

PHP

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

/**
 * Authenticate to a cloud client library using a service account implicitly.
 *
 * @param string $projectId The Google project ID.
 */
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

from google.cloud import storage


def authenticate_implicit_with_adc(project_id="your-google-cloud-project-id"):
    """
    When interacting with Google Cloud Client libraries, the library can auto-detect the
    credentials to use.

    // TODO(Developer):
    //  1. Before running this sample,
    //  set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
    //  2. Replace the project variable.
    //  3. Make sure that the user account or service account that you are using
    //  has the required permissions. For this sample, you must have "storage.buckets.list".
    Args:
        project_id: The project id of your Google Cloud project.
    """

    # This snippet demonstrates how to list buckets.
    # *NOTE*: Replace the client created below with the client required for your application.
    # Note that the credentials are not specified when constructing the client.
    # Hence, the client library will look for credentials using ADC.
    storage_client = storage.Client(project=project_id)
    buckets = storage_client.list_buckets()
    print("Buckets:")
    for bucket in buckets:
        print(bucket.name)
    print("Listed all storage buckets.")

Ruby

def authenticate_implicit_with_adc project_id:
  # The ID of your Google Cloud project
  # project_id = "your-google-cloud-project-id"

  ###
  # When interacting with Google Cloud Client libraries, the library can auto-detect the
  # credentials to use.
  # TODO(Developer):
  #   1. Before running this sample,
  #      set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
  #   2. Replace the project variable.
  #   3. Make sure that the user account or service account that you are using
  #      has the required permissions. For this sample, you must have "storage.buckets.list".
  ###

  require "google/cloud/storage"

  # This sample demonstrates how to list buckets.
  # *NOTE*: Replace the client created below with the client required for your application.
  # Note that the credentials are not specified when constructing the client.
  # Hence, the client library will look for credentials using ADC.
  storage = Google::Cloud::Storage.new project_id: project_id
  buckets = storage.buckets
  puts "Buckets: "
  buckets.each do |bucket|
    puts bucket.name
  end
  puts "Plaintext: Listed all storage buckets."
end

Usar chaves de API com bibliotecas de cliente

É possível usar chaves de API apenas com bibliotecas de cliente para APIs que aceitam chaves de API. Além disso, a chave não pode ter uma restrição que impeça o uso dela.

Para mais informações sobre as chaves de API criadas no modo expresso, consulte as Perguntas frequentes sobre o modo expresso do Google Cloud.

Este exemplo usa a API Cloud Natural Language, que aceita chaves de API, para demonstrar como fornecer uma chave de API à biblioteca.

C#

Para executar este exemplo, instale a biblioteca de cliente da Natural Language.

using Google.Cloud.Language.V1;
using System;

public class UseApiKeySample
{
    public void AnalyzeSentiment(string apiKey)
    {
        LanguageServiceClient client = new LanguageServiceClientBuilder
        {
            ApiKey = apiKey
        }.Build();

        string text = "Hello, world!";

        AnalyzeSentimentResponse response = client.AnalyzeSentiment(Document.FromPlainText(text));
        Console.WriteLine($"Text: {text}");
        Sentiment sentiment = response.DocumentSentiment;
        Console.WriteLine($"Sentiment: {sentiment.Score}, {sentiment.Magnitude}");
        Console.WriteLine("Successfully authenticated using the API key");
    }
}

C++

Para executar este exemplo, instale a biblioteca de cliente da Natural Language.

#include "google/cloud/language/v1/language_client.h"
#include "google/cloud/credentials.h"
#include "google/cloud/options.h"

void AuthenticateWithApiKey(std::vector<std::string> const& argv) {
  if (argv.size() != 2) {
    throw google::cloud::testing_util::Usage{
        "authenticate-with-api-key <project-id> <api-key>"};
  }
  namespace gc = ::google::cloud;
  auto options = gc::Options{}.set<gc::UnifiedCredentialsOption>(
      gc::MakeApiKeyCredentials(argv[1]));
  auto client = gc::language_v1::LanguageServiceClient(
      gc::language_v1::MakeLanguageServiceConnection(options));

  auto constexpr kText = "Hello, world!";

  google::cloud::language::v1::Document d;
  d.set_content(kText);
  d.set_type(google::cloud::language::v1::Document::PLAIN_TEXT);

  auto response = client.AnalyzeSentiment(d, {});
  if (!response) throw std::move(response.status());
  auto const& sentiment = response->document_sentiment();
  std::cout << "Text: " << kText << "\n";
  std::cout << "Sentiment: " << sentiment.score() << ", "
            << sentiment.magnitude() << "\n";
  std::cout << "Successfully authenticated using the API key\n";
}

Go

Para executar este exemplo, instale a biblioteca de cliente da Natural Language.

import (
	"context"
	"fmt"
	"io"

	language "cloud.google.com/go/language/apiv1"
	"cloud.google.com/go/language/apiv1/languagepb"
	"google.golang.org/api/option"
)

// authenticateWithAPIKey authenticates with an API key for Google Language
// service.
func authenticateWithAPIKey(w io.Writer, apiKey string) error {
	// apiKey := "api-key-string"

	ctx := context.Background()

	// Initialize the Language Service client and set the API key.
	client, err := language.NewClient(ctx, option.WithAPIKey(apiKey))
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	text := "Hello, world!"
	// Make a request to analyze the sentiment of the text.
	res, err := client.AnalyzeSentiment(ctx, &languagepb.AnalyzeSentimentRequest{
		Document: &languagepb.Document{
			Source: &languagepb.Document_Content{
				Content: text,
			},
			Type: languagepb.Document_PLAIN_TEXT,
		},
	})
	if err != nil {
		return fmt.Errorf("AnalyzeSentiment: %w", err)
	}

	fmt.Fprintf(w, "Text: %s\n", text)
	fmt.Fprintf(w, "Sentiment score: %v\n", res.DocumentSentiment.Score)
	fmt.Fprintln(w, "Successfully authenticated using the API key.")

	return nil
}

Node.js

Para executar este exemplo, instale a biblioteca de cliente da Natural Language.

const {
  v1: {LanguageServiceClient},
} = require('@google-cloud/language');

/**
 * Authenticates with an API key for Google Language service.
 *
 * @param {string} apiKey An API Key to use
 */
async function authenticateWithAPIKey(apiKey) {
  const language = new LanguageServiceClient({apiKey});

  // Alternatively:
  // const {GoogleAuth} = require('google-auth-library');
  // const auth = new GoogleAuth({apiKey});
  // const language = new LanguageServiceClient({auth});

  const text = 'Hello, world!';

  const [response] = await language.analyzeSentiment({
    document: {
      content: text,
      type: 'PLAIN_TEXT',
    },
  });

  console.log(`Text: ${text}`);
  console.log(
    `Sentiment: ${response.documentSentiment.score}, ${response.documentSentiment.magnitude}`
  );
  console.log('Successfully authenticated using the API key');
}

authenticateWithAPIKey();

Python

Para executar este exemplo, instale a biblioteca de cliente da Natural Language.

from google.cloud import language_v1


def authenticate_with_api_key(api_key_string: str) -> None:
    """
    Authenticates with an API key for Google Language service.

    TODO(Developer): Replace this variable before running the sample.

    Args:
        api_key_string: The API key to authenticate to the service.
    """

    # Initialize the Language Service client and set the API key
    client = language_v1.LanguageServiceClient(
        client_options={"api_key": api_key_string}
    )

    text = "Hello, world!"
    document = language_v1.Document(
        content=text, type_=language_v1.Document.Type.PLAIN_TEXT
    )

    # Make a request to analyze the sentiment of the text.
    sentiment = client.analyze_sentiment(
        request={"document": document}
    ).document_sentiment

    print(f"Text: {text}")
    print(f"Sentiment: {sentiment.score}, {sentiment.magnitude}")
    print("Successfully authenticated using the API key")

Ao usar chaves de API nos seus aplicativos, garanta que elas sejam mantidas em segurança durante o armazenamento e a transmissão. A exposição pública das chaves de API pode levar a cobranças inesperadas na sua conta. Para mais informações, consulte Práticas recomendadas para gerenciar chaves de API.

Requisitos de segurança ao usar configurações de credenciais de uma fonte externa

Normalmente, você gera configurações de credenciais usando comandos da CLI gcloud ou o console do Google Cloud. Por exemplo, é possível usar a CLI gcloud para gerar um arquivo ADC local ou um arquivo de configuração de login. Da mesma forma, é possível usar o console do Google Cloud para criar e fazer o download de uma chave de conta de serviço.

No entanto, para alguns casos de uso, as configurações de credenciais são fornecidas por uma entidade externa. Elas são usadas para autenticação nas APIs do Google.

Alguns tipos de configurações de credenciais incluem endpoints e caminhos de arquivo, que as bibliotecas de autenticação usam para adquirir um token. Quando você aceita configurações de credencial de uma fonte externa, é necessário validar a configuração antes de usá-la. Se você não validar a configuração, um agente malicioso poderá usar a credencial para comprometer seus sistemas e dados.

Validar configurações de credenciais de fontes externas

A forma de validar suas credenciais externas depende dos tipos de credencial que o aplicativo aceita.

Validar chaves de conta de serviço

Se o aplicativo aceitar apenas chaves da conta de serviço, use um carregador de credenciais específico para chaves da conta de serviço, conforme mostrado nos exemplos a seguir. O carregador de credenciais específico do tipo analisa apenas os campos presentes para chaves de conta de serviço, que não expõem vulnerabilidades.

C#

var saCredential = ServiceAccountCredential.FromServiceAccountData(stream);

C++

auto cred = google::cloud::MakeServiceAccountCredentials(json)

Java

ServiceAccountCredentials credentials =
      ServiceAccountCredentials.fromJson(json, new HttpTransportFactory());

Node.js

const keys = JSON.parse(json_input)
const authClient = JWT.fromJSON(keys);

PHP

cred = new Google\Auth\Credentials\ServiceAccountCredentials($scope, $jsonKey);

Python

cred = service_account.Credentials.from_service_account_info(json_data)

Ruby

creds = Google::Auth::ServiceAccountCredentials.make_creds(json_key_io: json_stream)

Se não for possível usar um carregador de credenciais específico do tipo, valide a credencial confirmando se o valor do campo type é service_account. Se o valor do campo type for qualquer outro valor, não use a chave da conta de serviço.

Validar outras configurações de credenciais

Se o app aceitar qualquer tipo de credencial além de uma chave de conta de serviço, será necessário realizar uma verificação adicional. Exemplos de outros tipos de configurações de credenciais incluem arquivos de credenciais do ADC, arquivos de credenciais da federação de identidade da carga de trabalho ou arquivos de configuração de login da federação de identidade da força de trabalho.

A tabela a seguir lista os campos que você precisa validar, se eles estiverem presentes nas suas credenciais. Nem todos esses campos estão presentes em todas as configurações de credenciais.

Importante: se algum desses campos contiver um valor que não está em conformidade com o esperado, não use a credencial.

Campo	Finalidade	Valor esperado
service_account_impersonation_url	As bibliotecas de autenticação usam esse campo para acessar um endpoint e gerar um token de acesso para a conta de serviço que está sendo personificada.	https://iamcredentials.googleapis.com.com/v1/projects/-/serviceAccounts/service account email:generateAccessToken
token_url	As bibliotecas de autenticação enviam um token externo para esse endpoint para trocá-lo por um token de acesso federado.	https://sts.googleapis.com.com/v1/token
credential_source.file	As bibliotecas de autenticação leem um token externo do arquivo no local especificado por esse campo e o enviam ao endpoint token_url.	O caminho de um arquivo que contém um token externo. Você deve reconhecer esse caminho.
credential_source.url	Um endpoint que retorna um token externo. As bibliotecas de autenticação enviam uma solicitação para esse URL e a resposta para o endpoint token_url.	Um dos seguintes itens: Um endpoint conhecido fornecido pelo seu provedor de nuvem. Um endpoint que você configurou explicitamente para fornecer tokens.
credential_source.executable.command	Se a variável de ambiente GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES estiver definida como 1, as bibliotecas de autenticação vão executar esse comando ou arquivo executável.	Um arquivo executável ou comando que retorna um token externo. Você deve reconhecer esse comando e validar se ele é seguro.
credential_source.aws.url	As bibliotecas de autenticação emitem uma solicitação para esse URL para recuperar um token de segurança da AWS.	Um destes valores exatos: http://169.254.169.254/latest/meta-data/iam/security-credentials http://[fd00:ec2::254]/latest/meta-data/iam/security-credentials
credential_source.aws.region_url	As bibliotecas de autenticação emitem uma solicitação para esse URL para recuperar a região ativa da AWS.	Um destes valores exatos: http://169.254.169.254/latest/meta-data/placement/availability-zone http://[fd00:ec2::254]/latest/meta-data/placement/availability-zone
credential_source.aws.imdsv2_session_token_url	As bibliotecas de autenticação emitem uma solicitação para esse URL para recuperar o token de sessão da AWS.	Um destes valores exatos: http://169.254.169.254/latest/api/token http://[fd00:ec2::254]/latest/api/token

A seguir

• Saiba mais sobre o Application Default Credentials.
• Saiba mais sobre as chaves de API.
• Consulte uma visão geral dos métodos de autenticação.