Informations de référence sur l’API de réinitialisation de mot de passe d’authentification native

S’applique à : cercle vert avec un symbole de coche blanc qui indique que le contenu suivant s’applique aux locataires externes. Locataires externes (en savoir plus)

Approche d’authentification : Authentification native incorporée.

La réinitialisation de mot de passe vérifie la méthode de récupération d’un client, accepte un mot de passe de remplacement et interroge une mise à jour asynchrone. Les méthodes de code secret à usage unique par e-mail et SMS prennent en charge la récupération. L’authentification multifacteur (MFA) et les exigences d’accès conditionnel peuvent s’appliquer après la réinitialisation et avant la fin de l’autorisation.

Pour les intégrations V1 existantes, utilisez la référence de l’API V1.

Prerequisites

Important

L’API d’authentification native V2 est en préversion. L’API d’authentification native V1 reste généralement disponible. Consultez les conditions d’utilisation supplémentaires pour les préversions Microsoft Azure pour connaître les conditions légales qui s’appliquent aux fonctionnalités en préversion.

Les exemples utilisent une autorité de domaine personnalisé vérifiée par le locataire. custom_domain est le domaine d’authentification et tenant est le GUID du locataire.

Les comptes e-mail-OTP sans mot de passe n’ont pas de mot de passe à réinitialiser.

Démarrer la réinitialisation du mot de passe

Le diagramme montre une séquence de récupération autonome à l’aide de la vérification du code secret à usage unique par e-mail. La récupération inline utilise plutôt le lien de la méthode de mot de recover passe dans la transaction de connexion active.

Diagramme de séquence de récupération de mot de passe, vérification du code secret, mise à jour de mot de passe, interrogation facultative et échange de code d’autorisation.

Démarrez l’autorisation et suivez le lien reset-password retourné (resetPassword ou reset_password). N’appelez pas la découverte de connexion en premier :

POST https://{custom_domain}/{tenant}/api/v2.0/resetpassword/start
Content-Type: application/json
Accept: application/hal+json
{
  "username": "user@contoso.com",
  "continuationToken": "******"
}

Envoyez l’identificateur username du client et le jeton d’autorisation actuel dans continuationToken. L’exemple utilise une adresse e-mail. Une réponse peut publier une méthode de récupération d’e-mail :

{
  "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"
          }
        }
      }
    ]
  }
}

Sélectionnez une méthode de récupération par e-mail ou SMS retournée par le biais d’une logique de flux d’application ou de choix utilisateur. L’exemple montre l’e-mail ; pour SMS, suivez les liens de la méthode SMS retournés sans réécrire l’exemple d’URL. Utilisez l’indicateur masqué où l’interface a besoin d’une étiquette de destination.

Récupération inline pendant la connexion

Offre la récupération inline uniquement lorsqu’une méthode de mot de passe dans la réponse de connexion actuelle publie un recover lien. Suivez ce lien à l’aide du jeton de continuation de connexion actuel. Ne démarrez pas une autre demande d’autorisation ou soumettez à nouveau le nom d’utilisateur ou le mot de passe.

POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/recover
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******"
}

Les deux points d’entrée utilisent la méthode de récupération, le défi, la vérification, la mise à jour de mot de passe et les opérations d’interrogation retournées par le service.

Défier et vérifier la méthode de récupération

Publier sur le lien de challenge la méthode sélectionnée :

{
  "continuationToken": "******"
}

Utiliser JSON et Accept: application/hal+json. L’opération de défi partagé retourne le type de méthode actuel, masquéhint, codeLengthet verify les liens facultatifsresend.

Publiez le code secret entré dans le lien retourné verify :

{
  "otp": "{one_time_passcode}",
  "continuationToken": "******"
}

Utilisez le jeton le plus récent pour chaque requête. Pour un autre code, utilisez les limites actuelles resend du lien et du service, et non une paire d’URL/jetons de défi antérieure.

Une vérification réussie peut retourner la méthode de mot de passe :

{
  "state": "interactionRequired",
  "action": "update",
  "id": "{password_method_id}",
  "type": "password",
  "continuationToken": "******",
  "_links": {
    "update": {
      "href": "/{tenant}/api/v2.0/auth/methods/password/{password_method_id}"
    }
  }
}

Utilisez l’ID de méthode de mot de passe du lien retourné update , et non l’ID de méthode de récupération par e-mail ou SMS. La récupération inline peut conserver l’ID de méthode de mot de passe à partir de la connexion parente.

