Começar a usar a Biblioteca de Autenticação do Google

Visão geral

A biblioteca de autenticação do Google é uma biblioteca de cliente de autenticação de código aberto para Java. Neste documento, descrevemos como usar essa biblioteca para autenticar seus aplicativos Java para acessar os serviços do Google Cloud .

Ao seguir este guia, você vai aprender a:

  • Adicione as dependências necessárias da biblioteca Auth ao seu projeto usando o Maven, o Gradle ou a Simple Build Tool (SBT).
  • Autenticar usando vários métodos, com foco no Application Default Credentials (ADC).
  • Configurar cenários de autenticação avançados, incluindo federação de identidade da carga de trabalho, federação de identidade de colaboradores e identidade temporária de conta de serviço.
  • Gerar e usar tokens com escopo reduzido para limitar as permissões.
  • Integrar credenciais com as bibliotecas de cliente HTTP do Google.

Esta documentação é destinada a desenvolvedores Java. Para detalhes completos da API, consulte a documentação da API Google Auth Library.

A biblioteca de autenticação do Google para Java consiste em quatro artefatos:

  • google-auth-library-credentials contém classes de base e interfaces para credenciais do Google.
  • google-auth-library-appengine contém credenciais do App Engine e depende do SDK do App Engine.
  • google-auth-library-oauth2-http contém uma variedade de credenciais e métodos utilitários, incluindo recursos para receber o Application Default Credentials. Ele também fornece a abordagem do lado do servidor para gerar tokens com escopo reduzido.
  • google-auth-library-cab-token-generator fornece a abordagem do lado do cliente para gerar tokens com escopo reduzido.

Validar configurações de credenciais

Ao usar configurações de credenciais, como JSON, caminhos de arquivo ou streams, de uma fonte externa, é necessário validá-las. Fornecer credenciais não validadas para APIs ou bibliotecas de cliente do Google para autenticação no Google Cloud pode comprometer a segurança dos seus sistemas e dados.

Para mais informações, consulte Credenciais de fontes externas. padrão.

Importar a biblioteca Auth

Para importar a biblioteca de autenticação, use com.google.cloud:libraries-bom ou a lista de materiais da biblioteca de autenticação do Google com o Maven ou o Gradle.

libraries-bom do SDK para Java

Para autenticar em uma biblioteca de cliente no SDK do Java (por exemplo, google-cloud-datastore) usando a biblioteca de autenticação, use libraries-bom, que vai extrair as versões da biblioteca de autenticação compatíveis com essa biblioteca de cliente.

Por exemplo, para importar a biblioteca Auth com o Maven usando um pom.xml:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.53.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Se você não usa libraries-bom ou outras bibliotecas de cliente, importe os módulos de autenticação diretamente com a lista de materiais da biblioteca de autenticação do Google.

Lista de materiais da biblioteca de autenticação do Google

Use a lista de materiais da biblioteca de autenticação do Google para garantir que os módulos de autenticação e as dependências transitivas relevantes sejam compatíveis.

Maven

Adicione a instrução a seguir ao seu arquivo pom.xml:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.auth</groupId>
      <artifactId>google-auth-library-bom</artifactId>
      <version>1.30.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Na seção <dependencies>, especifique os módulos de autenticação necessários. Por exemplo, para incluir o módulo google-auth-library-oauth2-http, adicione o seguinte item <dependency>:

<dependency>
  <groupId>com.google.auth</groupId>
  <!-- Let the BOM manage the module and dependency versions -->
  <!-- Replace with the module(s) that are needed -->
  <artifactId>google-auth-library-oauth2-http</artifactId>
</dependency>

Substitua google-auth-library-oauth2-http no exemplo por google-auth-library-credentials ou google-auth-library-appengine, dependendo das necessidades do aplicativo.

Gradle

Assim como no Maven, os usuários do Gradle podem usar o google-auth-library-bom para gerenciar versões de dependência e garantir a compatibilidade entre os diferentes módulos do google-auth-library.

Para usar a BOM com o Gradle, adicione-a como uma dependência platform. Em seguida, adicione os módulos google-auth-library necessários. A BoM garante que as versões de todos os módulos usados sejam compatíveis. Por exemplo, adicione o seguinte ao arquivo build.gradle:

dependencies {
    // The BOM will manage the module versions and transitive dependencies
    implementation platform('com.google.auth:google-auth-library-bom:1.30.1')
    // Replace with the module(s) that are needed
    implementation 'com.google.auth:google-auth-library-oauth2-http'
}

Scala

Ao contrário do Maven e do Gradle, o SBT (Scala Build Tool) não é compatível com as listas de materiais (BOMs, na sigla em inglês) do Maven. Como resultado, ao usar o Scala, não é possível importar o google-auth-library-bom para processar automaticamente as versões compatíveis dos módulos da biblioteca de autenticação e as dependências transitivas deles.

Em vez disso, adicione cada submódulo necessário diretamente ao arquivo build.sbt. É fundamental especificar e alinhar explicitamente as versões de todos os módulos google-auth-library que você está usando. Não manter as versões consistentes pode levar a conflitos de versão entre dependências transitivas, o que pode causar comportamentos inesperados ou erros de tempo de execução no aplicativo.

Adicione este código às dependências se estiver usando SBT:

// Replace this with the implementation module that suits your needs
libraryDependencies += "com.google.auth" % "google-auth-library-oauth2-http" % "1.30.1"

Geração de registros da biblioteca Auth

A biblioteca Auth do Java recomenda o uso da geração de registros de depuração da biblioteca de cliente. A geração de registros de depuração vai gerar hash de tokens sensíveis (por exemplo, access_token, refresh_token etc.) e os valores serão mascarados. A geração de registros com java.util.logging está desativada na biblioteca de autenticação para evitar o vazamento de tokens sensíveis.

A funcionalidade de registro de depuração do cliente é opcional e requer configuração.

O registro de depuração pode registrar o seguinte com base no nível de registro:

  • Informações da solicitação: cabeçalhos, URL, método (nível INFO)
  • Informações de resposta: cabeçalhos, status, mensagem (nível INFO)
  • Payload de resposta (nível DEBUG)

Migrar de GoogleCredential para GoogleCredentials

GoogleCredential de google-api-java-client foi descontinuado, e GoogleCredentials é a substituição recomendada.

Instancie GoogleCredentials usando o Application Default Credentials (ADC). Esta é a abordagem recomendada:

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();

A maneira como você usa GoogleCredentials depende da biblioteca de cliente:

Application Default Credentials

A biblioteca do Google Auth fornece uma implementação do Application Default Credentials (ADC) para Java. O ADC oferece uma maneira de receber credenciais de autorização para chamar as APIs do Google.

Use o ADC quando o aplicativo exigir um nível consistente de identidade e autorização, independentemente do usuário. Recomendamos o uso do ADC para autorizar chamadas para APIs do Cloud, especialmente ao criar aplicativos no Google Cloud.

