Partager via


Référence API de l’authentification native

S’applique à :Cercle blanc avec un symbole X gris. Clients de main-d’œuvre Cercle vert avec un symbole de coche blanche. Clients 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. Pour plus d’informations sur l’utilisation du Kit de développement logiciel (SDK), consultez Tutoriel : préparer votre application mobile Android pour l’authentification native et Tutoriel : préparer votre application iOS/macOS pour l’authentification native.

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 méthodes d’authentification :

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

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

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

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

  2. Si ce n’est déjà fait, Inscrire une application dans le Centre d’administration Microsoft Entra. Veillez à accorder des permissions déléguées et à activer les flux d’authentification client public et natif.

  3. Si ce n’est déjà fait, Créer un flux utilisateur dans le Centre d’administration Microsoft Entra. Quand vous créez le flux utilisateur, notez les attributs utilisateur obligatoires que vous configurez, car ces attributs sont ceux que Microsoft Entra s’attend à ce que votre application envoie.

  4. Associer l’inscription de votre application au flux utilisateur.

  5. Pour le flux de connexion, inscrire un utilisateur client, que vous utilisez pour tester les API de connexion. Vous pouvez également obtenir cet utilisateur de test après avoir exécuté le flux d’inscription.

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

Jeton de continuation

Chaque fois que vous appelez un point de terminaison dans l’un des flux, connexion, inscription ou SSPR, le point de terminaison inclut un jeton de continuation dans sa réponse. Le jeton de continuation est un identificateur unique utilisé par Microsoft Entra ID pour maintenir l’état entre les appels à différents points de terminaison au sein du même flux. Vous devez inclure ce jeton dans les requêtes suivantes dans le même flux.

Chaque jeton de continuation est valide pour une période spécifique et ne peut être utilisé que pour les requêtes suivantes dans le même flux.

Informations de référence sur l’API d’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/continue et /token.

Points de terminaison d’API d’inscription

Point de terminaison Description
/signup/v1.0/start Ce point de terminaison démarre le flux d’inscription. Vous transmettez l’ID d’application valide, le nouveau nom d’utilisateur et type de test, 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 de test pris en charge par Microsoft Entra. Microsoft Entra sélectionne 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.
/token L’application appelle ce point de terminaison pour enfin demander des jetons de sécurité. L’application doit inclure le jeton de continuation qu’elle acquiert à partir du dernier appel réussi au point de terminaison /signup/v1.0/continue.

Types de test d’inscription

L’API permet à l’application client 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 test dans les types de demande d’authentification native. Cet article explique les valeurs de type de test que vous devez attribuer à une méthode d’authentification.

Détails du protocole de flux d’inscription

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

Diagramme du flux d’inscription d’authentification native.

Ce diagramme indique que l’application collecte le nom d’utilisateur (e-mail), le mot de passe (pour les méthodes 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 via le point de terminaison /signup/v1.0/start. Dans ce cas, l’application n’a pas besoin d’effectuer des appels et de gérer les réponses pour les étapes facultatives.

É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 Requis Description
tenant_subdomain Oui Sous-domaine du client externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Annuaire (client). Par exemple, si le domaine principal de votre client est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de client, découvrez comment lire les détails de votre client.
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 Une liste séparée par l’espace des chaînes de type de test d’autorisation que l’application prend en charge, telles que oob password redirect. La liste doit toujours inclure le type de test 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 de l’utilisateur via le /signup/v1.0/start ou une version ultérieure dans le point de terminaison /signup/v1.0/continue. Remplacez {secure_password} par la valeur de mot de passe collectée par l’application auprès de l’utilisateur client. Il est de votre responsabilité de confirmer que l’utilisateur est conscient du mot de passe qu’il souhaite utiliser en fournissant le champ de confirmation du mot de passe dans l’interface utilisateur de l’application. Vous devez également vous assurer que l’utilisateur est conscient de ce qui constitue un mot de passe fort conformément à la stratégie de votre organisation. En savoir plus sur les stratégies de mot de passe de Microsoft Entra.
Ce paramètre s’applique uniquement 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 que l’administrateur a configurés dans le Centre d’administration Microsoft Entra. 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 soumettez, qui n’existent pas.

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…",
} 
Paramètre Description
continuation_token Jeton de continuation que Microsoft Entra retourne.

