Informations de référence sur l’API d’authentification native V1

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.

Cette référence documente le contrat V1 pour les intégrations existantes. Pour les interfaces spécifiques à la bibliothèque, utilisez les références du Kit de développement logiciel (SDK).

Avec l’authentification native incorporée, votre application présente l’interface d’authentification. Vous contrôlez sa disposition et ses interactions pendant que ID externe Microsoft Entra valide les demandes d’authentification.

Cette référence d’API V1 décrit les requêtes HTTP brutes pour les intégrations gérées. Pour obtenir une intégration de bibliothèque existante, consultez les références de la bibliothèque sdk.

Les réponses de parcours contiennent les informations nécessaires pour l’opération suivante. Les réponses de jeton peuvent inclure un jeton d’ID pour l’identification de l’utilisateur et un jeton d’accès pour une API protégée, en fonction de la demande et du contrat de point de terminaison.

L’API d’authentification native prend en charge l’inscription et la connexion pour deux flux d’authentification :

  • E-mail avec mot de passe, qui prend en charge l’inscription et la connexion avec un e-mail et un mot de passe, et la réinitialisation de mot de passe en libre-service (SSPR).

  • Code secret à usage unique par e-mail, qui prend en charge l’inscription et la connexion avec un code secret à usage unique.

Configuration requise pour cors du navigateur

Note

Les points de terminaison v1 de l’API d’authentification native ne prennent pas en charge l’accès direct au navigateur inter-origine via le partage de ressources cross-origin (CORS). Les intégrations de navigateur existantes nécessitent un proxy. Les applications Android et iOS utilisant des transports HTTP natifs n’ont pas besoin de CORS ou d’un proxy CORS.

Configurez le proxy pour les chemins de point de terminaison V1 utilisés par votre client.

Références du Kit de développement logiciel (

Utilisez la référence de bibliothèque qui correspond à votre package installé. La documentation liée peut également décrire des interfaces sdk plus récentes ; cet article définit le contrat HTTP V1.

Prerequisites

  1. Un client externe Microsoft Entra. Si vous n’avez pas encore créé de client externe, créez-en un maintenant.

  2. Si ce n’est déjà fait, Inscrire une application dans le Centre d’administration Microsoft Entra. Veillez à respecter les points suivants :

  3. Si ce n'est déjà fait, Créer un flux utilisateur dans le centre d'administration Microsoft Entra. Lorsque vous créez le flux utilisateur, notez les attributs utilisateur que vous configurez si nécessaire, car ces attributs sont ceux que Microsoft Entra attend que votre application envoie.

  4. Associez votre inscription d’application au flux utilisateur.

  5. Pour le flux de connexion, inscrivez-vous un utilisateur client, que vous utilisez pour tester le flux. Vous pouvez également obtenir ce compte de test après avoir effectué le processus d'inscription.

  6. Pour le flux SSPR, activez la réinitialisation de mot de passe en libre-service pour les utilisateurs clients dans le client externe. SSPR est disponible pour les utilisateurs clients qui utilisent un e-mail avec la méthode d’authentification par mot de passe.

  7. Si vous souhaitez permettre aux utilisateurs qui se connectent avec une adresse e-mail et un mot de passe de se connecter également avec un nom d’utilisateur et un mot de passe, utilisez les étapes de l’article Connexion avec un alias ou un nom d’utilisateur :

    1. Activez le nom d’utilisateur dans la connexion.
    2. Créez des utilisateurs avec un nom d’utilisateur dans le Centre d’administration ou mettez à jour les utilisateurs existants en ajoutant un nom d’utilisateur. Vous pouvez également automatiser la création et la mise à jour des utilisateurs dans votre application à l’aide de l’API Microsoft Graph.
  8. Pour appliquer l’authentification multifacteur (MFA) à vos clients, suivez les étapes décrites dans Ajouter l’authentification multifacteur (MFA) à une application pour ajouter l’authentification multifacteur à votre flux de connexion. L’authentification native prend en charge le code secret et SMS à usage unique par e-mail comme second facteur pour l’authentification multifacteur.

Jeton de liaison

Chaque fois que vous appelez une connexion, une inscription ou un point de terminaison SSPR, la réponse inclut un jeton de continuation. Ce jeton identifie de manière unique le flux actuel et permet Microsoft Entra ID maintenir l’état sur ses points de terminaison. Incluez le jeton dans chaque requête suivante dans ce flux. Il est valide uniquement pendant une durée limitée et ne peut être utilisé que pour les requêtes suivantes dans le même flux.

Types et fonctionnalités de défi V1

Les clients V1 publient des méthodes d’authentification via challenge_type et une prise en charge supplémentaire de l’interface utilisateur et du flux via capabilities.

Type de défi Description
mot de passe Ce type de défi indique que l’application prend en charge la collecte d’informations d’identification de mot de passe auprès de l’utilisateur.
oob Ce type de défi indique que l’application prend en charge l’utilisation de codes de mot de passe ou de code secret à usage unique envoyés à l’utilisateur à l’aide d’un canal secondaire. Actuellement, l’API prend uniquement en charge les E-mails et SMS OTP.
redirection Ce type de défi indique que l’application prend en charge un retour en arrière vers l’authentification déléguée par le navigateur, également appelée fallback web. Toutes les applications compatibles avec l’authentification native doivent prendre en charge cette fonctionnalité. Cette exigence signifie que dans chaque appel que l’application effectue à l’API d’authentification native, elle doit inclure ce type de défi. Si l’application cliente ne parvient pas à inclure ce type de défi, la demande échoue.
Méthode d’authentification Inscription Se connecter Réinitialisation du mot de passe en libre-service
Courrier électronique avec mot de passe oob password redirect oob password redirect oob redirect
Code secret à usage unique par e-mail oob redirect oob redirect Non applicable.

Les clients d’API directe sont inclus redirect lors de la déclaration de types de défis. Les kits SDK Android, iOS et JavaScript V1 l’incluent automatiquement.

Capability Meaning
mfa_required Le client peut gérer l’authentification multifacteur inline, y compris le , /challengeet la /introspectséquence et /token l’interface utilisateur correspondante. Cela inclut l’authentification multifacteur pilotée par le contexte lorsque la stratégie de locataire l’exige.
registration_required Le client peut appeler les API d’inscription de méthode d’authentification forte et afficher l’interface utilisateur d’inscription.

Un type ou une fonctionnalité de défi non pris en charge rend la requête non valide. Si le client omet un type de défi requis, le service nécessite une secours web. Si le client omet une fonctionnalité d’authentification multifacteur ou d’inscription, le flux ne peut se poursuivre que lorsque cette fonctionnalité n’est pas requise par le service ; sinon, la secours web est requise.

Les commutateurs de secours web V1 basculent vers l’authentification déléguée par navigateur. Par exemple, un flux d’inscription par e-mail avec mot de passe a besoin à la fois oob et password. Une application qui publie uniquement oob utilise la secours du navigateur pour ce flux. Utilisez les références du Kit de développement logiciel (SDK) pour les vérifications d’erreurs de plateforme et les points d’entrée de bibliothèque interactifs. La secours du navigateur démarre une tentative d’authentification distincte plutôt que de reprendre la progression native.

Activer les flux d’authentification client public et natifs

Pour une inscription d’application V1 existante que vous êtes autorisé à gérer :

Utilisez les autorisations de gestion des applications déléguées ou de propriété d’application déléguées pour l’inscription. Les paramètres d’authentification ne nécessitent pas d’affectation d’administrateur à l’échelle du locataire uniquement pour cette tâche ; les modifications de consentement et de stratégie ont des exigences d’autorisation distinctes.

  1. Ouvrez l’inscription de l’application dans le centre d’administration Microsoft Entra.
  2. Sous Gérer, sélectionnez Authentification.
  3. Sous Paramètres avancés, définissez Activer les flux mobiles et de bureau suivants et activez l’authentification native sur Oui.
  4. Sélectionnez Enregistrer.

Connexion au nom d’utilisateur V1

Vous pouvez autoriser les utilisateurs qui se connectent avec une adresse e-mail et un mot de passe à se connecter avec un nom d’utilisateur et un mot de passe. Le nom d’utilisateur, également appelé un identificateur de connexion alternatif, peut être un identifiant client, un numéro de compte ou un autre identificateur que vous choisissez d’utiliser comme nom d’utilisateur.

Vous pouvez affecter manuellement des noms d’utilisateur au compte d’utilisateur via le Centre d’administration Microsoft Entra ou l’automatiser dans votre application via l’API Microsoft Graph.

Utilisez les étapes de l’article Se connecter avec un alias ou un nom d'utilisateur pour permettre à vos utilisateurs de se connecter à l’aide d’un nom d’utilisateur dans votre application :

  1. Activez le nom d’utilisateur dans la connexion.
  2. Créez des utilisateurs avec un nom d’utilisateur dans le Centre d’administration ou mettez à jour les utilisateurs existants en ajoutant un nom d’utilisateur. Vous pouvez également automatiser la création et la mise à jour des utilisateurs dans votre application à l’aide de l’API Microsoft Graph.

Référence API pour l’inscription

Pour terminer un flux d’inscription utilisateur pour l’une ou l’autre méthode d’authentification, votre application interagit avec quatre points de terminaison, /signup/v1.0/start, /signup/v1.0/challenge, /signup/v1.0/continueet /token.

Points d’accès API pour l’inscription

Point de terminaison Description
/signup/v1.0/start Ce point de terminaison démarre le flux d’inscription. Vous transmettez l’ID d’application valide, le nouveau nom d’utilisateur et type de défi, puis vous récupérez un nouveau jeton de continuation. Le point de terminaison peut retourner une réponse pour indiquer à l'application d'utiliser un flux d'authentification web si les méthodes d'authentification choisies par l'application ne sont pas prises en charge par Microsoft Entra.
/signup/v1.0/challenge Votre application appelle ce point de terminaison avec une liste de types challenge pris en charge par Microsoft Entra. Microsoft Entra sélectionnez ensuite l’une des méthodes d’authentification prises en charge pour que l’utilisateur s’authentifie.
/signup/v1.0/continue Ce point de terminaison permet de poursuivre le flux pour créer le compte d’utilisateur ou interrompre le flux en raison de conditions manquantes, telles que les exigences de stratégie de mot de passe ou les formats d’attribut incorrects. Ce point de terminaison génère un jeton de continuation, puis le retourne à l’application. Le point de terminaison peut retourner une réponse pour indiquer à l'application d'utiliser un flux d'authentification web si l'application n'est pas une méthode d'authentification choisie par Microsoft Entra.
oauth/v2.0/token L’application appelle ce point de terminaison pour enfin demander des jetons de sécurité. L’application doit utiliser le jeton de continuation qu’elle acquiert à partir du dernier appel réussi au /signup/v1.0/continue point de terminaison.

Types de défis d’inscription

L’API permet à l’application cliente de publier les méthodes d’authentification qu’elle prend en charge, lorsqu’elle effectue un appel à Microsoft Entra. Pour ce faire, l’application utilise le paramètre challenge_type dans sa demande d’application. Ce paramètre contient des valeurs prédéfinies qui représentent différentes méthodes d’authentification.

En savoir plus sur les types de défis dans les types de défi d’authentification native. Cet article explique les valeurs de type de défi que vous devez utiliser pour une méthode d’authentification.

Détails du protocole de flux d’inscription

Le diagramme de séquence illustre le flux du processus d’inscription.

Diagramme de l’authentification native un flux d’inscription.

Ce diagramme indique que l’application collecte le nom d’utilisateur (e-mail), le mot de passe (pour le flux d’authentification par mot de passe) et les attributs de l’utilisateur à différents moments (et éventuellement sur des écrans distincts). Toutefois, vous pouvez concevoir votre application pour collecter le nom d’utilisateur (e-mail), le mot de passe et toutes les valeurs d’attribut requises et facultatives dans le même écran, puis les envoyer à l’ensemble du /signup/v1.0/start point de terminaison. Si l’application envoie toutes les informations requises au /signup/v1.0/start point de terminaison, l’application n’a pas besoin d’effectuer des appels et de gérer les réponses dans les étapes facultatives.

À l’étape 21, l’utilisateur est déjà inscrit. Toutefois, si l’application doit se connecter automatiquement à un utilisateur après l’inscription, l’application appelle le oauth/v2.0/token point de terminaison pour demander des jetons de sécurité.

Étape 1 : Demande de démarrage du flux d’inscription

Le flux d’inscription commence par l’application effectuant une requête POST au point de terminaison /signup/v1.0/start pour démarrer le flux d’inscription.

Voici des exemples de la requête (nous présentons l’exemple de requête dans plusieurs lignes pour la lisibilité) :

Exemple 1 :

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&username=contoso-consumer@contoso.com

Exemple 2 (inclure des attributs utilisateur et un mot de passe dans la demande) :

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&password={secure_password}
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postalCode": "{user_postal_code}"}
&username=contoso-consumer@contoso.com
Parameter Required Description
tenant_subdomain Yes Sous-domaine du tenant externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Répertoire (locataire). Par exemple, si le domaine principal de votre locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de locataire, découvrez comment lire les détails de votre locataire.
client_id Yes ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra.
username Yes E-mail de l’utilisateur client avec lequel il souhaite s’inscrire, tel que contoso-consumer@contoso.com.
challenge_type Yes Liste séparée par l’espace des chaînes de type de défi d’autorisation que l’application prend en charge, telles que oob password redirect. La liste doit toujours inclure le type de défi redirect. La valeur est censée être oob redirect ou oob password redirect pour l’e-mail avec la méthode d’authentification par mot de passe.
password No Valeur de mot de passe collectée par l’application auprès de l’utilisateur client. Vous pouvez envoyer le mot de passe d’un utilisateur via le /signup/v1.0/start ou une version ultérieure dans le point de terminaison /signup/v1.0/continue. Remplacez {secure_password} par la valeur de mot de passe collectée par l’application auprès de l’utilisateur client. Il est de votre responsabilité de confirmer que l’utilisateur est conscient du mot de passe qu’il souhaite utiliser en fournissant le champ de confirmation du mot de passe dans l’interface utilisateur de l’application. Vous devez également vous assurer que l’utilisateur est conscient de ce qui constitue un mot de passe fort conformément à la stratégie de votre organisation. En savoir plus sur les stratégies de mot de passe de Microsoft Entra.
Ce paramètre s’applique uniquement à l’e-mail avec la méthode d’authentification par mot de passe.
attributes No L’utilisateur attribue des valeurs que l’application collecte auprès de l’utilisateur client. La valeur est une chaîne, mais mise en forme en tant qu’objet JSON dont les valeurs de clé sont nom programmable d’attributs utilisateur. Ces attributs peuvent être intégrés ou personnalisés, et obligatoires ou facultatifs. Les noms de clé de l’objet dépendent des attributs configurés par l’administrateur dans Microsoft Entra centre d’administration. Vous pouvez envoyer un ou plusieurs attributs utilisateur via le point de terminaison /signup/v1.0/start ou version ultérieure dans le point de terminaison /signup/v1.0/continue. Si vous envoyez tous les attributs requis via le point de terminaison /signup/v1.0/start, vous n’avez pas besoin d’envoyer d’attributs dans le point de terminaison /signup/v1.0/continue. Toutefois, si vous envoyez certains attributs requis via le point de terminaison /signup/v1.0/start, vous pouvez soumettre les attributs requis restants plus loin dans le point de terminaison /signup/v1.0/continue. Remplacez {given_name}, {user_age} et {postal_code} par les valeurs de nom, d’âge et de code postal respectivement collectées par l’application auprès de l’utilisateur client. Microsoft Entra ignore tous les attributs que vous envoyez, qui n'existent pas.
capabilities No Indicateurs séparés par l’espace qui décrivent les fonctionnalités de l’application cliente. Alors que vous définissez challenge_type quelles méthodes peuvent être contestées, capabilities indiquez à l’API d’authentification native les flux supplémentaires que l’application cliente peut gérer et quelles interfaces utilisateur peuvent montrer à l’utilisateur. Par exemple, mfa_required signifie une autre /challenge boucle /token  ; registration_required signifie que l’application cliente appelle les API d’inscription et affiche l’interface utilisateur d’inscription. Si une fonctionnalité requise n’est pas publiée par l’application cliente, l’API retourne la redirection. Les valeurs prises en charge sont mfa_required et registration_required. En savoir plus sur les fonctionnalités.

Réponse de réussite

Voici un exemple de réponse réussie :

HTTP/1.1 200 OK
Content-Type: application/json
{
    "continuation_token": "AQABAAEAAA…"
}
Propriété Description
continuation_token Jeton de continuation qui Microsoft Entra retourne.

Réponse de redirection

Si l'application cliente ne prend pas en charge la méthode d'authentification ou les fonctionnalités requises par Microsoft Entra, un flux d'authentification web est nécessaire. Dans ce scénario, Microsoft Entra informe l’application en retournant un type de défi redirect dans la réponse :

HTTP/1.1 200 OK
Content-Type: application/json
{
   "challenge_type": "redirect"
}
Propriété Description
challenge_type Microsoft Entra retourne une réponse qui a un type de défi. La valeur de ce type de défi est la redirection, ce qui permet à l’application d’utiliser le flux d’authentification web.

Cette réponse est considérée comme réussie, mais l’application est nécessaire pour basculer vers un flux d’authentification web. Dans ce cas, nous vous recommandons d’utiliser une bibliothèque d’authentification intégrée et prise en charge par Microsoft.

Réponse d’erreur

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "user_already_exists",
    "error_description": "AADSTS1003037: It looks like you may already have an account.... .\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        1003037
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Propriété Description
error Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs et y répondre.
error_description Message d’erreur spécifique qui peut vous aider à identifier la cause d’une erreur d’authentification.
error_codes Liste des codes d’erreur spécifiques à Microsoft Entra qui peuvent vous aider à diagnostiquer les erreurs.
timestamp Heure à laquelle l’erreur s’est produite.
trace_id Identificateur unique de la demande qui peut vous aider à diagnostiquer les erreurs.
correlation_id Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants.
invalid_attributes Liste (tableau d’objets) d’attributs ayant échoué. Cette réponse est possible si l’application envoie des attributs utilisateur et que la valeur de la suberror propriété est attribute_validation_failed.
suberror Chaîne de code d’erreur qui peut être utilisée pour classifier davantage les types d’erreurs.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles de la error propriété) :

une valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple lorsque la valeur du paramètre challenge_type contient une méthode d’authentification non prise en charge ou si la requête n’a pas inclus le paramètre client_id, la valeur de l’ID client est vide ou non valide. Utilisez le paramètre error_description pour découvrir la cause exacte de l’erreur.
invalid_client L’ID client que l’application inclut dans la demande concerne une application qui n’a pas de configuration d’authentification native, telle qu’elle n’est pas un client public ou n’est pas activée pour l’authentification native. Utilisez la suberror propriété pour apprendre la cause exacte de l’erreur.
unauthorized_client L’ID client utilisé dans la requête a un format d’ID client valide, mais n’existe pas dans le tenant externe ou est incorrect.
unsupported_challenge_type La valeur du paramètre challenge_type n’inclut pas le type de défi redirect.
user_already_exists L’utilisateur existe déjà.
invalid_grant Le mot de passe envoyé par l’application ne répond pas à toutes les exigences de complexité, telles que le mot de passe est trop court. Utilisez la suberror propriété pour apprendre la cause exacte de l’erreur.
Ce paramètre s’applique uniquement à l’e-mail avec la méthode d’authentification par mot de passe.

Si le paramètre d’erreur a une valeur de invalid_grant, Microsoft Entra inclut une propriété suberror dans sa réponse. Voici les valeurs possibles de la suberror propriété pour une erreur invalid_grant :

Valeur de sous-erreur Description
password_too_weak Le mot de passe est trop faible, car il ne répond pas aux exigences de complexité. En savoir plus sur les stratégies de mot de passe de Microsoft Entra. Cette réponse est possible si l’application envoie un mot de passe utilisateur.
password_too_short Le nouveau mot de passe est inférieur à 8 caractères. En savoir plus sur les stratégies de mot de passe de Microsoft Entra. Cette réponse est possible si l’application envoie un mot de passe utilisateur.
password_too_long Le nouveau mot de passe dépasse 256 caractères. En savoir plus sur les stratégies de mot de passe de Microsoft Entra. Cette réponse est possible si l’application envoie un mot de passe utilisateur.
password_recently_used Le nouveau mot de passe ne doit pas être le même qu’un mot de passe récemment utilisé. En savoir plus sur les stratégies de mot de passe de Microsoft Entra. Cette réponse est possible si l’application envoie un mot de passe utilisateur.
password_banned Le nouveau mot de passe contient un mot, une expression ou un modèle interdit. En savoir plus sur les stratégies de mot de passe de Microsoft Entra. Cette réponse est possible si l’application envoie un mot de passe utilisateur.
password_is_invalid Le mot de passe n’est pas valide, par exemple parce qu’il utilise des caractères non autorisés. En savoir plus sur les stratégies de mot de passe de Microsoft Entra. Cette réponse est possible si l’application envoie un mot de passe utilisateur.

Si le paramètre d’erreur a une valeur de invalid_client, Microsoft Entra inclut une propriété suberror dans sa réponse. Voici les valeurs possibles de la suberror propriété pour une erreur invalid_client :

Valeur de sous-erreur Description
nativeauthapi_disabled ID client d’une application qui n’est pas activé pour l’authentification native.

Note

Si vous envoyez tous les attributs requis via le point de terminaison /signup/v1.0/start, mais pas tous les attributs facultatifs, vous ne pourrez pas envoyer d’attributs facultatifs supplémentaires ultérieurement via le point de terminaison /signup/v1.0/continue. Microsoft Entra ne demande pas explicitement les attributs facultatifs, car ils ne sont pas obligatoires pour que le flux d'inscription se termine. Consultez le tableau de la section Envoi d’attributs utilisateur aux points de terminaison pour savoir quels attributs utilisateur vous pouvez envoyer aux points de terminaison /signup/v1.0/start et /signup/v1.0/continue.

Étape 2 : Sélectionner une méthode d’authentification

L’application demande Microsoft Entra de sélectionner l’un des types de défis pris en charge pour que l’utilisateur s’authentifie. Pour ce faire, l’application passe un appel au point de terminaison /signup/v1.0/challenge. L’application doit inclure le jeton de continuation qu’elle acquiert à partir du point de terminaison /signup/v1.0/start dans la requête.

Voici un exemple de la requête (nous présentons l’exemple de requête dans plusieurs lignes pour la lisibilité) :

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…
Parameter Required Description
tenant_subdomain Yes Sous-domaine du tenant externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Répertoire (locataire). Par exemple, si le domaine principal de votre locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de locataire, découvrez comment lire les détails de votre locataire.
client_id Yes ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra.
challenge_type No Une liste séparée par des espaces de chaînes de caractères de type défi d'autorisation que l'application prend en charge, telles que oob password redirect. La liste doit toujours inclure le type de défi redirect. La valeur est censée être oob redirect pour le code secret à usage unique par e-mail et oob password redirect pour l’e-mail avec méthode d’authentification par mot de passe.
continuation_token Yes Jeton de continuation qui Microsoft Entra retourné dans la requête précédente.

Réponse de réussite

Microsoft Entra envoie un code secret unique à l'e-mail de l'utilisateur, puis répond avec le type de défi avec la valeur de oob et des informations supplémentaires sur le code secret à usage unique :

HTTP/1.1 200 OK
Content-Type: application/json
{
    "interval": 300,
    "continuation_token": "AQABAAEAAAYn...",
    "challenge_type": "oob",
    "binding_method": "prompt",
    "challenge_channel": "email",
    "challenge_target_label": "c***r@co**o**o.com",
    "code_length": 8
}
Propriété Description
interval Durée en secondes pendant laquelle l’application doit attendre avant de tenter de renvoyer le mot de passe par mot de passe.
continuation_token Jeton de continuation qui Microsoft Entra retourne.
challenge_type Type de défi sélectionné pour que l’utilisateur s’authentifie.
binding_method La seule valeur valide est invite. Ce paramètre peut être utilisé à l’avenir pour offrir davantage de moyens à l’utilisateur d’entrer le code secret à usage unique. Émis si challenge_type est oob
challenge_channel Type du canal via lequel le code secret à usage unique a été envoyé. Pour le moment, seul le canal de messagerie est pris en charge.
challenge_target_label E-mail obfusqué où le code secret à usage unique a été envoyé.
code_length Longueur du code secret à usage unique généré par Microsoft Entra.

Réponse de redirection

Si l'application cliente ne prend pas en charge la méthode d'authentification ou les fonctionnalités requises par Microsoft Entra, un flux d'authentification web est nécessaire. Dans ce scénario, Microsoft Entra informe l’application en retournant un type de défi redirect dans la réponse :

HTTP/1.1 200 OK
Content-Type: application/json
{
   "challenge_type": "redirect"
}
Propriété Description
challenge_type Microsoft Entra retourne une réponse qui a un type de défi. La valeur de ce type de défi est la redirection, ce qui permet à l’application d’utiliser le flux d’authentification web.

Cette réponse est considérée comme réussie, mais l’application est nécessaire pour basculer vers un flux d’authentification web. Dans ce cas, nous vous recommandons d’utiliser une bibliothèque d’authentification intégrée et prise en charge par Microsoft.

Réponse d’erreur

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        901007
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Propriété Description
error Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs et y répondre.
error_description Message d’erreur spécifique qui peut vous aider à identifier la cause d’une erreur d’authentification.
error_codes Liste des codes d’erreur spécifiques à Microsoft Entra qui peuvent vous aider à diagnostiquer les erreurs.
timestamp Heure à laquelle l’erreur s’est produite.
trace_id Identificateur unique de la demande qui peut vous aider à diagnostiquer les erreurs.
correlation_id Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles de la error propriété) :

une valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple l’ID client est vide ou non valide.
expired_token Le jeton de continuation a expiré.
unsupported_challenge_type La valeur du paramètre challenge_type n’inclut pas le type de défi redirect.
invalid_grant Le jeton de continuation n'est pas valide.

Étape 3 : Envoyer un code secret à usage unique

L’application envoie le code secret à usage unique envoyé à l’e-mail de l’utilisateur. Étant donné que nous envoyons un code secret à usage unique, un paramètre oob est requis et le paramètre grant_type doit avoir une valeur oob.

Voici un exemple de la requête (nous présentons l’exemple de requête dans plusieurs lignes pour la lisibilité) :

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=oob
&oob={otp_code}
Parameter Required Description
tenant_subdomain Yes Sous-domaine du tenant externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Répertoire (locataire). Par exemple, si le domaine principal de votre locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de locataire, découvrez comment lire les détails de votre locataire.
continuation_token Yes Jeton de continuation qui Microsoft Entra retourné dans la requête précédente.
client_id Yes ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra.
grant_type Yes Une demande adressée au point de terminaison /signup/v1.0/continue peut être utilisée pour envoyer des attributs de code secret, de mot de passe ou d’utilisateur à usage unique. Dans ce cas, la valeur grant_type est utilisée pour différencier ces trois cas d’usage. Les valeurs possibles pour grant_type sont oob, mot de passe, attributs. Dans cet appel, étant donné que nous envoyons un code secret à usage unique, la valeur est censée être oob.
oob Yes Code secret à usage unique reçu par l’utilisateur client dans son e-mail. Remplacez {otp_code} par les valeurs de code secret à usage unique reçu par l’utilisateur client dans son e-mail. Pour renvoyer un code secret à usage unique, l’application doit à nouveau envoyer une requête au point de terminaison /signup/v1.0/challenge.

Une fois que l’application a correctement envoyé le code secret à usage unique, le flux d’inscription dépend des scénarios comme indiqué dans le tableau :

