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

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

Ao seguir este guia, você vai aprender a:

Adicione as dependências necessárias da biblioteca de autenticação ao seu projeto usando Maven, Gradle ou Simple Build Tool (SBT).
Autenticar usando vários métodos, com foco no Application Default Credentials (ADC).
Configure cenários avançados de autenticação, incluindo federação de identidade da carga de trabalho, federação de identidade de colaboradores e personificação de conta de serviço.
Gere e use 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 da biblioteca de autenticação do Google.

A Biblioteca de Autenticação do Google para Java consiste em quatro artefatos:

O google-auth-library-credentials contém classes base e interfaces para credenciais do Google.
O 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 credenciais padrão do aplicativo. Ele também fornece a abordagem do lado do servidor para gerar tokens com escopo reduzido.
O google-auth-library-cab-token-generator fornece a abordagem do lado do cliente para gerar tokens com escopo reduzido.

Validar configurações de credenciais

Quando você usa configurações de credenciais, como JSON, caminhos de arquivos ou fluxos, de uma fonte externa, é necessário validá-las. Fornecer credenciais não validadas para APIs do Google ou bibliotecas de cliente para autenticação em Google Cloud pode comprometer a segurança dos seus sistemas e dados.

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

Importar a biblioteca de autenticação

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 Maven ou Gradle.

Java SDK libraries-bom

Para autenticar uma biblioteca de cliente no SDK 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 de autenticação 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 usar 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 seu 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 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 Scala, não é possível importar o google-auth-library-bom para processar automaticamente 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 entre dependências transitivas, causando comportamento inesperado ou erros de tempo de execução no aplicativo.

Adicione isso às suas dependências se estiver usando o SBT:

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

Migrar de `GoogleCredential` para `GoogleCredentials`

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

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

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();

A maneira de usar GoogleCredentials depende da biblioteca de cliente:

Bibliotecas de cliente do Cloud:essas bibliotecas usam automaticamente o Application Default Credentials (ADC), então não é necessário fornecer credenciais no código.
Bibliotecas de cliente das APIs do Google:é necessário instanciar GoogleCredentials e transmiti-los ao cliente. Para um exemplo, consulte o guia do cliente Java da API do Google.

Application Default Credentials

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

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

A 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 da carga de trabalho para ambientes que não sãoGoogle 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 as 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 seguintes itens são pesquisados, nesta ordem, para encontrar as Application Default Credentials:

Arquivo de credenciais apontado pela variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.
Credenciais fornecidas pelo comando gcloud auth application-default login do SDK do Google Cloud.
Credenciais integradas do Google App Engine.
Google Cloud Credenciais integradas do shell.
Credenciais integradas do Google Compute Engine.
- Pule essa verificação definindo 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 fique disponível.

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

Credenciais falsificadas

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

Para usar o ImpersonatedCredentials, você precisa atender aos seguintes 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). Os ImpersonatedCredentials resultantes são usados 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.iam.gserviceaccount.com")
        .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);
}

Federação de identidade da carga de trabalho

Com a federação de identidade da carga de trabalho, seu aplicativo pode acessar recursos 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 usavam chaves de conta de serviço para acessar 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 a sobrecarga de manutenção e segurança associada às chaves de conta de serviço.

Acessar recursos da AWS

Para acessar recursos Google Cloud da Amazon Web Services (AWS), primeiro configure a federação de identidade da carga de trabalho. O processo de configuração está 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 da 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 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 a ser personificada.

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

Se você estiver usando o AWS IMDSv2 , adicione uma flag --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 você pode usar a biblioteca de autenticação para chamar recursosGoogle Cloud da AWS.

Acessar recursos pelo Microsoft Azure

Para acessar recursos do Microsoft Azure, primeiro configure a federação de identidade da carga de trabalho. Google Cloud O processo de configuração está detalhado em Como acessar recursos do Azure.

# 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 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 a ser personificada.

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 Google Cloud do Azure.

Acesse recursos por um provedor de identidade OIDC

Para acessar 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 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 sensíveis que instruem a biblioteca a recuperar tokens de assunto externos e trocá-los por tokens de acesso da conta de serviço.