O ADC também é compatível com a federação de identidade da carga de trabalho, permitindo que os aplicativos acessem recursos do Google Cloud em plataformas externas, como Amazon Web Services (AWS), Microsoft Azure ou qualquer provedor de identidade compatível com o OpenID Connect (OIDC). Recomendamos a federação de identidade de carga de trabalho para ambientes que não sejam doGoogle Cloud porque ela elimina a necessidade de fazer o download, gerenciar e armazenar chaves privadas de conta de serviço localmente.

Receber o Application Default Credentials

Para receber o Application Default Credentials, use GoogleCredentials.getApplicationDefault() ou GoogleCredentials.getApplicationDefault(HttpTransportFactory). Esses métodos retornam o Application Default Credentials para identificar e autorizar o aplicativo inteiro.

Os itens a seguir são pesquisados, nesta ordem, para encontrar o Application Default Credentials:

  1. Arquivo de credenciais apontado pela variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.
  2. Credenciais fornecidas pelo comando gcloud auth application-default login do SDK Google Cloud.
  3. Credenciais integradas do Google App Engine.
  4. Google Cloud Credenciais integradas do shell.
  5. Credenciais integradas do Google Compute Engine.
    • Para pular essa verificação, defina a variável de ambiente NO_GCE_CHECK=true.
    • Personalize o endereço do servidor de metadados definindo a variável de ambiente GCE_METADATA_HOST=<hostname>.

Carregamento explícito de credenciais

Para receber credenciais de uma chave JSON de conta de serviço, use GoogleCredentials.fromStream(InputStream) ou GoogleCredentials.fromStream(InputStream, HttpTransportFactory), conforme mostrado no exemplo de código a seguir.

As credenciais precisam ser atualizadas antes que o token de acesso esteja disponível.

GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("/path/to/credentials.json"));
credentials.refreshIfExpired();
AccessToken token = credentials.getAccessToken();
// OR
AccessToken token = credentials.refreshAccessToken();

Credenciais personificadas

Use ImpersonatedCredentials para permitir que uma credencial (o principal) represente uma conta de serviço (o destino). Isso permite que o principal acesse recursos como o destino, sem precisar da chave privada do destino.

Para usar o ImpersonatedCredentials, você precisa atender a estes requisitos:

  • O projeto do principal precisa ter a API IAMCredentials ativada.
  • O principal precisa ter o papel Service Account Token Creator (Identity and Access Management) na conta de serviço de destino.

O exemplo de código a seguir cria ImpersonatedCredentials. A credencial do principal é obtida do Application Default Credentials (ADC). As ImpersonatedCredentials resultantes são usadas para acessar o Google Cloud Storage como a conta de serviço de destino.

// The principal (ADC) has the Service Account Token Creator role on the target service account.
GoogleCredentials sourceCredentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList("https://www.googleapis.com/auth/iam"));

ImpersonatedCredentials credentials =
    ImpersonatedCredentials.newBuilder()
        .setSourceCredentials(sourceCredentials)
        .setTargetPrincipal(
            "impersonated-account@project.")
        .setScopes(Arrays.asList("https://www.googleapis.com/auth/devstorage.read_only"))
        .build();

Storage storage =
    StorageOptions.newBuilder().setProjectId("project-id").setCredentials(credentials).build()
        .getService();

for (Bucket b : storage.list().iterateAll()) {
  System.out.println(b);
}

Tokens vinculados a certificados para identidades de agente

Quando o aplicativo é executado com uma identidade de agente (por exemplo, um serviço ou job do Cloud Run implantado com --identity-type=agent-identity), o ComputeEngineCredentials solicita tokens de acesso e tokens de ID vinculados a certificados do servidor de metadados por padrão. Um token vinculado está associado ao certificado X.509 da carga de trabalho e exige a comprovação da posse da chave privada correspondente por TLS mútuo (mTLS). Como essa chave privada está disponível apenas para a carga de trabalho, um token vazado não pode ser usado em nenhum outro lugar.

Um token vinculado só é aceito quando a solicitação que o carrega é enviada por mTLS com o mesmo certificado. As bibliotecas de cliente do Cloud para Java configuram o mTLS e recarregam automaticamente os certificados de carga de trabalho alternados quando a identidade do agente está ativada. Se você chamar as APIs do Google com seu próprio cliente HTTP, configure o mTLS com o certificado de carga de trabalho e recarregue-o quando o ambiente de execução alternar o certificado no disco. Após a rotação, os tokens de atualização recém-atualizados são vinculados ao novo certificado. Se um novo token for enviado por uma conexão mTLS estabelecida com o certificado anterior, a API rejeitará a solicitação com 401 UNAUTHENTICATED.

A biblioteca solicita um token vinculado somente quando todas as condições a seguir são verdadeiras:

  • Um certificado de carga de trabalho é encontrado, seja pelo arquivo nomeado pela variável de ambiente GOOGLE_API_CERTIFICATE_CONFIG ou no local padrão (/var/run/secrets/workload-spiffe-credentials/).
  • O ID do SPIFFE do certificado pertence a um domínio de confiança de identidade de agente.
  • A vinculação de token e o mTLS não foram desativados (consulte Desativar a vinculação de token).

Em todos os outros ambientes, ComputeEngineCredentials se comporta como antes e retorna tokens não vinculados.

Desativar a vinculação de token

Se você precisar desativar a vinculação de token (consulte Limitações conhecidas), defina a seguinte variável de ambiente:

GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false
Variável de ambiente Efeito
GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN Defina como false para solicitar tokens não vinculados.
GOOGLE_API_USE_CLIENT_CERTIFICATE Definir como false desativa completamente o mTLS, o que também desativa a vinculação de token. Prefira GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false se você só precisar de tokens não vinculados.

Os valores não diferenciam maiúsculas de minúsculas, e os espaços em branco ao redor são ignorados. Somente false desativa um recurso. Qualquer outro valor mantém o padrão.

As variáveis de ambiente se aplicam a todo o processo. Portanto, desativar a vinculação de token afeta todas as bibliotecas do aplicativo que usam o Application Default Credentials, não apenas as que precisam dele. Se você só precisar de tokens de ID não vinculados para alguns destinos, use a opção por destino descrita em Solicitar tokens de ID não vinculados para destinos específicos.

Solicitar tokens de ID não vinculados para destinos específicos