Scenario Modalités pratiques
L'application envoie correctement le mot de passe de l'utilisateur (pour la méthode d'authentification par mot de passe) via le point de terminaison /signup/v1.0/start, et aucun attribut n'est configuré dans Microsoft Entra centre d'administration ou tous les attributs utilisateur requis sont envoyés via le point de terminaison /signup/v1.0/start. Microsoft Entra émet un jeton de continuation. L’application peut utiliser le jeton de continuation pour demander des jetons de sécurité, comme indiqué dans Demande de jetons de sécurité.
L'application envoie correctement le mot de passe de l'utilisateur pour l'e-mail avec la méthode d'authentification par mot de passe) via le /signup/v1.0/start, mais pas tous les attributs utilisateur requis, Microsoft Entra indique les attributs que l'application doit envoyer comme indiqué dans attributs d'utilisateur requis. L’application doit envoyer les attributs utilisateur requis via le point de terminaison /signup/v1.0/continue. La réponse est similaire à celle des attributs utilisateur requis. Envoyez les attributs utilisateur affichés dans les attributs utilisateur d’envoi.
L'application ne soumet pas le mot de passe de l'utilisateur (pour les emails avec méthode d'authentification par mot de passe) via le point de terminaison /signup/v1.0/start. la réponse de Microsoft Entra indique que les informations d'identification sont requises. Consultez réponse.
Cette réponse est possible pour l’e-mail avec la méthode d’authentification par mot de passe.

Response

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "credential_required",
    "error_description": "AADSTS55103: Credential required. Trace ID: d6966055-...-80500 Correlation ID: 3944-...-60d6 Timestamp: yy-mm-dd 02:37:33Z",
    "error_codes": [
        55103
    ],
    "timestamp": "yy-mm-dd 02:37:33Z",
    "trace_id": "d6966055-...-80500",
    "correlation_id": "3944-...-60d6",
    "continuation_token": "AQABEQEAAAA..."
}
Propriété Description
error Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs et y répondre.
error_description Message d’erreur spécifique qui peut vous aider à identifier la cause d’une erreur d’authentification.
error_codes Liste des codes d’erreur spécifiques à Microsoft Entra qui peuvent vous aider à diagnostiquer les erreurs.
timestamp Heure à laquelle l’erreur s’est produite.
trace_id Identificateur unique de la demande qui peut vous aider à diagnostiquer les erreurs.
correlation_id Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants.
continuation_token Jeton de continuation qui Microsoft Entra retourne.
suberror Chaîne de code d’erreur qui peut être utilisée pour classifier davantage les types d’erreurs.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles de la error propriété) :

une valeur d’erreur Description
credential_required L’authentification est requise pour la création de compte. Vous devez donc effectuer un appel au point de terminaison /signup/v1.0/challenge pour déterminer les informations d’identification que l’utilisateur doit fournir.
invalid_request Échec de la validation des paramètres de requête, par exemple une validation de jeton de continuation a échoué ou la demande n’a pas inclus le paramètre client_id, la valeur de l’ID client est vide ou non valide ou l’administrateur client externe n’a pas activé le mot de passe à usage unique par e-mail pour tous les utilisateurs du tenant.
invalid_grant Le type d’octroi inclus dans la requête n’est pas valide ou pris en charge, ou la valeur OTP est incorrecte.
expired_token Le jeton de continuation inclus dans la requête a expiré.

Si le paramètre d’erreur a une valeur de invalid_grant, Microsoft Entra inclut une propriété suberror dans sa réponse. Voici les valeurs possibles de la suberror propriété pour une erreur invalid_grant :

Valeur de sous-erreur Description
invalid_oob_value La valeur du code secret à usage unique n’est pas valide.

Pour que les informations d’identification du mot de passe soient collectées auprès de l’utilisateur, l’application doit effectuer un appel au point de terminaison /signup/v1.0/challenge pour déterminer les informations d’identification que l’utilisateur doit fournir.

Voici un exemple de la requête (nous présentons l’exemple de requête dans plusieurs lignes pour la lisibilité) :

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…
Parameter Required Description
tenant_subdomain Yes Sous-domaine du tenant externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Répertoire (locataire). Par exemple, si le domaine principal de votre locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de locataire, découvrez comment lire les détails de votre locataire.
client_id Yes ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra.
challenge_type No Une liste séparée par des espaces de chaînes de caractères de type défi d'autorisation que l'application prend en charge, telles que oob password redirect. La liste doit toujours inclure le type de défi redirect. Pour l’e-mail avec le flux d’inscription par mot de passe, la valeur doit contenir password redirect.
continuation_token Yes Jeton de continuation qui Microsoft Entra retourné dans la requête précédente.

Réponse de réussite

Si le mot de passe est la méthode d’authentification configurée pour l’utilisateur dans le centre d’administration Microsoft Entra, une réponse réussie avec le jeton de continuation est retournée à l’application.

HTTP/1.1 200 OK
Content-Type: application/json
{
    "challenge_type": "password",
    "continuation_token": " AQABAAEAAAAty..."
}
Propriété Description
challenge_type le mot de passe est retourné dans la réponse pour les informations d’identification requises.
continuation_token Jeton de continuation qui Microsoft Entra retourne.

Réponse de redirection

Si l'application cliente ne prend pas en charge la méthode d'authentification ou les fonctionnalités requises par Microsoft Entra, un flux d'authentification web est nécessaire. Dans ce scénario, Microsoft Entra informe l’application en retournant un type de défi redirect dans la réponse :

HTTP/1.1 200 OK
Content-Type: application/json
{
    "challenge_type": "redirect"
}
Propriété Description
challenge_type Microsoft Entra retourne une réponse qui a un type de défi. La valeur de ce type de défi est la redirection, ce qui permet à l’application d’utiliser le flux d’authentification web.

Cette réponse est considérée comme réussie, mais l’application est nécessaire pour basculer vers un flux d’authentification web. Dans ce cas, nous vous recommandons d’utiliser une bibliothèque d’authentification intégrée et prise en charge par Microsoft.

Étape 4 : Authentifier et obtenir le jeton pour vous inscrire

L'application doit envoyer les informations d'identification de l'utilisateur, dans ce cas le mot de passe, qui Microsoft Entra demandé à l'étape précédente. L’application doit envoyer des informations d’identification de mot de passe si ce n’est pas le cas via le point de terminaison /signup/v1.0/start. L’application envoie une demande au point de terminaison /signup/v1.0/continue pour envoyer le mot de passe. Étant donné que nous envoyons un mot de passe, un paramètre password est requis, et le paramètre grant_type doit avoir une valeur mot de passe.

Voici un exemple de la requête (nous présentons l’exemple de requête dans plusieurs lignes pour la lisibilité) :

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=password
&password={secure_password}
Parameter Required Description
tenant_subdomain Yes Sous-domaine du tenant externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Répertoire (locataire). Par exemple, si le domaine principal de votre locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de locataire, découvrez comment lire les détails de votre locataire.
continuation_token Yes Jeton de continuation qui Microsoft Entra retourné à l’étape précédente.
client_id Yes ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra.
grant_type Yes Une demande adressée au point de terminaison /signup/v1.0/continue peut être utilisée pour envoyer des attributs de code secret, de mot de passe ou d’utilisateur à usage unique. Dans ce cas, la valeur grant_type est utilisée pour différencier ces trois cas d’usage. Les valeurs possibles pour grant_type sont oob, mot de passe, attributs. Dans cet appel, étant donné que nous envoyons le mot de passe de l’utilisateur, la valeur devrait être mot de passe.
password Yes Valeur de mot de passe collectée par l’application auprès de l’utilisateur client. Remplacez {secure_password} par la valeur de mot de passe collectée par l’application auprès de l’utilisateur client. Il est de votre responsabilité de confirmer que l’utilisateur est conscient du mot de passe qu’il souhaite utiliser en fournissant le champ de confirmation du mot de passe dans l’interface utilisateur de l’application. Vous devez également vous assurer que l’utilisateur est conscient de ce qui constitue un mot de passe fort conformément à la stratégie de votre organisation. En savoir plus sur les stratégies de mot de passe de Microsoft Entra.

Réponse de réussite

Si la demande réussit, mais qu’aucun attribut n’a été configuré dans Microsoft Entra centre d’administration ou que tous les attributs requis ont été envoyés via le point de terminaison /signup/v1.0/start, l’application obtient un jeton de continuation sans envoyer d’attributs. L’application peut utiliser le jeton de continuation pour demander des jetons de sécurité, comme indiqué dans Demande de jetons de sécurité. Sinon, la réponse de Microsoft Entra indique que l'application doit envoyer les attributs requis. Ces attributs, intégrés ou personnalisés, ont été configurés dans le centre d’administration Microsoft Entra par l’administrateur client.

Attributs utilisateur requis

Cette réponse demande à l’application d’envoyer des valeurs pour les attributs nom, âge et téléphone .

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "attributes_required",
    "error_description": "User attributes required",
    "error_codes": [
            55106
        ],
    "timestamp": "yy-mm-dd 02:37:33Z",
    "trace_id": "d6966055-...-80500",
    "correlation_id": "3944-...-60d6",
    "continuation_token": "AQABAAEAAAAtn...",
    "required_attributes": [
        {
            "name": "displayName",
            "type": "string",
            "required": true,
            "options": {
              "regex": ".*@.**$"
            }
        },
        {
            "name": "extension_2588abcdwhtfeehjjeeqwertc_age",
            "type": "string",
            "required": true
        },
        {
            "name": "postalCode",
            "type": "string",
            "required": true,
            "options": {
              "regex":"^[1-9][0-9]*$"
            }
        }
    ]
}

Note

Les attributs personnalisés (également appelés extensions de répertoire) sont nommés à l’aide de la convention extension_{appId-without-hyphens}_{attribute-name} où {appId-without-hyphens} est la version supprimée de l’ID client pour l’application d’extensions. Par exemple, si l’ID client de l’application extensions est 2588a-bcdwh-tfeehj-jeeqw-ertc et que le nom de l’attribut est passe-temps, l’attribut personnalisé est nomméextension_2588abcdwhtfeehjjeeqwertc_hobbies. En savoir plus sur attributs personnalisés et l’application d’extension.

Propriété Description
error Cet attribut est défini si Microsoft Entra ne pouvez pas créer le compte d'utilisateur, car un attribut doit être vérifié ou envoyé.
error_description Message d’erreur spécifique qui peut vous aider à identifier la cause de l’erreur.
error_codes Liste des codes d’erreur spécifiques à Microsoft Entra qui peuvent vous aider à diagnostiquer les erreurs.
timestamp Heure à laquelle l’erreur s’est produite.
trace_id Identificateur unique de la demande qui peut vous aider à diagnostiquer les erreurs.
correlation_id Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants.
continuation_token Jeton de continuation qui Microsoft Entra retourne.
required_attributes Liste (tableau d’objets) d’attributs que l’application doit soumettre à l’appel suivant pour continuer. Ces attributs sont les attributs supplémentaires que l’application doit envoyer en dehors du nom d’utilisateur. Microsoft Entra inclut ce paramètre est la réponse si la valeur du paramètre error est attributes_required.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles de la error propriété) :

une valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple une validation de jeton de continuation ayant échoué ou si la requête n’a pas inclus le paramètreclient_id, la valeur de l’ID client est vide ou non valide.
invalid_grant Le type d’octroi inclus dans la demande n’est pas valide ou pris en charge. Les valeurs possibles pour le grant_type sont oob, mot de passe, attributs
expired_token Le jeton de continuation inclus dans la requête a expiré.
attributes_required Un ou plusieurs attributs utilisateur sont requis.

Réponse de redirection

Si l'application cliente ne prend pas en charge la méthode d'authentification ou les fonctionnalités requises par Microsoft Entra, un flux d'authentification web est nécessaire. Dans ce scénario, Microsoft Entra informe l’application en retournant un type de défi redirect dans la réponse :

HTTP/1.1 200 OK
Content-Type: application/json
{
   "challenge_type": "redirect"
}
Propriété Description
challenge_type Microsoft Entra retourne une réponse qui a un type de défi. La valeur de ce type de défi est la redirection, ce qui permet à l’application d’utiliser le flux d’authentification web.

Cette réponse est considérée comme réussie, mais l’application est nécessaire pour basculer vers un flux d’authentification web. Dans ce cas, nous vous recommandons d’utiliser une bibliothèque d’authentification intégrée et prise en charge par Microsoft.

Réponse d’erreur

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_grant",
    "error_description": "New password is too weak",
    "error_codes": [
        399246
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
    "suberror": "password_too_weak"
}
Propriété Description
error Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs et y répondre.
error_description Message d’erreur spécifique qui peut vous aider à identifier la cause d’une erreur d’authentification.
error_codes Liste des codes d’erreur spécifiques à Microsoft Entra qui peuvent vous aider à diagnostiquer les erreurs.
timestamp Heure à laquelle l’erreur s’est produite.
trace_id Identificateur unique de la demande qui peut vous aider à diagnostiquer les erreurs.
correlation_id Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants.
suberror Chaîne de code d’erreur qui peut être utilisée pour classifier davantage les types d’erreurs.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles de la error propriété) :

une valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple lorsque le paramètre challenge_type inclut un type de défi non valide.
invalid_grant L’octroi envoyé n’est pas valide, par exemple le mot de passe envoyé est trop court. Utilisez la suberror propriété pour apprendre la cause exacte de l’erreur.
expired_token Le jeton de continuation a expiré.
attributes_required Un ou plusieurs attributs utilisateur sont requis.

Si le paramètre d’erreur a une valeur de invalid_grant, Microsoft Entra inclut une propriété suberror dans sa réponse. Voici les valeurs possibles de la suberror propriété :

Valeur de sous-erreur Description
password_too_weak Le mot de passe est trop faible, car il ne répond pas aux exigences de complexité. En savoir plus sur les stratégies de mot de passe de Microsoft Entra.
password_too_short Le nouveau mot de passe est inférieur à 8 caractères. En savoir plus sur les stratégies de mot de passe de Microsoft Entra.
password_too_long Le nouveau mot de passe dépasse 256 caractères. En savoir plus sur les stratégies de mot de passe de Microsoft Entra.
password_recently_used Le nouveau mot de passe ne doit pas être le même qu’un mot de passe récemment utilisé. En savoir plus sur les stratégies de mot de passe de Microsoft Entra.
password_banned Le nouveau mot de passe contient un mot, une expression ou un modèle interdit. En savoir plus sur les stratégies de mot de passe de Microsoft Entra.
password_is_invalid Le mot de passe n’est pas valide, par exemple parce qu’il utilise des caractères non autorisés. En savoir plus sur les stratégies de mot de passe de Microsoft Entra. Cette réponse est possible si l’application envoie un mot de passe utilisateur.

