Tipos de token

Nesta página, falamos sobre os tipos de tokens usados para autenticação nas APIs do Google, nos serviços do Google Cloud e nos serviços criados pelo cliente hospedados no Google Cloud.

Se você estiver acessando as APIs e serviços do Google com o uso de uma biblioteca de cliente, será possível configurar o Application Default Credentials e a biblioteca processará tokens para você. Esse é o método recomendado.

O que são tokens

Para autenticação e autorização, um token é um objeto digital que contém informações sobre a identidade do principal que faz a solicitação e para que tipo de acesso ele está autorizado. Na maioria dos fluxos de autenticação, o aplicativo, ou uma biblioteca usada pelo aplicativo, troca uma credencial por um token, que determina quais recursos o aplicativo pode ser autorizado a acessar.

Tipos de tokens

Diferentes tipos de tokens são usados em diferentes ambientes. Os tipos de token a seguir estão descritos nesta página:

Nesta página, não abordamos chaves de API ou IDs do cliente, que são considerados credenciais.

Tokens de acesso

Os tokens de acesso são opacos em conformidade com o framework do OAuth 2.0. Eles contêm informações de autorização, mas não informações de identidade. Eles são usados para autenticar e fornecer informações de autorização às APIs do Google.

Se você usa o Application Default Credentials (ADC) e as bibliotecas de cliente do Cloud ou de APIs do Google, não é necessário gerenciar tokens de acesso. as bibliotecas recuperam automaticamente a credencial, a trocam por um token de acesso e atualizam o token de acesso conforme necessário.

Conteúdo do token de acesso

Os tokens de acesso são opacos, o que significa que estão em um formato reservado; aplicativos não podem inspecioná-los.

Você pode conseguir as informações de um token de acesso válido (não expirado ou revogado) usando o endpoint tokeninfo do Google OAuth 2.0.

Substitua ACCESS_TOKEN pelo token de acesso válido e não expirado.

curl "https://oauth2.googleapis.com/tokeninfo?access_token=ACCESS_TOKEN"

Esse comando retorna algo semelhante ao exemplo a seguir:

{
  "azp": "32553540559.apps.googleusercontent.com",
  "aud": "32553540559.apps.googleusercontent.com",
  "sub": "111260650121245072906",
  "scope": "openid https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/accounts.reauth",
  "exp": "1650056632",
  "expires_in": "3488",
  "email": "user@example.com",
  "email_verified": "true"
}

A tabela a seguir lista os campos mais importantes para entender:

Campo Descrição
azp O ID do projeto, e-mail ou conta de serviço do aplicativo que solicitou o token. Esse valor só será incluído se https://www.googleapis.com/auth/userinfo.email for especificado na lista de escopos.
scope Os escopos do OAuth que foram adicionados a esse token de acesso. Para serviços do Google Cloud, é uma prática recomendada usar o escopo https://www.googleapis.com/auth/cloud-platform , que inclui todas as APIs do Google Cloud, além de Identity and Access Management (IAM), que fornece controle de acesso refinado.
expires_in O número de segundos até o token expirar Para mais informações, consulte Ciclo de vida do token de acesso.

Ciclo de vida do token de acesso

Por padrão, os tokens de acesso são válidos por 1 hora (3.600 segundos). Quando o token de acesso expirar, o código de gerenciamento de tokens precisará receber um novo.

Se você precisar de um token de acesso com um ciclo de vida mais longo ou mais curto, use o método serviceAccounts.generateAccessToken a fim de criar o token. Esse método permite escolher o ciclo de vida do token, com um máximo de 12 horas.

Se você quiser estender o ciclo de vida do token além do padrão, crie uma política da organização que ative a restrição iam.allowServiceAccountCredentialLifetimeExtension. Para mais informações, consulte Criar um token de acesso de curta duração.

Tokens de ID

Os tokens de ID são JSON Web Tokens (JWTs) que estão em conformidade com a especificação OpenID Connect (OIDC). Eles são compostos por um conjunto de pares de chave-valor chamados reivindicações.

Ao contrário dos tokens de acesso, que são objetos opacos que não podem ser inspecionados pelo aplicativo, os tokens de ID precisam ser inspecionados e usados pelo aplicativo. Informações do token, como "Quem assinou o token" ou a identidade para quem o token de ID foi emitido, estão disponíveis para uso pelo aplicativo.

Para mais informações sobre a implementação do OIDC do Google, consulte OpenID Connect. Para conhecer as práticas recomendadas ao trabalhar com JWTs, consulte Práticas recomendadas atuais para JSON Web Tokens.

Conteúdo do token de ID

É possível inspecionar um token de ID válido (não expirado ou revogado) usando o endpoint tokeninfo.

Substitua ID_TOKEN pelo token de ID válido e não expirado.

