Referência da API de redefinição de senha de autenticação nativa

Aplica-se a: Círculo verde com um símbolo de marca de seleção branca que indica que o conteúdo a seguir se aplica a locatários externos. 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.

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.

Diagrama de sequência de recuperação de senha, verificação de senha, atualização de senha, sondagem opcional e troca de código de autorização.

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.