Um token de ID vinculado inclui a impressão digital do certificado da carga de trabalho na declaração cnf (x5t#S256). Os serviços de recebimento podem validar essa declaração em relação ao certificado do cliente apresentado durante um handshake de mTLS ou ignorar a declaração se não aplicarem a vinculação de certificado.

O Cloud Run aplica automaticamente a vinculação de certificado quando a reivindicação cnf está presente em um token de ID. Se você chamar um serviço do Cloud Run com um token de ID vinculado, será necessário chamar o URL *.mtls.run.app por mTLS. Solicitações para um URL *.run.app padrão ou domínio personalizado sem mTLS são rejeitadas com 401 Unauthorized.

Se você chamar um serviço que aplica a vinculação de certificado em um endpoint que não é mTLS (como um URL *.run.app padrão) ou se não precisar da vinculação de certificado para um endpoint de destino, transmita IdTokenProvider.Option.DISABLE_BOUND_ID_TOKEN para solicitar um token de ID não vinculado apenas para esse destino:

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
IdTokenCredentials idTokenCredentials =
    IdTokenCredentials.newBuilder()
        .setIdTokenProvider((IdTokenProvider) credentials)
        .setTargetAudience("https://my-service-12345.us-central1.run.app")
        .setOptions(Arrays.asList(IdTokenProvider.Option.DISABLE_BOUND_ID_TOKEN))
        .build();

Os tokens de acesso e de ID de outros destinos ainda estão vinculados. Essa opção é compatível apenas com ComputeEngineCredentials. Outras implementações de IdTokenProvider não solicitam tokens de ID vinculados e ignoram essa opção. Assim, o mesmo código também funciona fora dos ambientes de identidade do agente.

Limitações conhecidas

  • O Kit de Desenvolvimento de Agente (ADK) para Java não usa mTLS ao chamar APIs do Google, como o Gemini na Vertex AI. Com tokens vinculados (o padrão), essas chamadas falham com com.google.genai.errors.ClientException: 401 . Request had invalid authentication credentials. Para contornar esse problema, defina GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false para agentes que usam o ADK para Java. Para mais informações, consulte Autenticar agentes no Cloud Run.

Federação de identidade da carga de trabalho

A federação de identidade da carga de trabalho permite que seu aplicativo acesse recursos do Google Cloud da Amazon Web Services (AWS), do Microsoft Azure ou de qualquer provedor de identidade compatível com o OpenID Connect (OIDC).

Normalmente, os aplicativos executados fora do Google Cloud usam chaves de conta de serviço para acessar os recursos do Google Cloud . Com a federação de identidade, sua carga de trabalho pode personificar uma conta de serviço. Isso permite que a carga de trabalho externa acesse os recursos do Google Cloud diretamente, eliminando o trabalho de manutenção e segurança das chaves de conta de serviço.

Acessar recursos da AWS

Para acessar os recursos do Google Cloud da Amazon Web Services (AWS), primeiro é necessário configurar a federação de identidade da carga de trabalho. O processo de configuração é detalhado em Como acessar recursos da AWS.

Como parte desse processo, você vai gerar um arquivo de configuração de credenciais. Esse arquivo contém metadados não sensíveis que instruem a biblioteca sobre como recuperar tokens de assunto externos e trocá-los por tokens de acesso de conta de serviço. É possível gerar o arquivo usando a Google Cloud CLI:

# Generate an AWS configuration file.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AWS_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --aws \
    --output-file /path/to/generated/config.json

Substitua:

  • PROJECT_NUMBER: o número do projeto do Google Cloud .
  • POOL_ID: o ID do pool de Identidade da carga de trabalho.
  • AWS_PROVIDER_ID: o ID do provedor da AWS.
  • SERVICE_ACCOUNT_EMAIL: o e-mail da conta de serviço que será personificada.

O exemplo gera o arquivo de configuração no arquivo de saída especificado.

Se você estiver usando o AWS IMDSv2, será necessário adicionar uma flag extra --enable-imdsv2 ao comando gcloud iam workload-identity-pools create-cred-config:

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/AWS_PROVIDER_ID \
    --service-account SERVICE_ACCOUNT_EMAIL \
    --aws \
    --output-file /path/to/generated/config.json \
    --enable-imdsv2

Agora é possível usar a biblioteca Auth para chamar recursos doGoogle Cloud da AWS.

Acessar recursos pelo Microsoft Azure

Para acessar os recursos do Google Cloud no Microsoft Azure, primeiro é preciso configurar a federação de identidade da carga de trabalho. O processo de configuração é detalhado em Como acessar recursos do Azure.

Como parte desse processo, você vai gerar um arquivo de configuração de credenciais. Esse arquivo contém metadados não sensíveis que instruem a biblioteca sobre como recuperar tokens de assunto externos e trocá-los por tokens de acesso de conta de serviço. É possível gerar o arquivo usando a Google Cloud CLI:

# Generate an Azure configuration file.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AZURE_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --azure \
    --output-file /path/to/generated/config.json

Substitua:

  • PROJECT_NUMBER: o número do projeto do Google Cloud .
  • POOL_ID: o ID do pool de Identidade da carga de trabalho.
  • AZURE_PROVIDER_ID: o ID do provedor do Azure.
  • SERVICE_ACCOUNT_EMAIL: o e-mail da conta de serviço que será representada.

Esse comando gera o arquivo de configuração no arquivo de saída especificado.

Agora é possível usar a biblioteca de autenticação para chamar recursos do Google Cloud no Azure.

Acesse recursos por um provedor de identidade OIDC

Para acessar os recursos do Google Cloud de um provedor de identidade compatível com o OpenID Connect (OIDC), primeiro configure a federação de identidade da carga de trabalho, conforme detalhado em Como configurar a federação de identidade da carga de trabalho de um provedor de identidade OIDC.

Como parte desse processo, você vai gerar um arquivo de configuração de credenciais usando a Google Cloud CLI. Esse arquivo contém metadados não confidenciais que instruem a biblioteca sobre como recuperar tokens de assunto externos e trocá-los por tokens de acesso de conta de serviço.

Para provedores OIDC, a biblioteca de autenticação pode recuperar tokens OIDC de um arquivo local (credenciais de origem de arquivo), um servidor local (credenciais de origem de URL) ou uma combinação de certificado X.509 e chave privada (credenciais de origem de certificado X.509).

Credenciais fornecidas pelo arquivo

Para credenciais de origem de arquivo, um processo em segundo plano precisa atualizar continuamente o local do arquivo com um novo token OIDC antes que ele expire. Para tokens com ciclo de vida de uma hora, é necessário atualizar o token no arquivo a cada hora. É possível armazenar o token diretamente como texto simples ou no formato JSON.

Para gerar uma configuração do OIDC com origem em arquivo, execute o seguinte comando:

# Generate an OIDC configuration file for file-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>OIDC_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-source-file <var>PATH_TO_OIDC_ID_TOKEN</var> \
    # Optional arguments for file types. Default is "text":
    # --credential-source-type "json" \
    # Optional argument for the field that contains the OIDC credential.
    # This is required for json.
    # --credential-source-field-name "id_token" \
    --output-file /path/to/generated/config.json

Substitua:

  • PROJECT_NUMBER: o número do projeto do Google Cloud .
  • POOL_ID: o ID do pool de Identidade da carga de trabalho.
  • OIDC_PROVIDER_ID: o ID do provedor do OIDC.
  • SERVICE_ACCOUNT_EMAIL: o e-mail da conta de serviço que será personificada.
  • PATH_TO_OIDC_ID_TOKEN: o caminho usado para recuperar o token OIDC.

Esse comando gera o arquivo de configuração no arquivo de saída especificado.

Credenciais fornecidas pelo URL

Para credenciais fornecidas por URL, um servidor local precisa hospedar um endpoint GET que forneça um token OIDC em texto simples ou formato JSON. É possível especificar outros cabeçalhos HTTP para enviar na solicitação de token, se exigido pelo endpoint.

Para gerar uma configuração de identidade de carga de trabalho do OIDC com origem em URL, execute o seguinte comando:

# Generate an OIDC configuration file for URL-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>OIDC_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-source-url <var>URL_TO_GET_OIDC_TOKEN</var> \
    --credential-source-headers <var>HEADER_KEY=HEADER_VALUE</var> \
    # Optional arguments for file types. Default is "text":
    # --credential-source-type "json" \
    # Optional argument for the field that contains the OIDC credential.
    # This is required for json.
    # --credential-source-field-name "id_token" \
    --output-file /path/to/generated/config.json

Substitua:

  • PROJECT_NUMBER: o número do projeto do Google Cloud .
  • POOL_ID: o ID do pool de Identidade da carga de trabalho.
  • OIDC_PROVIDER_ID: o ID do provedor do OIDC.
  • SERVICE_ACCOUNT_EMAIL: o e-mail da conta de serviço que será representada.
  • URL_TO_GET_OIDC_TOKEN: o URL do endpoint do servidor local a ser chamado para recuperar o token OIDC.
  • HEADER_KEY e HEADER_VALUE: os pares de chave-valor de cabeçalho adicionais para transmitir a solicitação GET para URL_TO_GET_OIDC_TOKEN, por exemplo, Metadata-Flavor=Google.

Agora é possível usar a biblioteca Auth para chamar recursos de umGoogle Cloud provedor OIDC.

Acessar recursos usando credenciais de certificado X.509

Para credenciais de certificado X.509, a biblioteca de autenticação usa um certificado X.509 e uma chave privada para comprovar a identidade do aplicativo. Os certificados X.509 incluem uma data de validade e precisam ser renovados antes de expirar para manter o acesso.

Para mais informações, consulte a documentação oficial.

Gerar arquivos de configuração para a federação X.509

Para configurar credenciais de certificado X.509, gere dois arquivos separados: um arquivo de configuração de credencial principal e um arquivo de configuração de certificado.

  • O arquivo de configuração de credencial principal contém os metadados necessários para autenticação. Esse arquivo também faz referência ao arquivo de configuração do certificado.
  • O arquivo de configuração do certificado especifica os caminhos de arquivo para o certificado X.509, a chave privada e a cadeia de confiança.

O comando gcloud iam workload-identity-pools create-cred-config pode ser usado para criar os dois.

O local em que gcloud cria o arquivo de configuração do certificado depende do uso da flag --credential-cert-configuration-output-file.

Se você omitir a flag --credential-cert-configuration-output-file, gcloud vai criar o arquivo de configuração do certificado em um local padrão e conhecido que a biblioteca de autenticação pode descobrir automaticamente. Essa abordagem é adequada para a maioria dos casos de uso. O arquivo de configuração de credenciais padrão é chamado config.json, e o arquivo de configuração de certificado padrão é chamado certificate_config.json.

Por exemplo, execute o seguinte comando para criar os arquivos de configuração usando o comportamento padrão:

gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
    --credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
    --credential-cert-trust-chain-path "<var>PATH_TO_TRUST_CHAIN</var>" \
    --output-file /path/to/config.json

Substitua:

  • PROJECT_NUMBER: o número do projeto do Google Cloud .
  • POOL_ID: o ID do pool de Identidade da carga de trabalho.
  • PROVIDER_ID: o ID do provedor.
  • SERVICE_ACCOUNT_EMAIL: o e-mail da conta de serviço que será representada.
  • PATH_TO_CERTIFICATE: o caminho em que o certificado X.509 folha está localizado.
  • PATH_TO_PRIVATE_KEY: o caminho em que a chave privada correspondente do certificado de folha está localizada.
  • PATH_TO_TRUST_CHAIN: o caminho do arquivo da cadeia de confiança do certificado X.509. Esse arquivo precisa estar no formato PEM e conter todos os certificados intermediários necessários para concluir a cadeia de confiança entre o certificado de folha e o repositório de confiança configurado no pool de federação de identidade da carga de trabalho. O certificado de folha é opcional nesse arquivo.

Esse comando resulta no seguinte:

  • /path/to/config.json: criado no caminho especificado. Esse arquivo vai conter "use_default_certificate_config": true para instruir os clientes a procurar a configuração do certificado no caminho padrão.
  • certificate_config.json: criado no caminho de configuração padrão da Google Cloud CLI, que normalmente é ~/.config/gcloud/certificate_config.json no Linux e no macOS ou %APPDATA%\gcloud\certificate_config.json no Windows.

Comportamento de local personalizado

Se você precisar armazenar o arquivo de configuração do certificado em um local não padrão, use a flag --credential-cert-configuration-output-file.

Exemplo de comando (local personalizado):

gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
    --credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
    --credential-cert-trust-chain-path "<var>PATH_TO_TRUST_CHAIN</var>" \
    --credential-cert-configuration-output-file "/custom/path/cert_config.json" \
    --output-file /path/to/config.json

Esse comando resulta em:

  • /path/to/config.json: criado no caminho especificado. Esse arquivo vai conter um campo "certificate_config_location" que aponta para o caminho personalizado.
  • cert_config.json: criado em /custom/path/cert_config.json, conforme especificado pela flag.

Agora é possível usar a biblioteca de autenticação para chamar recursos doGoogle Cloud com credenciais de certificado X.509.

Usar credenciais de origem executáveis com OIDC e SAML

Para credenciais de origem executável, um executável local é usado para recuperar o token de terceiros. O executável precisa fornecer um token de ID do OIDC ou uma declaração SAML válida e não expirada no formato JSON para stdout.

Para usar credenciais de origem executável, a variável de ambiente GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES precisa ser definida como 1.

Para gerar uma configuração de identidade da carga de trabalho de origem executável, execute o seguinte comando:

# Generate a configuration file for executable-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account=<var>SERVICE_ACCOUNT_EMAIL</var> \
    --subject-token-type=<var>SUBJECT_TOKEN_TYPE</var> \
    # The absolute path for the program, including arguments.
    # e.g. --executable-command="/path/to/command --foo=bar"
    --executable-command=<var>EXECUTABLE_COMMAND</var> \
    # Optional argument for the executable timeout. Defaults to 30s.
    # --executable-timeout-millis=<var>EXECUTABLE_TIMEOUT</var> \
    # Optional argument for the absolute path to the executable output file.
    # See below on how this argument impacts the library behaviour.
    # --executable-output-file=<var>EXECUTABLE_OUTPUT_FILE</var> \
    --output-file /path/to/generated/config.json

Substitua:

  • PROJECT_NUMBER: o número do projeto do Google Cloud .
  • POOL_ID: o ID do pool de Identidade da carga de trabalho.
  • PROVIDER_ID: o ID do provedor OIDC ou SAML.
  • SERVICE_ACCOUNT_EMAIL: o e-mail da conta de serviço que será representada.
  • SUBJECT_TOKEN_TYPE: o tipo de token de assunto.
  • EXECUTABLE_COMMAND: o comando completo a ser executado, incluindo argumentos. Precisa ser um caminho absoluto para o programa.

A flag --executable-timeout-millis é opcional. Ela especifica a duração (em milissegundos) que a biblioteca do Auth vai esperar para que o executável termine. Se não for fornecido, o padrão será 30 segundos. O valor máximo permitido é de dois minutos, e o mínimo é de cinco segundos.

A flag opcional --executable-output-file especifica um caminho para armazenar em cache a resposta de credencial de terceiros do executável. O armazenamento em cache ajuda a melhorar o desempenho, porque as bibliotecas de autenticação verificam primeiro se esse arquivo tem credenciais válidas e não expiradas antes de executar o executável. Se houver credenciais válidas em cache, as bibliotecas as usarão, evitando execuções desnecessárias.

O executável precisa gravar a resposta da credencial nesse arquivo. As bibliotecas de autenticação só leem desse local. O conteúdo do arquivo precisa corresponder ao formato JSON esperado.

Para recuperar o token de terceiros, a biblioteca vai executar o executável usando o comando especificado. A saída do executável precisa seguir o formato de resposta especificado nos exemplos a seguir e precisa gerar a resposta para stdout.

Veja um exemplo de resposta executável do OIDC:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

Veja um exemplo de resposta SAML executável bem-sucedida:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620499962
}

