Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
S’applique à : 
Locataires externes (en savoir plus)
l'authentification native de Microsoft Entra vous permet d'héberger l'interface utilisateur de votre application dans l'application cliente au lieu de déléguer l'authentification aux navigateurs, ce qui entraîne une expérience d'authentification intégrée en mode natif. En tant que développeur, vous avez un contrôle total sur l’apparence de l’interface de connexion.
Cet article de référence d’API décrit les détails requis uniquement lorsque vous effectuez manuellement des requêtes HTTP brutes pour exécuter le flux. Toutefois, nous vous déconseillons cette approche. Par conséquent, dans la mesure du possible, utilisez un Kit de développement logiciel (SDK) d’authentification créé et pris en charge par Microsoft. En savoir plus sur les kits SDK d’authentification natifs. Lorsqu’un appel aux points de terminaison d’API réussit, vous recevez à la fois un jeton d’ID pour l’identification de l’utilisateur et un jeton d’accès pour appeler des API protégées. Toutes les réponses de l’API sont au format JSON.
l'API d'authentification native de Microsoft Entra 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).
- Les utilisateurs qui se connectent avec une adresse e-mail et un mot de passe peuvent aussi se connecter avec un nom d’utilisateur et un mot de passe.
Code secret à usage unique par e-mail, qui prend en charge l’inscription et la connexion avec un code secret à usage unique.
Remarque
Actuellement, les points de terminaison de l’API d’authentification native ne prennent pas en charge le partage de ressources cross-origin (CORS).
Prérequis
Un locataire externe Microsoft Entra. Si vous n’avez pas encore créé de client externe, créez-en un maintenant.
Si ce n'est déjà fait, Enregistrer une application dans le centre d'administration Microsoft Entra. Veillez à :
- Enregistrez l’ID d’application (client) et l’ID d’annuaire (locataire) pour une utilisation ultérieure.
- Accordez le consentement de l’administrateur à l’application.
- Activez les flux d’authentification publics et natifs.
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.
Associer l’inscription de votre application au flux utilisateur.
Pour le flux de connexion, inscrivez-vous un utilisateur client, que vous utilisez pour tester le flux. Vous pouvez également obtenir cet utilisateur de test après avoir exécuté le flux d’inscription.
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.
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 :
- Activez le nom d’utilisateur dans la connexion.
- 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 automater la création et la mise à jour de l’utilisateur dans votre application à l’aide de Microsoft Graph API.
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.
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 | Descriptif |
|---|---|
/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.
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
| Paramètre | Obligatoire | Descriptif |
|---|---|---|
tenant_subdomain |
Oui | 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 |
Oui | ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra. |
username |
Oui | E-mail de l’utilisateur client avec lequel il souhaite s’inscrire, tel que contoso-consumer@contoso.com. |
challenge_type |
Oui | 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 |
Non | 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.
Learn plus sur les stratégies de mot de passe de Microsoft Entra. Ce paramètre s’applique uniquement aux e-mails avec méthode d’authentification par mot de passe. |
attributes |
Non | 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 |
Non | Indicateurs séparés par l’espace qui décrivent les fonctionnalités 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 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é | Descriptif |
|---|---|
continuation_token |
jeton Continuation retourné 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é | Descriptif |
|---|---|
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
Exemple :
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é | Descriptif |
|---|---|
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é) :
| Valeur d’erreur | Descriptif |
|---|---|
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 aux e-mails avec 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 | Descriptif |
|---|---|
password_too_weak |
Le mot de passe est trop faible, car il ne répond pas aux exigences de complexité. Learn 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. Learn 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. Learn 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é. Learn 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. Learn 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. Learn 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 | Descriptif |
|---|---|
nativeauthapi_disabled |
ID client d’une application qui n’est pas activé pour l’authentification native. |
Remarque
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…
| Paramètre | Obligatoire | Descriptif |
|---|---|---|
tenant_subdomain |
Oui | 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 |
Oui | ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra. |
challenge_type |
Non | 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 |
Oui | jetoncontinuation 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é | Descriptif |
|---|---|
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 Continuation retourné par Microsoft Entra. |
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é | Descriptif |
|---|---|
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
Exemple :
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é | Descriptif |
|---|---|
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é) :
| Valeur d’erreur | Descriptif |
|---|---|
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}
| Paramètre | Obligatoire | Descriptif |
|---|---|---|
tenant_subdomain |
Oui | 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 |
Oui | jetoncontinuation qui Microsoft Entra retourné dans la requête précédente. |
client_id |
Oui | ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra. |
grant_type |
Oui | 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 |
Oui | 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 :
| Scénario | Procédure à suivre |
|---|---|
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 les e-mails avec la méthode d’authentification par mot de passe. |
Réponse
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é | Descriptif |
|---|---|
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 Continuation retourné par Microsoft Entra. |
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é) :
| Valeur d’erreur | Descriptif |
|---|---|
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 | Descriptif |
|---|---|
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…
| Paramètre | Obligatoire | Descriptif |
|---|---|---|
tenant_subdomain |
Oui | 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 |
Oui | ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra. |
challenge_type |
Non | 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 |
Oui | jetoncontinuation 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é | Descriptif |
|---|---|
challenge_type |
mot de passe est retourné dans la réponse pour les informations d’identification requises. |
continuation_token |
jeton Continuation retourné 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é | Descriptif |
|---|---|
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}
| Paramètre | Obligatoire | Descriptif |
|---|---|---|
tenant_subdomain |
Oui | 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 |
Oui | jeton Continuation qui Microsoft Entra retourné à l’étape précédente. |
client_id |
Oui | ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra. |
grant_type |
Oui | 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 |
Oui | 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.
Learn 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]*$"
}
}
],
}
Remarque
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é | Descriptif |
|---|---|
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 Continuation retourné par Microsoft Entra. |
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é) :
| Valeur d’erreur | Descriptif |
|---|---|
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é | Descriptif |
|---|---|
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
Exemple :
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é | Descriptif |
|---|---|
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é) :
| Valeur d’erreur | Descriptif |
|---|---|
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 | Descriptif |
|---|---|
password_too_weak |
Le mot de passe est trop faible, car il ne répond pas aux exigences de complexité. Learn 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. Learn 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. Learn 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é. Learn 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. Learn 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. Learn 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...
| Paramètre | Obligatoire | Descriptif |
|---|---|---|
tenant_subdomain |
Oui | 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 |
Oui | jetoncontinuation qui Microsoft Entra retourné dans la requête précédente. |
client_id |
Oui | ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra. |
grant_type |
Oui | 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 |
Oui | 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é | Descriptif |
|---|---|
continuation_token |
jeton Continuation retourné 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é | Descriptif |
|---|---|
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
Exemple :
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é | Descriptif |
|---|---|
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 Continuation retourné par Microsoft Entra. |
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é) :
| Valeur d’erreur | Descriptif |
|---|---|
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 | Descriptif |
|---|---|
attribute_validation_failed |
Échec de la validation des attributs utilisateur. Le paramètre invalid_attributes 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 |
|---|---|---|---|
Point de terminaison /signup/v1.0/start |
Oui | Oui | Oui |
Point de terminaison /signup/v1.0/continue avant la vérification du nom d’utilisateur |
Oui | Oui | Oui |
Point de terminaison /signup/v1.0/continue après la vérification du nom d’utilisateur |
Oui | Non | Oui |
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 dans le 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 les attributs de profil utilisateur article 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 | Descriptif |
|---|---|
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.
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
| Paramètre | Obligatoire | Descriptif |
|---|---|---|
tenant_subdomain |
Oui | 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 |
Oui | ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra. |
username |
Oui | E-mail de l’utilisateur client tel que contoso-consumer@contoso.com. |
challenge_type |
Oui | 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 |
Non | 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 les méthodes qui 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é | Descriptif |
|---|---|
continuation_token |
jeton Continuation retourné 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é | Descriptif |
|---|---|
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
Exemple :
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é | Descriptif |
|---|---|
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é) :
| Valeur d’erreur | Descriptif |
|---|---|
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 | Descriptif |
|---|---|
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...
| Paramètre | Obligatoire | Descriptif |
|---|---|---|
tenant_subdomain |
Oui | 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 |
Oui | ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra. |
continuation_token |
Oui |
jetoncontinuation 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 |
Non | 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 |
Non | 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é | Descriptif |
|---|---|
continuation_token |
jeton Continuation retourné par Microsoft Entra. |
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é | Descriptif |
|---|---|
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
Exemple :
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é | Descriptif |
|---|---|
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é) :
| Valeur d’erreur | Descriptif |
|---|---|
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
| Paramètre | Obligatoire | Descriptif |
|---|---|---|
tenant_subdomain |
Oui | 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 |
Oui | ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra. |
continuation_token |
Oui | jetoncontinuation qui Microsoft Entra retourné dans la requête précédente. |
grant_type |
Oui | 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 |
Oui | 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 |
Non | 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 |
Non | 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 |
Non | 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 correcte
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é | Descriptif |
|---|---|
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 l’étendue offline_access. |
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 l’étendue openid. |
Réponse d’erreur
Exemple :
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é | Descriptif |
|---|---|
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é) :
| Valeur d’erreur | Descriptif |
|---|---|
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 | Descriptif |
|---|---|
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é | Descriptif |
|---|---|
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
| Paramètre | Obligatoire | Descriptif |
|---|---|---|
tenant_subdomain |
Oui | 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 |
Oui | ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra. |
continuation_token |
Oui | jetoncontinuation qui Microsoft Entra retourné dans la requête précédente. |
Réponse de réussite
Exemple :
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é | Descriptif |
|---|---|
continuation_token |
jeton Continuation retourné par Microsoft Entra. |
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é | Descriptif |
|---|---|
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
Exemple :
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é | Descriptif |
|---|---|
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é) :
| Valeur d’erreur | Descriptif |
|---|---|
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 :
L’application cliente appelle et
/oauth2/v2.0/challengeinclut le jeton de continuation obtenu à partir de la/oauth2/v2.0/introspectidmé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...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 }L’application peut désormais effectuer une requête POST au
/oauth2/v2.0/tokenpoint 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 l’utilisateur n’a pas de méthode forte inscrite, la réponse, registeration_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 | Descriptif |
|---|---|
/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
| Paramètre | Obligatoire | Descriptif |
|---|---|---|
tenant_subdomain |
Oui | 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 |
Oui | 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é | Descriptif |
|---|---|
continuation_token |
jeton Continuation retourné par Microsoft Entra. |
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é | Descriptif |
|---|---|
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
Exemple :
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é | Descriptif |
|---|---|
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é) :
| Valeur d’erreur | Descriptif |
|---|---|
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
| Paramètre | Obligatoire | Descriptif |
|---|---|---|
tenant_subdomain |
Oui | 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 |
Oui | ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra. |
continuation_token |
Oui | Jeton Continuation qui Microsoft Entra retourne à partir du point de terminaison /register/v1.0/introspect |
challenge_type |
Oui | Type de défi de la méthode d’authentification. Le type actuel est oob. |
challenge_target |
Oui | Numéro de téléphone ou e-mail que l’utilisateur souhaite inscrire. |
challenge_channel |
Non | 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é | Descriptif |
|---|---|
continuation_token |
jeton Continuation retourné par Microsoft Entra. |
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 :
| Valeur d’erreur | Descriptif |
|---|---|
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 | Descriptif |
|---|---|
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}
| Paramètre | Obligatoire | Descriptif |
|---|---|---|
tenant_subdomain |
Oui | 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 |
Oui | jetoncontinuation qui Microsoft Entra retourné dans la requête précédente. |
client_id |
Oui | ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra. |
grant_type |
Oui | 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 |
Non | 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é | Descriptif |
|---|---|
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
Exemple :
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é | Descriptif |
|---|---|
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é) :
| Valeur d’erreur | Descriptif |
|---|---|
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 | Descriptif |
|---|---|
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 | Descriptif |
|---|---|
/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.
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
| Paramètre | Obligatoire | Descriptif |
|---|---|---|
tenant_subdomain |
Oui | 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 |
Oui | ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra. |
username |
Oui | E-mail de l’utilisateur client tel que contoso-consumer@contoso.com. |
challenge_type |
Oui | 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 |
Non | 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 les méthodes qui 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
Exemple :
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| Propriété | Descriptif |
|---|---|
continuation_token |
jeton Continuation retourné 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é | Descriptif |
|---|---|
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
Exemple :
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é | Descriptif |
|---|---|
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é) :
| Valeur d’erreur | Descriptif |
|---|---|
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 | Descriptif |
|---|---|
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...
| Paramètre | Obligatoire | Descriptif |
|---|---|---|
tenant_subdomain |
Oui | 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 |
Oui | ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra. |
continuation_token |
Oui | jetoncontinuation qui Microsoft Entra retourné dans la requête précédente. |
challenge_type |
Non | 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
Exemple :
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é | Descriptif |
|---|---|
continuation_token |
jeton Continuation retourné par Microsoft Entra. |
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é | Descriptif |
|---|---|
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
Exemple :
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é | Descriptif |
|---|---|
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é) :
| Valeur d’erreur | Descriptif |
|---|---|
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}
| Paramètre | Obligatoire | Descriptif |
|---|---|---|
tenant_subdomain |
Oui | 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 |
Oui | jetoncontinuation qui Microsoft Entra retourné dans la requête précédente. |
client_id |
Oui | ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra. |
grant_type |
Oui | La seule valeur valide est oob. |
oob |
Oui | 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
Exemple :
HTTP/1.1 200 OK
Content-Type: application/json
{
"expires_in": 600,
"continuation_token": "czZCaGRSa3F0MzpnW...",
}
| Propriété | Descriptif |
|---|---|
expires_in |
Durée en secondes avant l’expiration du continuation_token. La valeur maximale de expires_in est 600 secondes. |
continuation_token |
jeton Continuation retourné par Microsoft Entra. |
Réponse d’erreur
Exemple :
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é | Descriptif |
|---|---|
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é) :
| Valeur d’erreur | Descriptif |
|---|---|
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 | Descriptif |
|---|---|
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}
| Paramètre | Obligatoire | Descriptif |
|---|---|---|
tenant_subdomain |
Oui | 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 |
Oui | jetoncontinuation qui Microsoft Entra retourné dans la requête précédente. |
client_id |
Oui | ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra. |
new_password |
Oui | 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.
Learn plus sur les stratégies de mot de passe de Microsoft Entra. |
Réponse de réussite
Exemple :
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY...",
"poll_interval": 2
}
| Propriété | Descriptif |
|---|---|
continuation_token |
jeton Continuation retourné par Microsoft Entra. |
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
Exemple :
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é | Descriptif |
|---|---|
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é) :
| Valeur d’erreur | Descriptif |
|---|---|
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 | Descriptif |
|---|---|
password_too_weak |
Le mot de passe est trop faible, car il ne répond pas aux exigences de complexité. Learn 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. Learn 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. Learn 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é. Learn 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. Learn 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. Learn 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...
| Paramètre | Obligatoire | Descriptif |
|---|---|---|
tenant_subdomain |
Oui | 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 |
Oui | jetoncontinuation qui Microsoft Entra retourné dans la requête précédente. |
client_id |
Oui | ID d’application (client) de l’application que vous avez inscrite dans le centre d’administration Microsoft Entra. |
Réponse de réussite
Exemple :
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "succeeded",
"continuation_token":"czZCaGRSa3F0..."
}
| Propriété | Descriptif |
|---|---|
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 Continuation retourné par Microsoft Entra. 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) :
| Valeur d’erreur | Descriptif |
|---|---|
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
Exemple :
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é | Descriptif |
|---|---|
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é) :
| Valeur d’erreur | Descriptif |
|---|---|
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.