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
| Token | Dirigido a | Para que serve | Validado por |
|---|---|---|---|
| ID token | A 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 token | Uma 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 token | A própria plataforma | Permite à 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 emscopee o autor da chamada emsub. A API valida-o offline face às chaves publicadas da plataforma. Com o RBAC ativado, transporta também claimspermissions/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 / artefacto | Duração de validade | Onde se configura |
|---|---|---|
| Authorization code | 1 minuto, utilização única | Fixa |
| Access token para uma API | Predefiniçã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 hora | Fixa |
| Token machine-to-machine sem API de destino | 10 minutos | Fixa |
| ID token | Predefinição de 1 hora | Por aplicação; consulte Aplicações |
| Refresh token | 14 dias, prolongáveis pela rotação até 1 ano no total | Fixa; ver abaixo |
| Device code | 10 minutos | Fixa |
| Sessão de single sign-on | Tempos limite de inatividade e absoluto | Para 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_accessestã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_accesssobrevivem 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
localStorageou emsessionStorageé 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
- Proteger uma API: validar access tokens na sua própria API.
- APIs: scopes, audiences e definições de token por API.
- Aplicações: definições de token e de logout por aplicação.
- Definições de início de sessão: os tempos limite da sessão SSO.