Tipos de tokens

Trusted Cloud by S3NS emite vários tipos de tokens, que diferem pela sua finalidade e pelas partes entre as quais são trocados.

A tabela seguinte apresenta uma vista geral das principais categorias de tokens, nas quais existem diferentes tipos de tokens.

Categoria do token Caminho de comunicação Finalidade
Chaves de acesso Servidor de autorização Cliente API Google Permite que os clientes chamem Trusted Cloud by S3NS APIs.
Tokens de concessão de tokens Servidor de autorização Cliente Permite que os clientes obtenham tokens novos ou diferentes, possivelmente, num momento posterior.
Tokens de identidade Servidor de autorização Cliente Permite que os clientes identifiquem o utilizador com o qual estão a interagir.

Os tokens de acesso e identidade são tokens de portador. Os tokens do portador são uma classe geral de tokens que concedem acesso à parte na posse do token.

A utilização de tokens de portador para autenticação baseia-se na segurança fornecida por um protocolo encriptado, como o HTTPS. Se um token de portador for intercetado, pode ser usado por um interveniente prejudicial para obter acesso.

Se os tokens de portador não oferecerem segurança suficiente para o seu exemplo de utilização, pode diminuir o risco de roubo de tokens através do acesso sensível ao contexto, limitando a duração total dos tokens de acesso ou usando uma solução de Transport Layer Security mútua (mTLS), como o Chrome Enterprise Premium.

Tokens de acesso

Os tokens de acesso permitem que os clientes façam chamadas autenticadas para Trusted Cloud by S3NS APIs. Trusted Cloud by S3NS suporta vários tipos diferentes de tokens de acesso, que têm as seguintes propriedades em comum:

  • Autenticam um principal, que pode ser um utilizador ou uma carga de trabalho.

  • São emitidos para um cliente específico.

  • São de curta duração e expiram após, no máximo, algumas horas.

  • Estão restritas a determinados âmbitos, pontos finais ou recursos de OAuth. Isto significa que um token de acesso normalmente não concede acesso a todos os recursos de um utilizador, mas apenas a um determinado subconjunto dos mesmos.

Os tokens de acesso podem diferir das seguintes formas:

  • Emissor: a parte que emite o token.

  • Principal: o tipo de principal que o token pode autenticar.

  • Restrições: as restrições que podem ser impostas ao token.

A tabela seguinte apresenta os diferentes tipos de tokens de acesso:

Tipo de token Emissor Diretores Restrições
Chave de acesso do utilizador Servidor de autorização da Google
  • Utilizador (utilizador gerido)
  • Utilizador (conta de consumidor)
âmbito do OAuth
Chave de acesso da conta de serviço
  • Servidor de autorização da Google
  • Trusted Cloud by S3NS Servidor de autorização de IAM
Conta de serviço âmbito do OAuth
Token de delegação ao nível do domínio Servidor de autorização da Google Utilizador (utilizador gerido) âmbito do OAuth
Símbolo da Web JSON (JWT) da conta de serviço Cliente Conta de serviço Âmbito do OAuth ou API
Chave de acesso federada Trusted Cloud by S3NS Servidor de autorização de IAM
  • Principal do Workforce Identity Pool
  • Principal do Workload Identity Pool
âmbito do OAuth
Token de limite de acesso às credenciais Trusted Cloud by S3NS Servidor de autorização de IAM
  • Utilizador (utilizador gerido)
  • Utilizador (conta de consumidor)
  • Conta de serviço
Objetos específicos do Cloud Storage
Token de limite de acesso de credenciais emitido pelo cliente Cliente Conta de serviço Objetos específicos do Cloud Storage

Os diferentes tipos de tokens de acesso também apresentam diferentes propriedades de segurança:

  • Formato: alguns tokens de acesso são opacos, o que significa que estão num formato proprietary e não podem ser inspecionados. Outros tokens são codificados como um símbolo da Web JSON, que pode ser descodificado pelo cliente.

  • Introspeção: alguns tokens opacos podem ser introspecionados através da APITrusted Cloud by S3NS , enquanto outros não podem.

  • Tempo de vida: os tokens diferem no tempo de vida e na medida em que podem ser modificados.

  • Revogabilidade: alguns tokens podem ser revogados. Os outros tokens permanecem válidos até à data de validade.

A tabela seguinte resume as diferenças entre os tipos de tokens de acesso.

Tipo de token Formato Introspectable Duração Revogável
Chave de acesso do utilizador Opaco Sim 1 hora Sim
Símbolo de acesso da conta de serviço Opaco Sim 5 minutos a 12 horas Não
Token de delegação ao nível do domínio Opaco Sim 1 hora Não
Símbolo da Web JSON (JWT) da conta de serviço JWT N/A 5 minutos a 1 hora Não
Chave de acesso federada Opaco Não Veja as chaves de acesso federadas Não
Token de limite de acesso de credenciais Opaco Não Veja Tokens de limite de acesso de credenciais Não
Token de limite de acesso de credenciais emitido pelo cliente Opaco Não N/A Não