Si une application ne peut pas prendre en charge une méthode d’authentification requise par Microsoft Entra, un secours au flux d’authentification web est nécessaire. Dans ce scénario, Microsoft Entra informe l’application en retournant un type de test redirigerdans sa réponse :

HTTP/1.1 200 OK
Content-Type: application/json
{     
   "challenge_type": "redirect" 
} 
Paramètre Description
challenge_type Microsoft Entra retourne une réponse qui a un type de test. La valeur de ce type de test 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"
} 
Paramètre Description
error Chaîne de code d’erreur qui peut être utilisée pour classer 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 dont la validation a échoué. Cette réponse est possible si l’application envoie des attributs utilisateur et que la valeur du paramètre suberror est attribute_validation_failed.
suberror Chaîne de code d’erreur qui peut être utilisée pour classer davantage les types d’erreurs.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles du paramètre error) :

Valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple lorsque la valeur du paramètre challenge_type contient une méthode d’authentification non prise en charge ou si la requête n’a pas inclus le paramètre client_id, la valeur de l’ID client est vide ou non valable. 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 le paramètre suberror 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 client externe ou est incorrect.
unsupported_challenge_type La valeur du paramètre challenge_type n’inclut pas le type de test 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 le paramètre suberror pour découvrir 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 un paramètre suberror dans sa réponse. Voici les valeurs possibles du paramètre suberror pour une erreur de invalid_grant :

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

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

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

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 des 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 test 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 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 Requis Description
tenant_subdomain Oui Sous-domaine du client externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Annuaire (client). Par exemple, si le domaine principal de votre client est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de client, découvrez comment lire les détails de votre client.
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 de test d'autorisation que l'application prend en charge, telles que oob password redirect. La liste doit toujours inclure le type de test 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 Jeton de continuation que Microsoft Entra a retourné dans la requête précédente.

Réponse de réussite

Microsoft Entra envoie un code secret à usage unique à l’e-mail de l’utilisateur, puis répond avec le type de test 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
} 
Paramètre Description
interval Durée en secondes pendant laquelle l’application doit attendre avant de tenter de renvoyer le OTP.
continuation_token Jeton de continuation que Microsoft Entra retourne.
challenge_type Type de test 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.

Si une application ne peut pas prendre en charge une méthode d’authentification requise par Microsoft Entra, un secours au flux d’authentification web est nécessaire. Dans ce scénario, Microsoft Entra informe l’application en retournant un type de test redirigerdans sa réponse :

HTTP/1.1 200 OK
Content-Type: application/json
{
   "challenge_type": "redirect"
}
Paramètre Description
challenge_type Microsoft Entra retourne une réponse qui a un type de test. La valeur de ce type de test 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"
} 
Paramètre Description
error Chaîne de code d’erreur qui peut être utilisée pour classer 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 du paramètre error) :

Valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple l’ID client est vide ou non valable.
expired_token Le jeton de continuation a expiré.
unsupported_challenge_type La valeur du paramètre challenge_type n’inclut pas le type de test 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 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 Requis Description
tenant_subdomain Oui Sous-domaine du client externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Annuaire (client). Par exemple, si le domaine principal de votre client est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de client, découvrez comment lire les détails de votre client.
continuation_token Oui Jeton de continuation que Microsoft Entra a 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 à usage unique, 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 l’e-mail avec 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 le Centre d’administration Microsoft Entra, ou bien 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é à l’étape 5.
L'application soumet avec succès le mot de passe de l'utilisateur (pour les emails avec 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 les attributs 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..."
} 
Paramètre Description
error Chaîne de code d’erreur qui peut être utilisée pour classer les types d’erreurs et y répondre.
error_description Message d’erreur spécifique qui peut vous aider à identifier la cause d’une erreur d’authentification.
error_codes Liste des codes d’erreur spécifiques à Microsoft Entra qui peuvent vous aider à diagnostiquer les erreurs.
timestamp Heure à laquelle l'erreur s'est produite.
trace_id Identificateur unique de la demande qui peut vous aider à diagnostiquer les erreurs.
correlation_id Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants.
continuation_token Jeton de continuation que Microsoft Entra retourne.
suberror Chaîne de code d’erreur qui peut être utilisée pour classer davantage les types d’erreurs.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles du paramètre error) :

