Informations de référence sur l’API d’inscription à 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.

Cette référence décrit l’inscription via la collection d’attributs pilotée par le serveur. L’inscription par e-mail avec mot de passe et par e-mail à usage unique utilise les mêmes opérations et formes de message. Pour ces méthodes de messagerie, le flux utilisateur associé à l’application sélectionne la méthode d’inscription ; le client ne le sélectionne pas dans la demande de démarrage.

Les exemples montrent l’inscription par e-mail. 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 l’inscription

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 d’inscription pilotée par la réponse. Le flux utilisateur détermine la méthode d’inscription et la réponse actuelle détermine quels attributs et interactions sont requis.

Diagramme séquentiel de l’inscription native avec la collection d’attributs définie par la réponse, la vérification et l’échange de code d’autorisation.

Démarrez l’autorisation, puis suivez son sign_up lien avec le jeton retourné :

POST https://{custom_domain}/{tenant}/api/v2.0/signup/start
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******"
}

continuationToken est une chaîne obligatoire. La réponse de démarrage peut demander un e-mail :

{
  "continuationToken": "******",
  "state": "interactionRequired",
  "action": "collectAttributes",
  "attributes": [
    {
      "attributeId": "email",
      "inputType": "text",
      "hidden": false,
      "required": true,
      "canChange": true,
      "label": "Email"
    }
  ],
  "_links": {
    "submitAttributes": {
      "href": "/{tenant}/api/v2.0/signup/submitattributes"
    }
  }
}

Les étiquettes, la nécessité et les métadonnées de validation proviennent de la stratégie. Utilisez ces exigences dans l’interface et la logique de collecte de votre application.

Envoyer des attributs

Suivez _links.submitAttributes.href. La collecte peut se produire plusieurs fois :

POST https://{custom_domain}/{tenant}/api/v2.0/signup/submitattributes
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******",
  "attributes": {
    "email": "user@contoso.com"
  }
}
Propriété Catégorie Required Description
continuationToken Chaîne. Oui. Jeton d’inscription le plus récent.
attributes Objet des valeurs de chaîne. Oui. Valeurs clé par les valeurs retournées attributeId exactement.

Toutes les valeurs requises doivent être fournies avant la fin de l’inscription. Les valeurs facultatives peuvent être omises. Les valeurs requises manquantes peuvent générer une erreur de validation ou une autre collectAttributes réponse.

Pour l’inscription par e-mail avec mot de passe, envoyez un mot de passe lorsqu’il est demandé. Par exemple, une série de regroupements qui demande des champs de mot de passe et de profil peut accepter :

{
  "continuationToken": "******",
  "attributes": {
    "email": "user@contoso.com",
    "password": "******",
    "givenName": "Example",
    "surname": "User"
  }
}

Envoyez des champs en fonction des descripteurs retournés par le flux utilisateur. L’inscription par courrier électronique unique du code secret crée un compte sans mot de passe qui se connecte avec un code secret de messagerie.

Ordre de collecte

Le service peut d’abord demander un e-mail, collecter plusieurs attributs ensemble ou revenir à la collection d’attributs après vérification. Envoyez les attributs demandés par la dernière réponse plutôt que de prédire la séquence à partir des valeurs envoyées.

Votre application peut organiser la collecte en fonction de sa logique de flux et des descripteurs disponibles. Consultez l’ordre de collecte et la vérification par e-mail. Chaque réponse détermine les opérations suivantes disponibles.

Interpréter les descripteurs d’attribut et de page

Chaque réponse décrit le formulaire actif. Les champs suivants définissent un attribut :

Champ Meaning
attributeId Clé de soumission.
inputType Type de contrôle d’entrée, tel que text, , password, booleandate, ou checkboxMultiSelect.
required Indique si une valeur doit être fournie.
hidden Indique si le champ est masqué.
canChange Informations d’édition, lorsqu’elles sont incluses.
label Étiquette d’affichage facultative.
initialValue Valeur préremplie facultative.
validation.validationRegEx Modèle de validation facultatif.
options Choix facultatifs avec label et value propriétés.
confirmationInput Comportement de confirmation facultatif, tel que retype, revealou none.