Quando você especifica um arquivo de saída usando o argumento --executable-output-file na configuração da credencial, as respostas executáveis bem-sucedidas precisam incluir um campo expiration_time. Isso permite que a biblioteca de autenticação armazene em cache e gerencie de maneira eficaz a validade das credenciais armazenadas nesse arquivo.

Veja um exemplo de resposta de erro executável:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Todos esses campos são obrigatórios para uma resposta de erro. A biblioteca usa os campos de código e mensagem como parte de uma exceção gerada.

Resumo dos campos de formato de resposta: * version: a versão da saída JSON. Apenas a versão 1 é compatível. * success: quando verdadeiro, a resposta precisa incluir o token e o tipo de token de terceiros. A resposta também precisa incluir o campo expiration_time se um arquivo de saída tiver sido especificado na configuração da credencial. O executável também precisa sair com um código de saída 0. Quando for "false", a resposta precisará incluir o código do erro e os campos de mensagem e sair com um valor diferente de zero. * token_type: este campo especifica o tipo de token de assunto de terceiros. Precisa ser urn:ietf:params:oauth:token-type:jwt, urn:ietf:params:oauth:token-type:id_token ou urn:ietf:params:oauth:token-type:saml2. * id_token: o token OIDC de terceiros. * saml_response: a resposta SAML de terceiros. * expiration_time: o prazo de validade do token de assunto de terceiros em segundos (horário da época Unix). * code: a string do código de erro. * message: a mensagem de erro.