Valeur d’erreur Description
credential_required L’authentification est requise pour la création de compte. Vous devez donc effectuer un appel au point de terminaison /signup/v1.0/challenge pour déterminer les identifiants 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 valable ou l’administrateur client externe n’a pas activé l’OTP par e-mail pour tous les utilisateurs du client.
invalid_grant Le type d’autorisation 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 un paramètre suberror dans sa réponse. Voici les valeurs possibles du paramètre suberror pour une erreur de invalid_grant :

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

Pour que les identifiants du mot de passe soient collectés 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 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 Requis Description
tenant_subdomain Oui Sous-domaine du client externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Annuaire (client). Par exemple, si le domaine principal de votre client est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de client, découvrez comment lire les détails de votre client.
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 de test d'autorisation que l'application prend en charge, telles que oob password redirect. La liste doit toujours inclure le type de test redirect. Pour l’e-mail avec le flux d’inscription par mot de passe, la valeur doit contenir password redirect.
continuation_token Oui Jeton de continuation que Microsoft Entra a 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..."
}
Paramètre Description
challenge_type mot de passe est retourné dans la réponse pour les identifiants requises.
continuation_token Jeton de continuation que Microsoft Entra retourne.

Si une application ne peut pas prendre en charge une méthode d’authentification requise par Microsoft Entra, un secours au flux d’authentification web est nécessaire. Dans ce scénario, Microsoft Entra informe l’application en retournant un type de test redirigerdans sa réponse :

HTTP/1.1 200 OK
Content-Type: application/json
{     
    "challenge_type": "redirect" 
} 
Paramètre Description
challenge_type Microsoft Entra retourne une réponse qui a un type de test. La valeur de ce type de test 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 d’utilisateur, dans ce cas, le mot de passe demandé par Microsoft Entra à l’étape précédente. L’application doit envoyer des identifiants 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 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 Requis Description
tenant_subdomain Oui Sous-domaine du client externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Annuaire (client). Par exemple, si le domaine principal de votre client est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de client, découvrez comment lire les détails de votre client.
continuation_token Oui Jeton de continuation que Microsoft Entra a 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 à usage unique, 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. En savoir plus sur les stratégies de mot de passe de Microsoft Entra.

Réponse de réussite

Si la demande réussit, mais qu’aucun attribut n’a été configuré dans le Centre d’administration Microsoft Entra 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é à l’étape 5. 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 nom, *âge et attributs de 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 d’annuaire) sont nommés à l’aide de la convention extension_{appId-without-hyphens}_{attribute-name}{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.

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

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles du paramètre error) :

Valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple une validation de jeton de continuation ayant échoué ou si la requête n’a pas inclus le paramètreclient_id, la valeur de l’ID client est vide ou non valable.
invalid_grant Le type d’autorisation 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.

Si une application ne peut pas prendre en charge une méthode d’authentification requise par Microsoft Entra, un secours au flux d’authentification web est nécessaire. Dans ce scénario, Microsoft Entra informe l’application en retournant un type de test redirigerdans sa réponse :

HTTP/1.1 200 OK
Content-Type: application/json
{     
   "challenge_type": "redirect" 
} 
Paramètre Description
challenge_type Microsoft Entra retourne une réponse qui a un type de test. La valeur de ce type de test 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"
}
Paramètre Description
error Chaîne de code d’erreur qui peut être utilisée pour classer 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 classer davantage les types d’erreurs.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles du paramètre error) :

Valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple lorsque le paramètre challenge_type inclut un type de test non valable.
invalid_grant L’octroi envoyé n’est pas valide, par exemple le mot de passe envoyé est trop court. Utilisez le paramètre suberror pour découvrir 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 un paramètre suberror dans sa réponse. Voici les valeurs possibles du paramètre suberror :

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