Envoyer des attributs utilisateur

Pour continuer avec le flux, l’application doit effectuer un appel au point de terminaison /signup/v1.0/continue pour envoyer les attributs utilisateur requis. Étant donné que nous envoyons des attributs, un paramètre attributes est requis et le paramètre grant_type doit avoir une valeur égale à attributs.

Voici un exemple de la requête (nous présentons l’exemple de requête dans plusieurs lignes pour la lisibilité) :

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=attributes
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postalCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...
Parameter Required Description
tenant_subdomain Yes Sous-domaine du tenant externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Répertoire (locataire). Par exemple, si le domaine principal de votre locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de locataire, découvrez comment lire les détails de votre locataire.
continuation_token Yes Jeton de continuation qui Microsoft Entra retourné dans la requête précédente.
client_id Yes ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra.
grant_type Yes Une demande adressée au point de terminaison /signup/v1.0/continue peut être utilisée pour envoyer des attributs de code secret, de mot de passe ou d’utilisateur à usage unique. Dans ce cas, la valeur grant_type est utilisée pour différencier ces trois cas d’usage. Les valeurs possibles pour grant_type sont oob, mot de passe, attributs. Dans cet appel, étant donné que nous envoyons des attributs utilisateur, la valeur devrait être attributs.
attributes Yes Valeurs d’attribut utilisateur collectées par l’application auprès de l’utilisateur client. La valeur est une chaîne, mais mise en forme en tant qu’objet JSON dont les valeurs de clé sont des noms d’attributs utilisateur, intégrés ou personnalisés. Les noms de clé de l’objet dépendent des attributs configurés par l’administrateur dans Microsoft Entra centre d’administration. Remplacez {given_name}, {user_age} et {postal_code} par les valeurs de nom, d’âge et de code postal respectivement collectées par l’application auprès de l’utilisateur client. Microsoft Entra ignore tous les attributs que vous envoyez, qui n'existent pas.

Réponse de réussite

Si la demande réussit, Microsoft Entra inscrivez l’utilisateur, puis émet un jeton de continuation. L’application peut utiliser le jeton de continuation pour demander des jetons de sécurité à partir du oauth/v2.0/token point de terminaison.

HTTP/1.1 200 OK
Content-Type: application/json
{
    "continuation_token": "AQABAAEAAAYn..."
}
Propriété Description
continuation_token Jeton de continuation qui Microsoft Entra retourne.

Réponse de redirection

Si l'application cliente ne prend pas en charge la méthode d'authentification ou les fonctionnalités requises par Microsoft Entra, un flux d'authentification web est nécessaire. Dans ce scénario, Microsoft Entra informe l’application en retournant un type de défi redirect dans la réponse :

HTTP/1.1 200 OK
Content-Type: application/json
{
   "challenge_type": "redirect"
}
Propriété Description
challenge_type Microsoft Entra retourne une réponse qui a un type de défi. La valeur de ce type de défi est la redirection, ce qui permet à l’application d’utiliser le flux d’authentification web.

Cette réponse est considérée comme réussie, mais l’application est nécessaire pour basculer vers un flux d’authentification web. Dans ce cas, nous vous recommandons d’utiliser une bibliothèque d’authentification intégrée et prise en charge par Microsoft.

Réponse d’erreur

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "expired_token",
    "error_description": "AADSTS901007: The continuation_token is expired.  .\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        552003
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Propriété Description
error Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs et y répondre.
error_description Message d’erreur spécifique qui peut vous aider à identifier la cause d’une erreur d’authentification.
error_codes Liste des codes d’erreur spécifiques à Microsoft Entra qui peuvent vous aider à diagnostiquer les erreurs.
timestamp Heure à laquelle l’erreur s’est produite.
trace_id Identificateur unique de la demande qui peut vous aider à diagnostiquer les erreurs.
correlation_id Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants.
continuation_token Jeton de continuation qui Microsoft Entra retourne.
unverified_attributes Liste (tableau d’objets) des noms de clés d’attribut qui doivent être vérifiés. Ce paramètre est inclus dans la réponse lorsque la valeur du paramètre error est verification_required.
required_attributes Liste (tableau d’objets) d’attributs que l’application doit envoyer. Microsoft Entra inclut ce paramètre dans sa réponse lorsque la valeur du paramètre error est attributes_required.
invalid_attributes Liste (tableau d’objets) d’attributs ayant échoué. Ce paramètre est inclus dans la réponse lorsque la valeur de la suberror propriété est attribute_validation_failed.
suberror Chaîne de code d’erreur qui peut être utilisée pour classifier davantage les types d’erreurs.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles de la error propriété) :

une valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple une validation de jeton de continuation ayant échoué ou si la requête n’a pas inclus le paramètreclient_id, la valeur de l’ID client est vide ou non valide.
invalid_grant Le type d’octroi fourni n’est pas valide ou pris en charge ou a échoué, par exemple la validation des attributs a échoué. Utilisez la suberror propriété pour apprendre la cause exacte de l’erreur.
expired_token Le jeton de continuation inclus dans la requête a expiré.
attributes_required Un ou plusieurs attributs utilisateur sont requis.

Si le paramètre d’erreur a une valeur de invalid_grant, Microsoft Entra inclut une propriété suberror dans sa réponse. Voici les valeurs possibles de la suberror propriété pour une erreur invalid_grant :

Valeur de sous-erreur Description
attribute_validation_failed Échec de la validation des attributs utilisateur. invalid_attributes le paramètre contient la liste (tableau d’objets) des attributs qui ont échoué.

Étape 5 : Se connecter automatiquement après l’inscription

Si l’utilisateur doit se connecter automatiquement après l’inscription, l’application effectue une requête POST au oauth/v2.0/token point de terminaison et fournit le jeton de continuation obtenu à l’étape précédente pour acquérir des jetons de sécurité. Découvrez comment appeler le point de terminaison de jeton.

Envoi d’attributs utilisateur aux points de terminaison

Dans le centre d’administration Microsoft Entra, vous pouvez configurer des attributs utilisateur en fonction des besoins ou facultatifs. Cette configuration détermine comment Microsoft Entra répond lorsque vous effectuez un appel à ses points de terminaison. Les attributs facultatifs ne sont pas obligatoires pour que le flux d’inscription se termine. Par conséquent, lorsque tous les attributs sont facultatifs, ils doivent être envoyés avant que le nom d’utilisateur soit vérifié. Sinon, l’inscription se termine sans les attributs facultatifs.

Le tableau suivant récapitule lorsqu'il est possible d'envoyer des attributs utilisateur à Microsoft Entra points de terminaison.

Point de terminaison Attributs requis Attributs facultatifs Attributs obligatoires et facultatifs
/signup/v1.0/start point de terminaison Yes Yes Yes
/signup/v1.0/continue point de terminaison avant la vérification du nom d’utilisateur Yes Yes Yes
/signup/v1.0/continue point de terminaison après vérification du nom d’utilisateur Yes No Yes

Format des valeurs d’attributs utilisateur

Vous spécifiez les informations que vous souhaitez collecter auprès de l’utilisateur en configurant les paramètres de flux utilisateur dans le centre d’administration Microsoft Entra. Utilisez l’article Collecter des attributs utilisateur personnalisés lors de l’inscription pour apprendre à collecter des valeurs pour les attributs intégrés et personnalisés.

Vous pouvez également spécifier le type d’entrée utilisateur pour les attributs que vous configurez. Le tableau suivant récapitule les types d’entrée utilisateur pris en charge et explique comment envoyer des valeurs collectées par les contrôles d’interface utilisateur à Microsoft Entra.

Type d’entrée utilisateur Format des valeurs soumises
Zone de texte  Valeur unique telle que le titre du travail, Ingénieur logiciel.
SingleRadioSelect Valeur unique telle que Language, norvégien. 
Case à cocherMultiSelect Une ou plusieurs valeurs telles qu’un passe-temps ou un passe-temps, Danse ou Danse, Natation, Voyage.

Voici un exemple de requête qui montre comment envoyer les valeurs des attributs :

POST /{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue HTTP/1.1
Host: {tenant_subdomain}.ciamlogin.com
Content-Type: application/x-www-form-urlencoded
 
continuation_token=ABAAEAAAAtfyo... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=attributes 
&attributes={"jobTitle": "Software Engineer", "extension_2588abcdwhtfeehjjeeqwertc_language": "Norwegian", "extension_2588abcdwhtfeehjjeeqwertc_hobbies": "Dancing,Swimming,Traveling"}
&continuation_token=AQABAAEAAAAtn...

En savoir plus sur les types d’entrée d’attributs utilisateur dans l’articleTypes d’entrée d’attributs utilisateur personnalisés.

Comment référencer les attributs utilisateur

Lorsque vous créer un flux utilisateur d’inscription, vous configurez les attributs utilisateur que vous souhaitez collecter auprès de l’utilisateur lors de l’inscription. Les noms des attributs utilisateur de l’centre d’administration Microsoft Entra diffèrent de la façon dont vous les référencez dans l’API d’authentification native.

Par exemple, Display Name dans le centre d’administration Microsoft Entra est référencé en tant que displayName dans l’API.

Utilisez l’article attributs de profil utilisateur pour apprendre à référencer à la fois des attributs utilisateur intégrés et personnalisés dans l’API d’authentification native.

Référence API pour le flux de connexion

Les utilisateurs doivent se connecter avec la méthode d’authentification qu’ils utilisent pour s’inscrire. Par exemple, les utilisateurs qui s'inscrivent en utilisant la méthode d'authentification par e-mail et par mot de passe doivent indiquer leur e-mail et leur mot de passe.

Pour demander des jetons de sécurité, votre application interagit avec trois points de terminaison, oauth/v2.0/initiate, oauth/v2.0/challenge, oauth/v2.0/tokenet éventuellement oauth/v2.0/introspect.

Points de terminaison API pour la connexion

Point de terminaison Description
oauth/v2.0/initiate Ce point de terminaison lance le flux de connexion. Si votre application l’appelle avec un nom d’utilisateur d’un compte d’utilisateur qui existe déjà, elle retourne une réponse réussie avec un jeton de continuation. Si votre application demande d'utiliser des méthodes d'authentification qui ne sont pas prises en charge par Microsoft Entra, cette réponse de point de terminaison peut indiquer à votre application qu'elle doit utiliser un flux d'authentification basé sur un navigateur.
oauth/v2.0/challenge Votre application appelle ce point de terminaison pour demander Microsoft Entra de sélectionner l’un des types de défi pris en charge sign-in pour que l’utilisateur s’authentifie. Lorsque l’administrateur client applique l’authentification multifacteur pour les utilisateurs clients, votre application appelle ce point de terminaison pour contester l’utilisateur pour la deuxième méthode d’authentification de facteur.
oauth/v2.0/token Ce point de terminaison vérifie les informations d’identification de l’utilisateur qu’il reçoit de votre application, puis émet des jetons de sécurité à votre application. Une réponse de ce point de terminaison peut également indiquer si l’utilisateur doit effectuer un défi MFA ou inscrire une méthode d’authentification forte.
oauth/v2.0/introspect Votre application l’appelle pour demander une liste de méthodes d’authentification forte inscrites pour l’authentification multifacteur (MFA). Découvrez comment utiliser le point de terminaison d’introspect

Types de défis de connexion

L’API permet à l’application de publier les méthodes d’authentification qu’elle prend en charge, lorsqu’elle effectue un appel à Microsoft Entra. Pour ce faire, l’application utilise le paramètre challenge_type dans ses requêtes. Ce paramètre contient des valeurs prédéfinies qui représentent différentes méthodes d’authentification.

Pour une méthode d’authentification donnée, le type de défi envoie une application à Microsoft Entra pendant le flux d’inscription est identique lorsque l’application se connecte. Par exemple, l’e-mail avec la méthode d’authentification par mot de passe utilise des valeurs de type oob, mot de passe et défi de redirection pour les flux d’inscription et de connexion.

N’hésitez pas à examiner les types de défis dans l’article types de défi d’authentification native.

Détails du protocole de flux de connexion

Le diagramme de séquence illustre le flux du processus de connexion. Le flux de connexion dépend de la méthode d’authentification de l’utilisateur.

Diagramme de la connexion d’authentification native avec un code secret à usage unique par e-mail.

Une fois que l’application a vérifié l’e-mail de l’utilisateur avec mot de passe à usage unique par e-mail, elle reçoit des jetons de sécurité. Si la remise du code secret à usage unique tarde ou si le code n’est jamais remis à l’e-mail de l’utilisateur, ce dernier peut demander de recevoir un autre code secret à usage unique. Microsoft Entra renvoie un autre code secret à usage unique si le code secret précédent n'a pas été vérifié. Lorsque Microsoft Entra renvoie un code secret unique, il invalide le code précédemment envoyé.

Dans les sections qui suivent, nous récapitulons le flux de connexion en trois étapes de base.

Étape 1 : Demande de démarrage du flux de connexion

Le flux d’authentification commence par l’application effectuant une requête POST au point de terminaison /initiate pour démarrer le flux de connexion.

Voici un exemple de la requête (nous présentons l’exemple de requête dans plusieurs lignes pour la lisibilité) :

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/initiate
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect
&username=contoso-consumer@contoso.com
&capabilities=registration_required mfa_required
Parameter Required Description
tenant_subdomain Yes Sous-domaine du tenant externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Répertoire (locataire). Par exemple, si le domaine principal de votre locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de locataire, découvrez comment lire les détails de votre locataire.
client_id Yes ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra.
username Yes E-mail de l’utilisateur client tel que contoso-consumer@contoso.com.
challenge_type Yes Une liste séparée par des espaces de chaînes de caractères de type défi d'autorisation que l'application prend en charge, telles que oob password redirect. La liste doit toujours inclure le type de défi redirect. La valeur est censée être oob redirect pour le code secret à usage unique par e-mail et password redirect pour l’e-mail avec mot de passe.
capabilities No Indicateurs séparés par l’espace qui décrivent l’état de préparation de l’application cliente. Lorsque vous définissez challenge_type quelles méthodes peuvent être contestées, capabilities indiquez à l’API d’authentification native les flux supplémentaires que l’application cliente peut gérer et quelles interfaces utilisateur peuvent afficher. Par exemple, mfa_required signifie /introspect, /challengeet /token boucle ; registration_required signifie que l’application cliente appelle les API d’inscription et affiche l’interface utilisateur d’inscription. Si la fonctionnalité nécessaire n’est pas incluse par l’application cliente, l’API retourne la redirection. Les valeurs prises en charge sont mfa_required et registration_required. En savoir plus sur les fonctionnalités.

Réponse de réussite

Voici un exemple de réponse réussie :

HTTP/1.1 200 OK
Content-Type: application/json
{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}
Propriété Description
continuation_token Jeton de continuation qui Microsoft Entra retourne.

Réponse de redirection

Si l'application cliente ne prend pas en charge la méthode d'authentification ou les fonctionnalités requises par Microsoft Entra, un flux d'authentification web est nécessaire. Dans ce scénario, Microsoft Entra informe l’application en retournant un type de défi redirect dans la réponse :

HTTP/1.1 200 OK
Content-Type: application/json

{
   "challenge_type": "redirect"
}
Propriété Description
challenge_type Microsoft Entra retourne une réponse qui a un type de défi. La valeur de ce type de défi est la redirection, ce qui permet à l’application d’utiliser le flux d’authentification web.

Cette réponse est considérée comme réussie, mais l’application est nécessaire pour basculer vers un flux d’authentification web. Dans ce cas, nous vous recommandons d’utiliser une bibliothèque d’authentification intégrée et prise en charge par Microsoft.

Réponse d’erreur

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        901007
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Propriété Description
error Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs et y répondre.
error_description Message d’erreur spécifique qui peut vous aider à identifier la cause d’une erreur d’authentification.
error_codes Liste des codes d’erreur spécifiques à Microsoft Entra qui peuvent vous aider à diagnostiquer les erreurs.
timestamp Heure à laquelle l’erreur s’est produite.
trace_id Identificateur unique de la demande qui peut vous aider à diagnostiquer les erreurs.
correlation_id Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles de la error propriété) :

une valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple lorsque le paramètre challenge_type inclut un type de défi non valide. ou la demande n’a pas inclus le paramètre client_id que la valeur de l’ID client est vide ou non valide. Utilisez le paramètre error_description pour découvrir la cause exacte de l’erreur.
unauthorized_client L’ID client utilisé dans la requête a un format d’ID client valide, mais n’existe pas dans le tenant externe ou est incorrect.
invalid_client L’ID client que l’application inclut dans la demande concerne une application qui n’a pas de configuration d’authentification native, telle qu’elle n’est pas un client public ou n’est pas activée pour l’authentification native. Utilisez la suberror propriété pour apprendre la cause exacte de l’erreur.
user_not_found Le nom d’utilisateur n’existe pas.
unsupported_challenge_type La valeur du paramètre challenge_type n’inclut pas le type de défi redirect.

Si le paramètre d’erreur a une valeur de invalid_client, Microsoft Entra inclut une propriété suberror dans sa réponse. Voici les valeurs possibles de la suberror propriété pour une erreur invalid_client :

Valeur de sous-erreur Description
nativeauthapi_disabled ID client d’une application qui n’est pas activé pour l’authentification native.

Étape 2 : Sélectionner une méthode d’authentification

Pour continuer avec le flux, l’application utilise le jeton de continuation qu’elle acquiert à partir de l’étape précédente pour demander Microsoft Entra de sélectionner l’un des types de défis pris en charge pour que l’utilisateur authentifie ou termine un défi MFA. L’application effectue une requête POST au point de terminaison /oauth2/v2.0/challenge.

Voici un exemple de la requête (nous présentons l’exemple de requête dans plusieurs lignes pour la lisibilité) :

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect
&continuation_token=uY29tL2F1dGhlbnRpY...
Parameter Required Description
tenant_subdomain Yes Sous-domaine du tenant externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Répertoire (locataire). Par exemple, si le domaine principal de votre locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de locataire, découvrez comment lire les détails de votre locataire.
client_id Yes ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra.
continuation_token Yes Jeton de continuation qui Microsoft Entra retourné dans la requête précédente. La requête précédente appelle le /oauth2/v2.0/initiate point de terminaison ou le /oauth2/v2.0/introspect point de terminaison si l’utilisateur effectue une demande MFA.
challenge_type No Une liste séparée par des espaces de chaînes de caractères de type défi d'autorisation que l'application prend en charge, telles que oob password redirect. La liste doit toujours inclure le type de défi redirect. La valeur est censée être oob redirect pour le code secret à usage unique par e-mail et password redirect pour l’e-mail avec mot de passe.
id No Identificateur de chaîne de la méthode d’authentification forte retournée par le /oauth2/v2.0/introspect point de terminaison. Ce paramètre est requis lorsque l’application cliente défie l’utilisateur pour une deuxième authentification de facteur. Découvrez comment utiliser le point de terminaison introspect.

Réponse de réussite

La réponse de réussite dépend de la méthode d’authentification de l’utilisateur.

Si l’administrateur client a configuré un code secret à usage unique dans le centre d’administration Microsoft Entra comme méthode d’authentification de l’utilisateur, Microsoft Entra envoie un code secret à usage unique à l’e-mail de l’utilisateur, puis répond avec un type de défi de oob et fournit plus d’informations sur le code secret à usage unique.

HTTP/1.1 200 OK
Content-Type: application/json
{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "challenge_type": "oob",
    "binding_method": "prompt ",
    "challenge_channel": "email",
    "challenge_target_label ": "c***r@co**o**o.com ",
    "code_length": 8
}
Propriété Description
continuation_token Jeton de continuation qui Microsoft Entra retourne.
challenge_type Type de défi sélectionné pour que l’utilisateur s’authentifie.
binding_method La seule valeur valide est invite. Ce paramètre pourra être utilisé à l’avenir pour offrir à l’utilisateur d’autres moyens d’entrer le code secret à usage unique. Émis si challenge_type est oob
challenge_channel Type du canal via lequel le code secret à usage unique a été envoyé. À l’heure actuelle, nous prenons en charge l’e-mail.
challenge_target_label E-mail obfusqué où le code secret à usage unique a été envoyé.
code_length Longueur du code secret à usage unique généré par Microsoft Entra.

Réponse de redirection

Un secours à un flux d’authentification web peut être nécessaire dans les scénarios suivants :

  • L'application cliente ne prend pas en charge la méthode d'authentification ni les fonctionnalités requises par Microsoft Entra.
  • L’utilisateur tente d’utiliser SMS comme méthode d’authentification forte, mais la protection contre les fraudes bloque la demande si elle le considère comme un risque élevé (uniquement dans l’e-mail avec l’authentification par mot de passe).

Dans ces scénarios, Microsoft Entra informe l’application en retournant un type de défi redirect dans la réponse :

HTTP/1.1 200 OK
Content-Type: application/json
{
   "challenge_type": "redirect"
}
Propriété Description
challenge_type Microsoft Entra retourne une réponse qui a un type de défi. La valeur de ce type de défi est la redirection, ce qui permet à l’application d’utiliser le flux d’authentification web.

Cette réponse est considérée comme réussie, mais l’application est nécessaire pour basculer vers un flux d’authentification web. Dans ce cas, nous vous recommandons d’utiliser une bibliothèque d’authentification intégrée et prise en charge par Microsoft.

Réponse d’erreur

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        901007
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Propriété Description
error Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs et y répondre.
error_description Message d’erreur spécifique qui peut vous aider à identifier la cause d’une erreur d’authentification.
error_codes Liste des codes d’erreur spécifiques à Microsoft Entra qui peuvent vous aider à diagnostiquer les erreurs.
timestamp Heure à laquelle l’erreur s’est produite.
trace_id Identificateur unique de la demande qui peut vous aider à diagnostiquer les erreurs.
correlation_id Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles de la error propriété) :

une valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple lorsque le paramètre challenge_type inclut un type de défi non valide.
invalid_grant Le jeton de continuation inclus dans la requête n’est pas valide.
expired_token Le jeton de continuation inclus dans la requête a expiré.
unsupported_challenge_type La valeur du paramètre challenge_type n’inclut pas le type de défi redirect.

Étape 3 : Demande de jetons de sécurité

L’application effectue une requête POST sur le oauth2/v2.0/token point de terminaison et fournit les informations d’identification de l’utilisateur choisies à l’étape précédente pour acquérir des jetons de sécurité.

Voici un exemple de la requête (nous présentons l’exemple de requête dans plusieurs lignes pour la lisibilité) :

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=password 
&password={secure_password}
&scope=openid offline_access 
Parameter Required Description
tenant_subdomain Yes Sous-domaine du tenant externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Répertoire (locataire). Par exemple, si le domaine principal de votre locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de locataire, découvrez comment lire les détails de votre locataire.
client_id Yes ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra.
continuation_token Yes Jeton de continuation qui Microsoft Entra retourné dans la requête précédente.
grant_type Yes Type d’octroi. Lorsque vous appelez le point de terminaison de jeton, cette valeur doit être :
- mot de passe pour l’e-mail avec la méthode d’authentification par mot de passe dans un flux de connexion pour vérifier l’authentification du premier facteur de l’utilisateur.
- oob pour la méthode d’authentification par code secret à usage unique par e-mail dans un flux de connexion.
- continuation_token pour la connexion automatique après un flux d’inscription.
- continuation_token pour la connexion automatique après le flux de réinitialisation de mot de passe en libre-service.
- continuation_token après un flux d’inscription de méthode d’authentification forte.
- mfa_oob lors de la vérification de l’authentification du deuxième facteur de l’utilisateur.
scope Yes Une liste d’étendues séparées par des espaces. Toutes les étendues doivent provenir d’une seule ressource, ainsi que des étendues OpenID Connect (OIDC), telles que le profil, l’openid et l’e-mail. L’application doit inclure openid étendue pour Microsoft Entra émettre un jeton d’ID. L’application doit inclure offline_access étendue pour Microsoft Entra émettre un jeton d’actualisation. En savoir plus sur les Autorisations et le consentement dans la plateforme d’identités Microsoft.
password No Valeur de mot de passe collectée par l’application auprès de l’utilisateur. Remplacez {secure_password} par la valeur de mot de passe que l’application collecte auprès de l’utilisateur. Ce paramètre est requis si la méthode d’authentification est e-mail avec mot de passe.
oob No Code secret unique que l’utilisateur reçoit par e-mail. Obligatoire si :
- La méthode d’authentification principale est un code secret à usage unique par e-mail.
- L’application envoie le code secret à usage unique de l’e-mail pour répondre à un défi MFA lorsque la méthode d’authentification principale est e-mail avec mot de passe.
Pour renvoyer un code secret à usage unique, appelez à nouveau le /challenge point de terminaison.
username No E-mail de l’utilisateur avec lequel il souhaite s’inscrire, par contoso-consumer@contoso.comexemple . Ce paramètre est requis dans un flux d’inscription.

Réponse réussie

Voici un exemple de réponse réussie :

HTTP/1.1 200 OK
Content-Type: application/json
{
    "token_type": "Bearer",
    "scope": "openid profile",
    "expires_in": 4141,
    "access_token": "eyJ0eXAiOiJKV1Qi...",
    "refresh_token": "AwABAAAA...",
    "id_token": "eyJ0eXAiOiJKV1Q..."
}
Propriété Description
token_type Indique la valeur du type de jeton. Le seul type pris en charge par Microsoft Entra est Bearer.
scopes Liste d’étendues séparées par un espace pour laquelle le jeton d’accès est valide.
expires_in Durée en secondes pendant laquelle le jeton d’accès reste valide.
access_token Jeton d’accès demandé par l’application à partir du point de terminaison /token. L’application peut utiliser ce jeton d’accès pour demander l’accès aux ressources sécurisées telles que les API web.
refresh_token Un jeton d’actualisation OAuth 2.0. L’application peut utiliser ce jeton pour acquérir des jetons d’accès supplémentaires après l’expiration du jeton d’accès actuel. Les jetons d’actualisation sont de longue durée. Ils peuvent conserver l’accès aux ressources pendant des périodes prolongées. Pour plus d’informations sur l’actualisation d’un jeton d’accès, consultez Actualiser le jeton d’accès.
Remarque : émis uniquement si vous demandez offline_access étendue.
id_token Jeton web JSON (Jwt) utilisé pour identifier l’utilisateur. L’application peut décoder le jeton pour demander des informations sur l’utilisateur qui s’est connecté. L’application peut mettre en cache les valeurs et les afficher. Les clients confidentiels peuvent utiliser ce jeton pour obtenir une autorisation. Pour plus d’informations sur les jetons d’ID, consultez les jetons d’ID dans la plateforme d’identités Microsoft.
Remarque : émis uniquement si vous demandez une étendue openid .

Réponse d’erreur

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{ 
    "error": "invalid_grant", 
    "error_description": "AADSTS901007: Error validating credentials due to invalid username or password.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 
Propriété Description
error Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs et réagir aux erreurs.
error_description Message d’erreur spécifique qui peut vous aider à identifier la cause d’une erreur d’authentification.
error_codes Liste des codes d’erreur spécifiques à Microsoft Entra qui peuvent vous aider à diagnostiquer les erreurs.
timestamp Heure à laquelle l’erreur s’est produite.
trace_id Identificateur unique de la demande qui peut vous aider à diagnostiquer les erreurs.
correlation_id Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles de la error propriété) :

une valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête. Pour comprendre ce qui s’est passé, utilisez le message dans la description de l’erreur.
invalid_grant Le jeton de continuation inclus dans la requête n’est pas valide, les informations d’identification de connexion de l’utilisateur incluses dans la demande ne sont pas valides, une interaction supplémentaire requise à partir de l’utilisateur ou le type d’octroi inclus dans la demande est inconnu.
invalid_client L’ID client inclus dans la requête n’est pas destiné à un client public.
expired_token Le jeton de continuation inclus dans la requête a expiré.
invalid_scope Une ou plusieurs des étendues incluses dans la demande ne sont pas valides.
unauthorized_client L’ID client inclus dans la requête n’est pas valide ou n’existe pas.
unsupported_grant_type Le type d’octroi inclus dans la demande n’est pas pris en charge ou est incorrect.