Tokens de acesso de utilizadores

Os tokens de acesso do utilizador autenticam um utilizador e autorizam um cliente a agir em nome do utilizador:

O principal autenticado é uma conta de utilizador gerida ou uma conta de consumidor. O cliente pode ser uma aplicação Web ou uma aplicação nativa.

As chaves de acesso de utilizadores são opacas. Para fins de diagnóstico, pode inspecionar um token de acesso através do seguinte comando, substituindo ACCESS_TOKEN por um token de acesso válido:

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

Este comando produz um resultado semelhante ao seguinte exemplo:

{
  "azp": "0000000000.apps.googleusercontent.com",
  "aud": "0000000000.apps.googleusercontent.com",
  "sub": "00000000000000000000",
  "scope": "openid https://www.googleapis.com/auth/userinfo.email",
  "exp": "1744687132",
  "expires_in": "3568",
  "email": "user@example.com",
  "email_verified": "true"
}

A saída inclui os seguintes campos:

Campo Nome Descrição
aud Público-alvo

O cliente OAuth para o qual este token se destina, identificado pelo respetivo ID de cliente OAuth.

Os clientes OAuth podem obter tokens de acesso para outros clientes OAuth que pertencem ao mesmo projeto. O público-alvo pode ser diferente da parte autorizada.

azp Parte autorizada O cliente OAuth que solicitou o token, identificado pelo respetivo ID de cliente OAuth.
email Endereço de email principal

O endereço de email principal do utilizador.

Este campo só está presente se o token incluir o âmbito https://www.googleapis.com/auth/userinfo.email.

exp Expira A hora de validade do token, no formato de hora de época Unix.
scope âmbitos do OAuth O conjunto de APIs às quais o cliente tem autorização para aceder em nome do utilizador, identificado por âmbito do OAuth.
sub Assunto

O principal autenticado, identificado pelo respetivo ID exclusivo.

Este ID é equivalente ao ID exposto na API Directory.

Os tokens de acesso do utilizador expiram automaticamente após uma hora, mas podem ser revogados antes, se necessário.

Por predefinição, os tokens de acesso do utilizador são tokens de portador, o que significa que não estão associados a nenhum canal de comunicação, rede ou credencial adicional específico. Opcionalmente, pode implementar a associação de tokens implementando o acesso baseado em certificados para que os tokens de acesso do utilizador só possam ser usados em conjunto com um certificado de cliente mTLS válido.

Tokens de acesso da conta de serviço

Os tokens de acesso da conta de serviço autenticam uma conta de serviço. Os tokens são opacos e pode inspecioná-los através da API https://oauth2.googleapis.com/tokeninfo.

Para uma chave de acesso da conta de serviço, a API devolve um resultado semelhante ao exemplo seguinte:

{
  "azp": "000000000000000000000",
  "aud": "000000000000000000000",
  "scope": "https://www.googleapis.com/auth/userinfo.email",
  "exp": "1744687132",
  "expires_in": "3568",
  "email": "service-account@example.s3ns.iam.gserviceaccount.com",
  "email_verified": "true",
  "access_type": "online"
}

Um token de conta de serviço inclui os seguintes campos:

Campo Nome Descrição
aud Público-alvo A conta de serviço à qual o token se destina, equivalente à parte autorizada.
azp Parte autorizada A conta de serviço que pediu o token, identificada pelo respetivo ID exclusivo.
email Endereço de email principal

O endereço de email da conta de serviço.

Este campo só está presente se o token incluir o âmbito https://www.googleapis.com/auth/userinfo.email.

exp Expira A hora de validade do token, no formato de hora de época Unix.

Não é possível revogar as chaves de acesso da conta de serviço, que permanecem válidas até expirarem.

Por predefinição, os tokens de acesso da conta de serviço expiram após uma hora. Ao usar o método serviceAccounts.generateAccessToken, pode pedir tokens com diferentes durações. Uma vez que os tempos de vida dos tokens mais longos podem aumentar o risco, tem de configurar a restrição iam.allowServiceAccountCredentialLifetimeExtension para permitir que os clientes peçam tokens de acesso da conta de serviço com tempos de vida superiores a uma hora.

Tokens de delegação ao nível do domínio

Os tokens de delegação ao nível do domínio autenticam um utilizador e autorizam uma conta de serviço a agir em nome do utilizador. Os tokens são opacos e pode analisá-los através da API https://oauth2.googleapis.com/tokeninfo.

Para um token de delegação ao nível do domínio, a API devolve uma saída semelhante ao exemplo seguinte:

{
  "azp": "000000000000000000000",
  "aud": "000000000000000000000",
  "scope": "https://www.googleapis.com/auth/admin.directory.user.readonly https://www.googleapis.com/auth/userinfo.email",
  "exp": "1744688957",
  "expires_in": "3540",
  "email": "user@example.com",
  "email_verified": "true",
  "access_type": "offline"
}

Um token de delegação ao nível do domínio inclui os seguintes campos:

Campo Nome Descrição
aud Público-alvo A conta de serviço à qual o token se destina, equivalente à parte autorizada.
azp Parte autorizada A conta de serviço que pediu o token, identificada pelo respetivo ID exclusivo.
email Endereço de email principal

O endereço de email principal do utilizador roubado.

Este campo só está presente se o token incluir o âmbito https://www.googleapis.com/auth/userinfo.email.

exp Expira A hora de validade do token, no formato de hora de época Unix.
scope âmbitos do OAuth O conjunto de APIs às quais o cliente tem autorização para aceder em nome do utilizador com identidade roubada, identificado pelo âmbito do OAuth.

Os tokens de delegação ao nível do domínio expiram automaticamente após uma hora e não podem ser revogados.

Símbolos da Web JSON da conta de serviço

Os símbolos da Web JSON (JWTs) da conta de serviço autenticam uma conta de serviço. Enquanto as chaves de acesso da conta de serviço são emitidas por um servidor de autorização, os JWTs da conta de serviço podem ser emitidos pelo próprio cliente.

Por vezes, estes são denominados JWTs "autossinados". Podem ser úteis quando precisa de fazer a autenticação em algumas APIs Google sem obter um token de acesso do servidor de autorização, por exemplo, quando cria as suas próprias bibliotecas cliente.

Para emitir um JWT de conta de serviço, os clientes têm de efetuar os seguintes passos:

  1. Prepare uma carga útil de assinatura Web JSON que inclua o endereço de email da conta de serviço, um âmbito do OAuth ou um ponto final da API e um prazo de validade.

  2. Assine a carga útil com uma chave de conta de serviço da respetiva conta de serviço. Os clientes podem assinar o payload offline através de uma chave de conta de serviço gerida pelo utilizador ou online através do método signJwt e de uma chave de conta de serviço gerida pela Google. Para mais informações, consulte o artigo Crie um símbolo da Web JSON autoassinado

Um JWT de conta de serviço descodificado tem um aspeto semelhante ao seguinte, com SIGNATURE substituído pela assinatura do token:

{
  "alg": "RS256",
  "kid": "290b7bf588eee0c35d02bf1164f4336229373300",
  "typ": "JWT"
}.{
  "iss": "service-account@example.s3ns.iam.gserviceaccount.com",
  "sub": "service-account@example.s3ns.iam.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/cloud-platform",
  "exp": 1744851267,
  "iat": 1744850967
}.SIGNATURE

Em vez de especificar um âmbito do OAuth na chave scope, um JWT de conta de serviço pode especificar um ponto final da API na chave aud:

{
  "alg": "RS256",
  "kid": "290b7bf588eee0c35d02bf1164f4336229373300",
  "typ": "JWT"
}.{
  "iss": "service-account@example.s3ns.iam.gserviceaccount.com",
  "sub": "service-account@example.s3ns.iam.gserviceaccount.com",
  "aud": "https://cloudresourcemanager.googleapis.com/",
  "exp": 1744854799,
  "iat": 1744851199
}.SIGNATURE

Um JWT de conta de serviço inclui os seguintes campos:

Campo Nome Descrição
aud Público-alvo Pontos finais da API aos quais o cliente tem autorização para aceder. Só é válido se scope não estiver especificado.
exp Expira A hora de validade do token, no formato de hora de época Unix.
iat Hora do problema A hora em que o token foi emitido, no formato de hora epoch Unix.
iss Emissor O emissor do token, que é a própria conta de serviço.
scope âmbitos do OAuth O conjunto de APIs às quais o cliente tem permissão de acesso, identificado por Âmbito OAuth. Só é válido se aud não estiver especificado.
sub Assunto Principal autenticado, que é a própria conta de serviço.

Os JWTs de contas de serviço podem ser válidos durante um máximo de uma hora e não podem ser revogados.

Tokens de acesso federados

Os tokens de acesso federados autenticam um principal do Workload Identity Pool ou um principal do Workforce Pool.

A federação de identidade da força de trabalho permite que os clientes troquem um token externo por um token de acesso federado que autentica um principal do Workload Identity Pool. O principal do Workload Identity Pool é identificado por um identificador principal semelhante ao seguinte:

principal://iam.googleapis.com/locations/global/workforcePools/POOL/subject/raha@altostrat.com.

A Workload Identity Federation permite que os clientes troquem um token externo por um token de acesso federado que autentica um principal do Workload Identity Pool. O principal do Workload Identity Pool é identificado por um identificador principal semelhante ao seguinte:

