Naslaginformatie over systeemeigen verificatie-API
Van toepassing op:
Externe tenants
van werknemers (meer informatie)
Met de systeemeigen verificatie van Microsoft Entra kunt u de gebruikersinterface van uw app in de clienttoepassing hosten in plaats van verificatie delegeren aan browsers, wat resulteert in een systeemeigen geïntegreerde verificatie-ervaring. Als ontwikkelaar hebt u volledige controle over het uiterlijk van de aanmeldingsinterface.
In dit API-naslagartikel worden details beschreven die alleen vereist zijn wanneer u handmatig onbewerkte HTTP-aanvragen uitvoert om de stroom uit te voeren. We raden deze methode echter niet aan. Gebruik dus, indien mogelijk, een door Microsoft gebouwde en ondersteunde verificatie-SDK. Zie Zelfstudie: Uw mobiele Android-app voorbereiden voor systeemeigen verificatie en zelfstudie: Uw mobiele iOS-/macOS-app voorbereiden voor systeemeigen verificatie voor meer informatie over het gebruik van de SDK.
Wanneer een aanroep naar de API-eindpunten is geslaagd, ontvangt u zowel een id-token voor gebruikersidentificatie als een toegangstoken om beveiligde API's aan te roepen. Alle antwoorden van de API hebben een JSON-indeling.
De systeemeigen verificatie-API van Microsoft Entra ondersteunt registratie en aanmelding voor twee verificatiemethoden:
E-mail met wachtwoord, die registratie en aanmelding ondersteunt met een e-mailadres en wachtwoord, en selfservice voor wachtwoordherstel (SSPR).
Een eenmalige wachtwoordcode per e-mail verzenden, die ondersteuning biedt voor registratie en aanmelding met eenmalige wachtwoordcode voor e-mail.
Notitie
Momenteel bieden de systeemeigen verificatie-API-eindpunten geen ondersteuning voor Cross-Origin Resource Sharing (CORS).
Voorwaarden
Een externe Microsoft Entra-tenant. Als u er nog geen hebt, maakt u een externe tenant.
Als u dit nog niet hebt gedaan, registreert u een toepassing in het Microsoft Entra-beheercentrum. Zorg ervoor dat u gedelegeerde machtigingen verleent en openbare client- en systeemeigen verificatiestromen inschakelt.
Als u dit nog niet hebt gedaan, maakt u een gebruikersstroom in het Microsoft Entra-beheercentrum. Wanneer u de gebruikersstroom maakt, noteert u de gebruikerskenmerken die u zo nodig configureert, omdat deze kenmerken de kenmerken zijn die door Microsoft Entra worden verwacht dat uw app wordt verzonden.
Registreer voor de aanmeldingsstroom een klantgebruiker die u gebruikt voor het testen van de aanmeldings-API's. U kunt deze testgebruiker ook ophalen nadat u de registratiestroom hebt uitgevoerd.
Schakel voor de SSPR-stroom selfservice voor wachtwoordherstel in voor klantgebruikers in de externe tenant. SSPR is beschikbaar voor klantgebruikers die e-mail met wachtwoordverificatiemethode gebruiken.
Vervolgtoken
Telkens wanneer u een eindpunt aanroept in een van de stromen, aanmelding, registratie of SSPR, bevat het eindpunt een vervolgtoken in het antwoord. Het vervolgtoken is een unieke id die door Microsoft Entra ID wordt gebruikt om de status tussen aanroepen naar verschillende eindpunten binnen dezelfde stroom te behouden. U moet dit token opnemen in de volgende aanvragen in dezelfde stroom.
Elk vervolgtoken is geldig voor een specifieke periode en kan alleen worden gebruikt voor de volgende aanvragen binnen dezelfde stroom.
Naslaginformatie over de registratie-API
Als u een aanmeldingsstroom van een gebruiker voor beide verificatiemethoden wilt voltooien, communiceert uw app met vier eindpunten, /signup/v1.0/start, /signup/v1.0/challenge, /signup/v1.0/continueen /token.
API-eindpunten registreren
| Eindpunt | Beschrijving |
|---|---|
/signup/v1.0/start |
Met dit eindpunt wordt de registratiestroom gestart. U geeft geldige toepassings-id, nieuwe gebruikersnaam en uitdagingstype door. Vervolgens krijgt u een nieuw vervolgtoken terug. Het eindpunt kan een antwoord retourneren om aan te geven dat de toepassing een webverificatiestroom gebruikt als de gekozen verificatiemethoden van de toepassing niet worden ondersteund door Microsoft Entra. |
/signup/v1.0/challenge |
Uw app roept dit eindpunt aan met een lijst met uitdagingstypen die worden ondersteund door Microsoft Entra. Microsoft Entra selecteert vervolgens een van de ondersteunde verificatiemethoden waarmee de gebruiker zich kan verifiëren. |
/signup/v1.0/continue |
Dit eindpunt helpt bij het voortzetten van de stroom om het gebruikersaccount te maken of de stroom te onderbreken vanwege ontbrekende vereisten, zoals vereisten voor wachtwoordbeleid of onjuiste kenmerkindelingen. Dit eindpunt genereert een vervolgtoken en retourneert het vervolgens naar de app. Het eindpunt kan een antwoord retourneren om aan te geven dat de toepassing een webverificatiestroom moet gebruiken als de toepassing geen verificatiemethode heeft gekozen door Microsoft Entra. |
/token |
De toepassing roept dit eindpunt aan om tot slot beveiligingstokens aan te vragen. De app moet het vervolgtoken opnemen dat wordt verkregen van de laatste geslaagde aanroep naar het /signup/v1.0/continue eindpunt. |
Typen aanmeldingsuitdaging
Met de API kan de client-app de verificatiemethoden adverteren die worden ondersteund, wanneer deze een aanroep naar Microsoft Entra doet. Hiervoor gebruikt de app de challenge_type parameter in de aanvraag van de app. Deze parameter bevat vooraf gedefinieerde waarden, die verschillende verificatiemethoden vertegenwoordigen.
Meer informatie over uitdagingstypen in de systeemeigen verificatievraagtypen. In dit artikel worden de waarden voor het type uitdaging uitgelegd die u moet gebruiken voor een verificatiemethode.
Details van registratiestroomprotocol
In het sequentiediagram ziet u de stroom van het registratieproces.
Dit diagram geeft aan dat de app de gebruikersnaam (e-mail), het wachtwoord (voor e-mail met methoden voor wachtwoordverificatie) en kenmerken van de gebruiker op verschillende tijdstippen verzamelt (en mogelijk op afzonderlijke schermen). U kunt uw app echter ontwerpen om de gebruikersnaam (e-mailadres), het wachtwoord en alle vereiste en optionele kenmerkwaarden in hetzelfde scherm te verzamelen en vervolgens alle waarden via het eindpunt in te /signup/v1.0/start dienen. In dit geval hoeft de app geen oproepen te doen en antwoorden te verwerken voor de optionele stappen.
Stap 1: Aanvragen om de registratiestroom te starten
De registratiestroom begint met het indienen van een POST-aanvraag naar het /signup/v1.0/start eindpunt om de registratiestroom te starten.
Hier volgen voorbeelden van de aanvraag (we presenteren de voorbeeldaanvraag in meerdere regels voor leesbaarheid):
Voorbeeld 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
Voorbeeld 2 (gebruikerskenmerken en wachtwoord opnemen in de aanvraag):
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
| Parameter | Vereist | Beschrijving |
|---|---|---|
tenant_subdomain |
Ja | Het subdomein van de externe tenant die u hebt gemaakt. Vervang in de URL door {tenant_subdomain} het subdomein Directory (tenant). Als het primaire domein van uw tenant bijvoorbeeld contoso.onmicrosoft.com is, gebruikt u contoso. Als u uw tenantsubdomein niet hebt, leest u de details van uw tenant. |
client_id |
Ja | De toepassings-id (client) van de app die u hebt geregistreerd in het Microsoft Entra-beheercentrum. |
username |
Ja | E-mail van de klantgebruiker waarmee ze zich willen registreren, zoals contoso-consumer@contoso.com. |
challenge_type |
Ja | Een door spaties gescheiden lijst met tekenreeksen voor autorisatievraagtypen die door de app worden ondersteund, zoals oob password redirect. De lijst moet altijd het redirect type uitdaging bevatten. De waarde wordt verwacht of oob redirect oob password redirect voor e-mail met wachtwoordverificatiemethode. |
password |
Nee | De wachtwoordwaarde die de app verzamelt van de klantgebruiker. U kunt het wachtwoord van een gebruiker verzenden via het /signup/v1.0/start of later in het /signup/v1.0/continue eindpunt. Vervang {secure_password} door de wachtwoordwaarde die de app verzamelt van de klantgebruiker. Het is uw verantwoordelijkheid om te bevestigen dat de gebruiker op de hoogte is van het wachtwoord dat ze willen gebruiken door het veld wachtwoord bevestigen in de gebruikersinterface van de app op te geven. U moet er ook voor zorgen dat de gebruiker op de hoogte is van wat een sterk wachtwoord is volgens het beleid van uw organisatie. Meer informatie over het wachtwoordbeleid van Microsoft Entra. Deze parameter is alleen van toepassing op e-mail met wachtwoordverificatiemethode. |
attributes |
Nee | De waarden van de gebruiker kenmerken die door de app worden verzameld van de klantgebruiker. De waarde is een tekenreeks, maar opgemaakt als een JSON-object waarvan de sleutelwaarden programmeerbare naam van gebruikerskenmerken zijn. Deze kenmerken kunnen worden ingebouwd of aangepast en vereist of optioneel. De sleutelnamen van het object zijn afhankelijk van de kenmerken die de beheerder heeft geconfigureerd in het Microsoft Entra-beheercentrum. U kunt bepaalde of alle gebruikerskenmerken verzenden via het /signup/v1.0/start eindpunt of later in het /signup/v1.0/continue eindpunt. Als u alle vereiste kenmerken via het /signup/v1.0/start eindpunt verzendt, hoeft u geen kenmerken in het /signup/v1.0/continue eindpunt in te dienen. Als u echter bepaalde vereiste kenmerken via /signup/v1.0/start eindpunt indient, kunt u de resterende vereiste kenmerken later in het /signup/v1.0/continue eindpunt indienen. Vervang {given_name}respectievelijk {user_age} {postal_code} de naam, leeftijd en postcode die door de app worden verzameld van de klantgebruiker. Microsoft Entra negeert alle kenmerken die u verzendt, die niet bestaan. |
Geslaagd antwoord
Hier volgt een voorbeeld van een geslaagd antwoord:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "AQABAAEAAA…",
}
| Parameter | Beschrijving |
|---|---|
continuation_token |
Vervolgtoken dat Microsoft Entra retourneert. |
Als een app geen ondersteuning biedt voor een vereiste verificatiemethode door Microsoft Entra, is een terugval naar de webverificatiestroom nodig. In dit scenario informeert Microsoft Entra de app door een omleidingsvraagtype in het antwoord te retourneren:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parameter | Beschrijving |
|---|---|
challenge_type |
Microsoft Entra retourneert een antwoord met een uitdagingstype. De waarde van dit vraagtype is omleiding, waarmee de app de webverificatiestroom kan gebruiken. |
Dit antwoord wordt als geslaagd beschouwd, maar de app is vereist om over te schakelen naar een webverificatiestroom. In dit geval raden we u aan een door Microsoft gebouwde en ondersteunde verificatiebibliotheek te gebruiken.
Foutreactie
Voorbeeld:
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"
}
| Parameter | Beschrijving |
|---|---|
error |
Een foutcodetekenreeks die kan worden gebruikt voor het classificeren van typen fouten en om te reageren op fouten. |
error_description |
Een specifiek foutbericht waarmee u de oorzaak van een verificatiefout kunt identificeren. |
error_codes |
Een lijst met Microsoft Entra-specifieke foutcodes waarmee u fouten kunt diagnosticeren. |
timestamp |
Het tijdstip waarop de fout is opgetreden. |
trace_id |
Een unieke id voor de aanvraag die u kan helpen bij het diagnosticeren van fouten. |
correlation_id |
Een unieke id voor de aanvraag die kan helpen bij diagnostische gegevens over verschillende onderdelen. |
invalid_attributes |
Een lijst (matrix met objecten) van kenmerken waarvoor de validatie is mislukt. Dit antwoord is mogelijk als de app gebruikerskenmerken verzendt en de waarde van de suberror parameter attribute_validation_failed. |
suberror |
Een foutcodetekenreeks die kan worden gebruikt voor het verder classificeren van typen fouten. |
Hier volgen de mogelijke fouten die u kunt tegenkomen (mogelijke waarden van de error parameter):
| Foutwaarde | Beschrijving |
|---|---|
invalid_request |
Validatie van aanvraagparameter is mislukt, bijvoorbeeld wanneer de parameterwaarde van de challenge_type een niet-ondersteunde verificatiemethode bevat of de aanvraag geen parameter bevat client_id die de client-id-waarde leeg of ongeldig is. Gebruik de error_description parameter om de exacte oorzaak van de fout te leren. |
invalid_client |
De client-id die de app in de aanvraag opneemt, is voor een app die geen systeemeigen verificatieconfiguratie heeft, zoals het geen openbare client is of niet is ingeschakeld voor systeemeigen verificatie. Gebruik de suberror parameter om de exacte oorzaak van de fout te leren. |
unauthorized_client |
De client-id die in de aanvraag wordt gebruikt, heeft een geldige client-id-indeling, maar bestaat niet in de externe tenant of is onjuist. |
unsupported_challenge_type |
De challenge_type parameterwaarde bevat niet het redirect vraagtype. |
user_already_exists |
Gebruiker bestaat al. |
invalid_grant |
Het wachtwoord dat door de app wordt ingediend, voldoet niet aan alle complexiteitsvereisten, zoals het wachtwoord is te kort. Gebruik de suberror parameter om de exacte oorzaak van de fout te leren. Deze parameter is alleen van toepassing op e-mail met wachtwoordverificatiemethode. |
Als de foutparameter een waarde van invalid_grant heeft, bevat Microsoft Entra een suberror parameter in het antwoord. Hier volgen de mogelijke waarden van de suberror parameter voor een invalid_grant-fout :
| Suberrorwaarde | Beschrijving |
|---|---|
password_too_weak |
Het wachtwoord is te zwak omdat het niet voldoet aan de complexiteitsvereisten. Meer informatie over het wachtwoordbeleid van Microsoft Entra. Dit antwoord is mogelijk als de app een gebruikerswachtwoord indient. |
password_too_short |
Nieuw wachtwoord is minder dan 8 tekens. Meer informatie over het wachtwoordbeleid van Microsoft Entra. Dit antwoord is mogelijk als de app een gebruikerswachtwoord indient. |
password_too_long |
Nieuw wachtwoord is langer dan 256 tekens. Meer informatie over het wachtwoordbeleid van Microsoft Entra. Dit antwoord is mogelijk als de app een gebruikerswachtwoord indient. |
password_recently_used |
Het nieuwe wachtwoord mag niet hetzelfde zijn als het wachtwoord dat onlangs is gebruikt. Meer informatie over het wachtwoordbeleid van Microsoft Entra. Dit antwoord is mogelijk als de app een gebruikerswachtwoord indient. |
password_banned |
Nieuw wachtwoord bevat een woord, woordgroep of patroon dat wordt verboden. Meer informatie over het wachtwoordbeleid van Microsoft Entra. Dit antwoord is mogelijk als de app een gebruikerswachtwoord indient. |
password_is_invalid |
Het wachtwoord is ongeldig, bijvoorbeeld omdat er niet-toegestane tekens worden gebruikt. Meer informatie over het wachtwoordbeleid van Microsoft Entra. Dit antwoord is mogelijk als de app een gebruikerswachtwoord indient. |
Als de foutparameter een waarde van invalid_client heeft, bevat Microsoft Entra een suberror parameter in het antwoord. Hier volgen de mogelijke waarden van de suberror parameter voor een invalid_client-fout :
| Suberrorwaarde | Beschrijving |
|---|---|
nativeauthapi_disabled |
De client-id voor een app die niet is ingeschakeld voor systeemeigen verificatie. |
Notitie
Als u alle vereiste kenmerken via /signup/v1.0/start eindpunt verzendt, maar niet alle optionele kenmerken, kunt u later geen extra optionele kenmerken indienen via het /signup/v1.0/continue eindpunt. Microsoft Entra vraagt niet expliciet om optionele kenmerken, omdat ze niet verplicht zijn om de registratiestroom te voltooien. Zie de tabel in de sectie Gebruikerskenmerken verzenden naar eindpunten voor meer informatie over de gebruikerskenmerken die u naar de /signup/v1.0/start eindpunten kunt verzenden./signup/v1.0/continue
Stap 2: Een verificatiemethode selecteren
De app vraagt Microsoft Entra om een van de ondersteunde uitdagingstypen te selecteren waarmee de gebruiker zich kan verifiëren. Hiervoor roept de app het /signup/v1.0/challenge eindpunt aan. De app moet het vervolgtoken opnemen dat deze verkrijgt van het /signup/v1.0/start eindpunt in de aanvraag.
Hier volgt een voorbeeld van de aanvraag (we presenteren de voorbeeldaanvraag in meerdere regels voor leesbaarheid).
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…
| Parameter | Vereist | Beschrijving |
|---|---|---|
tenant_subdomain |
Ja | Het subdomein van de externe tenant die u hebt gemaakt. Vervang in de URL door {tenant_subdomain} het subdomein Directory (tenant). Als het primaire domein van uw tenant bijvoorbeeld contoso.onmicrosoft.com is, gebruikt u contoso. Als u uw tenantsubdomein niet hebt, leest u de details van uw tenant. |
client_id |
Ja | De toepassings-id (client) van de app die u hebt geregistreerd in het Microsoft Entra-beheercentrum. |
challenge_type |
Nee | Een door spaties gescheiden lijst met tekenreeksen voor autorisatievraagtypen die door de app worden ondersteund, zoals oob password redirect. De lijst moet altijd het redirect type uitdaging bevatten. De waarde wordt verwacht oob redirect voor eenmalige wachtwoordcode voor e-mail en oob password redirect voor e-mail met wachtwoordverificatiemethode. |
continuation_token |
Ja | Vervolgtoken dat Microsoft Entra in de vorige aanvraag heeft geretourneerd. |
Geslaagd antwoord
Microsoft Entra verzendt een eenmalige wachtwoordcode naar de e-mail van de gebruiker en reageert vervolgens met het vraagtype met de waarde van oob en aanvullende informatie over de eenmalige wachtwoordcode:
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
}
| Parameter | Beschrijving |
|---|---|
interval |
De tijdsduur in seconden moet de app wachten voordat wordt geprobeerd OTP opnieuw te verzenden. |
continuation_token |
Vervolgtoken dat Microsoft Entra retourneert. |
challenge_type |
Het type uitdaging waarmee de gebruiker zich kan verifiëren. |
binding_method |
De enige geldige waarde is een prompt. Deze parameter kan in de toekomst worden gebruikt om de gebruiker meer manieren te bieden om de eenmalige wachtwoordcode in te voeren. Uitgegeven als challenge_type oob is |
challenge_channel |
Het type kanaal waarmee de eenmalige wachtwoordcode is verzonden. Op dit moment wordt alleen e-mailkanaal ondersteund. |
challenge_target_label |
Een verborgen e-mail waar de eenmalige wachtwoordcode is verzonden. |
code_length |
De lengte van de eenmalige wachtwoordcode die Door Microsoft Entra wordt gegenereerd. |
Als een app geen ondersteuning biedt voor een vereiste verificatiemethode door Microsoft Entra, is een terugval naar de webverificatiestroom nodig. In dit scenario informeert Microsoft Entra de app door een omleidingsvraagtype in het antwoord te retourneren:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parameter | Beschrijving |
|---|---|
challenge_type |
Microsoft Entra retourneert een antwoord met een uitdagingstype. De waarde van dit vraagtype is omleiding, waarmee de app de webverificatiestroom kan gebruiken. |
Dit antwoord wordt als geslaagd beschouwd, maar de app is vereist om over te schakelen naar een webverificatiestroom. In dit geval raden we u aan een door Microsoft gebouwde en ondersteunde verificatiebibliotheek te gebruiken.
Foutreactie
Voorbeeld:
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"
}
| Parameter | Beschrijving |
|---|---|
error |
Een foutcodetekenreeks die kan worden gebruikt voor het classificeren van typen fouten en om te reageren op fouten. |
error_description |
Een specifiek foutbericht waarmee u de oorzaak van een verificatiefout kunt identificeren. |
error_codes |
Een lijst met Microsoft Entra-specifieke foutcodes waarmee u fouten kunt diagnosticeren. |
timestamp |
Het tijdstip waarop de fout is opgetreden. |
trace_id |
Een unieke id voor de aanvraag die u kan helpen bij het diagnosticeren van fouten. |
correlation_id |
Een unieke id voor de aanvraag die kan helpen bij diagnostische gegevens over verschillende onderdelen. |
Hier volgen de mogelijke fouten die u kunt tegenkomen (mogelijke waarden van de error parameter):
| Foutwaarde | Beschrijving |
|---|---|
invalid_request |
Validatie van aanvraagparameters is mislukt, zoals de client-id is leeg of ongeldig. |
expired_token |
Het vervolgtoken is verlopen. |
unsupported_challenge_type |
De challenge_type parameterwaarde bevat niet het redirect vraagtype. |
invalid_grant |
Het vervolgtoken is ongeldig. |
Stap 3: Eenmalige wachtwoordcode verzenden
De app verzendt de eenmalige wachtwoordcode die naar het e-mailadres van de gebruiker wordt verzonden. Omdat we eenmalige wachtwoordcode indienen, is een oob parameter vereist en moet de grant_type parameter een waarde-oob hebben.
Hier volgt een voorbeeld van de aanvraag (we presenteren de voorbeeldaanvraag in meerdere regels voor leesbaarheid):
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}
| Parameter | Vereist | Beschrijving |
|---|---|---|
tenant_subdomain |
Ja | Het subdomein van de externe tenant die u hebt gemaakt. Vervang in de URL door {tenant_subdomain} het subdomein Directory (tenant). Als het primaire domein van uw tenant bijvoorbeeld contoso.onmicrosoft.com is, gebruikt u contoso. Als u uw tenantsubdomein niet hebt, leest u de details van uw tenant. |
continuation_token |
Ja | Vervolgtoken dat Microsoft Entra in de vorige aanvraag heeft geretourneerd. |
client_id |
Ja | De toepassings-id (client) van de app die u hebt geregistreerd in het Microsoft Entra-beheercentrum. |
grant_type |
Ja | Een aanvraag naar het /signup/v1.0/continue eindpunt kan worden gebruikt om eenmalige wachtwoordcode, wachtwoord of gebruikerskenmerken te verzenden. In dit geval wordt de grant_type waarde gebruikt om onderscheid te maken tussen deze drie use cases. De mogelijke waarden voor de grant_type zijn oob, wachtwoord, kenmerken. In deze aanroep, omdat we eenmalige wachtwoordcode verzenden, wordt verwacht dat de waarde oob is. |
oob |
Ja | De eenmalige wachtwoordcode die de klant heeft ontvangen in zijn e-mail. Vervang door {otp_code} de eenmalige wachtwoordcodewaarden die de klant in zijn e-mail heeft ontvangen. Als u een eenmalige wachtwoordcode opnieuw wilt verzenden, moet de app opnieuw een aanvraag naar het /signup/v1.0/challenge eindpunt indienen. |
Zodra de app de eenmalige wachtwoordcode heeft ingediend, is de registratiestroom afhankelijk van de scenario's zoals weergegeven in de tabel:
| Scenario | Doorgaan |
|---|---|
De app verzendt het wachtwoord van de gebruiker (voor e-mail met wachtwoordverificatiemethode) via het /signup/v1.0/start eindpunt en er worden geen kenmerken geconfigureerd in het Microsoft Entra-beheercentrum of alle vereiste gebruikerskenmerken worden verzonden via het /signup/v1.0/start eindpunt. |
Microsoft Entra geeft een vervolgtoken uit. De app kan het vervolgtoken gebruiken om beveiligingstokens aan te vragen, zoals wordt weergegeven in stap 5. |
De app verzendt het wachtwoord van de gebruiker (voor e-mail met wachtwoordverificatiemethode) via de /signup/v1.0/start, maar niet alle vereiste gebruikerskenmerken, Microsoft Entra geeft de kenmerken aan die de app moet verzenden zoals wordt weergegeven in gebruikerskenmerken die vereist zijn. |
De app moet de vereiste gebruikerskenmerken verzenden via het /signup/v1.0/continue eindpunt. Het antwoord is vergelijkbaar met het antwoord in gebruikerskenmerken die vereist zijn. Verzend de gebruikerskenmerken die worden weergegeven in gebruikerskenmerken verzenden. |
De app verzendt het wachtwoord van de gebruiker (voor e-mail met wachtwoordverificatiemethode) niet via /signup/v1.0/start eindpunt. |
Het antwoord van Microsoft Entra geeft aan dat de referentie is vereist. Zie het antwoord. Dit antwoord is mogelijk voor e-mail met wachtwoordverificatiemethode. |
Antwoord
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..."
}
| Parameter | Beschrijving |
|---|---|
error |
Een foutcodetekenreeks die kan worden gebruikt voor het classificeren van typen fouten en om te reageren op fouten. |
error_description |
Een specifiek foutbericht waarmee u de oorzaak van een verificatiefout kunt identificeren. |
error_codes |
Een lijst met Microsoft Entra-specifieke foutcodes waarmee u fouten kunt diagnosticeren. |
timestamp |
Het tijdstip waarop de fout is opgetreden. |
trace_id |
Een unieke id voor de aanvraag die u kan helpen bij het diagnosticeren van fouten. |
correlation_id |
Een unieke id voor de aanvraag die kan helpen bij diagnostische gegevens over verschillende onderdelen. |
continuation_token |
Vervolgtoken dat Microsoft Entra retourneert. |
suberror |
Een foutcodetekenreeks die kan worden gebruikt voor het verder classificeren van typen fouten. |
Hier volgen de mogelijke fouten die u kunt tegenkomen (mogelijke waarden van de error parameter):
| Foutwaarde | Beschrijving |
|---|---|
credential_required |
Verificatie is vereist voor het maken van accounts, dus u moet een aanroep uitvoeren naar het /signup/v1.0/challenge eindpunt om te bepalen welke referenties de gebruiker moet opgeven. |
invalid_request |
Validatie van aanvraagparameter is mislukt, zoals een validatie van het vervolgtoken , of de aanvraag bevat client_id geen parameter die de waarde van de client-id leeg of ongeldig is of de externe tenantbeheerder heeft geen e-mail OTP ingeschakeld voor alle tenantgebruikers. |
invalid_grant |
Het toekenningstype dat is opgenomen in de aanvraag, is niet geldig of wordt ondersteund, of OTP-waarde is onjuist. |
expired_token |
Het vervolgtoken dat in de aanvraag is opgenomen, is verlopen. |
Als de foutparameter een waarde van invalid_grant heeft, bevat Microsoft Entra een suberror parameter in het antwoord. Hier volgen de mogelijke waarden van de suberror parameter voor een invalid_grant-fout :
| Suberrorwaarde | Beschrijving |
|---|---|
invalid_oob_value |
De waarde van eenmalige wachtwoordcode is ongeldig. |
Om de wachtwoordreferenties van de gebruiker te kunnen verzamelen, moet de app het eindpunt aanroepen /signup/v1.0/challenge om de referenties te bepalen die de gebruiker moet opgeven.
Hier volgt een voorbeeld van de aanvraag (we presenteren de voorbeeldaanvraag in meerdere regels voor leesbaarheid):
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…
| Parameter | Vereist | Beschrijving |
|---|---|---|
tenant_subdomain |
Ja | Het subdomein van de externe tenant die u hebt gemaakt. Vervang in de URL door {tenant_subdomain} het subdomein Directory (tenant). Als het primaire domein van uw tenant bijvoorbeeld contoso.onmicrosoft.com is, gebruikt u contoso. Als u uw tenantsubdomein niet hebt, leest u de details van uw tenant. |
client_id |
Ja | De toepassings-id (client) van de app die u hebt geregistreerd in het Microsoft Entra-beheercentrum. |
challenge_type |
Nee | Een door spaties gescheiden lijst met tekenreeksen voor autorisatievraagtypen die door de app worden ondersteund, zoals oob password redirect. De lijst moet altijd het redirect type uitdaging bevatten. Voor de e-mail met aanmeldingsstroom voor wachtwoorden wordt verwacht dat deze waarde bevat password redirect. |
continuation_token |
Ja | Vervolgtoken dat Microsoft Entra in de vorige aanvraag heeft geretourneerd. |
Geslaagd antwoord
Als het wachtwoord de verificatiemethode is die is geconfigureerd voor de gebruiker in het Microsoft Entra-beheercentrum, wordt er een geslaagd antwoord met het vervolgtoken geretourneerd naar de app.
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "password",
"continuation_token": " AQABAAEAAAAty..."
}
| Parameter | Beschrijving |
|---|---|
challenge_type |
het wachtwoord wordt geretourneerd in het antwoord voor de vereiste referentie. |
continuation_token |
Vervolgtoken dat Microsoft Entra retourneert. |
Als een app geen ondersteuning biedt voor een vereiste verificatiemethode door Microsoft Entra, is een terugval naar de webverificatiestroom nodig. In dit scenario informeert Microsoft Entra de app door een omleidingsvraagtype in het antwoord te retourneren:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parameter | Beschrijving |
|---|---|
challenge_type |
Microsoft Entra retourneert een antwoord met een uitdagingstype. De waarde van dit vraagtype is omleiding, waarmee de app de webverificatiestroom kan gebruiken. |
Dit antwoord wordt als geslaagd beschouwd, maar de app is vereist om over te schakelen naar een webverificatiestroom. In dit geval raden we u aan een door Microsoft gebouwde en ondersteunde verificatiebibliotheek te gebruiken.
Stap 4: verifiëren en token ophalen om u te registreren
De app moet de referenties van de gebruiker indienen, in dit geval wachtwoord, dat Microsoft Entra in de vorige stap heeft aangevraagd. De app moet een wachtwoordreferentie indienen als dit niet via het /signup/v1.0/start eindpunt is gedaan. De app doet een aanvraag naar het /signup/v1.0/continue eindpunt om het wachtwoord in te dienen. Omdat we een wachtwoord indienen, is een password parameter vereist en moet de grant_type parameter een waardewachtwoord hebben.
Hier volgt een voorbeeld van de aanvraag (we presenteren de voorbeeldaanvraag in meerdere regels voor leesbaarheid):
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}
| Parameter | Vereist | Beschrijving |
|---|---|---|
tenant_subdomain |
Ja | Het subdomein van de externe tenant die u hebt gemaakt. Vervang in de URL door {tenant_subdomain} het subdomein Directory (tenant). Als het primaire domein van uw tenant bijvoorbeeld contoso.onmicrosoft.com is, gebruikt u contoso. Als u uw tenantsubdomein niet hebt, leest u de details van uw tenant. |
continuation_token |
Ja | Vervolgtoken dat Microsoft Entra in de vorige stap heeft geretourneerd. |
client_id |
Ja | De toepassings-id (client) van de app die u hebt geregistreerd in het Microsoft Entra-beheercentrum. |
grant_type |
Ja | Een aanvraag naar het /signup/v1.0/continue eindpunt kan worden gebruikt om eenmalige wachtwoordcode, wachtwoord of gebruikerskenmerken te verzenden. In dit geval wordt de grant_type waarde gebruikt om onderscheid te maken tussen deze drie use cases. De mogelijke waarden voor de grant_type zijn oob, wachtwoord, kenmerken. In deze aanroep, omdat we het wachtwoord van de gebruiker verzenden, is de waarde naar verwachting een wachtwoord. |
password |
Ja | De wachtwoordwaarde die de app verzamelt van de klantgebruiker. Vervang {secure_password} door de wachtwoordwaarde die de app verzamelt van de klantgebruiker. Het is uw verantwoordelijkheid om te bevestigen dat de gebruiker op de hoogte is van het wachtwoord dat ze willen gebruiken door het veld wachtwoord bevestigen in de gebruikersinterface van de app op te geven. U moet er ook voor zorgen dat de gebruiker op de hoogte is van wat een sterk wachtwoord is volgens het beleid van uw organisatie. Meer informatie over het wachtwoordbeleid van Microsoft Entra. |
Geslaagd antwoord
Als de aanvraag is geslaagd, maar er geen kenmerken zijn geconfigureerd in het Microsoft Entra-beheercentrum of alle vereiste kenmerken zijn verzonden via het /signup/v1.0/start eindpunt, krijgt de app een vervolgtoken zonder kenmerken in te dienen. De app kan het vervolgtoken gebruiken om beveiligingstokens aan te vragen, zoals wordt weergegeven in stap 5. Anders geeft het antwoord van Microsoft Entra aan dat de app vereiste kenmerken moet verzenden. Deze kenmerken, ingebouwd of aangepast, zijn geconfigureerd in het Microsoft Entra-beheercentrum door de tenantbeheerder.
Gebruikerskenmerken vereist
Dit antwoord vraagt de app om waarden in te dienen voor de naam, *leeftijd en telefoonkenmerken .
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]*$"
}
}
],
}
Notitie
Aangepaste kenmerken (ook wel directory-extensies genoemd) worden genoemd met behulp van de conventie extension_{appId-without-hyphens}_{attribute-name} waarbij {appId-without-hyphens} de stripped versie van de client-id voor de uitbreidings-app is. Als de client-id van de uitbreidings-app bijvoorbeeld is 2588a-bcdwh-tfeehj-jeeqw-ertc en de kenmerknaam hobby's is, wordt het aangepaste kenmerk benoemd alsextension_2588abcdwhtfeehjjeeqwertc_hobbies. Meer informatie over aangepaste kenmerken en extensie-app.
| Parameter | Beschrijving |
|---|---|
error |
Dit kenmerk wordt ingesteld als Microsoft Entra het gebruikersaccount niet kan maken omdat een kenmerk moet worden geverifieerd of ingediend. |
error_description |
Een specifiek foutbericht waarmee u de oorzaak van de fout kunt identificeren. |
error_codes |
Een lijst met Microsoft Entra-specifieke foutcodes waarmee u fouten kunt diagnosticeren. |
timestamp |
Het tijdstip waarop de fout is opgetreden. |
trace_id |
Een unieke id voor de aanvraag die u kan helpen bij het diagnosticeren van fouten. |
correlation_id |
Een unieke id voor de aanvraag die kan helpen bij diagnostische gegevens over verschillende onderdelen. |
continuation_token |
Vervolgtoken dat Microsoft Entra retourneert. |
required_attributes |
Een lijst (matrix met objecten) van kenmerken die de app nodig heeft om de volgende aanroep in te dienen om door te gaan. Deze kenmerken zijn de extra kenmerken die de app moet indienen, behalve de gebruikersnaam. Microsoft Entra bevat deze parameter is het antwoord als de waarde van error de parameter is attributes_required. |
Hier volgen de mogelijke fouten die u kunt tegenkomen (mogelijke waarden van de error parameter):
| Foutwaarde | Beschrijving |
|---|---|
invalid_request |
Validatie van aanvraagparameter is mislukt, zoals een validatie van het vervolgtoken is mislukt of de aanvraag bevat client_id geen parameter die de client-id-waarde leeg of ongeldig is. |
invalid_grant |
Het toekenningstype dat is opgenomen in de aanvraag, is niet geldig of wordt ondersteund. De mogelijke waarden voor het grant_type zijn oob, wachtwoord, kenmerken |
expired_token |
Het vervolgtoken dat in de aanvraag is opgenomen, is verlopen. |
attributes_required |
Een of meer gebruikerskenmerken zijn vereist. |
Als een app geen ondersteuning biedt voor een vereiste verificatiemethode door Microsoft Entra, is een terugval naar de webverificatiestroom nodig. In dit scenario informeert Microsoft Entra de app door een omleidingsvraagtype in het antwoord te retourneren:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parameter | Beschrijving |
|---|---|
challenge_type |
Microsoft Entra retourneert een antwoord met een uitdagingstype. De waarde van dit vraagtype is omleiding, waarmee de app de webverificatiestroom kan gebruiken. |
Dit antwoord wordt als geslaagd beschouwd, maar de app is vereist om over te schakelen naar een webverificatiestroom. In dit geval raden we u aan een door Microsoft gebouwde en ondersteunde verificatiebibliotheek te gebruiken.
Foutreactie
Voorbeeld:
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"
}
| Parameter | Beschrijving |
|---|---|
error |
Een foutcodetekenreeks die kan worden gebruikt voor het classificeren van typen fouten en om te reageren op fouten. |
error_description |
Een specifiek foutbericht waarmee u de oorzaak van een verificatiefout kunt identificeren. |
error_codes |
Een lijst met Microsoft Entra-specifieke foutcodes waarmee u fouten kunt diagnosticeren. |
timestamp |
Het tijdstip waarop de fout is opgetreden. |
trace_id |
Een unieke id voor de aanvraag die u kan helpen bij het diagnosticeren van fouten. |
correlation_id |
Een unieke id voor de aanvraag die kan helpen bij diagnostische gegevens over verschillende onderdelen. |
suberror |
Een foutcodetekenreeks die kan worden gebruikt voor het verder classificeren van typen fouten. |
Hier volgen de mogelijke fouten die u kunt tegenkomen (mogelijke waarden van de error parameter):
| Foutwaarde | Beschrijving |
|---|---|
invalid_request |
Validatie van aanvraagparameters is mislukt, bijvoorbeeld wanneer de challenge_type parameter een ongeldig uitdagingstype bevat. |
invalid_grant |
De ingediende subsidie is ongeldig, zoals het ingediende wachtwoord is te kort. Gebruik de suberror parameter om de exacte oorzaak van de fout te leren. |
expired_token |
Het vervolgtoken is verlopen. |
attributes_required |
Een of meer gebruikerskenmerken zijn vereist. |
Als de foutparameter een waarde van invalid_grant heeft, bevat Microsoft Entra een suberror parameter in het antwoord. Dit zijn de mogelijke waarden van de suberror parameter:
| Suberrorwaarde | Beschrijving |
|---|---|
password_too_weak |
Het wachtwoord is te zwak omdat het niet voldoet aan de complexiteitsvereisten. Meer informatie over het wachtwoordbeleid van Microsoft Entra. |
password_too_short |
Nieuw wachtwoord is minder dan 8 tekens. Meer informatie over het wachtwoordbeleid van Microsoft Entra. |
password_too_long |
Nieuw wachtwoord is langer dan 256 tekens. Meer informatie over het wachtwoordbeleid van Microsoft Entra. |
password_recently_used |
Het nieuwe wachtwoord mag niet hetzelfde zijn als het wachtwoord dat onlangs is gebruikt. Meer informatie over het wachtwoordbeleid van Microsoft Entra. |
password_banned |
Nieuw wachtwoord bevat een woord, woordgroep of patroon dat wordt verboden. Meer informatie over het wachtwoordbeleid van Microsoft Entra. |
password_is_invalid |
Het wachtwoord is ongeldig, bijvoorbeeld omdat er niet-toegestane tekens worden gebruikt. Meer informatie over het wachtwoordbeleid van Microsoft Entra. Dit antwoord is mogelijk als de app een gebruikerswachtwoord indient. |
Gebruikerskenmerken verzenden
Om door te gaan met de stroom, moet de app het eindpunt aanroepen /signup/v1.0/continue om de vereiste gebruikerskenmerken in te dienen. Omdat we kenmerken verzenden, is een attributes parameter vereist en moet de grant_type parameter een waarde hebben die gelijk is aan kenmerken.
Hier volgt een voorbeeld van de aanvraag (we presenteren de voorbeeldaanvraag in meerdere regels voor leesbaarheid):
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...
| Parameter | Vereist | Beschrijving |
|---|---|---|
tenant_subdomain |
Ja | Het subdomein van de externe tenant die u hebt gemaakt. Vervang in de URL door {tenant_subdomain} het subdomein Directory (tenant). Als het primaire domein van uw tenant bijvoorbeeld contoso.onmicrosoft.com is, gebruikt u contoso. Als u uw tenantsubdomein niet hebt, leest u de details van uw tenant. |
continuation_token |
Ja | Vervolgtoken dat Microsoft Entra in de vorige aanvraag heeft geretourneerd. |
client_id |
Ja | De toepassings-id (client) van de app die u hebt geregistreerd in het Microsoft Entra-beheercentrum. |
grant_type |
Ja | Een aanvraag naar het /signup/v1.0/continue eindpunt kan worden gebruikt om eenmalige wachtwoordcode, wachtwoord of gebruikerskenmerken te verzenden. In dit geval wordt de grant_type waarde gebruikt om onderscheid te maken tussen deze drie use cases. De mogelijke waarden voor de grant_type zijn oob, wachtwoord, kenmerken. In deze aanroep, omdat we gebruikerskenmerken verzenden, wordt verwacht dat de waarde kenmerken zijn. |
attributes |
Ja | De gebruikerskenmerkwaarden die de app verzamelt van de klantgebruiker. De waarde is een tekenreeks, maar opgemaakt als een JSON-object waarvan de sleutelwaarden de namen van gebruikerskenmerken zijn, ingebouwd of aangepast. De sleutelnamen van het object zijn afhankelijk van de kenmerken die de beheerder heeft geconfigureerd in het Microsoft Entra-beheercentrum. Vervang {given_name}respectievelijk {user_age} {postal_code} de naam, leeftijd en postcode die door de app worden verzameld van de klantgebruiker. Microsoft Entra negeert alle kenmerken die u verzendt, die niet bestaan. |
Geslaagd antwoord
Als de aanvraag is geslaagd, geeft Microsoft Entra een vervolgtoken uit, dat de app kan gebruiken om beveiligingstokens aan te vragen.
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "AQABAAEAAAYn..."
}
| Parameter | Beschrijving |
|---|---|
continuation_token |
Vervolgtoken dat Microsoft Entra retourneert. |
Als een app geen ondersteuning biedt voor een vereiste verificatiemethode door Microsoft Entra, is een terugval naar de webverificatiestroom nodig. In dit scenario informeert Microsoft Entra de app door een omleidingsvraagtype in het antwoord te retourneren:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parameter | Beschrijving |
|---|---|
challenge_type |
Microsoft Entra retourneert een antwoord met een uitdagingstype. De waarde van dit vraagtype is omleiding, waarmee de app de webverificatiestroom kan gebruiken. |
Dit antwoord wordt als geslaagd beschouwd, maar de app is vereist om over te schakelen naar een webverificatiestroom. In dit geval raden we u aan een door Microsoft gebouwde en ondersteunde verificatiebibliotheek te gebruiken.
Foutreactie
Voorbeeld:
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"
}
| Parameter | Beschrijving |
|---|---|
error |
Een foutcodetekenreeks die kan worden gebruikt voor het classificeren van typen fouten en om te reageren op fouten. |
error_description |
Een specifiek foutbericht waarmee u de oorzaak van een verificatiefout kunt identificeren. |
error_codes |
Een lijst met Microsoft Entra-specifieke foutcodes waarmee u fouten kunt diagnosticeren. |
timestamp |
Het tijdstip waarop de fout is opgetreden. |
trace_id |
Een unieke id voor de aanvraag die u kan helpen bij het diagnosticeren van fouten. |
correlation_id |
Een unieke id voor de aanvraag die kan helpen bij diagnostische gegevens over verschillende onderdelen. |
continuation_token |
Vervolgtoken dat Microsoft Entra retourneert. |
unverified_attributes |
Een lijst (matrix met objecten) van kenmerksleutelnamen die moeten worden geverifieerd. Deze parameter wordt opgenomen in het antwoord wanneer de waarde van de error parameter wordt verification_required. |
required_attributes |
Een lijst (matrix met objecten) van kenmerken die de app moet verzenden. Microsoft Entra bevat deze parameter in het antwoord wanneer de waarde van de error parameter is attributes_required. |
invalid_attributes |
Een lijst (matrix met objecten) van kenmerken waarvoor de validatie is mislukt. Deze parameter wordt opgenomen in het antwoord wanneer de waarde van de suberror parameter wordt attribute_validation_failed. |
suberror |
Een foutcodetekenreeks die kan worden gebruikt voor het verder classificeren van typen fouten. |
Hier volgen de mogelijke fouten die u kunt tegenkomen (mogelijke waarden van de error parameter):
| Foutwaarde | Beschrijving |
|---|---|
invalid_request |
Validatie van aanvraagparameter is mislukt, zoals een validatie van het vervolgtoken is mislukt of de aanvraag bevat client_id geen parameter die de client-id-waarde leeg of ongeldig is. |
invalid_grant |
Het opgegeven toekenningstype is ongeldig of wordt niet ondersteund of mislukt, zoals validatie van kenmerken is mislukt. Gebruik de suberror parameter om de exacte oorzaak van de fout te leren. |
expired_token |
Het vervolgtoken dat in de aanvraag is opgenomen, is verlopen. |
attributes_required |
Een of meer gebruikerskenmerken zijn vereist. |
Als de foutparameter een waarde van invalid_grant heeft, bevat Microsoft Entra een suberror parameter in het antwoord. Hier volgen de mogelijke waarden van de suberror parameter voor een invalid_grant-fout :
| Suberrorwaarde | Beschrijving |
|---|---|
attribute_validation_failed |
Validatie van gebruikerskenmerk is mislukt. invalid_attributes parameter bevat de lijst (matrix met objecten) van kenmerken die de validatie is mislukt. |
Stap 5: Aanvraag voor beveiligingstokens
De app doet een POST-aanvraag naar het /token eindpunt en biedt het vervolgtoken dat is verkregen uit de vorige stap om beveiligingstokens te verkrijgen.
Hier volgt een voorbeeld van de aanvraag (we presenteren de voorbeeldaanvraag in meerdere regels voor leesbaarheid):
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
| Parameter | Vereist | Beschrijving |
|---|---|---|
tenant_subdomain |
Ja | Het subdomein van de externe tenant die u hebt gemaakt. Vervang in de URL door {tenant_subdomain} het subdomein Directory (tenant). Als het primaire domein van uw tenant bijvoorbeeld contoso.onmicrosoft.com is, gebruikt u contoso. Als u uw tenantsubdomein niet hebt, leest u de details van uw tenant. |
client_id |
Ja | De toepassings-id (client) van de app die u hebt geregistreerd in het Microsoft Entra-beheercentrum. |
grant_type |
Ja | De parameterwaarde moet een vervolgtoken zijn. |
continuation_token |
Ja | Vervolgtoken dat Microsoft Entra in de vorige stap heeft geretourneerd. |
scope |
Ja | Een door spaties gescheiden lijst met bereiken waarvoor het toegangstoken geldig is. Vervang {scopes} door de geldige bereiken waarvoor het toegangstoken Microsoft Entra retourneert, geldig is. |
username |
Ja | E-mail van de klantgebruiker waarmee ze zich willen registreren, zoals contoso-consumer@contoso.com. |
Geslaagde reactie
Hier volgt een voorbeeld van een geslaagd antwoord:
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..."
}
| Parameter | Beschrijving |
|---|---|
access_token |
Het toegangstoken dat de app heeft aangevraagd vanuit het /token eindpunt. De app kan dit toegangstoken gebruiken om toegang aan te vragen tot beveiligde resources, zoals web-API's. |
token_type |
Geeft de waarde van het tokentype aan. Het enige type dat Microsoft Entra ondersteunt, is Bearer. |
expires_in |
De tijdsduur in seconden blijft het toegangstoken geldig. |
scopes |
Een door spaties gescheiden lijst met bereiken waarvoor het toegangstoken geldig is. |
refresh_token |
Een OAuth 2.0-vernieuwingstoken. De app kan dit token gebruiken om andere toegangstokens te verkrijgen nadat het huidige toegangstoken is verlopen. Vernieuwingstokens hebben een lange levensduur. Ze kunnen de toegang tot resources gedurende langere perioden behouden. Raadpleeg het artikel Het toegangstoken vernieuwen voor meer informatie over het vernieuwen van een toegangstoken . Opmerking: Alleen uitgegeven als offline_access bereik is aangevraagd. |
id_token |
Een JSON-webtoken (Jwt) dat wordt gebruikt om de klantgebruiker te identificeren. De app kan het token decoderen om informatie te lezen over de gebruiker die zich heeft aangemeld. De app kan de waarden in de cache opslaan en weergeven, en vertrouwelijke clients kunnen dit token gebruiken voor autorisatie. Zie ID-tokens voor meer informatie over id-tokens. Opmerking: Alleen uitgegeven als openid-bereik wordt aangevraagd. |
Foutreactie
Voorbeeld:
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"
}
| Parameter | Beschrijving |
|---|---|
error |
Een foutcodetekenreeks die kan worden gebruikt voor het classificeren van typen fouten en om te reageren op fouten. |
error_description |
Een specifiek foutbericht waarmee u de oorzaak van een verificatiefout kunt identificeren. |
error_codes |
Een lijst met Microsoft Entra-specifieke foutcodes waarmee u fouten kunt diagnosticeren. |
timestamp |
Het tijdstip waarop de fout is opgetreden. |
trace_id |
Een unieke id voor de aanvraag die u kan helpen bij het diagnosticeren van fouten. |
correlation_id |
Een unieke id voor de aanvraag die kan helpen bij diagnostische gegevens over verschillende onderdelen. |
Hier volgen de mogelijke fouten die u kunt tegenkomen (mogelijke waarden van de error parameter):
| Foutwaarde | Beschrijving |
|---|---|
invalid_request |
Validatie van aanvraagparameters is mislukt, zoals de client/app heeft geen toestemming voor de aangevraagde bereiken. |
invalid_grant |
Het vervolgtoken dat in de aanvraag is opgenomen, is ongeldig. |
unauthorized_client |
De client-id die in de aanvraag is opgenomen, is ongeldig of bestaat niet. |
unsupported_grant_type |
Het toekenningstype dat is opgenomen in de aanvraag, wordt niet ondersteund of is onjuist. |
Gebruikerskenmerken verzenden naar eindpunten
In het Microsoft Entra-beheercentrum kunt u gebruikerskenmerken configureren als vereist of optioneel. Deze configuratie bepaalt hoe Microsoft Entra reageert wanneer u een aanroep naar de eindpunten uitvoert. Optionele kenmerken zijn niet verplicht om de registratiestroom te voltooien. Als alle kenmerken optioneel zijn, moeten ze daarom worden ingediend voordat de gebruikersnaam wordt geverifieerd. Anders wordt de registratie voltooid zonder de optionele kenmerken.
De volgende tabel geeft een overzicht van wanneer het mogelijk is om gebruikerskenmerken naar Microsoft Entra-eindpunten te verzenden.
| Eindpunt | Vereiste kenmerken | Optionele kenmerken | Zowel vereiste als optionele kenmerken |
|---|---|---|---|
/signup/v1.0/start Eindpunt |
Ja | Ja | Ja |
/signup/v1.0/continue eindpunt vóór verificatie van gebruikersnaam |
Ja | Ja | Ja |
/signup/v1.0/continue eindpunt na verificatie van gebruikersnaam |
Ja | Nee | Ja |
Indeling van waarden voor gebruikerskenmerken
U geeft de gegevens op die u van de gebruiker wilt verzamelen door de instellingen voor de gebruikersstroom te configureren in het Microsoft Entra-beheercentrum. Gebruik het artikel Aangepaste gebruikerskenmerken verzamelen tijdens het registratieartikel voor informatie over het verzamelen van waarden voor zowel ingebouwde als aangepaste kenmerken.
U kunt ook het gebruikersinvoertype opgeven voor de kenmerken die u configureert. De volgende tabel bevat een overzicht van ondersteunde typen gebruikersinvoer en hoe u waarden verzendt die door de besturingselementen van de gebruikersinterface worden verzameld naar Microsoft Entra.
| Invoertype gebruiker | Notatie van ingediende waarden |
|---|---|
| Tekstvak | Eén waarde, zoals functie, Software Engineer. |
| SingleRadioSelect | Eén waarde, zoals Taal, Noors. |
| SelectievakjeMultiSelect | Een of meerdere waarden zoals hobby of hobby's, Dansen of Dansen, Zwemmen, Reizen. |
Hier volgt een voorbeeldaanvraag die laat zien hoe u de waarden van de kenmerken verzendt:
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...
Meer informatie over invoertypen voor gebruikerskenmerken in het artikel Invoertypen voor aangepaste gebruikerskenmerken.
Verwijzen naar gebruikerskenmerken
Wanneer u een gebruikersstroom voor registratie maakt, configureert u gebruikerskenmerken die u tijdens de registratie van de gebruiker wilt verzamelen. De namen van de gebruikerskenmerken in het Microsoft Entra-beheercentrum verschillen van de manier waarop u ernaar verwijst in de systeemeigen verificatie-API.
In het Microsoft Entra-beheercentrum wordt bijvoorbeeld verwezen naar displayName in de API.
Gebruik het artikel Gebruikersprofielkenmerken voor meer informatie over het verwijzen naar ingebouwde en aangepaste gebruikerskenmerken in de systeemeigen verificatie-API.
Naslaginformatie over de aanmeldings-API
Gebruikers moeten zich aanmelden met de verificatiemethode die ze gebruiken om zich te registreren. Gebruikers die zich bijvoorbeeld registreren met e-mail met wachtwoordverificatiemethode, moeten zich aanmelden bij e-mail en wachtwoord.
Als u beveiligingstokens wilt aanvragen, communiceert uw app met drie eindpunten, /initiate/challenge en /token.
Api-eindpunten voor aanmelden
| Eindpunt | Beschrijving |
|---|---|
/initiate |
Met dit eindpunt wordt de aanmeldingsstroom gestart. Als uw app deze aanroept met een gebruikersnaam van een gebruikersaccount dat al bestaat, retourneert deze een geslaagd antwoord met een vervolgtoken. Als uw app vraagt om verificatiemethoden te gebruiken die niet worden ondersteund door Microsoft Entra, kan dit eindpuntantwoord aangeven dat uw app een verificatiestroom op basis van een browser moet gebruiken. |
/challenge |
uw app roept dit eindpunt aan met een lijst met uitdagingstypen die worden ondersteund door de identiteitsservice. Onze identiteitsservice genereert en verzendt vervolgens een eenmalige wachtwoordcode naar het gekozen uitdagingskanaal, zoals e-mail. Als uw app dit eindpunt herhaaldelijk aanroept, wordt er steeds een nieuwe OTP verzonden wanneer er een oproep wordt gedaan. |
/token |
Dit eindpunt controleert de eenmalige wachtwoordcode die het ontvangt van uw app en geeft vervolgens beveiligingstokens aan uw app uit. |
Typen aanmeldingsuitdaging
Met de API kan de app de verificatiemethoden adverteren die door de app worden ondersteund, wanneer deze een aanroep naar Microsoft Entra doet. Hiervoor gebruikt de app de parameter in de challenge_type aanvragen. Deze parameter bevat vooraf gedefinieerde waarden, die verschillende verificatiemethoden vertegenwoordigen.
Voor een bepaalde verificatiemethode zijn de waarden voor het uitdagingstype die een app tijdens de registratiestroom naar Microsoft Entra verzendt, gelijk aan wanneer de app zich aanmeldt. De e-mail met wachtwoordverificatiemethode maakt bijvoorbeeld gebruik van oob-, wachtwoord - en omleidingstypewaarden voor registratie- en aanmeldingsstromen.
Meer informatie over uitdagingstypen in het artikel met systeemeigen verificatievraagtypen .
Details van aanmeldingsstroomprotocol
Het sequentiediagram toont de stroom van het aanmeldingsproces.
Nadat de app het e-mailadres van de gebruiker met OTP heeft geverifieerd, ontvangt deze beveiligingstokens. Als de bezorging van de eenmalige wachtwoordcode vertraging optreedt of nooit wordt bezorgd bij het e-mailadres van de gebruiker, kan de gebruiker een andere eenmalige wachtwoordcode aanvragen. Microsoft Entra verzendt een nieuwe eenmalige wachtwoordcode als de vorige niet is geverifieerd. Wanneer Microsoft Entra een eenmalige wachtwoordcode opnieuw verzendt, wordt de eerder verzonden code ongeldig gemaakt.
In de volgende secties vatten we de stroom van het sequentiediagram samen in drie basisstappen.
Stap 1: Aanvraag om de aanmeldingsstroom te starten
De verificatiestroom begint met het indienen van een POST-aanvraag naar het /initiate eindpunt om de aanmeldingsstroom te starten.
Hier volgt een voorbeeld van de aanvraag (we presenteren de voorbeeldaanvraag in meerdere regels voor leesbaarheid):
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
| Parameter | Vereist | Beschrijving |
|---|---|---|
tenant_subdomain |
Ja | Het subdomein van de externe tenant die u hebt gemaakt. Vervang in de URL door {tenant_subdomain} het subdomein Directory (tenant). Als het primaire domein van uw tenant bijvoorbeeld contoso.onmicrosoft.com is, gebruikt u contoso. Als u uw tenantsubdomein niet hebt, leest u de details van uw tenant. |
client_id |
Ja | De toepassings-id (client) van de app die u hebt geregistreerd in het Microsoft Entra-beheercentrum. |
username |
Ja | E-mail van de klantgebruiker, zoals contoso-consumer@contoso.com. |
challenge_type |
Ja | Een door spaties gescheiden lijst met tekenreeksen voor autorisatievraagtypen die door de app worden ondersteund, zoals oob password redirect. De lijst moet altijd het redirect type uitdaging bevatten. De waarde wordt verwacht oob redirect voor eenmalige wachtwoordcode voor e-mail en password redirect voor e-mail met wachtwoord. |
Geslaagd antwoord
Hier volgt een voorbeeld van een geslaagd antwoord:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| Parameter | Beschrijving |
|---|---|
continuation_token |
Vervolgtoken dat Microsoft Entra retourneert. |
Als een app geen ondersteuning biedt voor een vereiste verificatiemethode door Microsoft Entra, is een terugval naar de webverificatiestroom nodig. In dit scenario informeert Microsoft Entra de app door een omleidingsvraagtype in het antwoord te retourneren:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parameter | Beschrijving |
|---|---|
challenge_type |
Microsoft Entra retourneert een antwoord met een uitdagingstype. De waarde van dit vraagtype is omleiding, waarmee de app de webverificatiestroom kan gebruiken. |
Dit antwoord wordt als geslaagd beschouwd, maar de app is vereist om over te schakelen naar een webverificatiestroom. In dit geval raden we u aan een door Microsoft gebouwde en ondersteunde verificatiebibliotheek te gebruiken.
Foutreactie
Voorbeeld:
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"
}
| Parameter | Beschrijving |
|---|---|
error |
Een foutcodetekenreeks die kan worden gebruikt voor het classificeren van typen fouten en om te reageren op fouten. |
error_description |
Een specifiek foutbericht waarmee u de oorzaak van een verificatiefout kunt identificeren. |
error_codes |
Een lijst met Microsoft Entra-specifieke foutcodes waarmee u fouten kunt diagnosticeren. |
timestamp |
Het tijdstip waarop de fout is opgetreden. |
trace_id |
Een unieke id voor de aanvraag die u kan helpen bij het diagnosticeren van fouten. |
correlation_id |
Een unieke id voor de aanvraag die kan helpen bij diagnostische gegevens over verschillende onderdelen. |
Hier volgen de mogelijke fouten die u kunt tegenkomen (mogelijke waarden van de error parameter):
| Foutwaarde | Beschrijving |
|---|---|
invalid_request |
Validatie van aanvraagparameters is mislukt, bijvoorbeeld wanneer de challenge_type parameter een ongeldig uitdagingstype bevat. of de aanvraag bevat geen client_id parameter die de waarde van de client-id leeg of ongeldig is. Gebruik de error_description parameter om de exacte oorzaak van de fout te leren. |
unauthorized_client |
De client-id die in de aanvraag wordt gebruikt, heeft een geldige client-id-indeling, maar bestaat niet in de externe tenant of is onjuist. |
invalid_client |
De client-id die de app in de aanvraag opneemt, is voor een app die geen systeemeigen verificatieconfiguratie heeft, zoals het geen openbare client is of niet is ingeschakeld voor systeemeigen verificatie. Gebruik de suberror parameter om de exacte oorzaak van de fout te leren. |
user_not_found |
De gebruikersnaam bestaat niet. |
unsupported_challenge_type |
De challenge_type parameterwaarde bevat niet het redirect vraagtype. |
Als de foutparameter een waarde van invalid_client heeft, bevat Microsoft Entra een suberror parameter in het antwoord. Hier volgen de mogelijke waarden van de suberror parameter voor een invalid_client-fout :
| Suberrorwaarde | Beschrijving |
|---|---|
nativeauthapi_disabled |
De client-id voor een app die niet is ingeschakeld voor systeemeigen verificatie. |
Stap 2: Een verificatiemethode selecteren
Om door te gaan met de stroom, gebruikt de app het vervolgtoken dat wordt verkregen uit de vorige stap om Microsoft Entra aan te vragen om een van de ondersteunde uitdagingstypen te selecteren waarmee de gebruiker zich kan verifiëren. De app doet een POST-aanvraag naar het /challenge eindpunt.
Hier volgt een voorbeeld van de aanvraag (we presenteren de voorbeeldaanvraag in meerdere regels voor leesbaarheid):
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...
| Parameter | Vereist | Beschrijving |
|---|---|---|
tenant_subdomain |
Ja | Het subdomein van de externe tenant die u hebt gemaakt. Vervang in de URL door {tenant_subdomain} het subdomein Directory (tenant). Als het primaire domein van uw tenant bijvoorbeeld contoso.onmicrosoft.com is, gebruikt u contoso. Als u uw tenantsubdomein niet hebt, leest u de details van uw tenant. |
client_id |
Ja | De toepassings-id (client) van de app die u hebt geregistreerd in het Microsoft Entra-beheercentrum. |
continuation_token |
Ja | Vervolgtoken dat Microsoft Entra in de vorige aanvraag heeft geretourneerd. |
challenge_type |
Nee | Een door spaties gescheiden lijst met tekenreeksen voor autorisatievraagtypen die door de app worden ondersteund, zoals oob password redirect. De lijst moet altijd het redirect type uitdaging bevatten. De waarde wordt verwacht oob redirect voor eenmalige wachtwoordcode voor e-mail en password redirect voor e-mail met wachtwoord. |
Geslaagd antwoord
Als de tenantbeheerder eenmalige wachtwoordcode heeft geconfigureerd in het Microsoft Entra-beheercentrum als verificatiemethode van de gebruiker, verzendt Microsoft Entra een eenmalige wachtwoordcode naar de e-mail van de gebruiker en reageert vervolgens met een uitdagingstype oob en geeft meer informatie over de eenmalige wachtwoordcode.
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
}
| Parameter | Beschrijving |
|---|---|
continuation_token |
Vervolgtoken dat Microsoft Entra retourneert. |
challenge_type |
Het type uitdaging waarmee de gebruiker zich kan verifiëren. |
binding_method |
De enige geldige waarde is een prompt. Deze parameter kan in de toekomst worden gebruikt om de gebruiker meer manieren te bieden om de eenmalige wachtwoordcode in te voeren. Uitgegeven als challenge_type oob is |
challenge_channel |
Het type kanaal waarmee de eenmalige wachtwoordcode is verzonden. Op dit moment ondersteunen we e-mail. |
challenge_target_label |
Een verborgen e-mail waar de eenmalige wachtwoordcode is verzonden. |
code_length |
De lengte van de eenmalige wachtwoordcode die Door Microsoft Entra wordt gegenereerd. |
Als een app geen ondersteuning biedt voor een vereiste verificatiemethode door Microsoft Entra, is een terugval naar de webverificatiestroom nodig. In dit scenario informeert Microsoft Entra de app door een omleidingsvraagtype in het antwoord te retourneren:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parameter | Beschrijving |
|---|---|
challenge_type |
Microsoft Entra retourneert een antwoord met een uitdagingstype. De waarde van dit vraagtype is omleiding, waarmee de app de webverificatiestroom kan gebruiken. |
Dit antwoord wordt als geslaagd beschouwd, maar de app is vereist om over te schakelen naar een webverificatiestroom. In dit geval raden we u aan een door Microsoft gebouwde en ondersteunde verificatiebibliotheek te gebruiken.
Foutreactie
Voorbeeld:
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"
}
| Parameter | Beschrijving |
|---|---|
error |
Een foutcodetekenreeks die kan worden gebruikt voor het classificeren van typen fouten en om te reageren op fouten. |
error_description |
Een specifiek foutbericht waarmee u de oorzaak van een verificatiefout kunt identificeren. |
error_codes |
Een lijst met Microsoft Entra-specifieke foutcodes waarmee u fouten kunt diagnosticeren. |
timestamp |
Het tijdstip waarop de fout is opgetreden. |
trace_id |
Een unieke id voor de aanvraag die u kan helpen bij het diagnosticeren van fouten. |
correlation_id |
Een unieke id voor de aanvraag die kan helpen bij diagnostische gegevens over verschillende onderdelen. |
Hier volgen de mogelijke fouten die u kunt tegenkomen (mogelijke waarden van de error parameter):
| Foutwaarde | Beschrijving |
|---|---|
invalid_request |
Validatie van aanvraagparameters is mislukt, bijvoorbeeld wanneer de challenge_type parameter een ongeldig uitdagingstype bevat. |
invalid_grant |
Het vervolgtoken dat in de aanvraag is opgenomen, is niet geldig. |
expired_token |
Het vervolgtoken dat in de aanvraag is opgenomen, is verlopen. |
unsupported_challenge_type |
De challenge_type parameterwaarde bevat niet het redirect vraagtype. |
Stap 3: Aanvragen voor beveiligingstokens
De app doet een POST-aanvraag naar het /token eindpunt en verstrekt de referenties van de gebruiker die in de vorige stap zijn gekozen, in dit geval wachtwoord, om beveiligingstokens te verkrijgen.
Hier volgt een voorbeeld van de aanvraag (we presenteren de voorbeeldaanvraag in meerdere regels voor leesbaarheid):
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
| Parameter | Vereist | Beschrijving |
|---|---|---|
tenant_subdomain |
Ja | Het subdomein van de externe tenant die u hebt gemaakt. Vervang in de URL door {tenant_subdomain} het subdomein Directory (tenant). Als het primaire domein van uw tenant bijvoorbeeld contoso.onmicrosoft.com is, gebruikt u contoso. Als u uw tenantsubdomein niet hebt, leest u de details van uw tenant. |
client_id |
Ja | De toepassings-id (client) van de app die u hebt geregistreerd in het Microsoft Entra-beheercentrum. |
continuation_token |
Ja | Vervolgtoken dat Microsoft Entra in de vorige aanvraag heeft geretourneerd. |
grant_type |
Ja | De waarde moet een wachtwoord zijn voor e-mail met wachtwoordverificatiemethode en oob voor eenmalige verificatiemethode voor wachtwoordcode voor e-mail. |
scope |
Ja | Een door spaties gescheiden lijst met bereiken. Alle bereiken moeten afkomstig zijn van één resource, samen met OIDC-bereiken (OpenID Connect), zoals profiel, *openid en e-mail. De app moet een openid-bereik voor Microsoft Entra bevatten om een id-token uit te geven. De app moet offline_access bereik voor Microsoft Entra bevatten om een vernieuwingstoken uit te geven. Meer informatie over machtigingen en toestemming in het Microsoft Identity Platform. |
password |
Ja (voor e-mail met wachtwoord) |
De wachtwoordwaarde die de app verzamelt van de klantgebruiker. Vervang {secure_password} door de wachtwoordwaarde die de app verzamelt van de klantgebruiker. |
oob |
Ja (voor eenmalige wachtwoordcode voor e-mail) |
De eenmalige wachtwoordcode die de klant heeft ontvangen in zijn e-mail. Vervang {otp_code} door de eenmalige wachtwoordcode die de klant in zijn e-mail heeft ontvangen. Als u een eenmalige wachtwoordcode opnieuw wilt verzenden, moet de app opnieuw een aanvraag naar het /challenge eindpunt indienen. |
Geslaagde reactie
Hier volgt een voorbeeld van een geslaagd antwoord:
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..."
}
| Parameter | Beschrijving |
|---|---|
token_type |
Geeft de waarde van het tokentype aan. Het enige type dat Microsoft Entra ondersteunt, is Bearer. |
scopes |
Een door spaties gescheiden lijst met bereiken waarvoor het toegangstoken geldig is. |
expires_in |
De tijdsduur in seconden blijft het toegangstoken geldig. |
access_token |
Het toegangstoken dat de app heeft aangevraagd vanuit het /token eindpunt. De app kan dit toegangstoken gebruiken om toegang aan te vragen tot beveiligde resources, zoals web-API's. |
refresh_token |
Een OAuth 2.0-vernieuwingstoken. De app kan dit token gebruiken om andere toegangstokens te verkrijgen nadat het huidige toegangstoken is verlopen. Vernieuwingstokens hebben een lange levensduur. Ze kunnen de toegang tot resources gedurende langere perioden behouden. Raadpleeg het artikel Het toegangstoken vernieuwen voor meer informatie over het vernieuwen van een toegangstoken . Opmerking: Alleen uitgegeven als u offline_access bereik aanvraagt. |
id_token |
Een JSON-webtoken (Jwt) dat wordt gebruikt om de klantgebruiker te identificeren. De app kan het token decoderen om informatie op te vragen over de gebruiker die zich heeft aangemeld. De app kan de waarden in de cache opslaan en weergeven, en vertrouwelijke clients kunnen dit token gebruiken voor autorisatie. Zie ID-tokens voor meer informatie over id-tokens. Opmerking: Alleen uitgegeven als u openid-bereik aanvraagt. |
Foutreactie
Voorbeeld:
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"
}
| Parameter | Beschrijving |
|---|---|
error |
Een foutcodetekenreeks die kan worden gebruikt voor het classificeren van typen fouten en om te reageren op fouten. |
error_description |
Een specifiek foutbericht waarmee u de oorzaak van een verificatiefout kunt identificeren. |
error_codes |
Een lijst met Microsoft Entra-specifieke foutcodes waarmee u fouten kunt diagnosticeren. |
timestamp |
Het tijdstip waarop de fout is opgetreden. |
trace_id |
Een unieke id voor de aanvraag die u kan helpen bij het diagnosticeren van fouten. |
correlation_id |
Een unieke id voor de aanvraag die kan helpen bij diagnostische gegevens over verschillende onderdelen. |
Hier volgen de mogelijke fouten die u kunt tegenkomen (mogelijke waarden van de error parameter):
| Foutwaarde | Beschrijving |
|---|---|
invalid_request |
Validatie van aanvraagparameter is mislukt. Als u wilt weten wat er is gebeurd, gebruikt u het bericht in de foutbeschrijving. |
invalid_grant |
Het vervolgtoken dat is opgenomen in de aanvraag, is niet geldig of aanmeldingsreferenties van de klant die in de aanvraag zijn opgenomen, zijn ongeldig of het toekenningstype dat in de aanvraag is opgenomen, is onbekend. |
invalid_client |
De client-id die in de aanvraag is opgenomen, is niet voor een openbare client. |
expired_token |
Het vervolgtoken dat in de aanvraag is opgenomen, is verlopen. |
invalid_scope |
Een of meer van de bereiken die in de aanvraag zijn opgenomen, zijn ongeldig. |
Als de foutparameter een waarde van invalid_grant heeft, bevat Microsoft Entra een suberror parameter in het antwoord. Hier volgen de mogelijke waarden van de suberror parameter voor een invalid_grant-fout :
| Suberrorwaarde | Beschrijving |
|---|---|
invalid_oob_value |
De waarde van eenmalige wachtwoordcode is ongeldig. Met deze subfout wordt alleen eenmalige wachtwoordcode voor e-mail toegepast |
Selfservice voor wachtwoordherstel (SSPR)
Als u e-mail en wachtwoord gebruikt als verificatiemethode in uw app, gebruikt u de selfservice-API voor wachtwoordherstel (SSPR) om gebruikers in staat te stellen hun wachtwoord opnieuw in te stellen. Gebruik deze API om wachtwoord te vergeten of wachtwoordscenario's te wijzigen.
API-eindpunten voor selfservice voor wachtwoordherstel
Als u deze API wilt gebruiken, communiceert de app met het eindpunt dat wordt weergegeven in de volgende tabel:
| Eindpunt | Beschrijving |
|---|---|
/start |
Uw app roept dit eindpunt aan wanneer de klant het wachtwoord vergeten selecteert of de knop Wachtwoord wijzigen in de app selecteert. Dit eindpunt valideert de gebruikersnaam (e-mail) van de gebruiker en retourneert vervolgens een vervolgtoken voor gebruik in de stroom voor wachtwoordherstel. Als uw app vraagt om verificatiemethoden te gebruiken die niet worden ondersteund door Microsoft Entra, kan dit eindpuntantwoord aangeven dat uw app een verificatiestroom op basis van een browser moet gebruiken. |
/challenge |
Accepteert een lijst met uitdagingstypen die worden ondersteund door de client en het vervolgtoken. Er wordt een uitdaging uitgegeven aan een van de voorkeursherstelreferenties. Oob-uitdaging geeft bijvoorbeeld een out-of-band eenmalige wachtwoordcode uit aan het e-mailadres dat is gekoppeld aan het gebruikersaccount van de klant. Als uw app vraagt om verificatiemethoden te gebruiken die niet worden ondersteund door Microsoft Entra, kan dit eindpuntantwoord aangeven dat uw app een verificatiestroom op basis van een browser moet gebruiken. |
/continue |
Valideert de uitdaging die is uitgegeven door het /challenge eindpunt en retourneert vervolgens een vervolgtoken voor het /submit eindpunt of geeft een andere uitdaging aan de gebruiker. |
/submit |
Accepteert een nieuwe wachtwoordinvoer door de gebruiker, samen met het vervolgtoken om de stroom voor wachtwoordherstel te voltooien. Dit eindpunt geeft een ander vervolgtoken uit. |
/poll_completion |
Ten slotte kan de app het vervolgtoken gebruiken dat is uitgegeven door het /submit eindpunt om de status van de aanvraag voor wachtwoordherstel te controleren. |
Typen selfservice voor het opnieuw instellen van wachtwoorden
Met de API kan de app de verificatiemethoden adverteren die door de app worden ondersteund, wanneer deze een aanroep naar Microsoft Entra doet. Hiervoor gebruikt de app de parameter in de challenge_type aanvragen. Deze parameter bevat vooraf gedefinieerde waarden, die verschillende verificatiemethoden vertegenwoordigen.
Voor de SSPR-stroom zijn de waarden van het vraagtype oob en omleiding.
Meer informatie over uitdagingstypen in de systeemeigen verificatievraagtypen.
Details van het stroomprotocol voor selfservice voor wachtwoordherstel
In het sequentiediagram ziet u de stroom voor het proces voor het opnieuw instellen van wachtwoorden.
Dit diagram geeft aan dat de app op verschillende momenten gebruikersnaam (e-mailadres) en wachtwoord van de gebruiker verzamelt (en mogelijk op afzonderlijke schermen). U kunt uw app echter ontwerpen om de gebruikersnaam (e-mailadres) en het nieuwe wachtwoord op hetzelfde scherm te verzamelen. In dit geval bevat de app het wachtwoord en verzendt deze vervolgens via het /submit eindpunt waar het is vereist.
Stap 1: Aanvraag om de selfservice voor wachtwoordherstel te starten
De stroom voor het opnieuw instellen van wachtwoorden begint met de app die een POST-aanvraag naar het /start eindpunt verzendt om de selfservice voor wachtwoordherstel te starten.
Hier volgt een voorbeeld van de aanvraag (we presenteren de voorbeeldaanvraag in meerdere regels voor leesbaarheid):
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
| Parameter | Vereist | Beschrijving |
|---|---|---|
tenant_subdomain |
Ja | Het subdomein van de externe tenant die u hebt gemaakt. Vervang in de URL door {tenant_subdomain} het subdomein Directory (tenant). Als het primaire domein van uw tenant bijvoorbeeld contoso.onmicrosoft.com is, gebruikt u contoso. Als u uw tenantsubdomein niet hebt, leest u de details van uw tenant. |
client_id |
Ja | De toepassings-id (client) van de app die u hebt geregistreerd in het Microsoft Entra-beheercentrum. |
username |
Ja | E-mail van de klantgebruiker, zoals contoso-consumer@contoso.com. |
challenge_type |
Ja | Een door spaties gescheiden lijst met tekenreeksen voor autorisatievraagtypen die door de app worden ondersteund, zoals oob password redirect. De lijst moet altijd het redirect type uitdaging bevatten. Voor deze aanvraag zal de waarde naar verwachting bevatten oob redirect. |
Geslaagd antwoord
Voorbeeld:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| Parameter | Beschrijving |
|---|---|
continuation_token |
Vervolgtoken dat Microsoft Entra retourneert. |
Als een app geen ondersteuning biedt voor een vereiste verificatiemethode door Microsoft Entra, is een terugval naar de webverificatiestroom nodig. In dit scenario informeert Microsoft Entra de app door een omleidingsvraagtype in het antwoord te retourneren:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parameter | Beschrijving |
|---|---|
challenge_type |
Microsoft Entra retourneert een antwoord met een uitdagingstype. De waarde van dit vraagtype is omleiding, waarmee de app de webverificatiestroom kan gebruiken. |
Dit antwoord wordt als geslaagd beschouwd, maar de app is vereist om over te schakelen naar een webverificatiestroom. In dit geval raden we u aan een door Microsoft gebouwde en ondersteunde verificatiebibliotheek te gebruiken.
Foutreactie
Voorbeeld:
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"
}
| Parameter | Beschrijving |
|---|---|
error |
Een foutcodetekenreeks die kan worden gebruikt voor het classificeren van typen fouten en om te reageren op fouten. |
error_description |
Een specifiek foutbericht waarmee u de oorzaak van een verificatiefout kunt identificeren. |
error_codes |
Een lijst met Microsoft Entra-specifieke foutcodes waarmee u fouten kunt diagnosticeren. |
timestamp |
Het tijdstip waarop de fout is opgetreden. |
trace_id |
Een unieke id voor de aanvraag die u kan helpen bij het diagnosticeren van fouten. |
correlation_id |
Een unieke id voor de aanvraag die kan helpen bij diagnostische gegevens over verschillende onderdelen. |
Hier volgen de mogelijke fouten die u kunt tegenkomen (mogelijke waarden van de error parameter):
| Foutwaarde | Beschrijving |
|---|---|
invalid_request |
Validatie van aanvraagparameters is mislukt, bijvoorbeeld wanneer de challenge_type parameter een ongeldig vraagtype bevat of als de aanvraag geen parameter bevat client_id , is de client-id-waarde leeg of ongeldig. Gebruik de error_description parameter om de exacte oorzaak van de fout te leren. |
user_not_found |
De gebruikersnaam bestaat niet. |
unsupported_challenge_type |
De challenge_type parameterwaarde bevat niet het redirect vraagtype. |
invalid_client |
De client-id die de app in de aanvraag opneemt, is voor een app die geen systeemeigen verificatieconfiguratie heeft, zoals het geen openbare client is of niet is ingeschakeld voor systeemeigen verificatie. Gebruik de suberror parameter om de exacte oorzaak van de fout te leren. |
unauthorized_client |
De client-id die in de aanvraag wordt gebruikt, heeft een geldige client-id-indeling, maar bestaat niet in de externe tenant of is onjuist. |
Als de foutparameter een waarde van invalid_client heeft, bevat Microsoft Entra een suberror parameter in het antwoord. Hier volgen de mogelijke waarden van de suberror parameter voor een invalid_client-fout :
| Suberrorwaarde | Beschrijving |
|---|---|
nativeauthapi_disabled |
De client-id voor een app die niet is ingeschakeld voor systeemeigen verificatie. |
Stap 2: Een verificatiemethode selecteren
Om door te gaan met de stroom, gebruikt de app het vervolgtoken dat is verkregen uit de vorige stap om Microsoft Entra aan te vragen om een van de ondersteunde uitdagingstypen te selecteren waarmee de gebruiker zich kan verifiëren. De app doet een POST-aanvraag naar het /challenge eindpunt. Als deze aanvraag is geslaagd, verzendt Microsoft Entra een eenmalige wachtwoordcode naar het e-mailadres van het gebruikersaccount. Op dit moment ondersteunen we alleen e-mail OTP.
Hier volgt een voorbeeld (we presenteren de voorbeeldaanvraag in meerdere regels voor leesbaarheid):
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...
| Parameter | Vereist | Beschrijving |
|---|---|---|
tenant_subdomain |
Ja | Het subdomein van de externe tenant die u hebt gemaakt. Vervang in de URL door {tenant_subdomain} het subdomein Directory (tenant). Als het primaire domein van uw tenant bijvoorbeeld contoso.onmicrosoft.com is, gebruikt u contoso. Als u uw tenantsubdomein niet hebt, leest u de details van uw tenant. |
client_id |
Ja | De toepassings-id (client) van de app die u hebt geregistreerd in het Microsoft Entra-beheercentrum. |
continuation_token |
Ja | Vervolgtoken dat Microsoft Entra in de vorige aanvraag heeft geretourneerd. |
challenge_type |
Nee | Een door spaties gescheiden lijst met tekenreeksen voor autorisatievraagtypen die door de app worden ondersteund, zoals oob redirect. De lijst moet altijd het redirect type uitdaging bevatten. Voor deze aanvraag zal de waarde naar verwachting bevatten oob redirect. |
Geslaagd antwoord
Voorbeeld:
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
}
| Parameter | Beschrijving |
|---|---|
continuation_token |
Vervolgtoken dat Microsoft Entra retourneert. |
challenge_type |
Het type uitdaging waarmee de gebruiker zich kan verifiëren. |
binding_method |
De enige geldige waarde is een prompt. Deze parameter kan in de toekomst worden gebruikt om de gebruiker meer manieren te bieden om de eenmalige wachtwoordcode in te voeren. Uitgegeven als challenge_type oob is |
challenge_channel |
Het type kanaal waarmee de eenmalige wachtwoordcode is verzonden. Op dit moment ondersteunen we e-mail. |
challenge_target_label |
Een verborgen e-mail waar de eenmalige wachtwoordcode is verzonden. |
code_length |
De lengte van de eenmalige wachtwoordcode die Door Microsoft Entra wordt gegenereerd. |
Als een app geen ondersteuning biedt voor een vereiste verificatiemethode door Microsoft Entra, is een terugval naar de webverificatiestroom nodig. In dit scenario informeert Microsoft Entra de app door een omleidingsvraagtype in het antwoord te retourneren:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parameter | Beschrijving |
|---|---|
challenge_type |
Microsoft Entra retourneert een antwoord met een uitdagingstype. De waarde van dit vraagtype is omleiding, waarmee de app de webverificatiestroom kan gebruiken. |
Dit antwoord wordt als geslaagd beschouwd, maar de app is vereist om over te schakelen naar een webverificatiestroom. In dit geval raden we u aan een door Microsoft gebouwde en ondersteunde verificatiebibliotheek te gebruiken.
Foutreactie
Voorbeeld:
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"
}
| Parameter | Beschrijving |
|---|---|
error |
Een foutcodetekenreeks die kan worden gebruikt voor het classificeren van typen fouten en om te reageren op fouten. |
error_description |
Een specifiek foutbericht waarmee u de oorzaak van een verificatiefout kunt identificeren. |
error_codes |
Een lijst met Microsoft Entra-specifieke foutcodes waarmee u fouten kunt diagnosticeren. |
timestamp |
Het tijdstip waarop de fout is opgetreden. |
trace_id |
Een unieke id voor de aanvraag die u kan helpen bij het diagnosticeren van fouten. |
correlation_id |
Een unieke id voor de aanvraag die kan helpen bij diagnostische gegevens over verschillende onderdelen. |
Hier volgen de mogelijke fouten die u kunt tegenkomen (mogelijke waarden van de error parameter):
| Foutwaarde | Beschrijving |
|---|---|
invalid_request |
Validatie van aanvraagparameters is mislukt, bijvoorbeeld wanneer de challenge_type parameter een ongeldig uitdagingstype of vervolgtokenvalidatie bevat, is mislukt. |
expired_token |
Het vervolgtoken is verlopen. |
unsupported_challenge_type |
De challenge_type parameterwaarde bevat niet het redirect vraagtype. |
Stap 3: Eenmalige wachtwoordcode verzenden
De app doet vervolgens een POST-aanvraag naar het /continue eindpunt. In de aanvraag moet de app de referenties van de gebruiker opnemen die in de vorige stap zijn gekozen en het vervolgtoken dat is uitgegeven vanuit het /challenge eindpunt.
Hier volgt een voorbeeld van de aanvraag (we presenteren de voorbeeldaanvraag in meerdere regels voor leesbaarheid):
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}
| Parameter | Vereist | Beschrijving |
|---|---|---|
tenant_subdomain |
Ja | Het subdomein van de externe tenant die u hebt gemaakt. Vervang in de URL door {tenant_subdomain} het subdomein Directory (tenant). Als het primaire domein van uw tenant bijvoorbeeld contoso.onmicrosoft.com is, gebruikt u contoso. Als u uw tenantsubdomein niet hebt, leest u de details van uw tenant. |
continuation_token |
Ja | Vervolgtoken dat Microsoft Entra in de vorige aanvraag heeft geretourneerd. |
client_id |
Ja | De toepassings-id (client) van de app die u hebt geregistreerd in het Microsoft Entra-beheercentrum. |
grant_type |
Ja | De enige geldige waarde is oob. |
oob |
Ja | De eenmalige wachtwoordcode die de klant heeft ontvangen in zijn e-mail. Vervang {otp_code} door de eenmalige wachtwoordcode die de klant in zijn e-mail heeft ontvangen. Als u een eenmalige wachtwoordcode opnieuw wilt verzenden, moet de app opnieuw een aanvraag naar het /challenge eindpunt indienen. |
Geslaagd antwoord
Voorbeeld:
HTTP/1.1 200 OK
Content-Type: application/json
{
"expires_in": 600,
"continuation_token": "czZCaGRSa3F0MzpnW...",
}
| Parameter | Beschrijving |
|---|---|
expires_in |
Tijd in seconden voordat de continuation_token verloopt. De maximumwaarde van expires_in 600 seconden. |
continuation_token |
Vervolgtoken dat Microsoft Entra retourneert. |
Foutreactie
Voorbeeld:
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"
}
| Parameter | Beschrijving |
|---|---|
error |
Een foutcodetekenreeks die kan worden gebruikt voor het classificeren van typen fouten en om te reageren op fouten. |
error_description |
Een specifiek foutbericht waarmee u de oorzaak van een verificatiefout kunt identificeren. |
error_codes |
Een lijst met Microsoft Entra-specifieke foutcodes waarmee u fouten kunt diagnosticeren. |
timestamp |
Het tijdstip waarop de fout is opgetreden. |
trace_id |
Een unieke id voor de aanvraag die u kan helpen bij het diagnosticeren van fouten. |
correlation_id |
Een unieke id voor de aanvraag die kan helpen bij diagnostische gegevens over verschillende onderdelen. |
suberror |
Een foutcodetekenreeks die kan worden gebruikt voor het verder classificeren van typen fouten. |
Hier volgen de mogelijke fouten die u kunt tegenkomen (mogelijke waarden van de error parameter):
| Foutwaarde | Beschrijving |
|---|---|
invalid_request |
Validatie van aanvraagparameters is mislukt, zoals een validatie van het vervolgtoken is mislukt of de aanvraag bevat client_id geen parameter die de client-id-waarde leeg of ongeldig is of de externe tenantbeheerder SSPR en e-mail OTP niet heeft ingeschakeld voor alle tenantgebruikers. Gebruik de error_description parameter om de exacte oorzaak van de fout te leren. |
invalid_grant |
Het toekenningstype is onbekend of komt niet overeen met de verwachte waarde van het toekenningstype. Gebruik de suberror parameter om de exacte oorzaak van de fout te leren. |
expired_token |
Het vervolgtoken is verlopen. |
Als de foutparameter een waarde van invalid_grant heeft, bevat Microsoft Entra een suberror parameter in het antwoord. Hier volgen de mogelijke waarden van de suberror parameter voor een invalid_grant-fout :
| Suberrorwaarde | Beschrijving |
|---|---|
invalid_oob_value |
De eenmalige wachtwoordcode die door de gebruiker is opgegeven, is ongeldig. |
Stap 4: Een nieuw wachtwoord indienen
De app verzamelt een nieuw wachtwoord van de gebruiker en gebruikt vervolgens het vervolgtoken dat door het /continue eindpunt is uitgegeven om het wachtwoord in te dienen door een POST-aanvraag naar het /submit eindpunt te verzenden.
Hier volgt een voorbeeld (we presenteren de voorbeeldaanvraag in meerdere regels voor leesbaarheid):
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}
| Parameter | Vereist | Beschrijving |
|---|---|---|
tenant_subdomain |
Ja | Het subdomein van de externe tenant die u hebt gemaakt. Vervang in de URL door {tenant_subdomain} het subdomein Directory (tenant). Als het primaire domein van uw tenant bijvoorbeeld contoso.onmicrosoft.com is, gebruikt u contoso. Als u uw tenantsubdomein niet hebt, leest u de details van uw tenant. |
continuation_token |
Ja | Vervolgtoken dat Microsoft Entra in de vorige aanvraag heeft geretourneerd. |
client_id |
Ja | De toepassings-id (client) van de app die u hebt geregistreerd in het Microsoft Entra-beheercentrum. |
new_password |
Ja | Het nieuwe wachtwoord van de gebruiker. Vervang {new_password} door het nieuwe wachtwoord van de gebruiker. Het is uw verantwoordelijkheid om te bevestigen dat de gebruiker op de hoogte is van het wachtwoord dat ze willen gebruiken door het veld wachtwoord bevestigen in de gebruikersinterface van de app op te geven. U moet er ook voor zorgen dat de gebruiker op de hoogte is van wat een sterk wachtwoord is volgens het beleid van uw organisatie. Meer informatie over het wachtwoordbeleid van Microsoft Entra. |
Geslaagd antwoord
Voorbeeld:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY...",
"poll_interval": 2
}
| Parameter | Beschrijving |
|---|---|
continuation_token |
Vervolgtoken dat Microsoft Entra retourneert. |
poll_interval |
De minimale hoeveelheid tijd in seconden dat de app moet wachten tussen polling-aanvragen om de status van de aanvraag voor wachtwoordherstel via het /poll_completion eindpunt te controleren, zie stap 5 |
Foutreactie
Voorbeeld:
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"
}
| Parameter | Beschrijving |
|---|---|
error |
Een foutcodetekenreeks die kan worden gebruikt voor het classificeren van typen fouten en om te reageren op fouten. |
error_description |
Een specifiek foutbericht waarmee u de oorzaak van een verificatiefout kunt identificeren. |
error_codes |
Een lijst met Microsoft Entra-specifieke foutcodes waarmee u fouten kunt diagnosticeren. |
timestamp |
Het tijdstip waarop de fout is opgetreden. |
trace_id |
Een unieke id voor de aanvraag die u kan helpen bij het diagnosticeren van fouten. |
correlation_id |
Een unieke id voor de aanvraag die kan helpen bij diagnostische gegevens over verschillende onderdelen. |
suberror |
Een foutcodetekenreeks die kan worden gebruikt voor het verder classificeren van typen fouten. |
Hier volgen de mogelijke fouten die u kunt tegenkomen (mogelijke waarden van de error parameter):
| Foutwaarde | Beschrijving |
|---|---|
invalid_request |
Validatie van aanvraagparameter is mislukt, zoals een validatie van het vervolgtoken is mislukt. |
expired_token |
Het vervolgtoken is verlopen. |
invalid_grant |
De ingediende subsidie is ongeldig, zoals het ingediende wachtwoord is te kort. Gebruik de suberror parameter om de exacte oorzaak van de fout te leren. |
Als de foutparameter een waarde van invalid_grant heeft, bevat Microsoft Entra een suberror parameter in het antwoord. Dit zijn de mogelijke waarden van de suberror parameter:
| Suberrorwaarde | Beschrijving |
|---|---|
password_too_weak |
Het wachtwoord is te zwak omdat het niet voldoet aan de complexiteitsvereisten. Meer informatie over het wachtwoordbeleid van Microsoft Entra. |
password_too_short |
Nieuw wachtwoord is minder dan 8 tekens. Meer informatie over het wachtwoordbeleid van Microsoft Entra. |
password_too_long |
Nieuw wachtwoord is langer dan 256 tekens. Meer informatie over het wachtwoordbeleid van Microsoft Entra. |
password_recently_used |
Het nieuwe wachtwoord mag niet hetzelfde zijn als het wachtwoord dat onlangs is gebruikt. Meer informatie over het wachtwoordbeleid van Microsoft Entra. |
password_banned |
Nieuw wachtwoord bevat een woord, woordgroep of patroon dat wordt verboden. Meer informatie over het wachtwoordbeleid van Microsoft Entra. |
password_is_invalid |
Het wachtwoord is ongeldig, bijvoorbeeld omdat er niet-toegestane tekens worden gebruikt. Meer informatie over het wachtwoordbeleid van Microsoft Entra. Dit antwoord is mogelijk als de app een gebruikerswachtwoord indient. |
Stap 5: Peiling voor de status van het opnieuw instellen van wachtwoorden
Ten slotte kan de app, sinds het bijwerken van de configuratie van de gebruiker met het nieuwe wachtwoord enige vertraging oplopen, het /poll_completion eindpunt gebruiken om Microsoft Entra te peilen voor de status van het opnieuw instellen van wachtwoorden. De minimale hoeveelheid tijd in seconden die de app moet wachten tussen polling-aanvragen, wordt geretourneerd vanaf het /submit eindpunt in de poll_interval parameter.
Hier volgt een voorbeeld (we presenteren de voorbeeldaanvraag in meerdere regels voor leesbaarheid):
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...
| Parameter | Vereist | Beschrijving |
|---|---|---|
tenant_subdomain |
Ja | Het subdomein van de externe tenant die u hebt gemaakt. Vervang in de URL door {tenant_subdomain} het subdomein Directory (tenant). Als het primaire domein van uw tenant bijvoorbeeld contoso.onmicrosoft.com is, gebruikt u contoso. Als u uw tenantsubdomein niet hebt, leest u de details van uw tenant. |
continuation_token |
Ja | Vervolgtoken dat Microsoft Entra in de vorige aanvraag heeft geretourneerd. |
client_id |
Ja | De toepassings-id (client) van de app die u hebt geregistreerd in het Microsoft Entra-beheercentrum. |
Geslaagd antwoord
Voorbeeld:
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "succeeded",
"continuation_token":"czZCaGRSa3F0..."
}
| Parameter | Beschrijving |
|---|---|
status |
De status van de wachtwoordaanvraag opnieuw instellen. Als Microsoft Entra de status Mislukt retourneert, kan de app het nieuwe wachtwoord opnieuw indienen door een andere aanvraag naar het /submit eindpunt te verzenden en het nieuwe vervolgtoken op te nemen. |
continuation_token |
Vervolgtoken dat Microsoft Entra retourneert. Als de status is geslaagd, kan de app het vervolgtoken gebruiken dat Microsoft Entra retourneert om via het /token eindpunt om beveiligingstokens aan te vragen, zoals wordt uitgelegd in stap 5 van de registratiestroom. Dit betekent dat nadat een gebruiker zijn wachtwoord opnieuw heeft ingesteld, u deze rechtstreeks kunt aanmelden bij uw app zonder een nieuwe aanmeldingsstroom te starten. |
Hier volgen de mogelijke statussen die Microsoft Entra retourneert (mogelijke waarden van de status parameter):
| Foutwaarde | Beschrijving |
|---|---|
succeeded |
Wachtwoord opnieuw instellen is voltooid. |
failed |
Wachtwoord opnieuw instellen is mislukt. De app kan het nieuwe wachtwoord opnieuw indienen door een andere aanvraag naar het /submit eindpunt te verzenden. |
not_started |
Het opnieuw instellen van het wachtwoord is niet gestart. De app kan de status later opnieuw controleren. |
in_progress |
Het opnieuw instellen van het wachtwoord wordt uitgevoerd. De app kan de status later opnieuw controleren. |
Foutreactie
Voorbeeld:
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"
}
| Parameter | Beschrijving |
|---|---|
error |
Een foutcodetekenreeks die kan worden gebruikt voor het classificeren van typen fouten en om te reageren op fouten. |
error_description |
Een specifiek foutbericht waarmee u de oorzaak van een verificatiefout kunt identificeren. |
error_codes |
Een lijst met Microsoft Entra-specifieke foutcodes waarmee u fouten kunt diagnosticeren. |
timestamp |
Het tijdstip waarop de fout is opgetreden. |
trace_id |
Een unieke id voor de aanvraag die u kan helpen bij het diagnosticeren van fouten. |
correlation_id |
Een unieke id voor de aanvraag die kan helpen bij diagnostische gegevens over verschillende onderdelen. |
Hier volgen de mogelijke fouten die u kunt tegenkomen (mogelijke waarden van de error parameter):
| Foutwaarde | Beschrijving |
|---|---|
invalid_request |
Validatie van aanvraagparameters is mislukt, zoals de validatie van het vervolgtoken is mislukt. |
expired_token |
Het vervolgtoken is verlopen. |