Tokens de atualização rotacionam a cada uso, o reuso de um token gasto revoga toda a família de tokens, e tokens de acesso emitidos após a detecção são inválidos, seguindo as regras de concessão do RFC 6749 e as orientações de reutilização do OAuth 2.0 Security BCP.
Status do pacote: contexto de referência pronto para revisão humana. O contrato e os cenários de teste estão completos, mas não há garantia de que uma implementação adotante os tenha aprovado.
Decisão
Clientes OAuth confidenciais recebem tokens de atualização rotativos. Cada concessão de atualização bem-sucedida consome o token apresentado, emite um novo token de atualização da mesma família e emite um novo token de acesso. Se um token de atualização gasto for apresentado novamente, o servidor de autorização o trata como reutilização: toda a família de atualização é revogada, tokens de acesso relacionados são negados, e a resposta é invalid_grant conforme especificado pelo RFC 6749. O RFC 9700 descreve rotação e detecção de reutilização como prática atual para corridas de token roubado. Reautorização interativa é necessária após revogação da família.
Escopo
- Manipulação da concessão de token de atualização para oauth-clients usando autenticação de cliente confidencial.
- Rotação, detecção de token gasto, revogação da família, invalidação de token de acesso e corridas concorrentes de atualização.
Fora deste bloco
- Emissão de código de autorização e PKCE, armazenamento de cliente nativo público e verificações de assinatura JWT do servidor de recursos além da revogação.
- Formato de cookie de sessão (pacote relacionado ao ciclo de vida da sessão).
Contrato
- Uma atualização bem-sucedida consome o token de atualização apresentado antes ou na mesma transação que persiste o sucessor.
- O sucessor pertence à mesma family_id até que a reutilização ou logout revogue a família.
- Apresentar um token de atualização gasto retorna invalid_grant e revoga todos os digests de atualização da família.
- Tokens de acesso de uma família revogada falham no servidor de recursos dentro do caminho denylist ou introspecção escolhido no perfil.
- Atualizações concorrentes não podem produzir dois tokens atuais sobreviventes para a mesma família.
- Respostas de erro não distinguem roubo de bugs do cliente.
Orientação para implementação
- Armazene apenas digests de atualização; o token bruto é mostrado uma vez. Serialize atualizações da família com uma versão de linha. Prefira tokens restritos ao remetente como defesa em profundidade; eles não substituem a detecção de reutilização.
- Siga reuse-playbook.md para serialização de concorrência e paginação após eventos de detecção de reutilização.
Tratamento de falhas e salvaguardas
- Se a persistência do sucessor falhar após o consumo, a família fica inutilizável; o cliente deve reautorizar em vez de ressuscitar o token gasto.
- Após um tempo limite, o cliente deve apresentar o token de atualização mais novo que persistiu; apresentar o antigo aciona a reutilização.
Verificação e operações
- Rotacione duas vezes e prove que o primeiro token foi consumido. Reuse o primeiro token e prove a revogação da família mais a negação de acesso. Faça uma corrida de duas atualizações e afirme um único token principal.
Os exemplos com aparência executável neste pacote são fixtures e contratos de aceitação. Execute
python tools/validate.py a partir da raiz da coleção para verificar a estrutura e metadados do pacote; então
implemente e execute os cenários no repositório alvo.
Suposições para adoção
- Nomes e valores numéricos em
example.yamlsão um perfil de adoção, não padrões universais. - A equipe adotante deve mapear atores, classes de dados, vocabulário de erros e propriedade para seu sistema.