Todos os tipos de resposta precisam incluir os campos version e success. * As respostas bem-sucedidas precisam incluir token_type e id_token ou saml_response. O campo expiration_time também precisa estar presente se um arquivo de saída tiver sido especificado na configuração da credencial. * As respostas de erro precisam incluir os campos code e message.

A biblioteca preenche as seguintes variáveis de ambiente quando executa o executável:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: o campo de público-alvo da configuração da credencial. Sempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: o tipo de token de assunto esperado. Sempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL: o endereço de e-mail da conta de serviço. Presente apenas quando a identidade temporária de conta de serviço é usada.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: o local do arquivo de saída da configuração da credencial. Presente somente quando especificado na configuração de credencial.

Essas variáveis de ambiente podem ser usadas pelo executável para evitar que esses valores sejam codificados.

Considerações sobre segurança

Recomendamos as seguintes práticas de segurança:

  • Impeça que processos invasores executem o executável, porque ele vai gerar credenciais sensíveis para esses processos e os usuários deles por meio de stdout.
  • Impedir que processos invasores alterem a configuração ou a invocação do executável.

Devido à complexidade do uso de credenciais de origem executável, recomendamos que você use outros mecanismos compatíveis, como fontes de arquivos ou URLs, para fornecer credenciais de terceiros, a menos que elas não atendam aos seus requisitos específicos.

Agora é possível usar a biblioteca de autenticação para chamar recursos doGoogle Cloud de um provedor OIDC ou SAML.

Usar um fornecedor personalizado com OIDC e SAML

Uma implementação personalizada de IdentityPoolSubjectTokenSupplier pode ser usada ao criar IdentityPoolCredentials para fornecer um token de assunto que pode ser trocado por um token de acesso do Google Cloud . O fornecedor precisa retornar um token de assunto válido e não expirado quando chamado pela credencial Google Cloud.

IdentityPoolCredentials não armazena em cache o token retornado. Portanto, implemente a lógica de armazenamento em cache no fornecedor de tokens para evitar várias solicitações para o mesmo token de assunto.

import java.io.IOException;

public class CustomTokenSupplier implements IdentityPoolSubjectTokenSupplier {

  @Override
  public String getSubjectToken(ExternalAccountSupplierContext context) throws IOException {
    // Any call to the supplier passes a context object with the requested
    // audience and subject token type.
    string audience = context.getAudience();
    string tokenType = context.getSubjectTokenType();

    try {
      // Return a valid, unexpired token for the requested audience and token type.
      // Note that IdentityPoolCredentials don't cache the subject token so
      // any caching logic needs to be implemented in the token supplier.
      return retrieveToken(audience, tokenType);
    } catch (Exception e) {
      // If token is unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  private String retrieveToken(string tokenType, string audience) {
    // Retrieve a subject token of the requested type for the requested audience.
  }
}

CustomTokenSupplier tokenSupplier = new CustomTokenSupplier();
IdentityPoolCredentials identityPoolCredentials =
    IdentityPoolCredentials.newBuilder()
        .setSubjectTokenSupplier(tokenSupplier) // Sets the token supplier.
        .setAudience(...) // Sets the Google Cloud audience.
        .setSubjectTokenType(SubjectTokenTypes.JWT) // Sets the subject token type.
        .build();

Em que o público-alvo é:

//iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/providers/<var>PROVIDER_ID</var>

Substitua:

  • PROJECT_NUMBER: o número do projeto do Google Cloud .
  • WORKLOAD_POOL_ID: o ID do pool de Identidade da carga de trabalho.
  • PROVIDER_ID: o ID do provedor.

Também é possível encontrar os valores de público-alvo, URL de identidade temporária de conta de serviço e qualquer outro campo do builder gerando um arquivo de configuração de credencial com a CLI gcloud.

Usar um fornecedor personalizado com a AWS

Uma implementação personalizada de AwsSecurityCredentialsSupplier pode ser fornecida ao inicializar AwsCredentials. Se fornecida, a instância AwsCredentials vai adiar para o fornecedor a recuperação das credenciais de segurança da AWS para trocar por um token de acesso doGoogle Cloud . O fornecedor precisa retornar credenciais de segurança da AWS válidas e não expiradas quando chamado pela credencial Google Cloud .

AwsCredentials não armazena em cache as credenciais de segurança ou a região da AWS retornadas. Portanto, implemente a lógica de armazenamento em cache no fornecedor para evitar várias solicitações para os mesmos recursos.

class CustomAwsSupplier implements AwsSecurityCredentialsSupplier {
  @Override
  AwsSecurityCredentials getAwsSecurityCredentials(ExternalAccountSupplierContext context) throws IOException {
    // Any call to the supplier passes a context object with the requested
    // audience.
    String audience = context.getAudience();

    try {
      // Return valid, unexpired AWS security credentials for the requested audience.
      // Note that AwsCredentials don't cache the AWS security credentials so
      // any caching logic needs to be implemented in the credentials' supplier.
      return retrieveAwsSecurityCredentials(audience);
    } catch (Exception e) {
      // If credentials are unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  @Override
  String getRegion(ExternalAccountSupplierContext context) throws IOException {
    try {
      // Return a valid AWS region. i.e. "us-east-2".
      // Note that AwsCredentials don't cache the region so
      // any caching logic needs to be implemented in the credentials' supplier.
      return retrieveAwsRegion();
    } catch (Exception e) {
      // If region is unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  private AwsSecurityCredentials retrieveAwsSecurityCredentials(string audience) {
    // Retrieve Aws security credentials for the requested audience.
  }

  private String retrieveAwsRegion() {
    // Retrieve current AWS region.
  }
}

CustomAwsSupplier awsSupplier = new CustomAwsSupplier();
AwsCredentials credentials = AwsCredentials.newBuilder()
    .setSubjectTokenType(SubjectTokenTypes.AWS4) // Sets the subject token type.
    .setAudience(...) // Sets the Google Cloud audience.
    .setAwsSecurityCredentialsSupplier(supplier) // Sets the supplier.
    .build();

Em que o público-alvo é: //iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/providers/<var>PROVIDER_ID</var>

Substitua:

  • PROJECT_NUMBER: o número do projeto do Google Cloud .
  • WORKLOAD_POOL_ID: o ID do pool de Identidade da carga de trabalho.
  • PROVIDER_ID: o ID do provedor.

Também é possível encontrar os valores de público-alvo, URL de identidade temporária de conta de serviço e qualquer outro campo do builder gerando um arquivo de configuração de credencial com a CLI gcloud.

Ciclo de vida do token configurável

Ao criar uma configuração de credencial com a federação de identidade da carga de trabalho usando a identidade temporária de conta de serviço, é possível fornecer um argumento opcional para configurar o ciclo de vida do token de acesso da conta de serviço.

Para gerar a configuração com o ciclo de vida do token configurável, execute o seguinte comando (este exemplo usa uma configuração da AWS, mas o ciclo de vida do token pode ser configurado para todos os provedores de federação de identidade de carga de trabalho):

  # Generate an AWS configuration file with configurable token lifetime.
  gcloud iam workload-identity-pools create-cred-config \
      projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AWS_PROVIDER_ID</var> \
      --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
      --aws \
      --output-file /path/to/generated/config.json \
      --service-account-token-lifetime-seconds <var>TOKEN_LIFETIME</var>

Substitua:

  • PROJECT_NUMBER: o número do projeto do Google Cloud .
  • POOL_ID: o ID do pool de Identidade da carga de trabalho.
  • AWS_PROVIDER_ID: o ID do provedor da AWS.
  • SERVICE_ACCOUNT_EMAIL: o e-mail da conta de serviço que será personificada.
  • TOKEN_LIFETIME: a duração do ciclo de vida selecionado do token de acesso da conta de serviço em segundos.

A sinalização service-account-token-lifetime-seconds é opcional. Se não for fornecida, a flag vai usar o padrão de uma hora. O valor mínimo permitido é 600 (10 minutos) e o valor máximo permitido é 43200 (12 horas). Se você precisar de um ciclo de vida maior que uma hora, adicione a conta de serviço como um valor permitido em um Serviço de Política da Organização que aplique a restrição constraints/iam.allowServiceAccountCredentialLifetimeExtension.

Configurar um ciclo de vida curto (por exemplo, 10 minutos) faz com que a biblioteca inicie todo o fluxo de troca de tokens a cada 10 minutos. Isso chama o provedor de token de terceiros, mesmo que o token de terceiros não tenha expirado.

Usar credenciais de força de trabalho de usuário autorizado de conta externa

As credenciais de usuário autorizado de conta externa permitem que você faça login com um navegador da web em uma conta de provedor de identidade externa usando a CLI gcloud e crie uma configuração para a biblioteca Auth usar.

Para gerar uma configuração de identidade de colaboradores de usuário autorizado de conta externa, execute o seguinte comando:

gcloud auth application-default login --login-config=LOGIN_CONFIG

Em que a seguinte variável precisa ser substituída:

Isso abre um fluxo do navegador para você fazer login usando o provedor de identidade de terceiros configurado. Em seguida, ele armazena a configuração do usuário autorizado da conta externa no local conhecido do ADC.

A biblioteca de autenticação vai usar o token de atualização fornecido na configuração para gerar e atualizar um token de acesso para chamar os serviços do Google Cloud .

A vida útil padrão do token de atualização é de uma hora. Depois disso, você precisa gerar uma nova configuração na CLI gcloud. É possível modificar o ciclo de vida alterando a duração da sessão do pool de força de trabalho, e defini-lo como até 12 horas.

Usar identidades externas

É possível usar identidades externas com o Application Default Credentials. Para usar identidades externas com o Application Default Credentials, gere o arquivo de configuração de credenciais JSON para sua identidade externa, conforme descrito na seção Federação de Identidade da Carga de Trabalho. Depois de gerado, armazene o caminho para esse arquivo na variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.json

Agora, a biblioteca pode escolher o tipo certo de cliente e inicializar as credenciais do contexto fornecido pelo arquivo de configuração.

GoogleCredentials googleCredentials = GoogleCredentials.getApplicationDefault();

String projectId = "your-project-id";
String url = "https://storage.googleapis.com/storage/v1/b?project=" + projectId;

HttpCredentialsAdapter credentialsAdapter = new HttpCredentialsAdapter(googleCredentials);
HttpRequestFactory requestFactory = new NetHttpTransport().createRequestFactory(credentialsAdapter);
HttpRequest request = requestFactory.buildGetRequest(new GenericUrl(url));

JsonObjectParser parser = new JsonObjectParser(GsonFactory.getDefaultInstance());
request.setParser(parser);

HttpResponse response = request.execute();
System.out.println(response.parseAsString());

Também é possível inicializar explicitamente os clientes de contas externas usando o arquivo de configuração gerado.

ExternalAccountCredentials credentials =
    ExternalAccountCredentials.fromStream(new FileInputStream("/path/to/credentials.json"));

Considerações sobre segurança

Essa biblioteca não realiza nenhuma validação nos campos token_url, token_info_url ou service_account_impersonation_url da configuração da credencial. Não recomendamos que você use uma configuração de credencial que não tenha sido gerada com a CLI gcloud, a menos que verifique se os campos de URL apontam para um domínio googleapis.com.

Reduzir escopo com limites de acesso a credenciais

A redução de escopo com limites de acesso a credenciais permite restringir as permissões do Identity and Access Management (IAM) que uma credencial de curta duração pode usar para o Cloud Storage. Isso envolve a criação de uma CredentialAccessBoundary que define as restrições que se aplicam ao token com escopo reduzido. O uso de credenciais com escopo reduzido garante que os tokens em trânsito sempre tenham o privilégio mínimo. Consulte Princípio de privilégio mínimo.

Criar um CredentialAccessBoundary

O limite de acesso a credenciais especifica quais recursos a credencial recém-criada pode acessar. Ela também especifica um limite superior para as permissões disponíveis em cada recurso. Ele inclui um ou mais objetos AccessBoundaryRule.

O snippet a seguir mostra como inicializar um CredentialAccessBoundary com um AccessBoundaryRule. Essa regra especifica que o token com escopo reduzido terá acesso somente leitura a objetos que começam com customer-a no bucket bucket-123.

// Create the AccessBoundaryRule.
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
        CredentialAccessBoundary.AccessBoundaryRule.AvailabilityCondition.newBuilder().setExpression(expression).build())
        .build();

// Create the CredentialAccessBoundary with the rule.
CredentialAccessBoundary credentialAccessBoundary =
        CredentialAccessBoundary.newBuilder().addRule(rule).build();

Padrão de uso comum

O padrão de uso comum envolve um agente de token com acesso elevado. Esse agente gera credenciais com escopo reduzido com base em credenciais de origem de acesso mais alto. Em seguida, ele transmite os tokens de acesso de curta duração com escopo reduzido para um consumidor de tokens por um canal autenticado seguro para acesso limitado aos recursos do armazenamento do Google Cloud.

Gerar tokens com escopo reduzido

Há duas maneiras de gerar tokens com escopo reduzido usando um CredentialAccessBoundary:

  • Do lado do servidor (usando DownscopedCredentials): o cliente chama o Security Token Service (STS) sempre que um token com escopo reduzido é necessário. Isso é adequado para aplicativos em que as regras de limite de acesso de credenciais mudam com pouca frequência ou em que você reutiliza uma única credencial com escopo reduzido várias vezes. Uma consideração importante é que cada mudança de regra exige que você faça uma nova chamada para o STS. Essa abordagem está disponível na biblioteca google-auth-library-oauth2-http e não requer outras dependências. Isso simplifica a integração. É uma boa opção se o caso de uso não exigir os benefícios específicos da abordagem do lado do cliente.

  • Do lado do cliente (usando ClientSideCredentialAccessBoundaryFactory): o cliente recupera o material criptográfico uma vez e gera vários tokens com escopo reduzido localmente. Isso minimiza as chamadas para o STS e é mais eficiente quando as regras de limite de acesso de credenciais mudam com frequência, porque o cliente não precisa entrar em contato com o STS para cada mudança de regra. Isso também é mais eficiente para aplicativos que precisam gerar muitos tokens com escopo reduzido exclusivos. Essa abordagem está disponível no módulo google-auth-library-cab-token-generator. No entanto, esse módulo tem um conjunto próprio de dependências. Essas dependências podem adicionar complexidade ao projeto. Considere essa abordagem se minimizar as chamadas do STS e gerar vários tokens exclusivos forem as principais preocupações. Você também precisará gerenciar as dependências extras.

CAB do lado do servidor

A classe DownscopedCredentials pode ser usada para produzir um token de acesso com escopo reduzido com base em uma credencial de origem e no CredentialAccessBoundary.

// Retrieve the source credentials from ADC.
GoogleCredentials sourceCredentials = GoogleCredentials.getApplicationDefault()
        .createScoped("https://www.googleapis.com/auth/cloud-platform");

// Create an Access Boundary Rule which will restrict the downscoped token to having read-only
// access to objects starting with "customer-a" in bucket "bucket-123".
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
            new AvailabilityCondition(expression, /* title= */ null, /* description= */ null))
        .build();

// Initialize the DownscopedCredentials class.
DownscopedCredentials downscopedCredentials =
    DownscopedCredentials.newBuilder()
        .setSourceCredential(sourceCredentials)
        .setCredentialAccessBoundary(CredentialAccessBoundary.newBuilder().addRule(rule).build())
        .build();

// Retrieve the downscoped access token.
// You will need to pass this to the Token Consumer.
AccessToken downscopedAccessToken = downscopedCredentials.refreshAccessToken();

CAB do lado do cliente

Para CAB do lado do cliente, o ClientSideCredentialAccessBoundaryFactory é usado com uma credencial de origem. Depois de inicializar a fábrica, o método generateToken() pode ser chamado repetidamente com diferentes objetos CredentialAccessBoundary para criar vários tokens com escopo reduzido.

// Retrieve the source credentials from ADC.
GoogleCredentials sourceCredentials = GoogleCredentials.getApplicationDefault()
        .createScoped("https://www.googleapis.com/auth/cloud-platform");

// Create an Access Boundary Rule which will restrict the downscoped token to having read-only
// access to objects starting with "customer-a" in bucket "bucket-123".
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
            new AvailabilityCondition(expression, /* title= */ null, /* description= */ null))
        .build();

// Initialize the ClientSideCredentialAccessBoundaryFactory.
ClientSideCredentialAccessBoundaryFactory factory =
    ClientSideCredentialAccessBoundaryFactory.newBuilder()
        .setSourceCredential(sourceCredentials)
        .build();

// Create the CredentialAccessBoundary with the rule.
CredentialAccessBoundary credentialAccessBoundary =
        CredentialAccessBoundary.newBuilder().addRule(rule).build();

// Generate the downscoped access token.
// You will need to pass this to the Token Consumer.
AccessToken downscopedAccessToken = factory.generateToken(credentialAccessBoundary);

Usar tokens de acesso com escopo reduzido

É possível configurar um agente de token em um servidor em uma rede privada. Várias cargas de trabalho (consumidores de token) na mesma rede enviam solicitações autenticadas para esse agente para tokens com escopo reduzido. Esses tokens permitem que eles acessem ou modifiquem buckets específicos do Google Cloud Storage.

O agente instancia instâncias de credenciais com escopo reduzido que podem gerar tokens de acesso com escopo reduzido de curta duração. Em seguida, ele transmite esses tokens para o consumidor de tokens.

Esses tokens de acesso com escopo reduzido podem ser usados pelo consumidor de tokens usando OAuth2Credentials ou OAuth2CredentialsWithRefresh. Em seguida, use essa credencial para inicializar uma instância de cliente do Storage para acessar recursos do Google CloudStorage com acesso restrito.

// You can pass an `OAuth2RefreshHandler` to `OAuth2CredentialsWithRefresh` that will allow the
// library to seamlessly handle downscoped token refreshes on expiration.
OAuth2CredentialsWithRefresh.OAuth2RefreshHandler handler =
        new OAuth2CredentialsWithRefresh.OAuth2RefreshHandler() {
    @Override
    public AccessToken refreshAccessToken() {
      // Retrieve the token from your Token Broker.
      return accessToken;
    }
};

// The downscoped token is retrieved from the token broker.
AccessToken downscopedToken = handler.refreshAccessToken();

// Build the OAuth2CredentialsWithRefresh from the downscoped token and pass a refresh handler
// to handle token expiration. Passing the original downscoped token or the expiry here is optional,
// because the refresh_handler will generate the downscoped token on demand.
OAuth2CredentialsWithRefresh credentials =
    OAuth2CredentialsWithRefresh.newBuilder()
        .setAccessToken(downscopedToken)
        .setRefreshHandler(handler)
        .build();

// Use the credentials with the Cloud Storage SDK.
StorageOptions options = StorageOptions.newBuilder().setCredentials(credentials).build();
Storage storage = options.getService();

// Call Cloud Storage APIs.
// Because we passed the downscoped credential, we will have limited read-only access to objects
// starting with "customer-a" in bucket "bucket-123".
storage.get(...)

Somente o Cloud Storage é compatível com os limites de acesso a credenciais. Outros serviços doGoogle Cloud não são compatíveis com esse recurso.

Usar credenciais com google-http-client

As credenciais fornecidas por com.google.auth:google-auth-library-oauth2-http podem ser usadas com os clientes baseados em HTTP do Google. Os clientes baseados em HTTP do Google fornecem um HttpCredentialsAdapter que pode ser usado como um HttpRequestInitializer, o último argumento para os builders.

import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.services.bigquery.Bigquery;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(credentials);

Bigquery bq = new Bigquery.Builder(HTTP_TRANSPORT, JSON_FACTORY, requestInitializer)
    .setApplicationName(APPLICATION_NAME)
    .build();

Verificar tokens JWT (recurso Beta)

Para verificar um token JWT, use a classe TokenVerifier.

Verificar uma assinatura

Para verificar uma assinatura, use o TokenVerifier padrão:

import com.google.api.client.json.webtoken.JsonWebSignature;
import com.google.auth.oauth2.TokenVerifier;

TokenVerifier tokenVerifier = TokenVerifier.newBuilder().build();
try {
  JsonWebSignature jsonWebSignature = tokenVerifier.verify(tokenString);
  // Optionally, verify additional claims.
  if (!"expected-value".equals(jsonWebSignature.getPayload().get("additional-claim"))) {
    // Handle custom verification error.
  }
} catch (TokenVerifier.VerificationException e) {
  // The token is invalid.
}

Personalizar o TokenVerifier

Para personalizar um TokenVerifier, instancie-o usando o builder:

import com.google.api.client.json.webtoken.JsonWebSignature;
import com.google.auth.oauth2.TokenVerifier;

TokenVerifier tokenVerifier = TokenVerifier.newBuilder()
  .setAudience("audience-to-verify")
  .setIssuer("issuer-to-verify")
  .build();
try {
  JsonWebSignature jsonWebSignature = tokenVerifier.verify(tokenString);
  // Optionally, verify additional claims.
  if (!"expected-value".equals(jsonWebSignature.getPayload().get("additional-claim"))) {
    // Handle custom verification error.
  }
} catch (TokenVerifier.VerificationException e) {
  // The token is invalid.
}

Para mais opções, consulte a documentação do TokenVerifier.Builder.

google-auth-library-credentials

Esse artefato contém classes de base e interfaces para credenciais do Google:

