Troca de Senha
O fluxo de troca de senha permite que um usuário redefina sua senha sem precisar estar autenticado. O processo ocorre por meio de um link seguro enviado por e-mail, gerado com um token JWT de uso único com validade de 24 horas.
Diagrama de sequência
Etapas do fluxo
1. Solicitar o link de redefinição
O usuário acessa a tela Segurança e clica no botão Alterar no campo de senha.
O sistema consulta se o usuário possui um e-mail de recuperação cadastrado:
- Sem e-mail de recuperação: o link é enviado diretamente para o e-mail principal, sem exibir modal.
- Com e-mail de recuperação: é exibido um modal para que o usuário escolha o destino do link.
TODO: screenshot da tela de Segurança com o botão Alterar em destaque
2. Escolha do destino do link (quando aplicável)
Se o usuário possui e-mail de recuperação, um modal é exibido com duas opções:
- E-mail principal — endereço de login da conta.
- E-mail de recuperação — endereço alternativo cadastrado (exibido parcialmente mascarado).
3. Redefinição da senha
O usuário recebe o e-mail, clica no link e é direcionado para a tela /change-password. O link é validado automaticamente ao abrir a página. Caso seja válido, o formulário de nova senha é exibido.
O usuário preenche e confirma a nova senha. Ao submeter, o sistema atualiza a senha no Cognito e redireciona para a tela de login.
Endpoints envolvidos
| Método | Rota | Auth | Descrição |
|---|---|---|---|
GET | /user/password/recovery/poolid/:poolId/email/:email | Não | Verifica se o usuário possui e-mail de recuperação cadastrado |
POST | /user/password/recovery/recoveryemail/poolid/:poolId/email/:email | Não | Envia o link de redefinição para o destino escolhido |
POST | /user/password/recovery/jwt/validate | Não | Valida o token JWT do link recebido |
PUT | /user/password/recovery/jwt/complete | Não | Conclui a redefinição com a nova senha |
Regras de validação
| Campo | Regra |
|---|---|
newPassword | Entre 8 e 16 caracteres |
newPassword | Pelo menos uma letra maiúscula |
newPassword | Pelo menos uma letra minúscula |
newPassword | Pelo menos um dígito numérico |
newPassword | Pelo menos um símbolo: # ! @ $ % ^ & * |
newPassword | Apenas os caracteres permitidos acima |
newPassword | Não pode ser igual à senha atual |
response_type | Deve ser email ou recoveryEmail |
| Token JWT | Deve ser válido, não expirado e não utilizado anteriormente |
:::info Token de uso único O link enviado por e-mail é válido por 24 horas e pode ser utilizado apenas uma vez. Após a conclusão do fluxo ou expiração, o link se torna inválido. :::
Comportamentos de erro
| Situação | Resposta da API | Comportamento no frontend |
|---|---|---|
| E-mail com formato inválido | 400 BadFieldError('email') | Mensagem de campo inválido |
| Usuário não encontrado | 200 com mensagem genérica | Não revela a existência do usuário |
response_type inválido | 400 | Mensagem de erro |
| E-mail de recuperação escolhido mas não cadastrado | 400 BadFieldError('recoveryEmail') | Mensagem de campo inválido |
| Falha no envio do e-mail | SendEmailError | Toast de erro genérico |
| Token inválido, expirado ou já utilizado | 400 | Tela "Link inválido, expirado ou já utilizado" |
| Nova senha igual à atual | 400 | Mensagem: "A nova senha não pode ser igual à senha atual." |
| Senha rejeitada pelo Cognito | 400 | Mensagem com as regras de senha |