Naslaginformatie voor registratie-API voor systeemeigen verificatie

Van toepassing op: Groene cirkel met een wit vinkje dat aangeeft dat de volgende inhoud van toepassing is op externe tenants. Externe tenants (meer informatie)

Verificatiemethode: Ingesloten systeemeigen verificatie.

In deze verwijzing wordt beschreven hoe u zich registreert via een servergestuurde kenmerkverzameling. Eenmalige aanmelding via e-mail met wachtwoord en e-mail gebruiken dezelfde bewerkingen en berichtshapes. Voor deze e-mailmethoden selecteert de gebruikersstroom die is gekoppeld aan de toepassing de registratiemethode; de client selecteert deze niet in de startaanvraag.

In de voorbeelden ziet u aanmelding op basis van e-mail. Voor bestaande V1-integraties gebruikt u de V1 API-verwijzing.

In de voorbeelden wordt een tenant-geverifieerde aangepaste domeininstantie gebruikt. custom_domain is het verificatiedomein en tenant is de tenant-GUID.

Registreren starten

Important

De systeemeigen verificatie-API V2 is in preview. De systeemeigen verificatie-API V1 blijft algemeen beschikbaar. Zie de aanvullende gebruiksvoorwaarden voor Microsoft Azure previews voor juridische voorwaarden die van toepassing zijn op preview-functies.

In het diagram ziet u een op antwoord gestuurde registratiereeks. De gebruikersstroom bepaalt de registratiemethode en het huidige antwoord bepaalt welke kenmerken en interacties vereist zijn.

Sequentiediagram van systeemeigen registratie met door antwoord gedefinieerde kenmerkverzameling, verificatie en uitwisseling van autorisatiecode.

Start autorisatie en volg sign_up vervolgens de koppeling met het geretourneerde token:

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

continuationToken is een vereiste tekenreeks. Het antwoord op het begin kan een e-mail aanvragen:

{
  "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"
    }
  }
}

Labels, vereiste en validatiemetagegevens zijn afkomstig van beleid. Gebruik deze vereisten binnen de interface- en verzamelingslogica van uw toepassing.

Kenmerken verzenden

Volg _links.submitAttributes.href. Verzameling kan meerdere keren voorkomen:

POST https://{custom_domain}/{tenant}/api/v2.0/signup/submitattributes
Content-Type: application/json
Accept: application/hal+json
{
  "continuationToken": "******",
  "attributes": {
    "email": "user@contoso.com"
  }
}
Property Type Required Description
continuationToken Tekenreeks. Yes. Meest recente registratietoken.
attributes Object van tekenreekswaarden. Yes. Waarden die zijn gekoppeld aan de exacte geretourneerde attributeId waarden.

Alle vereiste waarden moeten worden opgegeven voordat de registratie is voltooid. Optionele waarden kunnen worden weggelaten. Ontbrekende vereiste waarden kunnen een validatiefout of een ander collectAttributes antwoord opleveren.

Voor aanmelding via e-mail met wachtwoord dient u een wachtwoord in wanneer u hierom wordt gevraagd. Een verzamelingsronde die bijvoorbeeld wachtwoord- en profielvelden aanvraagt, kan het volgende accepteren:

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

Verzend velden op basis van de geretourneerde descriptors van de gebruikersstroom. Eenmalige aanmelding voor wachtwoordcodes per e-mail maakt een account zonder wachtwoord dat zich aanmeldt met een e-mailwachtwoordcode.

Verzamelingsvolgorde

De service kan eerst e-mail aanvragen, verschillende kenmerken verzamelen of na verificatie terugkeren naar de kenmerkverzameling. Verzend kenmerken die zijn aangevraagd door het meest recente antwoord in plaats van de reeks te voorspellen van de verzonden waarden.

Uw app kan verzameling organiseren op basis van de stroomlogica en de beschikbare descriptors. Zie Bestellings- en e-mailverificatie voor verzamelingen. Elk antwoord bepaalt de beschikbare volgende bewerkingen.

Kenmerk- en paginadescriptors interpreteren

Elk antwoord beschrijft het huidige formulier. De volgende velden definiëren een kenmerk:

Veld Meaning
attributeId Inzendingssleutel.
inputType Type invoerbesturing, zoals , , , of datecheckboxMultiSelect. booleanpasswordtext
required Of een waarde moet worden opgegeven.
hidden Of het veld verborgen is.
canChange Informatie over bewerkbaarheid, indien opgenomen.
label Optioneel weergavelabel.
initialValue Optionele vooraf ingevulde waarde.
validation.validationRegEx Optioneel validatiepatroon.
options Optionele opties met label en value eigenschappen.
confirmationInput Optioneel bevestigingsgedrag, zoals retype, revealof none.

Geen lid nodig pages . De huidige attributes matrix definieert de velden en vereisten; metagegevens van paginagroepering, indien geretourneerd, zijn aanvullende presentatiegegevens. Invoerbesturingselementtypen wijzigen het inzendingsobject met tekenreekswaarden niet. Zie concepten van gebruikerskenmerken.

E-mail verifiëren

Wanneer voor het verzenden van kenmerken e-mailverificatie is vereist, wordt de wachtwoordcode verzonden en wordt het volgende geretourneerd:

{
  "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"
    }
  }
}

De service heeft de wachtwoordcode al verzonden; ga rechtstreeks verder met verificatie. Gebruik de geretourneerde lengte en gemaskeerde hint. Posten naar 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}"
}

Als u een andere code wilt aanvragen, plaatst u alleen de meest recente continuationToken naar de huidige resend koppeling, afhankelijk van servicelimieten.

Verificatie kan meer kenmerkverzamelingen retourneren:

{
  "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"
    }
  }
}

Verzend de aangevraagde waarden en ga verder met het verwerken van het volgende antwoord.

Beleidsvereisten en autorisatie voltooien

Nadat het account is gemaakt en elke vereiste verificatie, moet u alle vereisten voor meervoudige verificatie (MFA) en voorwaardelijke toegang voltooien voordat u de autorisatie hervat.

Als het antwoord een andere methodevraag aangeeft, gebruikt u de gedeelde uitdaging en verificatiebewerkingen. Methoderegistratie verschilt van het verifiëren van een registratie-e-mail. Zie Methodedetectie en -registratie voor het inschrijvingscontract.

Wanneer de service wordt geretourneerd state: continue, volgt _links.continueu de autorisatie, hervat u de autorisatie en wisselt u de code uit. Hiermee worden tokens verkregen zonder een niet-gerelateerde aanmeldingstransactie te starten.

Fouten en levenscyclus

Gebruik de gedeelde foutenvelop. Gestructureerde validatievermeldingen kunnen codebevatten, message, attributeIds, en suggestionsoptioneel recovery.

Condition Status of gedrag projectverbruik
Ongeldig vervolgtoken 400 Start de stroom opnieuw.
Ontbrekend of ongeldig kenmerk 400 of een ander collectAttributes antwoord Feedback op veldniveau presenteren en gecorrigeerde waarden verzenden.
Gebruiker bestaat al 400 invalidRequest Bied algemene aanmeldings- of herstelrichtlijnen aan zonder onnodig accountbestaan bekend te maken.
Schending van wachtwoordbeleid 400 Een compatibel wachtwoord verzamelen.
Onjuiste wachtwoordcode voor e-mail 400 invalidGrant met innerError.code: invalidOneTimeCode Laat de gebruiker de code corrigeren met behulp van de bruikbare huidige status of een geadverteerd opnieuw verzenden.
Ontbrekende wachtwoordcode 400 invalidRequest Corrigeer de ontbrekende invoer.
Throttling 429 De richtlijnen voor opnieuw proberen van de server respecteren.
Niet-ondersteunde systeemeigen interactie state: redirect Stop systeemeigen aanvragen en bied het geconfigureerde browserpad of een duidelijke fout aan.

Andere fouten verwerken via hun werkelijke status en stabiele foutcodes. Behandel een verlopen transactie niet als een herstelbare onjuiste-codevermelding.

Het verzenden van kenmerken is niet idempotent nadat de gebruiker is gemaakt. Niet opnieuw afspelen geslaagde inzendingen, logboekgevoelige kenmerkwaarden of behandelen clientvalidatie als gezaghebbend.