principal://iam.googleapis.com/projects/PROJECT/locations/global/workloadIdentityPools/POOL/subject/SUBJECT_ATTRIBUTE_VALUE

As chaves de acesso federadas são opacas e não podem ser inspecionadas. Não é possível revogar os tokens, e estes permanecem válidos até à data de validade. As datas de validade de cada tipo de token baseiam-se no seguinte:

  • A federação de identidade da força de trabalho define o prazo de validade do token com base na configuração do fornecedor do Workload Identity Pool.

  • A federação de identidade da carga de trabalho define a expiração do token de forma a corresponder à expiração do token externo.

Tokens de limite de acesso de credenciais

Os tokens de limite de acesso de credenciais autenticam um utilizador ou uma conta de serviço e incluem um limite de acesso. O limite de acesso restringe o token para que só possa ser usado para aceder a um subconjunto definido de recursos do Cloud Storage.

Os tokens de limite de acesso de credenciais são por vezes referidos como com âmbito reduzido, porque são derivados de um token de entrada, mas são mais restritos nos recursos aos quais concedem acesso.

O prazo de validade das chaves de limite de acesso das credenciais é derivado do prazo de validade da chave de entrada, que pode ser uma chave de acesso do utilizador ou uma chave de acesso da conta de serviço. Os tokens do limite de acesso às credenciais são opacos e não podem ser inspecionados nem revogados.

Tokens de limite de acesso de credenciais emitidos pelo cliente

Os tokens de limite de acesso de credenciais emitidos pelo cliente são semelhantes aos tokens de limite de acesso de credenciais, mas são otimizados para cenários em que os clientes precisam de obter tokens de limite de acesso de credenciais com limites de acesso diferentes com alta frequência.

Os clientes podem criar tokens de limite de acesso de credenciais emitidas pelo cliente localmente através das bibliotecas de cliente do Google Cloud e de um token intermediário de limite de acesso, que têm de atualizar periodicamente.

Os tokens de limite de acesso de credenciais emitidos pelo cliente são opacos e não podem ser analisados nem revogados.

Tokens de concessão de tokens

Os tokens de concessão de tokens permitem que os clientes obtenham tokens novos ou diferentes, possivelmente mais tarde.O Trusted Cloud by S3NS suporta vários tipos diferentes de tokens de concessão de tokens, e todos têm o seguinte em comum:

  • Representam uma autenticação anterior.

  • Autenticam um principal, que pode ser uma identidade Google (um utilizador ou uma carga de trabalho) ou uma identidade externa.

  • Podem ser trocados por um token de acesso.

  • Não podem ser usadas para fazer chamadas à API Google, o que as distingue dos tokens de acesso.

Os tokens de concessão de tokens podem diferir das seguintes formas:

  • Emissor: a parte que emite o token.

  • Principal: o tipo de identidade principal que o token pode autenticar.

  • Restrições: as restrições que podem ser impostas ao token.

A tabela seguinte indica os diferentes tipos de tokens de concessão de tokens.

Tipo de token Emissor Tipo de token de acesso resgatado Diretores Restrições
Token de atualização Servidor de autorização da Google Chave de acesso do utilizador
  • Utilizador (utilizador gerido)
  • Utilizador (conta de consumidor)
âmbito do OAuth
Código de autorização Servidor de autorização da Google Chave de acesso do utilizador
  • Utilizador (utilizador gerido)
  • Utilizador (conta de consumidor)
âmbito do OAuth
Declaração do símbolo da Web JSON da conta de serviço Cliente
  • Token de delegação ao nível do domínio
  • Símbolo de acesso da conta de serviço
  • Utilizador (utilizador gerido)
  • Conta de serviço
âmbito do OAuth
Símbolo da Web JSON externo Fornecedor de identidade externo Chave de acesso federada Capital principal externo Nenhum
Afirmação ou resposta SAML externa Fornecedor de identidade externo Chave de acesso federada Capital principal externo Nenhum
Token GetCallerIdentity do Amazon Web Services (AWS) Fornecedor de identidade externo Chave de acesso federada Capital principal externo Nenhum

Os diferentes tipos de tokens de concessão de tokens também apresentam diferentes propriedades de segurança:

  • Formato: alguns tokens são opacos. O cliente pode descodificar outros tokens.

  • Tempo de vida: os tokens diferem no tempo de vida e na medida em que podem ser modificados.

  • Várias utilizações: alguns tokens de concessão de tokens só podem ser usados uma vez. Outros tokens podem ser usados várias vezes.

  • Revogabilidade: alguns tokens podem ser revogados. Os outros tokens permanecem válidos até à data de validade.

A tabela seguinte resume as diferenças entre estas propriedades para tokens de concessão de tokens:

Tipo de token Formato Duração Revogável Várias utilizações
Símbolo de atualização Opaco Consulte Tokens de atualização Sim Sim
Código de autorização Opaco 10 minutos Não Não
Afirmação do símbolo da Web JSON da conta de serviço JWT 5 minutos a 1 hora Não Sim
Token externo ou símbolo da Web JSON externo JWT Depende do fornecedor de identidade Depende do fornecedor de identidade Sim
Resposta ou afirmação SAML externa SAML Depende do fornecedor de identidade Depende do fornecedor de identidade Sim
Símbolo GetCallerIdentity do Amazon Web Services (AWS) Blob de texto Depende do fornecedor de identidade Depende do fornecedor de identidade Sim

Tokens de atualização

Os tokens de atualização são tokens opacos que permitem que os clientes obtenham tokens de ID e tokens de acesso para um utilizador, se o utilizador tiver autorizado anteriormente um cliente a agir em seu nome.

Os tokens de atualização estão associados a um cliente específico e só podem ser usados em combinação com credenciais de cliente válidas, por exemplo, um ID de cliente e um segredo do cliente.

Se a autorização do cliente incluir um ou mais Trusted Cloud by S3NS âmbitos do OAuth, a duração do símbolo de atualização está sujeita ao controlo da Trusted Cloud by S3NS duração da sessão. Caso contrário, os tokens de atualização permanecem válidos até o utilizador revogar a respetiva autorização ou ocorrerem outros eventos de revogação de tokens.

Códigos de autorização

Os códigos de autorização são tokens opacos de curta duração. Os códigos destinam-se apenas a ser usados durante a autenticação do utilizador como intermediário entre o cliente e o servidor de autorizações da Google.

Tal como os tokens de atualização, os códigos de autorização estão associados a um cliente e só podem ser usados em combinação com credenciais de cliente válidas. Ao contrário dos tokens de atualização, os códigos de autorização só podem ser usados uma vez.

Afirmações de símbolos da Web JSON da conta de serviço

As afirmações de símbolos da Web JSON (JWTs) de contas de serviço afirmam a identidade de uma conta de serviço. As cargas de trabalho podem usar afirmações JWT de contas de serviço para obter chaves de acesso de contas de serviço ou chaves de delegação ao nível do domínio. A declaração JWT da conta de serviço é assinada por uma chave de conta de serviço.

Uma afirmação JWT de conta de serviço descodificada tem um aspeto semelhante ao seguinte, com SIGNATURE substituído pela assinatura do token:

{
  "alg": "RS256",
  "kid": "290b7bf588eee0c35d02bf1164f4336229373300",
  "typ": "JWT"
}.{
  "iss": "service-account@example.s3ns.iam.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/devstorage.read_only",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1744851267,
  "iat": 1744850967
}.SIGNATURE

As afirmações JWT da conta de serviço são estruturalmente semelhantes aos JWTs da conta de serviço: ambos os tipos de tokens podem ser emitidos pelo próprio cliente e são assinados por uma chave de conta de serviço. No entanto, os dois tipos de tokens usam payloads diferentes, conforme descrito na tabela seguinte.

Campo JWT da conta de serviço Declaração JWT da conta de serviço
aud Trusted Cloud by S3NS API, omitido se scope for especificado Tem de ser https://oauth2.googleapis.com/token
exp Expira Expira
iat Hora do problema Hora do problema
iss Endereço de email da conta de serviço Endereço de email da conta de serviço
scope Âmbitos do OAuth, omitidos se aud for especificado âmbitos do OAuth
sub Endereço de email da conta de serviço Endereço de email de uma conta de utilizador para delegação ao nível do domínio, omitido caso contrário

As afirmações JWT da conta de serviço podem ser válidas até uma hora e não podem ser revogadas.

Símbolos da Web JSON externos

Os tokens da Web JSON (JWTs) externos são emitidos por um fornecedor de identidade externo, como o Microsoft Entra ID, o Okta, o Kubernetes ou o GitHub. Podem diferir na respetiva estrutura e conteúdos.

Ao configurar a federação de identidade da força de trabalho ou a federação de identidade da carga de trabalho, pode configurar uma relação de confiança entre Trusted Cloud by S3NS e um fornecedor de identidade externo. Em seguida, as cargas de trabalho podem usar JWTs externos como tokens de concessão de tokens para obter tokens de acesso federados.

Quando usa a federação de identidade da força de trabalho, o token de acesso federado resultante autentica um principal do Workload Identity Pool da força de trabalho.

Quando usa a federação de identidades de cargas de trabalho, o token de acesso federado resultante autentica um principal do conjunto do Workload Identity de carga de trabalho.

Em ambos os casos, o identificador principal é derivado de uma ou mais reivindicações do JWT externo.

Para serem compatíveis com a federação de identidade da força de trabalho ou a federação de identidade da carga de trabalho, os JWTs externos têm de cumprir requisitos específicos.

Respostas ou afirmações SAML externas

