Postmortem: mudança inesperada em `iss` do JWT

Resumo#

Em 2024-03-18, uma atualização que alterou o comportamento do emissor do JWT no Logto Cloud quebrou fluxos de autenticação para usuários com domínios personalizados e validação de iss. A correção exigiu que esses usuários atualizassem sua lógica de validação.

• Usuários afetados: usuários com domínios personalizados habilitados e realizando validação de iss.
• Severidade: Crítico, quebrando a validação de iss dentro dos fluxos de autenticação.

Causa raiz#

A atualização alterou o campo iss para corresponder ao domínio solicitado, quebrando validações existentes que esperavam o emissor padrão anterior.

Cronograma#

• 2024-03-18 10:00 (UTC): atualizações implantadas, mudando o comportamento de iss.
• 2024-03-18 23:30 (UTC): primeiro relatório de usuário recebido sobre o comportamento quebrado existente.
• 2024-03-19 12:00 (UTC): confirmado o problema e iniciado a investigação.
• 2024-03-19 14:00 (UTC): identificada a causa raiz e o impacto.
• 2024-03-20 20:00 (UTC): preparado o email para usuários afetados.
• 2024-03-20 06:00 (UTC): enviados emails para todos os usuários afetados.

Análise de impacto#

Detalhes da liberação#

O Logto Cloud suporta domínio personalizado para autenticação, desenvolvedores que têm locatários com domínio personalizado habilitado podem definir o endpoint para o domínio personalizado nos SDKs, então o usuário final usará este endpoint para iniciar o processo de autenticação e obter tokens. Alguns tokens estão na forma de JWT, que incluem um campo iss indicando o emissor desse token. Anteriormente, mesmo quando um endpoint de domínio personalizado era usado para solicitar um token de acesso, o emissor ainda seria por padrão nosso domínio padrão ([tenant-id].logto.app).

Mas o domínio do emissor deve ser o mesmo que o endpoint solicitado. Então, lançamos uma atualização para corrigir esse problema, e agora o campo iss refletirá automaticamente o domínio usado na solicitação.

Para aqueles que já estão usando o domínio personalizado para conceder tokens e implementaram a validação do campo iss no servidor de recursos, essa pode ser uma mudança crítica. A verificação de autenticação existente falhará por causa da mudança do emissor. Para corrigir isso, os desenvolvedores precisam mudar o código de validação, substituindo o emissor esperado pelo novo com domínio personalizado.

Não conseguimos considerar completamente o impacto nas validações iss existentes, como resultado, essa liberação se tornou uma mudança crítica sem notificação prévia.

Resolução#

Notificamos os usuários afetados via email, aconselhando-os a atualizar sua validação de iss para corresponder ao domínio solicitado.

Reversões?#

A mudança é uma correção necessária para o campo do emissor, e alguns usuários podem já ter se adaptado ao novo comportamento. Uma reversão causaria confusão e inconsistência.

Lições aprendidas#

• Alterações de código que afetam a autenticação principal devem ser aprovadas pela equipe além de revisões regulares.
• Testes automáticos devem cobrir mais casos, especialmente em cenários específicos da nuvem.

Medidas corretivas e preventivas#

• Adicionar testes de integração: Adicionar casos de teste para cobrir o cenário deste incidente.
• Projetos de monitoramento de funcionalidades: Além do Logto Cloud, criar nossos próprios projetos paralelos e integrá-los profundamente com o Logto para detectar problemas potenciais antes das liberações.