Para provedores OIDC, a biblioteca Auth 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 do arquivo, um processo em segundo plano precisa atualizar continuamente o local do arquivo com um novo token OIDC antes da expiração. Para tokens com ciclo de vida de uma hora, é necessário atualizar o token no arquivo a cada hora. Você pode 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 Google Cloud .
POOL_ID:o ID do pool de identidade da carga de trabalho.
OIDC_PROVIDER_ID:o ID do provedor OIDC.
SERVICE_ACCOUNT_EMAIL:o e-mail da conta de serviço a ser personificada.
PATH_TO_OIDC_ID_TOKEN:o caminho usado para recuperar o token do 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 fornece 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 da carga de trabalho do OIDC fornecida por 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 Google Cloud .
POOL_ID:o ID do pool de identidade da carga de trabalho.
OIDC_PROVIDER_ID:o ID do provedor OIDC.
SERVICE_ACCOUNT_EMAIL:o e-mail da conta de serviço a ser personificada.
URL_TO_GET_OIDC_TOKEN:o URL do endpoint do servidor local a ser chamado para recuperar o token do OIDC.
HEADER_KEY e HEADER_VALUE: os pares de chave-valor de cabeçalho adicionais a serem transmitidos com a solicitação GET para URL_TO_GET_OIDC_TOKEN, por exemplo, Metadata-Flavor=Google.

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

Acessar recursos usando credenciais de origem do certificado X.509

Para credenciais originadas de certificados X.509, a biblioteca de autenticação usa um certificado X.509 e uma chave privada para comprovar a identidade do seu 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 credenciais 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 dos arquivos 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.

Comportamento padrão (recomendado)

Se você omitir a flag --credential-cert-configuration-output-file, o 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 comando a seguir 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 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 a ser personificada.
PATH_TO_CERTIFICATE:o caminho onde o certificado X.509 folha está localizado.
PATH_TO_PRIVATE_KEY:o caminho onde a chave privada correspondente do certificado 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 folha e o Truststore configurado no pool da federação de identidade da carga de trabalho. O certificado de folha é opcional neste 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 geralmente é ~/.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 seu caminho personalizado.
cert_config.json:criado em /custom/path/cert_config.json, conforme especificado pela flag.

Agora é possível usar a biblioteca Auth para chamar recursosGoogle Cloud com credenciais de origem 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 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 a ser personificada.
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 e especifica a duração (em milissegundos) que a biblioteca de autenticação vai esperar para que o executável seja concluído. Se não for fornecido, o padrão será de 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 a performance porque as bibliotecas de autenticação primeiro verificam esse arquivo em busca de credenciais válidas e não expiradas antes de executar o executável. Se houver credenciais válidas em cache, as bibliotecas vão usá-las, evitando execuções desnecessárias.

O executável precisa gravar a resposta de 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 obedecer ao formato de resposta especificado nos exemplos a seguir e precisa gerar a resposta para stdout.

Confira um exemplo de resposta OIDC executável bem-sucedida:

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

Confira 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 de credenciais, 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 a validade das credenciais armazenadas nesse arquivo.

Confira 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 "code" e "message" 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 de terceiros e o tipo de token. 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 o 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 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 o token_type e um dos 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 de credenciais. 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 representação da 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 fixados no código.

Considerações sobre segurança

Recomendamos as seguintes práticas de segurança:

Evite que processos não autorizados executem o executável porque ele vai gerar credenciais sensíveis para esses processos e os usuários deles via stdout.
Impedir que processos não autorizados alterem a configuração ou a invocação do executável.

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

Agora é possível usar a biblioteca Auth para chamar recursosGoogle 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 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 do 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 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 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 representação da conta de serviço e qualquer outro campo do builder gerando um arquivo de configuração de credenciais 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 transferir para o fornecedor a recuperação das credenciais de segurança da AWS para troca por um token de acessoGoogle 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 cache no fornecedor para evitar várias solicitações dos 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 Google Cloud .
WORKLOAD_POOL_ID:o ID do pool de identidade da carga de trabalho.
PROVIDER_ID:o ID do provedor.

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 representação da conta de serviço, é possível fornecer um argumento opcional para configurar o tempo de vida do token de acesso da conta de serviço.