As afirmações externas Security Assertion Markup Language (SAML) são afirmações SAML 2.0 emitidas por um fornecedor de identidade externo, como o Microsoft Entra ID, o Okta ou os Active Directory Federation Services. Estas afirmações SAML externas podem ser opcionalmente incluídas numa resposta SAML 2.0 ou encriptadas.

Tal como acontece com os símbolos da Web JSON externos, pode configurar a federação de identidades da força de trabalho ou a federação de identidades da carga de trabalho para que as cargas de trabalho possam usar afirmações ou respostas SAML externas como tokens de concessão de tokens para obter tokens de acesso federados.

Para serem compatíveis com a federação de identidade da força de trabalho ou a federação de identidade da carga de trabalho, as declarações SAML externas têm de cumprir requisitos específicos.

Símbolo GetCallerIdentity do Amazon Web Services (AWS)

Os tokens GetCallerIdentity da AWS externos são blobs de texto que contêm um pedido assinado à API GetCallerIdentity da AWS. Semelhante aos símbolos da Web JSON externos e às afirmações SAML, pode configurar a federação de identidade da força de trabalho ou a federação de identidade da carga de trabalho para que as cargas de trabalho possam usar estes blobs de texto como um símbolo de concessão de símbolos para obter símbolos de acesso federados.

Tokens de identidade

Os tokens de identidade (ID) permitem que os clientes identifiquem o utilizador com o qual estão a interagir. Trusted Cloud by S3NS suporta vários tipos diferentes de tokens de identidade, e todos têm o seguinte em comum:

  • Estão formatados como Símbolos da Web JSON (JWTs) para que possam ser descodificados, validados e interpretados pelo cliente.

  • Autenticam um principal, que pode ser um utilizador ou uma carga de trabalho.

  • São emitidos para um cliente específico.

  • São de curta duração e expiram, no máximo, após uma hora.

  • Não são revogáveis.

  • Não podem ser usadas para fazer chamadas à API Google, o que as distingue dos tokens de acesso.

  • Não podem ser usados para obter tokens de acesso, o que os distingue dos tokens de concessão de tokens.

  • Podem ser usadas para autenticar chamadas entre microsserviços ou para autenticar programaticamente no Identity-Aware Proxy (IAP).

Os tokens de identidade podem diferir das seguintes formas:

  • Público-alvo: a parte que se destina a descodificar e consumir o token.

  • Emissor: a parte que emite o token.

  • Tempo de vida: os tokens diferem no tempo de vida e na medida em que podem ser modificados.

  • Principal: o tipo de identidade principal que o token pode autenticar.

A tabela seguinte apresenta os diferentes tipos de tokens de identidade.

Tipo de token Emissor Público-alvo Principal Duração
Token de ID do utilizador Servidor de autorização da Google Cliente OAuth/OIDC
  • Utilizador (utilizador gerido)
  • Utilizador (conta de consumidor)
1 hora
Token de ID da conta de serviço Trusted Cloud by S3NS Servidor de autorização de IAM Liberdade de escolher qualquer público-alvo Conta de serviço 1 hora
Afirmação do Identity-Aware Proxy (IAP) IAP
  • Back-end
  • App do App Engine
  • Utilizador (utilizador gerido)
  • Utilizador (conta de consumidor)
  • Principal do Workforce Identity Pool
10 minutos
Declaração SAML Servidor de autorização da Google App SAML Utilizador (utilizador gerido) 10 minutos

Tokens de ID do utilizador

Os tokens de ID de utilizador são tokens da Web JSON (JWTs) que autenticam um utilizador. Os clientes podem obter um token de ID do utilizador iniciando um fluxo de autenticação OIDC.

Os tokens de User ID são assinados através do conjunto de chaves Web JSON (JWKS) da Google. O JWKS da Google é um recurso global e as mesmas chaves de assinatura são usadas para diferentes tipos de utilizadores, incluindo o seguinte:

  • Contas de utilizador geridas

  • Contas de utilizadores consumidores

  • Contas de serviço

Um token de ID do utilizador descodificado tem um aspeto semelhante ao seguinte, com SIGNATURE substituído pela assinatura do token:

{
  "alg": "RS256",
  "kid": "c37da75c9fbe18c2ce9125b9aa1f300dcb31e8d9",
  "typ": "JWT"
}.{
  "iss": "https://accounts.google.com",
  "azp": "1234567890-123456789abcdef.apps.googleusercontent.com",
  "aud": "1234567890-123456789abcdef.apps.googleusercontent.com",
  "sub": "12345678901234567890",
  "at_hash": "y0LZEe-ervzRNSxn4R-t9w",
  "name": "Example user",
  "picture": "https://lh3.googleusercontent.com/a/...",
  "given_name": "Example",
  "family_name": "User",
  "hd": "example.com",
  "iat": 1745361695,
  "exp": 1745365295
}.SIGNATURE