Envoyer des attributs utilisateur

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

Voici un exemple de 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}", "postaCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...
Paramètre Requis Description
tenant_subdomain Oui Sous-domaine du client externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Annuaire (client). Par exemple, si le domaine principal de votre client est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de client, découvrez comment lire les détails de votre client.
continuation_token Oui Jeton de continuation que Microsoft Entra a 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 à usage unique, 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 que l’administrateur a configurés dans le Centre d’administration Microsoft Entra. 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 soumettez, qui n’existent pas.

Réponse de réussite

Si la demande réussit, Microsoft Entra émet un jeton de continuation, que l’application peut utiliser pour demander des jetons de sécurité.

HTTP/1.1 200 OK
Content-Type: application/json
{  
    "continuation_token": "AQABAAEAAAYn..."
} 
Paramètre Description
continuation_token Jeton de continuation que Microsoft Entra retourne.

Si une application ne peut pas prendre en charge une méthode d’authentification requise par Microsoft Entra, un secours au flux d’authentification web est nécessaire. Dans ce scénario, Microsoft Entra informe l’application en retournant un type de test redirigerdans sa réponse :

HTTP/1.1 200 OK
Content-Type: application/json
{     
   "challenge_type": "redirect" 
} 
Paramètre Description
challenge_type Microsoft Entra retourne une réponse qui a un type de test. La valeur de ce type de test 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" 
}
Paramètre Description
error Chaîne de code d’erreur qui peut être utilisée pour classer les types d’erreurs et y répondre.
error_description Message d’erreur spécifique qui peut vous aider à identifier la cause d’une erreur d’authentification.
error_codes Liste des codes d’erreur spécifiques à Microsoft Entra qui peuvent vous aider à diagnostiquer les erreurs.
timestamp Heure à laquelle l'erreur s'est produite.
trace_id Identificateur unique de la demande qui peut vous aider à diagnostiquer les erreurs.
correlation_id Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants.
continuation_token Jeton de continuation que Microsoft Entra retourne.
unverified_attributes Liste (tableau d’objets) des noms de clés d’attribut qui doivent être vérifiés. Ce paramètre est inclus dans la réponse lorsque la valeur du paramètre error est verification_required.
required_attributes Liste (tableau d’objets) d’attributs que l’application doit envoyer. Microsoft Entra inclut ce paramètre dans sa réponse lorsque la valeur du paramètre error est attributes_required.
invalid_attributes Liste (tableau d’objets) d’attributs dont la validation a échoué. Ce paramètre est inclus dans la réponse lorsque la valeur du paramètre suberror est attribute_validation_failed.
suberror Chaîne de code d’erreur qui peut être utilisée pour classer davantage les types d’erreurs.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles du paramètre error) :

Valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple une validation de jeton de continuation ayant échoué ou si la requête n’a pas inclus le paramètreclient_id, la valeur de l’ID client est vide ou non valable.
invalid_grant Le type d’autorisation fourni n’est pas valide ou pris en charge ou a échoué, par exemple la validation des attributs a échoué. Utilisez le paramètre suberror pour découvrir 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 un paramètre suberror dans sa réponse. Voici les valeurs possibles du paramètre suberror pour une erreur de invalid_grant :

Valeur de sous-erreur Description
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 : Demande de jetons de sécurité