curl "https://oauth2.googleapis.com/tokeninfo?id_token=ID_TOKEN"

Esse comando retorna algo semelhante ao exemplo a seguir:

{
  "iss": "https://accounts.google.com",
  "azp": "32555350559.apps.googleusercontent.com",
  "aud": "32555350559.apps.googleusercontent.com",
  "sub": "111260650121185072906",
  "hd": "google.com",
  "email": "user@example.com",
  "email_verified": "true",
  "at_hash": "_LLKKivfvfme9eoQ3WcMIg",
  "iat": "1650053185",
  "exp": "1650056785",
  "alg": "RS256",
  "kid": "f1338ca26835863f671403941738a7b49e740fc0",
  "typ": "JWT"
}

A tabela a seguir descreve as declarações de token de ID obrigatórias ou usadas com frequência:

Reivindicação Descrição
iss O emissor ou signatário do token. Para tokens de ID assinados pelo Google, esse valor é https://accounts.google.com.
azp Opcional. Para quem o token foi emitido.
aud O público do token. O valor dessa declaração precisa corresponder ao aplicativo ou serviço que usa o token para autenticar a solicitação. Para mais informações, consulte a reivindicação aud do token de ID.
sub O assunto: o ID que representa o principal que está fazendo a solicitação.
iat Tempo de época do Unix em que o token foi emitido.
exp Tempo de época do Unix quando o token expira.

Outras reivindicações podem estar presentes, dependendo do emissor e do aplicativo.

Declaração do token de ID aud

A declaração aud descreve o nome do serviço em que esse token foi criado para invocar. Se um serviço receber um token de ID, ele precisará verificar a integridade (assinatura), a validade (ele expirou) e se a declaração aud corresponde ao nome esperado. Se ele não corresponder, o serviço precisará rejeitar o token, porque pode ser uma reprodução repetida para outro sistema.

Geralmente, ao receber um token de ID, você usa as credenciais fornecidas por uma conta de serviço, em vez de credenciais de usuário. Isso ocorre porque a declaração aud para tokens de ID gerados usando credenciais de usuário está vinculada estaticamente ao aplicativo usado pelo usuário para autenticar. Ao usar uma conta de serviço para adquirir um token de ID, é possível especificar um valor diferente para a declaração aud.

Ciclo de vida do token de ID

Os tokens de ID são válidos por até uma hora (3.600 segundos). Quando um token de ID expirar, você precisará adquirir um novo.

Validação do token de ID

Quando o serviço ou app usa um serviço do Google, como Cloud Run, funções do Cloud Run ou Identity-Aware Proxy, o Google valida os tokens de ID para você. Nesses casos, os tokens de ID precisam ser assinados pelo Google.

Se for necessário validar os tokens de ID no seu aplicativo, você pode fazer isso, embora esse fluxo de trabalho seja avançado. Para mais informações, consulte Como validar um token de ID.

JSON Web Tokens (JWTs) autoassinados

É possível usar JWTs autoassinados para autenticação em algumas APIs do Google sem precisar receber um token de acesso do servidor de autorização.

A criação de JWTs autoassinados é recomendada se você está criando suas próprias bibliotecas de cliente para acessar as APIs do Google, mas é um fluxo de trabalho avançado. Para mais informações sobre JWTs autoassinados, consulte Como criar um token da Web JSON autoassinado. Para conhecer as práticas recomendadas para trabalhar com JWTs, consulte Práticas recomendadas atuais de tokens da Web JSON.

Tokens de atualização

Seu IdP gerencia o ciclo de vida dos tokens de longa duração. Uma exceção são os arquivos locais do ADC, que contêm tokens de atualização usados pelas bibliotecas de autenticação para atualizar automaticamente os tokens de acesso para bibliotecas de cliente.

Tokens federados

Os tokens federados são usados como uma etapa intermediária pela federação de identidade da carga de trabalho. Os tokens federados são retornados pelo Security Token Service e não podem ser usados diretamente. Eles precisam ser trocados por um token de acesso usando a representação da conta de serviço.

Tokens do portador

Os tokens do portador são uma classe geral do token que concede acesso à parte em posse do token. Os tokens de acesso, tokens de ID e JWTs autoassinados são tokens do portador.

O uso de tokens do portador para autenticação depende da segurança fornecida por um protocolo criptografado, como HTTPS; se um token do portador for interceptado, ele poderá ser usado por um usuário de má-fé para conseguir acesso.

Se os tokens do portador não fornecerem segurança suficiente para seu caso de uso, considere adicionar outra camada de criptografia ou usar uma solução de Transport Layer Security mútuo (mTLS), como o Chrome Enterprise Premium, que limita o acesso apenas a usuários autenticados em um dispositivo confiável.

A seguir