Si le paramètre d’erreur a une valeur de invalid_grant, Microsoft Entra inclut une propriété suberror dans sa réponse. Voici les valeurs possibles de la suberror propriété pour une erreur invalid_grant :

Valeur de sous-erreur Description
invalid_oob_value La valeur du code secret unique envoyé par l’application n’est pas valide.
mfa_required L’authentification multifacteur est requise. La réponse inclut un jeton de continuation. Appelez le oauth2/v2.0/introspect point de terminaison pour obtenir les méthodes d’authentification forte inscrites de l’utilisateur. Cette sous-erreur se produit uniquement lorsque la méthode d’authentification principale de l’utilisateur est e-mail avec mot de passe. Découvrez comment obtenir les méthodes d’authentification forte inscrites d’un utilisateur.

Remarque : Dans certains cas, l’authentification multifacteur est requise, mais l’authentification native ne retourne mfa_requiredpas . ou, par exemple, si un flux d’inscription de méthode d’authentification forte précède un appel à l’utilisateur /oauth2/v2.0/token et que la seule méthode disponible (e-mail) a déjà été vérifiée pendant ce flux.
registration_required L’utilisateur doit effectuer un défi MFA, mais n’a pas de méthode d’authentification forte inscrite. Invitez l’utilisateur à en inscrire un. Cette erreur se produit lorsque la méthode d’authentification principale de l’utilisateur est e-mail avec mot de passe. Découvrez comment inscrire une méthode d’authentification forte.

Réponse de redirection

Si l'application cliente ne prend pas en charge la méthode d'authentification ou la fonctionnalité requise par Microsoft Entra, un flux d'authentification basé sur le web est nécessaire. Dans ce scénario, Microsoft Entra informe l’application en retournant un type de défi redirect dans sa réponse :

HTTP/1.1 200 OK
Content-Type: application/json
{     
    "challenge_type": "redirect",
    "redirect_reason": "Client is missing registration_required capability"
} 
Propriété Description
challenge_type Microsoft Entra retourne une réponse qui a un type de défi. La valeur de ce type de défi est la redirection, ce qui permet à l’application d’utiliser le flux d’authentification web.
redirect_reason Raison pour laquelle une redirection est requise. Par exemple, Microsoft Entra détecte que l'authentification multifacteur ou une inscription pour une méthode d'authentification forte est requise, mais l'application n'a pas inclus ces fonctionnalités dans sa demande.

Cette réponse est considérée comme réussie, mais l’application est nécessaire pour basculer vers un flux d’authentification web. Dans ce cas, nous vous recommandons d’utiliser une bibliothèque d’authentification intégrée et prise en charge par Microsoft.

Obtenir des méthodes d’authentification forte inscrites par l’utilisateur

Utilisez le oauth2/v2.0/introspect point de terminaison pour demander la liste des méthodes d’authentification forte enregistrées par l’utilisateur.

Voici un exemple de la requête (nous présentons l’exemple de requête dans plusieurs lignes pour la lisibilité) :

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/introspect
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
Parameter Required Description
tenant_subdomain Yes Sous-domaine du tenant externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Répertoire (locataire). Par exemple, si le domaine principal de votre locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de locataire, découvrez comment lire les détails de votre locataire.
client_id Yes ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra.
continuation_token Yes Jeton de continuation qui Microsoft Entra retourné dans la requête précédente.

Réponse de réussite

Example:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "methods":[
        {
            "id":"0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c",
            "challenge_type":"oob",
            "challenge_channel":"email",
            "login_hint":"c***r@co**o**o.com"
        },
        {
          "id": "1b1b1b1b-2222-cccc-3333-4d4d4d4d4d4d",
          "challenge_type": "oob",
          "challenge_channel": "sms",
          "login_hint": "+1********6"
        }
    ]
}
Propriété Description
continuation_token Jeton de continuation qui Microsoft Entra retourne.
methods Liste (d’objets) des méthodes d’authentification forte inscrites par l’utilisateur.

L’objet de méthode MFA a les propriétés suivantes :

Propriété Description
id Identificateur de chaîne unique généré automatiquement pour la méthode MFA. L’application utilise cette chaîne comme id lorsqu’elle appelle le /oauth2/v2.0/challenge point de terminaison.
challenge_type Type de défi sélectionné pour que l’utilisateur utilise comme méthode MFA. Le type de défi pris en charge actuel est oob.
challenge_channel Type du canal auquel la méthode MFA est envoyée. Le canal de défi pris en charge actuel est l’e-mail.
login_hint Indicateur de la méthode d’authentification forte telle qu’un e-mail obfusqué.

Réponse de redirection

Si l'application cliente ne prend pas en charge la méthode d'authentification ou les fonctionnalités requises par Microsoft Entra, un flux d'authentification web est nécessaire. Dans ce scénario, Microsoft Entra informe l’application en retournant un type de défi redirect dans la réponse :

HTTP/1.1 200 OK
Content-Type: application/json
{
   "challenge_type": "redirect"
}

Réponse d’erreur

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS901007: The continuation_token provided is not valid for this endpoint.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        50126
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Propriété Description
error Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs et y répondre.
error_description Message d’erreur spécifique qui peut vous aider à identifier la cause d’une erreur d’authentification.
error_codes Liste des codes d’erreur spécifiques à Microsoft Entra qui peuvent vous aider à diagnostiquer les erreurs.
timestamp Heure à laquelle l’erreur s’est produite.
trace_id Identificateur unique de la demande qui peut vous aider à diagnostiquer les erreurs.
correlation_id Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles de la error propriété) :

une valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête. Pour comprendre ce qui s’est passé, utilisez le message dans la description de l’erreur.
invalid_client L’ID client inclus dans la requête n’est pas destiné à un client public.
expired_token Le jeton de continuation inclus dans la requête a expiré.
server_error Un problème s’est produit avec la demande.

Une fois l’application cliente récupérée avec succès une liste de méthodes d’authentification forte inscrites pour l’utilisateur, l’utilisateur sélectionne une méthode qu’il souhaite utiliser pour effectuer le défi MFA. Le flux se poursuit ensuite comme suit :

  1. L’application cliente appelle et /oauth2/v2.0/challenge inclut le jeton de continuation obtenu à partir de la /oauth2/v2.0/introspectid méthode MFA de votre choix :

    POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/challenge
    Content-Type: application/x-www-form-urlencoded
    client_id=00001111-aaaa-2222-bbbb-3333cccc4444
    &id=0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c
    &continuation_token=uY29tL2F1dGhlbnRpY...
    
  2. Microsoft Entra envoie un code de défi au canal de défi de l'utilisateur, tel que l'e-mail, puis répond à l'application cliente avec un jeton de continuation et les détails du défi MFA :

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "continuation_token": "uY29tL2F1dGhlbnRpY...",
        "challenge_type": "oob",
        "binding_method": "prompt ",
        "challenge_channel": "email",
        "challenge_target_label ": "c***r@co**o**o.com ",
        "code_length": 8
    }
    
  3. L’application peut désormais effectuer une requête POST au /oauth2/v2.0/token point de terminaison et inclut un jeton de continuation, un type d’octroi correct et des valeurs de type d’octroi correspondantes pour obtenir des jetons de sécurité. Consultez la réponse attendue dans La demande de jetons de sécurité :

    POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
    Content-Type: application/x-www-form-urlencoded
    client_id=00001111-aaaa-2222-bbbb-3333cccc4444
    &continuation_token=uY29tL2F1dGhlbnRpY...
    &grant_type=mfa_oob
    &oob={otp_code}
    &scope=openid offline_access
    

Inscrire une référence d’API de méthode d’authentification forte

L’authentification native prend en charge l’inscription de la méthode d’authentification forte. Lorsque l’application appelle le point de terminaison /oauth2/v2.0/token et que l’authentification multifacteur est requise, mais que l’utilisateur n’a pas de méthode forte inscrite, la réponse, registration_required, indique à l’application d’en inscrire un avant que les jetons puissent être émis.

Une fois que l’application cliente a terminé le flux pour inscrire une méthode d’authentification forte, il appelle le /oauth2/v2.0/token point de terminaison pour demander des jetons de sécurité.

Points de terminaison d’inscription de méthode d’authentification forte

Pour utiliser l’API d’inscription de méthode d’authentification forte, l’application utilise le point de terminaison indiqué dans le tableau suivant :

Point de terminaison Description
/register/v1.0/introspect Appelez ce point de terminaison pour récupérer la liste des méthodes d’authentification fortes que l’utilisateur peut inscrire.
/register/v1.0/challenge Appelez ce point de terminaison pour envoyer le défi à l’utilisateur, tel que le code secret à usage unique par e-mail.
/register/v1.0/continue Appelez ce point de terminaison pour soumettre le défi que l’application collecte auprès de l’utilisateur, comme le code secret unique, pour terminer un flux pour inscrire une méthode d’authentification forte. Une fois l’appel réussi et que vous obtenez un jeton de continuation, appelez le point de terminaison de /oauth2/v2.0/token point de terminaison pour demander des jetons de sécurité. Découvrez comment appeler le point de terminaison de jeton.

Étape 1 : Obtenir la liste des méthodes d’authentification forte

Le flux d’inscription commence lorsque l’application demande la liste des méthodes d’authentification forte que l’utilisateur est autorisé à inscrire.

Voici un exemple de la requête (nous présentons l’exemple de requête dans plusieurs lignes pour la lisibilité) :

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/introspect
Content-Type: application/x-www-form-urlencoded
?continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
Parameter Required Description
tenant_subdomain Yes Sous-domaine du tenant externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Répertoire (locataire). Par exemple, si le domaine principal de votre locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de locataire, découvrez comment lire les détails de votre locataire.
client_id Yes ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra.

Réponse de réussite

Voici un exemple de réponse réussie :

HTTP/1.1 200 OK
Content-Type: application/json
{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "methods":[
        {
            "id":"email",
            "challenge_type":"oob",
            "challenge_channel":"email",
            "login_hint":"caseyjensen@contoso.com"
        },
        {
          "id": "sms",
          "challenge_type": "oob",
          "challenge_channel": "sms"
        }
    ]
}
Propriété Description
continuation_token Jeton de continuation qui Microsoft Entra retourne.
methods Liste (d’objets) des méthodes d’authentification fortes disponibles pour l’utilisateur à inscrire.

L’objet méthodes d’authentification forte a les propriétés suivantes :

Propriété Description
id Clé de chaîne de la méthode. Valeurs prises en charge par e-mail, sms.
challenge_type Type de défi sélectionné pour que l’utilisateur utilise comme méthode MFA. Le type de défi pris en charge actuel est oob.
challenge_channel Type du canal auquel la méthode MFA est envoyée. Valeurs prises en charge par e-mail, sms.
login_hint Indicateur de la méthode d’authentification forte telle qu’un e-mail. Cette valeur est utilisée par l’application cliente pour préremplir la zone de texte de l’e-mail.

Réponse d’erreur

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS901007: The continuation_token provided is not valid for this endpoint.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        50126
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Propriété Description
error Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs et y répondre.
error_description Message d’erreur spécifique qui peut vous aider à identifier la cause d’une erreur d’authentification.
error_codes Liste des codes d’erreur spécifiques à Microsoft Entra qui peuvent vous aider à diagnostiquer les erreurs.
timestamp Heure à laquelle l’erreur s’est produite.
trace_id Identificateur unique de la demande qui peut vous aider à diagnostiquer les erreurs.
correlation_id Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles de la error propriété) :

une valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple une validation de jeton de continuation a échoué ou la demande n’a pas inclus le paramètre client_id, la valeur de l’ID client est vide ou non valide ou l’administrateur client externe n’a pas activé le mot de passe à usage unique par e-mail pour tous les utilisateurs du tenant.
expired_token Le jeton de continuation inclus dans la requête a expiré.

Étape 2 : Sélectionner une méthode d’authentification forte

Dans cette étape, envoyez la méthode d’authentification forte que l’utilisateur souhaite inscrire. Microsoft Entra envoyez ensuite un défi, tel que le code secret à usage unique de l’e-mail, à l’utilisateur.

Voici un exemple de la requête (nous présentons l’exemple de requête dans plusieurs lignes pour la lisibilité) :

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/challenge

?continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob
&challenge_channel=email
&challenge_target=contoso-consumer@contoso.com
Parameter Required Description
tenant_subdomain Yes Sous-domaine du tenant externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Répertoire (locataire). Par exemple, si le domaine principal de votre locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de locataire, découvrez comment lire les détails de votre locataire.
client_id Yes ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra.
continuation_token Yes Jeton Continuation qui Microsoft Entra retourne à partir du point de terminaison /register/v1.0/introspect
challenge_type Yes Type de défi de la méthode d’authentification. Le type actuel est oob.
challenge_target Yes Numéro de téléphone ou e-mail que l’utilisateur souhaite inscrire.
challenge_channel No Canal sur lequel envoyer le défi. Valeurs de canal de défi prises en charge : e-mail, sms.

Réponse de réussite

Voici un exemple de réponse réussie.

Exemple 1 :

HTTP/1.1 200 OK
Content-Type: application/json
{
  "continuation_token": "uY29tL2F1dGhlbnRpY...",
  "challenge_type": "oob",
  "binding_method": "prompt",
  "challenge_target": "contoso-consumer@contoso.com",
  "challenge_channel": "email",
  "code_length": 8
}

Exemple 2 :

Si le flux d’inscription précède le flux d’inscription de méthode d’authentification forte et que l’e-mail envoyé au /register/v1.0/challenge point de terminaison correspond à celui vérifié dans le flux d’inscription, l’API d’authentification native inscrit la méthode sans envoyer de défi à l’utilisateur. Dans ce cas, la réponse ressemble à l’extrait de code suivant :

