Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Aplica-se a:
Locatários externos (saiba mais)
Abordagem de autenticação: Autenticação nativa inserida.
A redefinição de senha verifica o método de recuperação de um cliente, aceita uma senha de substituição e sonda uma atualização assíncrona. Os métodos de senha única (OTP) por email e SMS dão suporte à recuperação. Os requisitos de MFA (autenticação multifator) e acesso condicional podem ser aplicados após a redefinição e antes da conclusão da autorização.
Para integrações V1 existentes, use a referência da API V1.
Prerequisites
Importante
A API de Autenticação Nativa V2 está em versão prévia. A API de Autenticação Nativa V1 permanece disponível em geral. Consulte os Termos de Uso Complementares para visualizações de Microsoft Azure para termos legais que se aplicam aos recursos de visualização.
- Um aplicativo configurado para autenticação nativa.
- Redefinição de senha habilitada para o locatário e o cliente, com um método de recuperação utilizável. Consulte Habilitar redefinição de senha de autoatendimento.
- As permissões delegadas e o consentimento necessários para uma API de destino, se você solicitar um escopo de API.
Os exemplos usam uma autoridade de domínio personalizado verificada pelo locatário.
custom_domain é o domínio de autenticação e tenant é o GUID do locatário.
Contas OTP sem senha não têm uma senha para redefinir.
Iniciar redefinição de senha
O diagrama mostra uma sequência de recuperação autônoma usando a verificação de senha única por email. Em vez disso, a recuperação embutida usa o link do recover método de senha dentro da transação de entrada ativa.
Inicie a autorização e siga o link de redefinição-senha retornado (resetPassword ou reset_password). Não chame a descoberta de entrada primeiro:
POST https://{custom_domain}/{tenant}/api/v2.0/resetpassword/start
Content-Type: application/json
Accept: application/hal+json
{
"username": "user@contoso.com",
"continuationToken": "******"
}
Envie o identificador username do cliente e o token de autorização atual em continuationToken. O exemplo usa um endereço de email. Uma resposta pode anunciar um método de recuperação de email:
{
"state": "interactionRequired",
"action": "challenge",
"continuationToken": "******",
"_links": {
"self": {
"href": "/{tenant}/api/v2.0/resetpassword/start"
}
},
"_embedded": {
"methods": [
{
"id": "{email_method_id}",
"type": "email",
"hint": "j****n@c****o",
"_links": {
"challenge": {
"href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/challenge"
},
"verify": {
"href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/verify"
}
}
}
]
}
}
Selecione um email retornado ou um método de recuperação de SMS por meio da escolha do usuário ou da lógica de fluxo do aplicativo. O exemplo mostra o email; para SMS, siga os links do método SMS retornado sem reescrever a URL de exemplo. Use a dica mascarada em que a interface precisa de um rótulo de destino.
Recuperação embutida durante a entrada
Ofereça recuperação embutida somente quando um método de senha na resposta de entrada atual anunciar um recover link. Siga esse link usando o token de continuação de entrada atual. Não inicie outra solicitação de autorização nem reenvie o nome de usuário ou a senha.
POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/recover
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******"
}
Ambos os pontos de entrada usam o método de recuperação, o desafio, a verificação, a atualização de senha e as operações de sondagem retornadas pelo serviço.
Desafiar e verificar o método de recuperação
Poste no link do challenge método selecionado:
{
"continuationToken": "******"
}
Use JSON e Accept: application/hal+json. A operação de desafio compartilhado retorna o tipo de método atual, mascarado hintcodeLengthe verify links opcionaisresend.
Poste a senha inserida no link retornado verify :
{
"otp": "{one_time_passcode}",
"continuationToken": "******"
}
Use o token mais recente para cada solicitação. Para outro código, use o link atual resend e os limites de serviço, não um par de URL/token de desafio anterior.
Uma verificação bem-sucedida pode retornar o método de senha:
{
"state": "interactionRequired",
"action": "update",
"id": "{password_method_id}",
"type": "password",
"continuationToken": "******",
"_links": {
"update": {
"href": "/{tenant}/api/v2.0/auth/methods/password/{password_method_id}"
}
}
}
Use a ID do método de senha do link retornado update , não a ID do método de recuperação de SMS ou email. A recuperação embutida pode reter a ID do método de senha da entrada pai.
Atualizar uma senha
Envie a senha de substituição com PUT, não POST:
PUT https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}
Content-Type: application/json
Accept: application/hal+json
{
"newPassword": "{new_password}",
"continuationToken": "******"
}
| Property | Tipo | Required | Description |
|---|---|---|---|
continuationToken |
Cadeia de caracteres. | Sim. | Token atual solicitando atualização de senha. |
newPassword |
Cadeia de caracteres. | Sim. | Senha de substituição. A confirmação de senha é local para sua interface, não um campo de solicitação adicional. |
O serviço pode retornar:
{
"state": "interactionRequired",
"action": "poll",
"pollInterval": "2",
"id": "{password_method_id}",
"type": "password",
"continuationToken": "******",
"_links": {
"poll": {
"href": "/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/pollUpdate"
}
}
}
Isso indica uma atualização assíncrona, não uma autorização final. Não envie a senha novamente enquanto aguarda ou repita automaticamente a atualização após uma falha de rede ambígua.
Atualização de senha de votação
Siga o link mais recente poll :
POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/pollUpdate
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******"
}
Enquanto a atualização está em andamento, o serviço retorna interactionRequired com action: pollum token atualizado e um poll link. Substitua a resposta anterior antes da próxima votação.
Quando incluído, pollInterval é uma cadeia de caracteres que contém o intervalo em segundos. Use o intervalo da resposta atual para a próxima solicitação e as diretrizes de repetição do servidor de honra. O exemplo "2" não é um intervalo de serviço fixo. Pare a sondagem quando a ação for alterada ou um erro for retornado e manipule qualquer autenticação posterior exigida pela política.
Uma resposta de continuação é:
{
"state": "continue",
"continuationToken": "******",
"_links": {
"continue": {
"href": "/{tenant}/oauth2/v2.0/authorize-challenge"
}
}
}
Preencher requisitos de política e adquirir tokens
A redefinição de senha não ignora a MFA ou o Acesso Condicional. Se outro desafio for retornado, conclua-o usando as operações de método compartilhado. A troca de tokens segue a conclusão das etapas de política restantes e da continuação da autorização.
Depois state: continue, retome a autorização usando o token mais recente e troque o código. Os escopos e as declarações solicitados permanecem aqueles estabelecidos no início da transação.
Resultados e erros
Use o tratamento de erros compartilhados. O contrato de recuperação descreve estes resultados:
| Condition | Tratamento de resultados e cliente |
|---|---|
| Nome de usuário desconhecido | A recuperação não é iniciada. Use uma mensagem genérica voltada para o cliente. |
| Senha de email ou SMS incorreta | HTTP 400 invalidGrant com innerError.code: invalidOneTimeCode. Permitir que o usuário corrija o código usando o estado atual utilizável ou uma reenviação anunciada. |
| Senha ausente | HTTP 400 invalidRequest. Corrija a entrada ausente. |
| Reenviar | Uma nova senha é enviada por meio do link retornado resend . |
| Token de atualização de senha expirado | HTTP 400 expiredToken com innerError.code: expiredContinuationToken. Reinicie a autorização. |
| Senha de substituição fraca ou comum | HTTP 400 invalidRequest com um erro interno aplicável, como passwordTooWeak ou passwordTooCommon. Colete uma senha em conformidade. |
| Atualização em andamento | Siga a resposta de sondagem mais recente e as diretrizes de repetição do servidor. |
| Falha na pesquisa na política de senha | HTTP 400 invalidRequest com um erro interno como passwordTooCommon ou passwordBannedByPolicy. Manipule o erro em vez de sondar indefinidamente. |
| Conta bloqueada ou desabilitada durante a sondagem | HTTP 403 forbidden com innerError.code: accountLocked. Pare a operação de recuperação. |
| Falha no trabalho de atualização de senha | HTTP 500 serverError. Mostrar uma falha clara sem repetir automaticamente a atualização de senha. |
| Recuperação concluída | Manipule as ações de política restantes, retome a autorização e solicite tokens. |
Esta tabela descreve resultados específicos, não um catálogo de erros exaustivo. A aceitação da atualização de senha, a conclusão da sondagem e a emissão de token são limites separados.
Não registre senhas de recuperação, senhas de substituição ou tokens de transação. Registre apenas IDs de diagnóstico seguras, carimbos de data/hora e status HTTP. Não reproduza automaticamente as atualizações de verificação ou senha.