Um token de ID inclui os seguintes campos:

Campo Nome Descrição
aud Público-alvo

O cliente OAuth para o qual este token se destina, identificado pelo respetivo ID de cliente OAuth.

Os clientes OAuth podem obter tokens de acesso para outros clientes OAuth que pertencem ao mesmo projeto. Neste caso, o público-alvo pode ser diferente da parte autorizada.

azp Parte autorizada O cliente OAuth que realizou o fluxo de autenticação OIDC, identificado pelo respetivo ID de cliente OAuth.
exp Expira A hora de validade do token, no formato de hora de época Unix.
hd Domínio alojado

O domínio principal da conta do Cloud ID ou do Google Workspace do utilizador.

Esta reivindicação só está presente se o utilizador for uma conta de utilizador gerida e o cliente tiver especificado o parâmetro hd no pedido de autenticação.

iss Emissor O emissor do token. Está sempre definido como https://accounts.google.com.
sub Assunto

O principal autenticado, identificado pelo respetivo ID exclusivo.

Este ID é equivalente ao ID exposto na API Directory.

O conjunto exato de reivindicações incluídas num token de ID depende do parâmetro scope no pedido de autenticação.

Para identificar se uma conta de utilizador é gerida ou para identificar a conta do Cloud ID ou do Google Workspace à qual um utilizador pertence, os clientes têm de inspecionar a reivindicação hd.

Os tokens de ID do utilizador são válidos durante uma hora e não podem ser revogados.

Símbolos de ID da conta de serviço

Os tokens de ID da conta de serviço são tokens da Web JSON (JWTs) que autenticam uma conta de serviço.

Ao contrário dos JWTs de contas de serviço e das afirmações JWT de contas de serviço, os tokens de ID de contas de serviço não são assinados por uma chave de conta de serviço. Em alternativa, os tokens de ID da conta de serviço são assinados pelo conjunto de chaves Web JSON (JWKS) da Google.

Um token de ID de conta de serviço descodificado tem um aspeto semelhante ao seguinte, com SIGNATURE substituído pela assinatura do token:

{
  "alg": "RS256",
  "kid": "c37da75c9fbe18c2ce9125b9aa1f300dcb31e8d9",
  "typ": "JWT"
}.{
  "aud": "example-audience",
  "azp": "112010400000000710080",
  "email": "service-account@example.s3ns.iam.gserviceaccount.com",
  "email_verified": true,
  "exp": 1745365618,
  "iat": 1745362018,
  "iss": "https://accounts.google.com",
  "sub": "112010400000000710080"
}.SIGNATURE

Um token de ID da conta de serviço inclui os seguintes campos:

Campo Nome Descrição
aud Público-alvo Identificador da parte para a qual este token se destina. O valor pode ser escolhido livremente pelo requerente do token.
azp Parte autorizada A conta de serviço que pediu o token, identificada pelo respetivo ID exclusivo.
exp Expira A hora de validade do token, no formato de hora de época Unix.
iss Emissor O emissor do token, sempre definido como https://accounts.google.com.
sub Assunto A conta de serviço que pediu o token, identificada pelo respetivo ID exclusivo.

O conjunto exato de reivindicações incluídas num token de ID depende da forma como o token de ID é pedido. Por exemplo, os tokens de ID pedidos pelo servidor de metadados do Compute Engine podem incluir opcionalmente reivindicações adicionais que afirmam a identidade da VM. Os tokens de ID pedidos através da API IAM Credentials podem, opcionalmente, conter o ID da organização do projeto da conta de serviço.

Ao contrário dos tokens de ID do utilizador, os tokens de ID da conta de serviço não suportam a reivindicação hd.

Os tokens de ID da conta de serviço são válidos durante uma hora e não podem ser revogados.

Afirmações do Identity-Aware Proxy

As afirmações do Identity-Aware Proxy (IAP) são tokens da Web JSON (JWTs) que o IAP transmite às aplicações Web protegidas pelo IAP no x-goog-iap-jwt-assertioncabeçalho do pedido HTTP. As afirmações de IAP autenticam um utilizador e também servem como prova de que um pedido foi autorizado pelo IAP.

Ao contrário dos tokens de ID do utilizador e dos tokens de ID da conta de serviço, as afirmações de IAP não são assinadas com o conjunto de chaves Web JSON (JWKS) da Google. Em alternativa, as declarações de IAP são assinadas com um JWKS separado, o IAP JWKS. Este JWKS é um recurso global e as mesmas chaves de assinatura são usadas para diferentes tipos de utilizadores, incluindo o seguinte:

  • Contas de utilizador geridas

  • Contas de consumidor

  • Contas de serviço

  • Principais do Workforce Identity Pool

Uma declaração de IAP descodificada é semelhante à seguinte, com SIGNATURE substituído pela assinatura do token:

{
  "alg": "ES256",
  "typ": "JWT",
  "kid": "4BCyVw"
}.{
  "aud": "/projects/0000000000/global/backendServices/000000000000",
  "azp": "/projects/0000000000/global/backendServices/000000000000",
  "email": "user@example.com",
  "exp": 1745362883,
  "google": {
    "access_levels": [
      "accessPolicies/0000000000/accessLevels/Australia"
    ]
  },
  "hd": "example.com",
  "iat": 1745362283,
  "identity_source": "GOOGLE",
  "iss": "https://cloud.google.com/iap",
  "sub": "accounts.google.com:112010400000000710080"
}.SIGNATURE

Se configurar o IAP para usar a federação de identidades da força de trabalho em vez das identidades Google, as afirmações do IAP têm um aspeto ligeiramente diferente:

{
  "alg": "ES256",
  "typ": "JWT",
  "kid": "4BCyVw"
}.{
  "aud": "/projects/0000000000/global/backendServices/000000000000",
  "azp": "/projects/0000000000/global/backendServices/000000000000",
  "email": "user@example.com",
  "exp": 1745374290,
  "google": {
    "access_levels": [
      "accessPolicies/0000000000/accessLevels/Australia"
    ]
  },
  "iat": 1745373690,
  "identity_source": "WORKFORCE_IDENTITY",
  "iss": "https://cloud.google.com/iap",
  "sub": "sts.google.com:AAFTZ...Q",
  "workforce_identity": {
    "iam_principal": "principal://iam.googleapis.com/locations/global/workforcePools/example/subject/user-0000000000",
    "workforce_pool_name": "locations/global/workforcePools/example"
  }
}.SIGNATURE

Uma afirmação de IAP inclui os seguintes campos:

Campo Nome Descrição
aud Público-alvo O serviço de back-end, a aplicação do App Engine ou o serviço do Cloud Run para o qual a declaração do IAP se destina.
iss Emissor O emissor do token, sempre definido como https://cloud.google.com/iap
sub Assunto

O principal autenticado, identificado pelo respetivo ID exclusivo.

Se o IAP estiver configurado para usar identidades Google, este ID é equivalente ao ID exposto na API Directory.

Para mais detalhes sobre as reivindicações de declaração de IAP, consulte o artigo Validar a carga útil do JWT.

As declarações de IAP são válidas durante 10 minutos e não podem ser revogadas.

Afirmações SAML

As declarações da Linguagem de marcação de declaração de segurança (SAML) autenticam uma conta de utilizador gerida e autorizam-na a aceder a uma app SAML personalizada. As declarações SAML são emitidas e assinadas pelo Cloud Identity e só podem ser usadas para autenticar contas de utilizador geridas.

Ao contrário dos tokens de ID, que são assinados através de uma chave global, as afirmações SAML são assinadas através de uma chave específica de uma conta do Cloud ID ou do Google Workspace.

Uma afirmação de resposta SAML descodificada tem um aspeto semelhante ao seguinte:

<saml2:Assertion
  xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
  ID="..."
  IssueInstant="2025-04-23T22:47:20.881Z"
  Version="2.0">
  <saml2:Issuer>
    https://accounts.google.com/o/saml2?idpid=C0123456789
  </saml2:Issuer>
  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">...</ds:Signature>
  <saml2:Subject>
    <saml2:NameID
      Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">
        user@example.com
    </saml2:NameID>
    <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
      <saml2:SubjectConfirmationData
        NotOnOrAfter="2025-04-23T22:52:20.881Z"
        Recipient="https://app.example.com/"/>
    </saml2:SubjectConfirmation>
  </saml2:Subject>

  <saml2:Conditions
    NotBefore="2025-04-23T22:42:20.881Z"
    NotOnOrAfter="2025-04-23T22:52:20.881Z">
    <saml2:AudienceRestriction>
      <saml2:Audience>example-app</saml2:Audience>
    </saml2:AudienceRestriction>
  </saml2:Conditions>

  <saml2:AuthnStatement
    AuthnInstant="2025-04-23T22:46:44.000Z"
    SessionIndex="...">
    <saml2:AuthnContext>
      <saml2:AuthnContextClassRef>
        urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified
      </saml2:AuthnContextClassRef>
    </saml2:AuthnContext>
  </saml2:AuthnStatement>
</saml2:Assertion>

Uma declaração SAML inclui os seguintes campos:

Campo Nome Descrição
Audience Público-alvo ID da entidade da app SAML.
Issuer Emissor Emissor do token, específico de uma conta do Cloud ID ou do Google Workspace.
NameID Assunto O principal autenticado. O formato do identificador depende da configuração da app SAML.

O conjunto exato de atributos incluídos numa afirmação SAML depende da configuração da app SAML.

As afirmações SAML são válidas durante 10 minutos e não podem ser revogadas.