L’application effectue une requête POST au point de terminaison /token et fournit le jeton de continuation obtenu à 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=ABAAEAAAAtyo... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&username=contoso-consumer@contoso.com
&scope={scopes}
&grant_type=continuation_token 
Paramètre Requis Description
tenant_subdomain Oui Sous-domaine du client externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Annuaire (client). Par exemple, si le domaine principal de votre client est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de client, découvrez comment lire les détails de votre client.
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 valeur du paramètre doit être jeton de continuation.
continuation_token Oui Jeton de continuation que Microsoft Entra a retourné à l’étape précédente.
scope Oui Liste d’étendues séparées par un espace pour laquelle le jeton d’accès est valide. Remplacez {scopes} par les étendues valides pour laquelle le jeton d’accès retourné par Microsoft Entra est valide.
username Oui E-mail de l’utilisateur client avec lequel il souhaite s’inscrire, tel que contoso-consumer@contoso.com.

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..."
}
Paramètre Description
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.
token_type Indique la valeur du type de jeton. Le seul type pris en charge par Microsoft Entra est porteur.
expires_in Durée en secondes pendant laquelle le jeton d’accès reste valide.
scopes Liste d’étendues séparées par un espace pour laquelle le jeton d’accès est valide.
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, reportez-vous à l’article Actualiser le jeton d’accès.
Remarque : émis uniquement si l’étendue offline_access a été demandée.
id_token Jeton web JSON (Jwt) utilisé pour identifier l’utilisateur client. L’application peut décoder le jeton pour lire 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 jetons d’ID.
Remarque : émis uniquement si l’étendue openid est demandée.

Réponse d’erreur

Exemple :

HTTP/1.1 400 Bad Request
Content-Type: application/json
{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The client doesn't have consent for the requested scopes.\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"
} 
Paramètre Description
error Chaîne de code d’erreur qui peut être utilisée pour classer 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 du paramètre error) :

Valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple le client/l’application n’a pas le consentement pour les étendues demandées.
invalid_grant Le jeton de continuation inclus dans la requête n’est pas valide.
unauthorized_client L’ID client inclus dans la requête est non valable ou n’existe pas.
unsupported_grant_type Le type d’autorisation inclus dans la demande n’est pas pris en charge ou est incorrect.

Envoi d’attributs utilisateur aux points de terminaison

Dans le centre d’administration Microsoft Entra, vous pouvez configurer les attributs utilisateur comme étant obligatoires ou facultatifs. Cette configuration détermine la façon dont 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 les cas dans lesquels vous pouvez envoyer des attributs utilisateur aux points de terminaison Microsoft Entra.

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
TextBox  Valeur unique telle que le titre du travail, Ingénieur logiciel.
SingleRadioSelect Valeur unique telle que Language, norvégien. 
CheckboxMultiSelect 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 sont différents de la façon dont vous les référencez dans l’API d’authentification native.

Par exemple, nom complet dans le Centre d’administration Microsoft Entra est référencé comme 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.

Informations de référence sur l’API 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 d’authentification 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, /initiate, /challenge et /token.

Points de terminaison d’API de connexion

Point de terminaison Description
/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.
/challenge votre application appelle ce point de terminaison avec une liste de types de test pris en charge par le service d’identité. Notre service d’identité génère, puis envoie un code secret unique au canal de test choisi, tel que l’e-mail. Si votre application appelle ce point de terminaison à plusieurs reprises, un nouvel OTP est envoyé chaque fois qu’un appel est effectué.
/token Ce point de terminaison vérifie le code secret unique qu’il reçoit de votre application, puis émet des jetons de sécurité à votre application.

Types de test 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, les valeurs de type de test qu’une application envoie à Microsoft Entra pendant le flux d’inscription sont les mêmes que 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 test de redirection pour les flux d’inscription et de connexion.

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

Détails du protocole de flux de connexion

Le diagramme de séquence illustre le flux du processus de connexion.

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

Une fois que l’application a vérifié l’e-mail de l’utilisateur avec OTP, 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 précédent n’a pas été vérifié. Lorsque Microsoft Entra renvoie un code secret à usage unique, il invalide le code précédemment envoyé.

Dans les sections qui suivent, nous récapitulons le flux de diagramme de séquence 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 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 
Paramètre Requis Description
tenant_subdomain Oui Sous-domaine du client externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Annuaire (client). Par exemple, si le domaine principal de votre client est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de client, découvrez comment lire les détails de votre client.
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 de test d'autorisation que l'application prend en charge, telles que oob password redirect. La liste doit toujours inclure le type de test 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.

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..."
}
Paramètre Description
continuation_token Jeton de continuation que Microsoft Entra retourne.

Si une application ne peut pas prendre en charge une méthode d’authentification requise par Microsoft Entra, un secours au flux d’authentification web est nécessaire. Dans ce scénario, Microsoft Entra informe l’application en retournant un type de test redirigerdans sa réponse :

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

