Informations de référence sur l’API de connexion à l’authentification native

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

Approche d’authentification : Authentification native incorporée.

La connexion découvre les méthodes autorisées pour l’identificateur d’un client et effectue les vérifications d’informations d’identification requises. La connexion par mot de passe par e-mail et par mot de passe unique (OTP) à usage unique utilise le même modèle piloté par la réponse. L’application sélectionne les opérations autorisées à partir de la réponse par le biais d’une logique de choix utilisateur ou de flux d’application, puis répond aux exigences d’authentification restantes avant de reprendre l’autorisation.

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

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

Démarrer la découverte de la connexion

Important

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

Le diagramme montre une séquence de connexion possible. Les exigences de stratégie peuvent ajouter, répéter ou réorganiser des actions ; suivez toujours la réponse actuelle.

Diagramme séquentiel de la connexion native, de la vérification des informations d’identification, des interactions de stratégie supplémentaires et de l’échange de code d’autorisation.

Démarrez l’autorisation, puis suivez le lien retourné sign_in . Envoyez la valeur de continuation_token la réponse OAuth comme continuationTokensuit :

POST https://{custom_domain}/{tenant}/api/v2.0/signin/start
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******",
  "username": "user@contoso.com"
}
Propriété Catégorie Required Description
continuationToken Chaîne. Oui. Jeton du défi d’autorisation actuel.
username Chaîne. Oui. Identificateur de connexion accepté par la stratégie de locataire. Cet exemple utilise l’e-mail.

Une réponse de sélection de méthode de mot de passe peut être :

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

Email-OTP connexion retourne une méthode d’e-mail avec ses propres idliens, masqués hintet autorisés. Votre application peut présenter des choix retournés ou sélectionner une méthode disponible via la logique de flux d’application. Tous les comptes ne proposent pas à la fois un mot de passe et un mot de passe par e-mail. Utilisez des échecs de découverte génériques et protégez les informations d’existence de compte.

Défier la méthode sélectionnée

Suivez le lien de challenge la méthode avec POST et le dernier jeton de continuation :

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

Le contrat de défi partagé définit les en-têtes, les champs de réponse et le comportement de réexécriture.

Méthode retournée Interaction
password Aucun code n’est envoyé. Collectez le mot de passe lorsque la réponse demande verify.
email Collectez le code secret remis. Utilisez le masquage hint retourné et codeLength.
sms Lorsqu’il est publié pour un facteur requis, collectez le code secret SMS à l’aide de son propre indicateur, de sa longueur et de ses liens.

Utilisez resend uniquement lorsque le service le publie et que le client demande un autre code. Ne renvoyez pas automatiquement après un délai de remise.

Vérifier les informations d’identification

Suivez le lien actuel verify à l’aide POSTde . Utilisez JSON, Accept: application/hal+jsonet l’un de ces corps.

Mot de passe :

{
  "continuationToken": "******",
  "password": "******"
}

Code secret unique par e-mail ou SMS :

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

Utilisez le champ d’informations d’identification pour le type de méthode retourné. N’envoyez pas de mot de passe ou otp de code secret dans password. Ne relectez pas automatiquement la vérification après une défaillance réseau ambiguë.

Remplir des exigences de stratégie supplémentaires

Une vérification réussie peut retourner une autre interactionRequired réponse avec action: challenge et _embedded.methods. Sélectionnez une méthode annoncée et répétez le défi et la vérification avec le nouveau jeton et les liens.

L’authentification multifacteur (MFA) utilise les mêmes opérations d’informations d’identification partagées et prend en charge les codes secrets à usage unique par e-mail et SMS en tant que deuxième facteurs. L’authentification multifacteur via des stratégies système est prise en charge. Sélectionnez une méthode à partir de celles retournées pour le facteur requis. L’exemple SMS décrit une interaction second facteur.

Si la réponse suivante nécessite enroll ou activate, utilisez le contrat d’inscription inline. Les comptes e-mail avec mot de passe peuvent inscrire un facteur e-mail ou SMS proposé. Email-OTP comptes de premier facteur ne peuvent pas réutiliser les e-mails comme deuxième facteur ; utilisez une alternative proposée telle que SMS.

Si une interaction requise n’est pas prise en charge par votre client, ou si le service retourne state: redirect, arrêtez les requêtes natives et offrez une connexion de navigateur configurée séparément ou un échec clair.

Reprendre l’autorisation et acquérir des jetons

Lorsque les exigences de stratégie sont satisfaites, une réponse peut retourner :

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

Publiez le jeton encodé continuation_token sous forme de formulaire dans le lien retourné. Échangez ensuite le code d’autorisation pour les jetons. Ni une réponse de défi ni une réponse de vérification réussie ne remplace cet échange.

Errors

Utilisez l’enveloppe d’erreur partagée avec ces conditions de connexion :

Pathologie État ou erreur Handling
Nom d’utilisateur ou jeton manquant 400 Corrigez la requête.
Code secret d’e-mail ou SMS incorrect 400 invalidGrant, avec innerError.code: invalidOneTimeCode Laissez l’utilisateur corriger le code à l’aide de l’état actuel utilisable ou d’un renvoi annoncé.
Code secret manquant 400 invalidRequest Corrigez l’entrée manquante.
État de transaction non valide 400 avec l’enveloppe d’erreur native Redémarrez au lieu de relire un jeton antérieur.
Limitation du débit 429 Arrêtez les nouvelles tentatives automatiques et respectez les instructions du serveur.
Interaction native non prise en charge state: redirectou OAuth invalid_grant avec web_redirect_required Arrêtez les requêtes natives. Une connexion de navigateur distincte redémarre l’authentification.

Pour d’autres informations d’identification, de découverte ou d’échecs de remise, gérez l’état réel et les codes d’erreur stables sans exposer les détails de l’existence du compte. Cette table n’est pas un catalogue d’erreurs exhaustif. Conservez uniquement les ID de requête sécurisés, les ID de corrélation, les horodatages et les informations d’état, pas les informations d’identification ni les corps de réponse entiers.