HTTP/1.1 200 OK
Content-Type: application/json
{
  "continuation_token": "uY29tL2F1dGhlbnRpY...",
  "challenge_type": "preverified"
}
Propriété Description
continuation_token Jeton de continuation qui Microsoft Entra retourne.
challenge_type Type de défi sélectionné pour que l’utilisateur s’authentifie, par exemple oob ou préverifié si la méthode d’authentification forte est préverifiée.
binding_method La seule valeur valide est invite. Ce paramètre peut être utilisé à l’avenir pour offrir davantage de moyens à l’utilisateur d’entrer le code secret à usage unique. Émis s’il challenge_type s’agit d’oob et que la méthode d’authentification forte n’est pas préverifiée.
challenge_channel Type du canal via lequel le code secret à usage unique a été envoyé. Valeurs prises en charge par e-mail, sms. Retourné si la méthode d’authentification forte n’est pas préverifiée.
code_length Durée du code secret à usage unique si binding_method vous y êtes invité. Retourné si la méthode d’authentification forte n’est pas préverifiée.
challenge_target La cible du défi a été envoyée. Il s’agit de la même entrée fournie dans la demande. Retourné si la méthode d’authentification forte n’est pas préverifiée.
interval Intervalle (en secondes) que le client doit attendre entre l’interrogation de /register/continue. Retourné uniquement si prompt=none et la méthode d’authentification forte n’est pas préverifiée. Les clients doivent doubler l’intervalle chaque fois qu’ils reçoivent une HTTP 429 de l’API d’authentification native.

Réponse d’erreur

Les erreurs ici sont similaires à celles que vous pouvez rencontrer lorsque vous appelez le /register/v1.0/introspect point de terminaison. Toutefois, lors de l’inscription du numéro de téléphone, si le numéro de téléphone est considéré comme à haut risque, la demande peut être bloquée.

Voici les erreurs possibles que vous pouvez rencontrer si la demande est bloquée :

une valeur d’erreur Description
access_denied Sms a été bloqué.

Si le paramètre d’erreur a une valeur de access_denied, Microsoft Entra inclut une propriété de sous-erreur dans sa réponse. Voici les valeurs possibles de la propriété suberror pour une erreur invalid_grant :

Valeur de sous-erreur Description
provider_blocked_by_admin L’administrateur client a bloqué la région du téléphone.
provider_blocked_by_rep La méthode d’authentification multifacteur est bloquée (le numéro de téléphone a été bloqué par RepMap).

Étape 3 : Soumettre un défi

Dans cette étape, appelez le /register/v1.0/continue point de terminaison pour terminer l’inscription de la méthode d’authentification forte.

Voici un exemple de la requête (nous présentons l’exemple de requête dans plusieurs lignes pour la lisibilité) :

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/continue

?continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=oob
&oob={otp_code}
Parameter Required Description
tenant_subdomain Yes Sous-domaine du tenant externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Répertoire (locataire). Par exemple, si le domaine principal de votre locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de locataire, découvrez comment lire les détails de votre locataire.
continuation_token Yes Jeton de continuation qui Microsoft Entra retourné dans la requête précédente.
client_id Yes ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra.
grant_type Yes Type d’octroi. La valeur prise en charge actuelle est oob ou continuation_token si la méthode d’authentification forte est préverifiée dans le /register/v1.0/challenge point de terminaison.
oob No Code secret à usage unique reçu par l’utilisateur client dans son e-mail. Remplacez {otp_code} par les valeurs de code secret à usage unique reçu par l’utilisateur client dans son e-mail. Pour renvoyer un code secret à usage unique, l’application doit à nouveau envoyer une requête au point de terminaison /register/v1.0/challenge. Obligatoire si la méthode d’authentification forte n’est pas préverifiée dans le /register/v1.0/challenge point de terminaison.

Réponse de réussite

Voici un exemple de réponse réussie :

HTTP/1.1 200 OK
Content-Type: application/json
{
  "continuation_token": "uY29tL2F1dGhlbnRpY..."
}
Propriété Description
continuation_token Jeton de continuation qui Microsoft Entra retourne. Utilisez ce jeton de continuation pour appeler le /oauth2/v2.0/token point de terminaison pour demander des jetons de sécurité. Découvrez comment appeler le point de terminaison de jeton.

Réponse d’erreur

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS55200: The continuation_token is invalid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        55200
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Propriété Description
error Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs et y répondre.
error_description Message d’erreur spécifique qui peut vous aider à identifier la cause d’une erreur d’authentification.
error_codes Liste des codes d’erreur spécifiques à Microsoft Entra qui peuvent vous aider à diagnostiquer les erreurs.
timestamp Heure à laquelle l’erreur s’est produite.
trace_id Identificateur unique de la demande qui peut vous aider à diagnostiquer les erreurs.
correlation_id Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles de la error propriété) :

une valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple une validation de jeton de continuation a échoué ou la demande n’a pas inclus le paramètre client_id, la valeur de l’ID client est vide ou non valide ou l’administrateur client externe n’a pas activé le mot de passe à usage unique par e-mail pour tous les utilisateurs du tenant.
invalid_grant Le type d’octroi inclus dans la requête n’est pas valide ou pris en charge, ou la valeur OTP est incorrecte.
expired_token Le jeton de continuation inclus dans la requête a expiré.

Si le paramètre d’erreur a une valeur de invalid_grant, Microsoft Entra inclut une propriété suberror dans sa réponse. Voici les valeurs possibles de la suberror propriété pour une erreur invalid_grant :

Valeur de sous-erreur Description
invalid_oob_value La valeur du code secret à usage unique n’est pas valide.

Réinitialisation de mot de passe en libre-service (SSPR)

Pour les utilisateurs dont la méthode d’authentification principale est e-mail avec mot de passe, utilisez l’API de réinitialisation de mot de passe en libre-service (SSPR) pour permettre aux utilisateurs clients de réinitialiser leur mot de passe. Vous pouvez utiliser cette API pour les scénarios de mot de passe oubliés ou modifier le mot de passe.

Points de terminaison API pour la réinitialisation du mot de passe en libre-service

Pour utiliser cette API, l’application utilise le point de terminaison indiqué dans le tableau suivant :

Point de terminaison Description
/resetpassword/v1.0/start Votre application appelle ce point de terminaison lorsque l’utilisateur client sélectionne le lien ou le bouton Mot de passe oublié ou Modifier le mot de passe dans l’application. Ce point de terminaison valide le nom d’utilisateur (e-mail), puis retourne un jeton de continuation à utiliser dans le flux de réinitialisation de mot de passe. Si votre application demande d'utiliser des méthodes d'authentification qui ne sont pas prises en charge par Microsoft Entra, cette réponse de point de terminaison peut indiquer à votre application qu'elle doit utiliser un flux d'authentification basé sur un navigateur.
/resetpassword/v1.0/challenge Accepte une liste de types de défis pris en charge par le client et le jeton de continuation. Un défi est émis à l’une des informations d’identification de récupération préférées. Par exemple, oob challenge émet un code secret hors bande unique pour l’e-mail associé au compte d’utilisateur client. Si votre application demande d'utiliser des méthodes d'authentification qui ne sont pas prises en charge par Microsoft Entra, cette réponse de point de terminaison peut indiquer à votre application qu'elle doit utiliser un flux d'authentification basé sur un navigateur.
/resetpassword/v1.0/continue Valide le défi émis par le point de terminaison /resetpassword/v1.0/challenge, puis retourne un jeton de continuation pour le point de terminaison /resetpassword/v1.0/submit, ou émet un autre défi à l’utilisateur.
/resetpassword/v1.0/submit Accepte une nouvelle entrée de mot de passe par l’utilisateur, ainsi que le jeton de continuation pour terminer le flux de réinitialisation du mot de passe. Ce point de terminaison émet un autre jeton de continuation.
/resetpassword/v1.0/poll_completion L’application peut utiliser le jeton de continuation émis par le /resetpassword/v1.0/submit point de terminaison pour vérifier l’état de la demande de réinitialisation de mot de passe.
oauth2/v2.0/token Si la réinitialisation du mot de passe réussit, l’application peut utiliser le jeton de continuation qu’elle obtient auprès du /resetpassword/v1.0/poll_completion point de terminaison pour obtenir des jetons de sécurité à partir du oauth2/v2.0/token point de terminaison.

Types de défis de réinitialisation de mot de passe en libre-service

L’API permet à l’application de publier les méthodes d’authentification qu’elle prend en charge, lorsqu’elle effectue un appel à Microsoft Entra. Pour ce faire, l’application utilise le paramètre challenge_type dans ses requêtes. Ce paramètre contient des valeurs prédéfinies qui représentent différentes méthodes d’authentification.

Pour le flux SSPR, les valeurs du type de défi sont oob et rediriger.

En savoir plus sur les types de défis dans les types de défi d’authentification native.

Détails du protocole de flux de réinitialisation de mot de passe en libre-service

Le diagramme de séquence illustre le flux du processus de réinitialisation de mot de passe.

Diagramme du flux de réinitialisation de mot de passe en libre-service d’authentification native.

Ce diagramme indique que l’application collecte le nom d’utilisateur (e-mail) et le mot de passe de l’utilisateur à différents moments (et éventuellement sur des écrans distincts). Toutefois, vous pouvez concevoir votre application pour collecter le nom d’utilisateur (e-mail) et le nouveau mot de passe sur le même écran. Dans ce cas, l’application contient le mot de passe, puis l’envoie via le point de terminaison /resetpassword/v1.0/submit où elle est requise.

Étape 1 : Demande de démarrage du flux de réinitialisation de mot de passe en libre-service

Le flux de réinitialisation de mot de passe commence par l’application effectuant une requête POST au point de terminaison /resetpassword/v1.0/start pour démarrer le flux de réinitialisation de mot de passe en libre-service.

Voici un exemple de la requête (nous présentons l’exemple de requête dans plusieurs lignes pour la lisibilité) :

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/start
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&username=contoso-consumer@contoso.com
Parameter Required Description
tenant_subdomain Yes Sous-domaine du tenant externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Répertoire (locataire). Par exemple, si le domaine principal de votre locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de locataire, découvrez comment lire les détails de votre locataire.
client_id Yes ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra.
username Yes E-mail de l’utilisateur client tel que contoso-consumer@contoso.com.
challenge_type Yes Une liste séparée par des espaces de chaînes de caractères de type défi d'autorisation que l'application prend en charge, telles que oob password redirect. La liste doit toujours inclure le type de défi redirect. Pour cette requête, la valeur doit contenir oob redirect.
capabilities No Indicateurs séparés par l’espace qui décrivent l’état de préparation de l’application cliente. Lorsque vous définissez challenge_type quelles méthodes peuvent être contestées, capabilities indiquez à l’API d’authentification native les flux supplémentaires que l’application cliente peut gérer et quelles interfaces utilisateur peuvent afficher. Par exemple, mfa_required signifie une autre /challenge boucle /token  ; registration_required signifie que l’application cliente appelle les API d’inscription et affiche l’interface utilisateur d’inscription. Si une fonctionnalité requise n’est pas publiée par l’application cliente, l’API retourne la redirection. Les valeurs prises en charge sont mfa_required et registration_required. En savoir plus sur les fonctionnalités.

Réponse de réussite

Example:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}
Propriété Description
continuation_token Jeton de continuation qui Microsoft Entra retourne.

Réponse de redirection

Si l'application cliente ne prend pas en charge la méthode d'authentification ou les fonctionnalités requises par Microsoft Entra, un flux d'authentification web est nécessaire. Dans ce scénario, Microsoft Entra informe l’application en retournant un type de défi redirect dans la réponse :

HTTP/1.1 200 OK
Content-Type: application/json
{
   "challenge_type": "redirect"
}
Propriété Description
challenge_type Microsoft Entra retourne une réponse qui a un type de défi. La valeur de ce type de défi est la redirection, ce qui permet à l’application d’utiliser le flux d’authentification web.

Cette réponse est considérée comme réussie, mais l’application est nécessaire pour basculer vers un flux d’authentification web. Dans ce cas, nous vous recommandons d’utiliser une bibliothèque d’authentification intégrée et prise en charge par Microsoft.

Réponse d’erreur

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        901007
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Propriété Description
error Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs et y répondre.
error_description Message d’erreur spécifique qui peut vous aider à identifier la cause d’une erreur d’authentification.
error_codes Liste des codes d’erreur spécifiques à Microsoft Entra qui peuvent vous aider à diagnostiquer les erreurs.
timestamp Heure à laquelle l’erreur s’est produite.
trace_id Identificateur unique de la demande qui peut vous aider à diagnostiquer les erreurs.
correlation_id Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles de la error propriété) :

une valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple lorsque le paramètre challenge_type inclut un type de défi non valide ou que la requête n’a pas inclus le paramètre client_id que la valeur de l’ID client est vide ou non valide. Utilisez le paramètre error_description pour découvrir la cause exacte de l’erreur.
user_not_found Le nom d’utilisateur n’existe pas.
unsupported_challenge_type La valeur du paramètre challenge_type n’inclut pas le type de défi redirect.
invalid_client L’ID client que l’application inclut dans la demande concerne une application qui n’a pas de configuration d’authentification native, telle qu’elle n’est pas un client public ou n’est pas activée pour l’authentification native. Utilisez la suberror propriété pour apprendre la cause exacte de l’erreur.
unauthorized_client L’ID client utilisé dans la requête a un format d’ID client valide, mais n’existe pas dans le tenant externe ou est incorrect.

Si le paramètre d’erreur a une valeur de invalid_client, Microsoft Entra inclut une propriété suberror dans sa réponse. Voici les valeurs possibles de la suberror propriété pour une erreur invalid_client :

Valeur de sous-erreur Description
nativeauthapi_disabled ID client d’une application qui n’est pas activée pour l’authentification native.

Étape 2 : Sélectionner une méthode d’authentification

Pour continuer avec le flux, l’application utilise le jeton de continuation acquis à l’étape précédente pour demander Microsoft Entra de sélectionner l’un des types de défis pris en charge pour que l’utilisateur s’authentifie. L’application effectue une requête POST au point de terminaison /resetpassword/v1.0/challenge. Si cette demande réussit, Microsoft Entra envoie un code secret unique à l'e-mail du compte de l'utilisateur. Pour le moment, nous prenons uniquement en charge le protocole OTP par e-mail.