{     
   "challenge_type": "redirect" 
} 
Paramètre Description
challenge_type Microsoft Entra retourne une réponse qui a un type de test. La valeur de ce type de test 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"
} 
Paramètre Description
error Chaîne de code d’erreur qui peut être utilisée pour classer 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 du paramètre error) :

Valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple lorsque le paramètre challenge_type inclut un type de test non valable. ou la demande n’a pas inclus le paramètre client_id que la valeur de l’ID client est vide ou non valable. 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 client 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 le paramètre suberror 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 test redirect.

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

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

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

Pour continuer avec le flux, l’application utilise le jeton de continuation acquis à l’étape précédente pour demander à Microsoft Entra de sélectionner l’un des types de test pris en charge pour que l’utilisateur s’authentifie. L’application effectue une requête POST au point de terminaison /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 Requis Description
tenant_subdomain Oui Sous-domaine du client externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Annuaire (client). Par exemple, si le domaine principal de votre client est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de client, découvrez comment lire les détails de votre client.
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 de continuation que Microsoft Entra a 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 de test d'autorisation que l'application prend en charge, telles que oob password redirect. La liste doit toujours inclure le type de test 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.

Réponse de réussite

Si l’administrateur client a configuré le code secret à usage unique par e-mail 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 test 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
} 
Paramètre Description
continuation_token Jeton de continuation que Microsoft Entra retourne.
challenge_type Type de test 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.

Si une application ne peut pas prendre en charge une méthode d’authentification requise par Microsoft Entra, un secours au flux d’authentification web est nécessaire. Dans ce scénario, Microsoft Entra informe l’application en retournant un type de test redirigerdans sa réponse :

HTTP/1.1 200 OK
Content-Type: application/json
{     
   "challenge_type": "redirect" 
} 
Paramètre Description
challenge_type Microsoft Entra retourne une réponse qui a un type de test. La valeur de ce type de test 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"
} 
Paramètre Description
error Chaîne de code d’erreur qui peut être utilisée pour classer 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 du paramètre error) :

Valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple lorsque le paramètre challenge_type inclut un type de test non valable.
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 test redirect.

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

L’application effectue une requête POST au point de terminaison /token et fournit les informations d’identification d’utilisateur choisies à l’étape précédente, dans ce cas, le mot de passe pour acquérir des jetons de sécurité.

Voici un exemple de 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 Requis Description
tenant_subdomain Oui Sous-domaine du client externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Annuaire (client). Par exemple, si le domaine principal de votre client est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de client, découvrez comment lire les détails de votre client.
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 de continuation que Microsoft Entra a retourné dans la requête précédente.
grant_type Oui La valeur doit être un mot de passe pour l’e-mail avec la méthode d’authentification par mot de passe et oob pour la méthode d’authentification par code secret à usage unique par e-mail.
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 profil, *openid et e-mail. L’application doit inclure l’étendue openid pour que Microsoft Entra émette un jeton d’ID. L’application doit inclure l’étendue offline_access de Microsoft Entra pour émettre un jeton d’actualisation. En savoir plus sur les Autorisations et consentement dans la plateforme d’identités Microsoft.
password Oui
(pour les e-mails avec mot de passe)
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.
oob Oui
(pour le code secret à usage unique par e-mail)
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 /challenge.

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..."
}
Paramètre Description
token_type Indique la valeur du type de jeton. Le seul type pris en charge par Microsoft Entra est porteur.
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, reportez-vous à l’article 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 client. 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 jetons d’ID.
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"
} 
Paramètre Description
error Chaîne de code d’erreur qui peut être utilisée pour classer 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 du paramètre error) :

Valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête. Pour comprendre ce qui s’est passé, utilisez le message dans la description de l’erreur.
invalid_grant Le jeton de continuation inclus dans la demande n’est pas valide ou les identifiants de connexion de l’utilisateur client incluses dans la demande sont non valables ou le type d'autorisation 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.

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

