Skip to Content

Tokens

Para que serve cada token de ID, de acesso e de atualização, quem valida qual, quanto duram e como funcionam a rotação e o armazenamento seguro.

Um único início de sessão pode produzir três tokens diferentes, e a maior parte dos problemas de integração resulta de se confundir para que serve cada um. Esta página é a tabela de consulta: finalidade, audience, duração de validade e regras de manuseamento por tipo de token.

Os três tokens

TokenDirigido aPara que serveValidado por
ID tokenA aplicação (o seu client ID é a audience)Comprova quem iniciou sessão e transporta claims de perfil (sub, name, email, ...).A aplicação, normalmente através da sua biblioteca OIDC.
Access tokenUma API (o identificador desta é a audience)Autoriza chamadas a essa API, transportando os scopes concedidos.A API, em cada pedido; consulte Proteger uma API.
Refresh tokenA própria plataformaPermite à aplicação renovar mais tarde o seu access token sem reenviar o utilizador para a página de início de sessão.A plataforma, no token endpoint.

O erro mais frequente é enviar o ID token para uma API. Um ID token autentica o utilizador perante a aplicação e a sua audience é o client ID da aplicação, pelo que uma API corretamente implementada rejeita-o. Envie o access token para as APIs e trate-o como opaco dentro do cliente: o seu conteúdo é um contrato entre a plataforma e a API, não com a aplicação.

Formatos de access token

  • Para uma API registada (o cliente passou o identificador da API como resource indicator): um JWT assinado com o identificador da API em aud, os scopes concedidos em scope e o autor da chamada em sub. A API valida-o offline face às chaves publicadas da plataforma. Com o RBAC ativado, transporta também claims permissions / roles.
  • Sem API de destino: um token opaco, utilizável apenas no endpoint UserInfo da plataforma. Os tokens opacos (e os refresh tokens) podem ser verificados no endpoint padrão de token introspection e cancelados no endpoint de revogação; ambos constam do documento de discovery. Um cliente pode fazer introspection dos seus próprios tokens; só uma aplicação criada na consola de administração com um client secret ou uma chave (um resource server) pode fazer introspection dos tokens de outros clientes, e não uma aplicação registada dinamicamente.

Durações de validade

Token / artefactoDuração de validadeOnde se configura
Authorization code1 minuto, utilização únicaFixa
Access token para uma APIPredefinição de 1 dia (2 horas através de fluxos implicit)Por API, no separador de definições desta; consulte APIs
Access token sem API de destino (UserInfo)1 horaFixa
Token machine-to-machine sem API de destino10 minutosFixa
ID tokenPredefinição de 1 horaPor aplicação; consulte Aplicações
Refresh token14 dias, prolongáveis pela rotação até 1 ano no totalFixa; ver abaixo
Device code10 minutosFixa
Sessão de single sign-onTempos limite de inatividade e absolutoPara toda a instância, em Definições → Início de sessão, com possibilidade de substituição por diretório; consulte Definições de início de sessão

Refresh tokens

Quando é emitido um. A aplicação tem de ter o grant type refresh token ativado. As aplicações first-party (sem ecrã de consentimento) recebem então um automaticamente; as aplicações com Exigir consentimento do utilizador ativado só recebem um quando o utilizador tiver concedido o scope offline_access.

Rotação. Os refresh tokens rodam em vez de durarem para sempre:

  • Um cliente public (aplicação single-page ou nativa, sem client secret) recebe um refresh token de substituição em cada utilização. Nos clientes baseados em browser, a substituição mantém o tempo de vida restante, pelo que a rotação não o prolonga.
  • Um cliente confidential mantém o seu refresh token até terem decorrido cerca de 70% do respetivo tempo de vida; a utilização seguinte emite então um token novo de 14 dias.
  • Independentemente da forma como roda, uma cadeia de refresh tokens termina, o mais tardar, um ano após o início de sessão original; a partir daí o utilizador tem de iniciar sessão novamente.

Um refresh token rodado (já utilizado) é inválido; se o seu cliente persistir tokens, guarde sempre o mais recente de cada resposta.

Revogar. Uma aplicação pode cancelar proativamente um refresh token no endpoint de revogação (indicado no documento de discovery), o que constitui boa higiene durante o seu próprio fim de sessão. Os utilizadores podem terminar as suas sessões a partir do portal da conta («terminar sessão em todo o lado»), e os tokens ligados à sessão terminam com elas; consulte a secção seguinte.

Tokens e fim de sessão

Terminar a sessão encerra a sessão SSO da plataforma, mas os tokens seguem as suas próprias regras:

  • Os tokens emitidos sem offline_access estão ligados à sessão. Os tokens opacos deixam de funcionar no momento em que a sessão termina.
  • Um access token JWT não pode ser recolhido: as APIs validam-no offline, pelo que se mantém tecnicamente utilizável até expirar, mesmo depois do fim de sessão. Se essa janela for relevante para uma API, encurte a duração de validade do access token dessa API em vez de contar com o logout.
  • Os refresh tokens obtidos com offline_access sobrevivem ao fim de sessão por concepção (é precisamente isso que significa acesso offline). Terminam quando expiram, quando atingem o limite de um ano ou quando são revogados.
  • As aplicações podem ser informadas do termino de sessão através do back-channel logout; consulte Tempos de vida dos tokens e logout. A relação entre a sessão da plataforma, as sessões das aplicações e a sessão de um fornecedor de identidade a montante é descrita em Ciclo de vida do utilizador: sessões.

Guardar tokens

  • Contra scripts em execução na página (cross-site scripting): um token em localStorage ou em sessionStorage é legível por qualquer script injetado. As aplicações de browser guardam os tokens apenas em memória e recorrem à rotação de refresh tokens para cobrir a curta duração de validade do access token.
  • Contra outro software no dispositivo: um token guardado num ficheiro simples ou num repositório de preferências está à distância de uma leitura de ficheiro. As aplicações nativas usam o armazenamento protegido do sistema operativo (Keychain, Keystore, credential locker).
  • Contra o browser no seu todo: uma aplicação do lado do servidor nunca precisa que o browser guarde um token. Mantenha os tokens no servidor, ligados ao seu próprio cookie de sessão.
  • Contra fugas em trânsito e em registos: envie os tokens apenas por TLS no cabeçalho Authorization, nunca em URLs (acabam nos registos de proxies e servidores), e nunca os escreva você mesmo em registos.

Relacionado

Nesta página