# 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 [#the-three-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](https://dts-identity.com/pt/docs/quickstarts/protect-an-api.md). |
| **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 [#access-token-formats]

- **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](https://dts-identity.com/pt/docs/integrations/apis.md#role-based-access-control) 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 [#lifetimes]

| 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](https://dts-identity.com/pt/docs/integrations/apis.md) |
| 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](https://dts-identity.com/pt/docs/integrations/applications.md#token-lifetimes-and-logout) |
| 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](https://dts-identity.com/pt/docs/settings/login.md) |

## Refresh tokens [#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 [#tokens-and-sign-out]

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](https://dts-identity.com/pt/docs/integrations/applications.md#token-lifetimes-and-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](https://dts-identity.com/pt/docs/directories/user-lifecycle.md#sessions).

## Guardar tokens [#storing-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

- [Proteger uma API](https://dts-identity.com/pt/docs/quickstarts/protect-an-api.md): validar access tokens na sua própria API.
- [APIs](https://dts-identity.com/pt/docs/integrations/apis.md): scopes, audiences e definições de token por API.
- [Aplicações](https://dts-identity.com/pt/docs/integrations/applications.md): definições de token e de logout por aplicação.
- [Definições de início de sessão](https://dts-identity.com/pt/docs/settings/login.md): os tempos limite da sessão SSO.