Valeur de sous-erreur Description
invalid_oob_value La valeur du code secret à usage unique n’est pas valide. Cette sous-erreur applique uniquement le code secret à usage unique par e-mail

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

Si vous utilisez l’e-mail et le mot de passe comme méthode d’authentification dans votre application, 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. Utilisez cette API pour les scénarios de mot de passe oubliés ou modifier le mot de passe.

Points de terminaison de l’API de réinitialisation de mot de passe en libre-service

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

Point de terminaison Description
/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.
/challenge Accepte une liste de types de test pris en charge par le client et le jeton de continuation. Un test est émis à l’une des informations d’identification de récupération préférées. Par exemple, le test oob é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.
/continue Valide le test émis par le point de terminaison /challenge, puis retourne un jeton de continuation pour le point de terminaison /submit, ou émet un autre test à l’utilisateur.
/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.
/poll_completion Enfin, l’application peut utiliser le jeton de continuation émis par le point de terminaison /submit pour vérifier l’état de la demande de réinitialisation de mot de passe.

Types de test 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 test sont oob et rediriger.

En savoir plus sur les types de test dans les types de demande d’authentification native.

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

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

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

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 /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 /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 Requis Description
tenant_subdomain Oui Sous-domaine du client externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Annuaire (client). Par exemple, si le domaine principal de votre client est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de client, découvrez comment lire les détails de votre client.
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 de test d'autorisation que l'application prend en charge, telles que oob password redirect. La liste doit toujours inclure le type de test 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..."
}
Paramètre Description
continuation_token Jeton de continuation que Microsoft Entra retourne.

Si une application ne peut pas prendre en charge une méthode d’authentification requise par Microsoft Entra, un secours au flux d’authentification web est nécessaire. Dans ce scénario, Microsoft Entra informe l’application en retournant un type de test redirigerdans sa réponse :

HTTP/1.1 200 OK
Content-Type: application/json
{     
   "challenge_type": "redirect" 
} 
Paramètre Description
challenge_type Microsoft Entra retourne une réponse qui a un type de test. La valeur de ce type de test 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"
} 
Paramètre Description
error Chaîne de code d’erreur qui peut être utilisée pour classer 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 du paramètre error) :

Valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple lorsque le paramètre challenge_type inclut un type de test non valable 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 valable. 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 test 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 le paramètre suberror 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 client externe ou est incorrect.

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

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

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

Pour continuer avec le flux, l’application utilise le jeton de continuation acquis à l’étape précédente pour demander à Microsoft Entra de sélectionner l’un des types de test pris en charge pour que l’utilisateur s’authentifie. L’application effectue une requête POST au point de terminaison /challenge. Si cette demande réussit, Microsoft Entra envoie un code secret à usage unique à l’e-mail du compte d’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=client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&continuation_token=uY29tL2F1dGhlbnRpY... 
Paramètre Requis Description
tenant_subdomain Oui Sous-domaine du client externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Annuaire (client). Par exemple, si le domaine principal de votre client est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de client, découvrez comment lire les détails de votre client.
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 de continuation que Microsoft Entra a 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 de test d'autorisation que l'application prend en charge, telles que oob redirect. La liste doit toujours inclure le type de test 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
} 
Paramètre Description
continuation_token Jeton de continuation que Microsoft Entra retourne.
challenge_type Type de test 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é.
code_length Longueur du code secret à usage unique généré par Microsoft Entra.

Si une application ne peut pas prendre en charge une méthode d’authentification requise par Microsoft Entra, un secours au flux d’authentification web est nécessaire. Dans ce scénario, Microsoft Entra informe l’application en retournant un type de test redirigerdans sa réponse :

HTTP/1.1 200 OK
Content-Type: application/json
{     
   "challenge_type": "redirect" 
} 
Paramètre Description
challenge_type Microsoft Entra retourne une réponse qui a un type de test. La valeur de ce type de test 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"
} 
Paramètre Description
error Chaîne de code d’erreur qui peut être utilisée pour classer 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 du paramètre error) :

Valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple lorsque le paramètre challenge_type inclut un type de test non valable 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 test redirect.