Para gerar a configuração com tempo de vida do token configurável, execute o comando a seguir. Este exemplo usa uma configuração da AWS, mas o tempo de vida do token pode ser configurado para todos os provedores de federação de identidade da 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 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 a ser personificada.
TOKEN_LIFETIME:a duração selecionada do ciclo de vida 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 será definida como uma hora por padrão. O valor mínimo permitido é 600 (10 minutos) e o máximo é 43.200 (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 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 fazer login com um navegador da Web em uma conta de provedor de identidade externa usando a CLI gcloud e criar uma configuração para uso da biblioteca de autenticação.

Para gerar uma configuração de identidade de colaboradores do usuário autorizado de uma 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:

LOGIN_CONFIG:o arquivo de configuração de login gerado com o console Google Cloud ou gcloud iam workforce-pools create-login-config

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

Em seguida, a biblioteca Auth vai usar o token de atualização fornecido da configuração para gerar e atualizar um token de acesso para chamar serviços Google Cloud .

A vida útil padrão do token de atualização é de uma hora. Depois disso, gere uma nova configuração na CLI gcloud. É possível modificar o tempo de vida mudando a duração da sessão do pool de força de trabalho, que pode ser de até 12 horas.

Usar identidades externas

É possível usar identidades externas com o Application Default Credentials. Para usar identidades externas com 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 no 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 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 de credencial. Não recomendamos o uso de uma configuração de credenciais que não foi gerada com a CLI gcloud, a menos que você verifique se os campos de URL apontam para um domínio googleapis.com.

Reduzir escopo com limites de acesso a credenciais

Diminuir o 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 no Cloud Storage. Isso envolve a criação de um CredentialAccessBoundary que define as restrições aplicadas ao token com escopo reduzido. O uso de credenciais com escopo reduzido garante que os tokens em trânsito sempre tenham privilégios mínimos. Consulte o 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. Ele também especifica um limite máximo 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 tokens com acesso elevado. Esse broker gera credenciais com escopo reduzido de credenciais de origem de acesso mais alto. Em seguida, ele transmite os tokens de acesso de curta duração com escopo reduzido a um consumidor de token por um canal autenticado seguro para acesso limitado aos recursos do Google Cloud Storage.

Gerar tokens com escopo reduzido

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

No 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 a credenciais mudam com pouca frequência ou em que você reutiliza uma única credencial com escopo reduzido muitas 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 dependências extras. Isso simplifica a integração. É uma boa opção se o seu 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 ao STS e é mais eficiente quando as regras do limite de acesso às 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 exclusivos com escopo reduzido. 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 aumentar a complexidade do 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 de uma credencial de origem e o 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 o 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 broker de tokens em um servidor em uma rede privada. Várias cargas de trabalho (consumidores de token) na mesma rede enviam solicitações autenticadas a esse agente para tokens com escopo reduzido. Esses tokens permitem que eles acessem ou modifiquem intervalos de armazenamento Google Cloud específicos.

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

Esses tokens de acesso com escopo reduzido podem ser usados pelo consumidor de token usando OAuth2Credentials ou OAuth2CredentialsWithRefresh. Em seguida, use essa credencial para inicializar uma instância de cliente de armazenamento e acessar recursos do Google Cloud Storage 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(...)

Apenas o Cloud Storage é compatível com limites de acesso a credenciais. Outros serviços doGoogle Cloud não oferecem suporte a esse recurso.

Usar credenciais com `google-http-client`

As credenciais fornecidas por com.google.auth:google-auth-library-oauth2-http podem ser usadas com 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 deles.

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, crie uma instância dele 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 e interfaces básicas para credenciais do Google:

Credentials:é a classe 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 assinante de 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 executados em ambientes do App Engine que usam urlfetch. A classe AppEngineCredentials permite autorizar o aplicativo do App Engine usando 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

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

Começar a usar a Biblioteca de Autenticação do Google Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Validar configurações de credenciais

Importar a biblioteca de autenticação

Java SDK libraries-bom

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

Maven

Gradle

Scala

Migrar de GoogleCredential para GoogleCredentials

Application Default Credentials

Receber o Application Default Credentials

Carregamento explícito de credenciais

Credenciais falsificadas

Federação de identidade da carga de trabalho

Acessar recursos da AWS

Acessar recursos pelo Microsoft Azure

Acesse recursos por um provedor de identidade OIDC

Credenciais fornecidas pelo arquivo

Credenciais fornecidas pelo URL

Acessar recursos usando credenciais de origem do certificado X.509

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

Comportamento padrão (recomendado)

Comportamento de local personalizado

Usar credenciais de origem executáveis com OIDC e SAML

Considerações sobre segurança

Usar um fornecedor personalizado com OIDC e SAML

Usar um fornecedor personalizado com a AWS

Ciclo de vida do token configurável

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

Usar identidades externas

Considerações sobre segurança

Reduzir escopo com limites de acesso a credenciais

Criar um CredentialAccessBoundary

Padrão de uso comum

Gerar tokens com escopo reduzido

CAB do lado do servidor

CAB do lado do cliente

Usar tokens de acesso com escopo reduzido

Usar credenciais com google-http-client

Verificar tokens JWT (recurso Beta)

Verificar uma assinatura

Personalizar o TokenVerifier

google-auth-library-credentials

google-auth-library-appengine

google-auth-library-cab-token-generator

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

Migrar de `GoogleCredential` para `GoogleCredentials`

Criar um `CredentialAccessBoundary`

Usar credenciais com `google-http-client`

Personalizar o `TokenVerifier`

`google-auth-library-credentials`

`google-auth-library-appengine`