Nesta página, descrevemos como usar bibliotecas de cliente para acessar as APIs do Google.
As bibliotecas de cliente facilitam o acesso às APIs doGoogle Cloud usando uma linguagem compatível. É possível usar as APIs do 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 fluxos) de uma fonte externa (por exemplo, um cliente), revise os requisitos de segurança ao usar configurações de credenciais de uma fonte 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:
Go
Java
Node.js
PHP
Python
Ruby
Usar chaves de API com bibliotecas de cliente
Você pode usar chaves de API apenas com bibliotecas de cliente para APIs que aceitam chaves de API. Além disso, a chave de API não pode ter uma restrição que impeça o uso dela na API.
Para mais informações sobre 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.
C++
Para executar este exemplo, instale a biblioteca de cliente da Natural Language.
Go
Para executar este exemplo, instale a biblioteca de cliente da Natural Language.
Node.js
Para executar este exemplo, instale a biblioteca de cliente da Natural Language.
Python
Para executar este exemplo, instale a biblioteca de cliente da Natural Language.
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, as configurações de credenciais são geradas usando comandos da CLI gcloud ou o console Google Cloud . Por exemplo, use 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 Google Cloud para criar e baixar uma chave de conta de serviço.
No entanto, em alguns casos de uso, as configurações de credenciais são fornecidas por uma entidade externa e destinadas à autenticação nas APIs do Google.
Alguns tipos de configurações de credenciais incluem endpoints e caminhos de arquivos, que as bibliotecas de autenticação usam para adquirir um token. Ao aceitar configurações de credenciais de uma fonte externa, valide 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 credenciais que seu aplicativo aceita.
Validar chaves de conta de serviço
Se o aplicativo aceitar apenas chaves de conta de serviço, use um carregador de credenciais específico para elas, conforme mostrado nos exemplos a seguir. O carregador de credenciais específico do tipo analisa apenas os campos presentes nas 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.fromStream(credentialsStream);
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 que o valor do campo type
é service_account
. Se o valor do campo type
for qualquer outro, não use a chave da conta de serviço.
Validar outras configurações de credenciais
Se o aplicativo 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.
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 representada. | https://iamcredentials.googleapis.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/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 para o
endpoint token_url .
|
O caminho para 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 enviam a resposta ao endpoint
token_url .
|
Um dos seguintes itens:
|
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ê precisa 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:
|
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:
|
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:
|
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.