Étape 3 : Envoyer un code secret à usage unique

L’application effectue ensuite une requête POST au point de terminaison /continue. Dans la demande, l’application doit inclure les informations d’identification d’utilisateur choisies à l’étape précédente et le jeton de continuation émis à partir du point de terminaison /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 Requis Description
tenant_subdomain Oui Sous-domaine du client externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Annuaire (client). Par exemple, si le domaine principal de votre client est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de client, découvrez comment lire les détails de votre client.
continuation_token Oui Jeton de continuation que Microsoft Entra a 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 /challenge.

Réponse de réussite

Exemple :

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

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"
} 
Paramètre Description
error Chaîne de code d’erreur qui peut être utilisée pour classer 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 classer davantage les types d’erreurs.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles du paramètre error) :

Valeur d’erreur Description
invalid_request Échec de la validation des paramètres de requête, par exemple une validation de jeton de continuation a échoué ou la demande n’a pas inclus le paramètre client_id, la valeur de l’ID client est vide ou non valable ou l’administrateur client externe n’a pas activé la SSPR et l’OTP d’e-mail pour tous les utilisateurs du client. Utilisez le paramètre error_description pour découvrir la cause exacte de l’erreur.
invalid_grant Le type d'autorisation est inconnu ou ne correspond pas à la valeur de type d'autorisation attendue. Utilisez le paramètre suberror pour découvrir 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 un paramètre suberror dans sa réponse. Voici les valeurs possibles du paramètre suberror pour une erreur de invalid_grant :

Valeur de sous-erreur Description
invalid_oob_value Le code secret à usage unique fourni par l’utilisateur 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 /continue pour envoyer le mot de passe en effectuant une demande POST au point de terminaison /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 Requis Description
tenant_subdomain Oui Sous-domaine du client externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Annuaire (client). Par exemple, si le domaine principal de votre client est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de client, découvrez comment lire les détails de votre client.
continuation_token Oui Jeton de continuation que Microsoft Entra a 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. En savoir 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
}
Paramètre Description
continuation_token Jeton de continuation que Microsoft Entra retourne.
poll_interval Durée minimale en secondes pendant laquelle l’application doit attendre entre les demandes d’interrogation pour vérifier l’état de la demande de réinitialisation de mot de passe via le point de terminaison /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"
} 
Paramètre Description
error Chaîne de code d’erreur qui peut être utilisée pour classer 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 classer davantage les types d’erreurs.

Voici les erreurs possibles que vous pouvez rencontrer (valeurs possibles du paramètre error) :

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

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

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

Étape 5 : Interroger l’état de réinitialisation de 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 /poll_completion pour interroger Microsoft Entra pour l’état de réinitialisation de 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 /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 Requis Description
tenant_subdomain Oui Sous-domaine du client externe que vous avez créé. Dans l’URL, remplacez {tenant_subdomain} par le sous-domaine Annuaire (client). Par exemple, si le domaine principal de votre client est contoso.onmicrosoft.com, utilisez contoso. Si vous n’avez pas votre sous-domaine de client, découvrez comment lire les détails de votre client.
continuation_token Oui Jeton de continuation que Microsoft Entra a 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..."
} 
Paramètre Description
status État de la demande de réinitialisation de mot de passe. Si Microsoft Entra retourne un état échec, l’application peut renvoyer le nouveau mot de passe en effectuant une autre demande au point de terminaison /submit et en incluant le nouveau jeton de continuation.
continuation_token Jeton de continuation que Microsoft Entra retourne. Si l’état est réussi, l’application peut utiliser le jeton de continuation que Microsoft Entra retourne pour demander des jetons de sécurité via le point de terminaison /token, comme expliqué à étape 5 du flux d’inscription. 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 Description
succeeded La réinitialisation de 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 /submit.
not_started La réinitialisation de mot de passe n’a pas démarré. L’application peut vérifier le statut ultérieurement.
in_progress La réinitialisation de mot de passe est en cours. L’application peut vérifier le statut 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"
} 
Paramètre Description
error Chaîne de code d’erreur qui peut être utilisée pour classer 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 du paramètre error) :

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