Voici un exemple (nous présentons l’exemple de requête dans plusieurs lignes pour la lisibilité) :

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&continuation_token=uY29tL2F1dGhlbnRpY...
Parameter Required Description
tenant_subdomain Yes Sous-domaine du tenant externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Répertoire (locataire). Par exemple, si le domaine principal de votre locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de locataire, découvrez comment lire les détails de votre locataire.
client_id Yes ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra.
continuation_token Yes Jeton de continuation qui Microsoft Entra retourné dans la requête précédente.
challenge_type No Une liste séparée par des espaces de chaînes de caractères de type défi d'autorisation que l'application prend en charge, telles que oob redirect. La liste doit toujours inclure le type de défi redirect. Pour cette requête, la valeur doit contenir oob redirect.

Réponse de réussite

Example:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "challenge_type": "oob",
    "binding_method": "prompt ",
    "challenge_channel": "email",
    "challenge_target_label ": "c***r@co**o**o.com ",
    "code_length": 8
}
Propriété Description
continuation_token Jeton de continuation qui Microsoft Entra retourne.
challenge_type Type de défi sélectionné pour que l’utilisateur s’authentifie.
binding_method La seule valeur valide est invite. Ce paramètre peut être utilisé à l’avenir pour offrir davantage de moyens à l’utilisateur d’entrer le code secret à usage unique. Émis si challenge_type est oob
challenge_channel Type du canal via lequel le code secret à usage unique a été envoyé. À l’heure actuelle, nous prenons en charge l’e-mail.
challenge_target_label E-mail obfusqué où le code secret à usage unique a été envoyé. Si l’authentification multifacteur est activée pour l’utilisateur, l’e-mail contenant le code secret à usage unique est envoyé à l’adresse suivante :
: adresse e-mail utilisée comme méthode d’authentification forte lorsque l’adresse e-mail est différente de l’adresse e-mail du compte.
: adresse e-mail du compte lorsque la méthode d’authentification forte est SMS.
code_length Longueur du code secret à usage unique généré par Microsoft Entra.

Réponse de redirection

Si l'application cliente ne prend pas en charge la méthode d'authentification ou les fonctionnalités requises par Microsoft Entra, un flux d'authentification web est nécessaire. Dans ce scénario, Microsoft Entra informe l’application en retournant un type de défi redirect dans la réponse :

HTTP/1.1 200 OK
Content-Type: application/json
{
   "challenge_type": "redirect"
}
Propriété Description
challenge_type Microsoft Entra retourne une réponse qui a un type de défi. La valeur de ce type de défi est la redirection, ce qui permet à l’application d’utiliser le flux d’authentification web.

Cette réponse est considérée comme réussie, mais l’application est nécessaire pour basculer vers un flux d’authentification web. Dans ce cas, nous vous recommandons d’utiliser une bibliothèque d’authentification intégrée et prise en charge par Microsoft.

Réponse d’erreur

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        901007
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Propriété Description
error Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs et y répondre.
error_description Message d’erreur spécifique qui peut vous aider à identifier la cause d’une erreur d’authentification.
error_codes Liste des codes d’erreur spécifiques à Microsoft Entra qui peuvent vous aider à diagnostiquer les erreurs.
timestamp Heure à laquelle l’erreur s’est produite.
trace_id Identificateur unique de la demande qui peut vous aider à diagnostiquer les erreurs.
correlation_id Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles de la error propriété) :

une valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple lorsque le paramètre challenge_type inclut un type de défi non valide ou que la validation jeton de continuation a échoué.
expired_token Le jeton de continuation a expiré.
unsupported_challenge_type La valeur du paramètre challenge_type n’inclut pas le type de défi redirect.

Étape 3 : Envoyer un code secret à usage unique

L’application effectue ensuite une requête POST au point de terminaison /resetpassword/v1.0/continue. Dans la demande, l’application doit inclure les informations d’identification de l’utilisateur choisies à l’étape précédente et le jeton de continuation émis à partir du point de terminaison /resetpassword/v1.0/challenge.

Voici un exemple de la requête (nous présentons l’exemple de requête dans plusieurs lignes pour la lisibilité) :

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/continue
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=oob
&oob={otp_code}
Parameter Required Description
tenant_subdomain Yes Sous-domaine du tenant externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Répertoire (locataire). Par exemple, si le domaine principal de votre locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de locataire, découvrez comment lire les détails de votre locataire.
continuation_token Yes Jeton de continuation qui Microsoft Entra retourné dans la requête précédente.
client_id Yes ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra.
grant_type Yes La seule valeur valide est oob.
oob Yes Code secret à usage unique reçu par l’utilisateur client dans son e-mail. Remplacez {otp_code} par le code secret à usage unique reçu par l’utilisateur client dans son e-mail. Pour renvoyer un code secret à usage unique, l’application doit à nouveau envoyer une requête au point de terminaison /resetpassword/v1.0/challenge.

Réponse de réussite

Example:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "expires_in": 600,
    "continuation_token": "czZCaGRSa3F0MzpnW..."
}
Propriété Description
expires_in Durée en secondes avant l’expiration du continuation_token. La valeur maximale de expires_in est 600 secondes.
continuation_token Jeton de continuation qui Microsoft Entra retourne.

Réponse d’erreur

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS55200: The continuation_token is invalid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        55200
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Propriété Description
error Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs et y répondre.
error_description Message d’erreur spécifique qui peut vous aider à identifier la cause d’une erreur d’authentification.
error_codes Liste des codes d’erreur spécifiques à Microsoft Entra qui peuvent vous aider à diagnostiquer les erreurs.
timestamp Heure à laquelle l’erreur s’est produite.
trace_id Identificateur unique de la demande qui peut vous aider à diagnostiquer les erreurs.
correlation_id Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants.
suberror Chaîne de code d’erreur qui peut être utilisée pour classifier davantage les types d’erreurs.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles de la error propriété) :

une valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple une validation de jeton de continuation a échoué ou la demande n’a pas inclus le paramètre client_id, la valeur de l’ID client est vide ou non valide ou l’administrateur client externe n’a pas activé la réinitialisation de mot de passe en libre-service et le mot de passe à usage unique par e-mail pour tous les utilisateurs du tenant. Utilisez le paramètre error_description pour découvrir la cause exacte de l’erreur.
invalid_grant Le type d’octroi est inconnu ou ne correspond pas à la valeur de type d’octroi attendue. Utilisez la suberror propriété pour apprendre la cause exacte de l’erreur.
expired_token Le jeton de continuation a expiré.

Si le paramètre d’erreur a une valeur de invalid_grant, Microsoft Entra inclut une propriété suberror dans sa réponse. Voici les valeurs possibles de la suberror propriété pour une erreur invalid_grant :

Valeur de sous-erreur Description
invalid_oob_value La valeur du code secret à usage unique n’est pas valide.

Étape 4 : Envoyer un nouveau mot de passe

L’application collecte un nouveau mot de passe auprès de l’utilisateur, puis utilise le jeton de continuation émis par le point de terminaison /resetpassword/v1.0/continue pour envoyer le mot de passe en effectuant une demande POST au point de terminaison /resetpassword/v1.0/submit.

Voici un exemple (nous présentons l’exemple de requête dans plusieurs lignes pour la lisibilité) :

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/submit
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0Mzp...
&new_password={new_password}
Parameter Required Description
tenant_subdomain Yes Sous-domaine du tenant externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Répertoire (locataire). Par exemple, si le domaine principal de votre locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de locataire, découvrez comment lire les détails de votre locataire.
continuation_token Yes Jeton de continuation qui Microsoft Entra retourné dans la requête précédente.
client_id Yes ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra.
new_password Yes Nouveau mot de passe de l’utilisateur. Remplacez {new_password} par le nouveau mot de passe de l’utilisateur. Il est de votre responsabilité de confirmer que l’utilisateur est conscient du mot de passe qu’il souhaite utiliser en fournissant le champ de confirmation du mot de passe dans l’interface utilisateur de l’application. Vous devez également vous assurer que l’utilisateur est conscient de ce qui constitue un mot de passe fort conformément à la stratégie de votre organisation. En savoir plus sur les stratégies de mot de passe de Microsoft Entra.

Réponse de réussite

Example:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "poll_interval": 2
}
Propriété Description
continuation_token Jeton de continuation qui Microsoft Entra retourne.
poll_interval Durée minimale en secondes pendant laquelle l’application doit attendre entre les demandes d’interrogation pour vérifier l’état de la demande de réinitialisation de mot de passe via le point de terminaison /resetpassword/v1.0/poll_completion, voir étape 5

Réponse d’erreur

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        901007
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Propriété Description
error Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs et y répondre.
error_description Message d’erreur spécifique qui peut vous aider à identifier la cause d’une erreur d’authentification.
error_codes Liste des codes d’erreur spécifiques à Microsoft Entra qui peuvent vous aider à diagnostiquer les erreurs.
timestamp Heure à laquelle l’erreur s’est produite.
trace_id Identificateur unique de la demande qui peut vous aider à diagnostiquer les erreurs.
correlation_id Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants.
suberror Chaîne de code d’erreur qui peut être utilisée pour classifier davantage les types d’erreurs.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles de la error propriété) :

une valeur d’erreur Description
invalid_request La validation des paramètres de requête a échoué, par exemple une validation de jeton de continuation a échoué.
expired_token Le jeton de continuation a expiré.
invalid_grant L’octroi envoyé n’est pas valide, par exemple le mot de passe envoyé est trop court. Utilisez la suberror propriété pour apprendre la cause exacte de l’erreur.

Si le paramètre d’erreur a une valeur de invalid_grant, Microsoft Entra inclut une propriété suberror dans sa réponse. Voici les valeurs possibles de la suberror propriété :

Valeur de sous-erreur Description
password_too_weak Le mot de passe est trop faible, car il ne répond pas aux exigences de complexité. En savoir plus sur les stratégies de mot de passe de Microsoft Entra.
password_too_short Le nouveau mot de passe est inférieur à 8 caractères. En savoir plus sur les stratégies de mot de passe de Microsoft Entra.
password_too_long Le nouveau mot de passe dépasse 256 caractères. En savoir plus sur les stratégies de mot de passe de Microsoft Entra.
password_recently_used Le nouveau mot de passe ne doit pas être le même qu’un mot de passe récemment utilisé. En savoir plus sur les stratégies de mot de passe de Microsoft Entra.
password_banned Le nouveau mot de passe contient un mot, une expression ou un modèle interdit. En savoir plus sur les stratégies de mot de passe de Microsoft Entra.
password_is_invalid Le mot de passe n’est pas valide, par exemple parce qu’il utilise des caractères non autorisés. En savoir plus sur les stratégies de mot de passe de Microsoft Entra. Cette réponse est possible si l’application envoie un mot de passe utilisateur.

Étape 5 : Interroger l’état de réinitialisation du mot de passe

Enfin, étant donné que la mise à jour de la configuration de l’utilisateur avec le nouveau mot de passe entraîne un certain délai, l’application peut utiliser le point de terminaison /resetpassword/v1.0/poll_completion pour interroger Microsoft Entra pour l’état de réinitialisation du mot de passe. La durée minimale en secondes pendant laquelle l’application doit attendre entre les requêtes d’interrogation est retournée à partir du point de terminaison /resetpassword/v1.0/submit dans le paramètre poll_interval.

Voici un exemple (nous présentons l’exemple de requête dans plusieurs lignes pour la lisibilité) :

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/poll_completion
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0...
Parameter Required Description
tenant_subdomain Yes Sous-domaine du tenant externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Répertoire (locataire). Par exemple, si le domaine principal de votre locataire est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de locataire, découvrez comment lire les détails de votre locataire.
continuation_token Yes Jeton de continuation qui Microsoft Entra retourné dans la requête précédente.
client_id Yes ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra.

Réponse de réussite

Example:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "status": "succeeded",
    "continuation_token":"czZCaGRSa3F0..."
}
Propriété Description
status État de la demande de réinitialisation du mot de passe. Si Microsoft Entra retourne un état de failed, l’application peut renvoyer le nouveau mot de passe en effectuant une autre demande au point de terminaison /resetpassword/v1.0/submit et inclure le nouveau jeton de continuation.
continuation_token Jeton de continuation qui Microsoft Entra retourne. Si l’état est succeed, l’application peut utiliser le jeton de continuation retourné par Microsoft Entra demander des jetons de sécurité via le point de terminaison oauth2/v2.0/token comme expliqué dans Request pour les jetons de sécurité. Cela signifie qu’une fois qu’un utilisateur a correctement réinitialisé son mot de passe, vous pouvez directement les connecter à votre application sans lancer de nouveau flux de connexion.

Voici les états possibles retournés par Microsoft Entra (valeurs possibles du paramètre status) :

une valeur d’erreur Description
succeeded La réinitialisation du mot de passe s’est terminée avec succès.
failed Échec de la réinitialisation du mot de passe. L’application peut renvoyer le nouveau mot de passe en effectuant une autre requête au point de terminaison /resetpassword/v1.0/submit.
not_started La réinitialisation du mot de passe n’a pas démarré. L’application peut vérifier l’état ultérieurement.
in_progress La réinitialisation du mot de passe est en cours. L’application peut vérifier l’état ultérieurement.

Réponse d’erreur

Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "expired_token",
    "error_description": "AADSTS901007: The continuation_token is expired.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        552003
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Propriété Description
error Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs et y répondre.
error_description Message d’erreur spécifique qui peut vous aider à identifier la cause d’une erreur d’authentification.
error_codes Liste des codes d’erreur spécifiques à Microsoft Entra qui peuvent vous aider à diagnostiquer les erreurs.
timestamp Heure à laquelle l’erreur s’est produite.
trace_id Identificateur unique de la demande qui peut vous aider à diagnostiquer les erreurs.
correlation_id Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles de la error propriété) :

une valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple la validation de jeton de continuation a échoué.
expired_token Le jeton de continuation a expiré.

Se connecter automatiquement après la réinitialisation du mot de passe

Si l’utilisateur doit se connecter après une réinitialisation de mot de passe réussie. L’application doit appeler le /oauth2/v2.0/token point de terminaison. Découvrez comment appeler le point de terminaison de jeton.