Mettre à jour un mot de passe

Envoyez le mot de passe de remplacement avec PUT, et non 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": "******"
}
Propriété Catégorie Required Description
continuationToken Chaîne. Oui. Jeton actuel demandant la mise à jour du mot de passe.
newPassword Chaîne. Oui. Mot de passe de remplacement. La confirmation du mot de passe est locale dans votre interface, et non dans un champ de requête supplémentaire.

Le service peut retourner :

{
  "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"
    }
  }
}

Cela indique une mise à jour asynchrone, et non une autorisation finale. N’envoyez pas à nouveau le mot de passe en attendant ou répétez automatiquement la mise à jour après une défaillance réseau ambiguë.

Interroger la mise à jour du mot de passe

Suivez le lien le plus récent 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": "******"
}

Pendant que la mise à jour est en cours, le service retourne interactionRequired avec action: poll, un jeton mis à jour et un poll lien. Remplacez la réponse précédente avant le prochain sondage.

En cas d’inclusion, pollInterval est une chaîne contenant l’intervalle en secondes. Utilisez l’intervalle de réponse actuel pour la requête suivante et respectez les instructions de nouvelle tentative du serveur. L’exemple "2" n’est pas un intervalle de service fixe. Arrêtez l’interrogation lorsque l’action change ou qu’une erreur est retournée et gérez toute authentification ultérieure requise par la stratégie.

Une réponse de continuation est la suivante :

{
  "state": "continue",
  "continuationToken": "******",
  "_links": {
    "continue": {
      "href": "/{tenant}/oauth2/v2.0/authorize-challenge"
    }
  }
}

Remplir les exigences de stratégie et acquérir des jetons

La réinitialisation du mot de passe ne contourne pas l’authentification multifacteur ou l’accès conditionnel. Si un autre défi est retourné, effectuez-le à l’aide des opérations de méthode partagée. L’échange de jetons suit l’achèvement des étapes de stratégie restantes et de la continuation d’autorisation.

Après state: continue, reprenez l’autorisation à l’aide du dernier jeton et échangez le code. Les étendues et revendications demandées restent celles établies au début de la transaction.

Résultats et erreurs

Utilisez la gestion des erreurs partagées. Le contrat de récupération décrit ces résultats :

Pathologie Gestion des résultats et des clients
Nom d’utilisateur inconnu La récupération ne démarre pas. Utilisez un message générique côté client.
Code secret d’e-mail ou SMS incorrect HTTP 400 invalidGrant avec innerError.code: invalidOneTimeCode. Laissez l’utilisateur corriger le code à l’aide de l’état actuel utilisable ou d’un renvoi annoncé.
Code secret manquant HTTP 400 invalidRequest. Corrigez l’entrée manquante.
Renvoyer Un nouveau code secret est envoyé via le lien retourné resend .
Jeton de mise à jour du mot de passe expiré HTTP 400 expiredToken avec innerError.code: expiredContinuationToken. Redémarrez l’autorisation.
Mot de passe de remplacement faible ou courant HTTP 400 invalidRequest avec une erreur interne applicable telle que passwordTooWeak ou passwordTooCommon. Collecter un mot de passe conforme.
Mise à jour en cours Suivez la dernière réponse d’interrogation et les instructions de nouvelle tentative de serveur.
La stratégie de mot de passe d’interrogation échoue HTTP 400 invalidRequest avec une erreur interne telle que passwordTooCommon ou passwordBannedByPolicy. Gérez l’erreur plutôt que d’interroger indéfiniment.
Compte verrouillé ou désactivé lors de l’interrogation HTTP 403 forbidden avec innerError.code: accountLocked. Arrêtez l’opération de récupération.
Échec du travail de mise à jour du mot de passe HTTP 500 serverError. Afficher un échec clair sans répéter automatiquement la mise à jour du mot de passe.
Récupération terminée Gérez les actions de stratégie restantes, reprenez l’autorisation et demandez des jetons.

Ce tableau décrit des résultats spécifiques, et non un catalogue d’erreurs exhaustif. L’acceptation de la mise à jour du mot de passe, l’achèvement de l’interrogation et l’émission de jetons sont des limites distinctes.

Ne consignez pas les codes secrets de récupération, les mots de passe de remplacement ou les jetons de transaction. Enregistrez uniquement les ID de diagnostic sécurisés, les horodatages et l’état HTTP. Ne relectez pas automatiquement les mises à jour de vérification ou de mot de passe.