N’avez pas besoin d’un pages membre. Le tableau actuel attributes définit les champs et les exigences ; les métadonnées de regroupement de pages, si elles sont retournées, sont des informations de présentation supplémentaires. Les types de contrôle d’entrée ne modifient pas l’objet de soumission à valeur de chaîne. Consultez les concepts d’attribut utilisateur.

Vérifier l’e-mail

Lorsque la soumission d’attribut nécessite une vérification par e-mail, elle envoie le code secret et retourne :

{
  "continuationToken": "******",
  "state": "interactionRequired",
  "action": "verify",
  "id": "{email_method_id}",
  "type": "email",
  "hint": "u***@contoso.com",
  "codeLength": 8,
  "_links": {
    "verify": {
      "href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/verify"
    },
    "resend": {
      "href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/challenge"
    }
  }
}

Le service a déjà envoyé le code secret ; passez directement à la vérification. Utilisez la longueur retournée et l’indicateur masqué. Publier jusqu’à verify:

POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/verify
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******",
  "otp": "{one_time_passcode}"
}

Pour demander un autre code, publiez uniquement la dernière continuationToken version du lien actuel resend , sous réserve des limites de service.

La vérification peut retourner davantage de collection d’attributs :

{
  "continuationToken": "******",
  "state": "interactionRequired",
  "action": "collectAttributes",
  "attributes": [
    {
      "attributeId": "givenName",
      "inputType": "text",
      "hidden": false,
      "required": true,
      "canChange": true,
      "label": "First name"
    }
  ],
  "_links": {
    "submitAttributes": {
      "href": "/{tenant}/api/v2.0/signup/submitattributes"
    }
  }
}

Envoyez les valeurs demandées et continuez à gérer la réponse suivante.

Remplir les exigences de stratégie et l’autorisation

Après la création du compte et toute vérification requise, effectuez toutes les exigences d’authentification multifacteur (MFA) et d’accès conditionnel avant de reprendre l’autorisation.

Si la réponse publie un autre défi de méthode, utilisez les opérations de vérification et de défi partagés. L’inscription de méthode est distincte de la vérification d’un e-mail d’inscription. Consultez la découverte et l’inscription des méthodes pour le contrat d’inscription.

Lorsque le service retourne state: continue, suivez , reprenez_links.continue l’autorisation et échangez le code. Cela acquiert des jetons sans démarrer une transaction de connexion non liée.

Erreurs et cycle de vie

Utilisez l’enveloppe d’erreur partagée. Les entrées de validation structurée peuvent contenir code, , messageattributeIds, suggestionset facultatives recovery.

Pathologie État ou comportement Handling
Jeton de continuation non valide 400 Redémarrez le flux.
Attribut manquant ou non valide 400 ou une autre collectAttributes réponse Présenter des commentaires au niveau du champ et envoyer des valeurs corrigées.
L’utilisateur existe déjà 400 invalidRequest Proposez des conseils de connexion ou de récupération génériques sans divulguer inutilement l’existence du compte.
Violation de stratégie de mot de passe 400 Collecter un mot de passe conforme.
Code secret de courrier 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.
Limitation du débit 429 Respectez les instructions de nouvelle tentative du serveur.
Interaction native non prise en charge state: redirect Arrêtez les requêtes natives et offrez le chemin d’accès du navigateur configuré ou un échec clair.

Gérez d’autres défaillances par le biais de leur état réel et de codes d’erreur stables. Ne traitez pas une transaction expirée comme une entrée de code incorrecte récupérable.

La soumission d’attribut n’est pas idempotente après la création de l’utilisateur. Ne relectez pas les soumissions réussies, consignez les valeurs d’attribut sensibles ou traitez la validation côté client comme faisant autorité.