  • Credentials: é a classe de base de uma identidade autorizada. As implementações dessa classe podem autorizar seu aplicativo.
  • RequestMetadataCallback: é a interface do callback que recebe o resultado do Credentials.getRequestMetadata(URI, Executor, RequestMetadataCallback) assíncrono.
  • ServiceAccountSigner: é a interface de um signatário da conta de serviço. As implementações dessa classe podem assinar matrizes de bytes usando as credenciais associadas a uma conta de serviço do Google.

google-auth-library-appengine

Esse artefato depende do SDK do App Engine (appengine-api-1.0-sdk). Use-o apenas para aplicativos em execução em ambientes do App Engine que usam urlfetch. A classe AppEngineCredentials permite autorizar o aplicativo do App Engine com uma instância de AppIdentityService.

Uso:

import com.google.appengine.api.appidentity.AppIdentityService;
import com.google.appengine.api.appidentity.AppIdentityServiceFactory;
import com.google.auth.Credentials;
import com.google.auth.appengine.AppEngineCredentials;

AppIdentityService appIdentityService = AppIdentityServiceFactory.getAppIdentityService();

Credentials credentials =
    AppEngineCredentials.newBuilder()
        .setScopes(...)
        .setAppIdentityService(appIdentityService)
        .build();

google-auth-library-cab-token-generator

Esse módulo fornece a classe ClientSideCredentialAccessBoundaryFactory, permitindo a geração no lado do cliente de tokens com escopo reduzido para o Cloud Storage usando limites de acesso a credenciais. Essa abordagem é útil principalmente para aplicativos que exigem mudanças frequentes nas regras de limite de acesso de credenciais ou a geração de muitos tokens exclusivos com escopo reduzido, porque minimiza as chamadas para o Security Token Service (STS). Para exemplos de uso, consulte a seção CAB do lado do cliente. Esse módulo vem com o próprio conjunto de dependências. Avalie se os benefícios da redução de escopo do lado do cliente superam a complexidade adicional para seu caso de uso específico.