API-Referenz zur nativen Authentifizierung

Gilt für: Externe Mandanten (weitere Informationen)

Microsoft Entra native Authentifizierung ermöglicht es Ihnen, die Benutzeroberfläche Ihrer App in der Clientanwendung zu hosten, anstatt die Authentifizierung an Browser zu delegieren, was zu einer systemeigenen integrierten Authentifizierung führt. Als Entwickler haben Sie die volle Kontrolle über das Aussehen und Verhalten der Anmeldeschnittstelle.

Dieser Artikel zur API-Referenz beschreibt Details, die nur erforderlich sind, wenn Sie unformatierte HTTP-Anforderungen zum Ausführen des Flows manuell vornehmen. Wir empfehlen diesen Ansatz jedoch nicht. Verwenden Sie also nach Möglichkeit ein von Microsoft erstelltes und unterstütztes Authentifizierungs-SDK. Erfahren Sie mehr über systemeigene Authentifizierungs-SDKs. Wenn ein Aufruf zum API-Endpunkt erfolgreich ist, erhalten Sie sowohl ein ID-Token für die Benutzeridentifikation als auch ein Zugriffstoken zum Aufrufen geschützter APIs. Alle Antworten aus der API sind im JSON-Format.

die systemeigene Authentifizierungs-API von Microsoft Entra unterstützt die Registrierung und Anmeldung für zwei Authentifizierungsflüsse:

• Email mit Kennwort, das die Registrierung und Anmeldung mit einer Email und einem Kennwort sowie die Self-Service-Kennwortzurücksetzung (Self-Service Password Reset, SSPR) ermöglicht.

  • Nutzer, die sich mit E-Mail-Adresse und Passwort anmelden, melden sich auch mit Benutzernamen und Passwort an.

• Einmal-Passcode per E-Mail, der die Registrierung und Anmeldung mit einem Einmal-Passcode über E-Mail ermöglicht.

Voraussetzungen

1. Ein Microsoft Entra externer Mandant. Erstellen Sie einen externen Mandanten wenn Sie noch keinen haben.

2. Falls noch nicht geschehen, Registern Sie eine Anwendung im Microsoft Entra Admin Center. Stellen Sie sicher, dass:

   • Notieren Sie die Anwendungs-ID (Client-ID) und die Verzeichnis-ID (Mandant) für die spätere Verwendung.
   • Erteilen sie der Administratorzustimmung für die Anwendung.
   • Aktivieren Sie öffentliche Client- und systemeigene Authentifizierungsflüsse.

3. Wenn dies noch nicht geschehen ist, Create a user flow in the Microsoft Entra Admin Center. Beachten Sie beim Erstellen des Benutzerablaufs die Benutzerattribute, die Sie als erforderlich konfigurieren, da diese Attribute diejenigen sind, die Microsoft Entra erwarten, dass Ihre App übermittelt wird.

4. Ordnen Sie Ihre App-Registrierung dem Benutzerflow zu.

5. Für den Anmeldefluss registrieren Sie einen Kundennutzer, den Sie zum Testen des Ablaufs verwenden. Alternativ können Sie diesen Testbenutzer erhalten, nachdem Sie den Registrierungsflow ausgeführt haben.

6. Für den SSPR-Flow (Self-Service-Kennwortzurücksetzung) aktivieren Sie die Self-Service-Kennwortzurücksetzung für Kundenbenutzer im externen Mandanten. SSPR ist für Kundenbenutzer verfügbar, die die Authentifizierungsmethode „E-Mail mit Kennwort“ verwenden.

7. Wenn Sie Nutzern, die sich mit E-Mail-Adresse und Passwort anmelden, auch mit Benutzernamen und Passwort einloggen möchten, verwenden Sie die Schritte im Artikel " Mit Alias oder Benutzername anmelden ":

   1. Aktivieren Sie die Anmeldung mit dem Benutzernamen.
   2. Erstellen Sie Benutzer mit Benutzername im Admin Center , oder aktualisieren Sie vorhandene Benutzer, indem Sie einen Benutzernamen hinzufügen. Alternativ können Sie die Benutzererstellung und -aktualisierung in Ihrer App auch automatisieren, indem Sie microsoft Graph API verwenden.

8. Verwenden Sie zum Erzwingen der mehrstufigen Authentifizierung (MFA) für Ihre Kunden die Schritte unter Hinzufügen der mehrstufigen Authentifizierung (Multifactor Authentication, MFA) zu einer App , um Ihrem Anmeldeablauf MFA hinzuzufügen. Native Authentifizierung unterstützt einmalige E-Mail-Kennung und SMS als zweiten Faktor für MFA.

Fortsetzungstoken

Immer wenn Sie einen Anmelde-, Registrierungs- oder SSPR-Endpunkt aufrufen, enthält die Antwort ein Fortsetzungstoken. Dieses Token identifiziert den aktuellen Fluss eindeutig und ermöglicht es Microsoft Entra ID, den Zustand über seine Endpunkte hinweg aufrechtzuerhalten. Schließen Sie das Token in jede nachfolgende Anforderung in diesen Fluss ein. Sie ist nur für einen begrenzten Zeitraum gültig und kann nur für die nachfolgenden Anforderungen innerhalb desselben Flusses verwendet werden.

API-Referenz für die Anmeldung

Um den Registrierungsflow mit beiden Authentifizierungsmethoden für einen Benutzer abzuschließen, interagiert Ihre App mit vier Endpunkten: /signup/v1.0/start, /signup/v1.0/challenge, /signup/v1.0/continue und /token.

API-Endpunkte für die Anmeldung

Aufforderungstypen für die Registrierung

Die API ermöglicht der Client-App, die unterstützten Authentifizierungsmethoden anzukündigen, wenn sie einen Aufruf an Microsoft Entra. Dafür verwendet die App den Parameter challenge_type in der Anforderung der App. Dieser Parameter enthält vordefinierte Werte, die unterschiedliche Authentifizierungsmethoden darstellen.

Weitere Informationen zu den Aufforderungstypen finden Sie unter Aufforderungstypen für native Authentifizierung. In diesem Artikel werden die Abfragetypwerte erläutert, die Sie für eine Authentifizierungsmethode verwenden sollten.

Details des Registrierungsflowprotokolls

Das Sequenzdiagramm veranschaulicht den Flow des Registrierungsvorgangs.

Dieses Diagramm gibt an, dass die App Benutzernamen (E-Mail), Kennwort (für E-Mail mit Kennwortauthentifizierungsfluss) und Attribute des Benutzers zu unterschiedlichen Zeiten (und möglicherweise auf separaten Bildschirmen) sammelt. Sie können Ihre App jedoch so entwerfen, dass sie den Benutzernamen (E-Mail), das Kennwort und alle erforderlichen und optionalen Attributwerte auf demselben Bildschirm sammeln und dann alle an den /signup/v1.0/start Endpunkt übermitteln. Wenn die App alle erforderlichen Informationen an den /signup/v1.0/start Endpunkt übermittelt, muss die App in den optionalen Schritten keine Anrufe tätigen und Antworten behandeln.

In Schritt 21 ist der Benutzer bereits registriert. Wenn die App jedoch nach der Registrierung automatisch einen Benutzer anmelden muss, ruft die App den oauth/v2.0/token Endpunkt auf, um Sicherheitstoken anzufordern.

Schritt 1: Anforderung zum Starten des Registrierungsflows

Der Registrierungsflow beginnt mit der Anwendung, die eine POST-Anforderung an den /signup/v1.0/start-Endpunkt sendet, um den Registrierungsflow zu starten.

Hier sind Beispiele für die Anforderung (wir stellen die Beispielanforderung in mehreren Zeilen zur Lesbarkeit dar):

Beispiel 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 

Beispiel 2 (einschließen von Benutzerattributen und Kennwort in der Anforderung):

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 

Antwort bei Erfolg

Hier ist ein Beispiel für eine erfolgreiche Antwort:

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

{
    "continuation_token": "AQABAAEAAA…",
} 

Umleitungsantwort

Wenn die Client-App die Authentifizierungsmethode oder -funktionen, die Microsoft Entra erfordert, nicht unterstützt, ist ein Fallback auf den webbasierten Authentifizierungsfluss erforderlich. In diesem Szenario informiert Microsoft Entra die App durch Zurückgeben eines redirect Abfragetyps in der Antwort:

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

{     
   "challenge_type": "redirect" 
} 

Diese Antwort gilt als erfolgreich, die App muss jedoch zu einem webbasierten Authentifizierungsflow wechseln. In diesem Fall empfehlen wird Ihnen, eine von Microsoft erstellte und unterstützte Authentifizierungsbibliothek zu verwenden.

Fehlerantwort

Beispiel:

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

Hier sind die möglichen Fehler, auf die Sie stoßen können (mögliche Werte der error Eigenschaft):

Wenn der Fehlerparameter den Wert invalid_grant aufweist, enthält Microsoft Entra eine suberror-Eigenschaft in der Antwort. Hier sind die möglichen Werte der suberror Eigenschaft für einen invalid_grant Fehler:

Wenn der Fehlerparameter den Wert invalid_client aufweist, enthält Microsoft Entra eine suberror-Eigenschaft in der Antwort. Hier sind die möglichen Werte der suberror Eigenschaft für einen invalid_client Fehler:

Schritt 2: Authentifizierungsmethode auswählen

Die App fordert Microsoft Entra an, einen der unterstützten Abfragetypen auszuwählen, mit denen der Benutzer sich authentifizieren kann. Dazu tätigt die App einen Aufruf an den /signup/v1.0/challenge-Endpunkt. Die App muss das Fortsetzungstoken enthalten, das sie vom /signup/v1.0/start-Endpunkt in der Anforderung erhält.

Hier ist ein Beispiel für die Anforderung (zur besseren Lesbarkeit wird die Beispielanforderung in mehreren Zeilen dargestellt):

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…

Antwort bei Erfolg

Microsoft Entra eine einmalkennung an die E-Mail des Benutzers sendet, antwortet dann mit dem Abfragetyp mit dem Wert oob und weiteren Informationen zur einmaligen Kennung:

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
} 

Umleitungsantwort

Wenn die Client-App die Authentifizierungsmethode oder -funktionen, die Microsoft Entra erfordert, nicht unterstützt, ist ein Fallback auf den webbasierten Authentifizierungsfluss erforderlich. In diesem Szenario informiert Microsoft Entra die App durch Zurückgeben eines redirect Abfragetyps in der Antwort:

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

{
   "challenge_type": "redirect"
}

Diese Antwort gilt als erfolgreich, die App muss jedoch zu einem webbasierten Authentifizierungsflow wechseln. In diesem Fall empfehlen wird Ihnen, eine von Microsoft erstellte und unterstützte Authentifizierungsbibliothek zu verwenden.

Fehlerantwort

Beispiel:

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

Hier sind die möglichen Fehler, auf die Sie stoßen können (mögliche Werte der error Eigenschaft):

Schritt 3: Übermitteln eines Einmal-Passcodes

Die App übermittelt den Einmal-Passcode, der an die E-Mail-Adresse des Benutzers gesendet wurde. Da wir einen Einmal-Passcode übermitteln, ist ein oob-Parameter erforderlich, und der grant_type-Parameter muss den Wert oob aufweisen.

Hier ist ein Beispiel für die Anforderung (zur besseren Lesbarkeit wird die Beispielanforderung in mehreren Zeilen dargestellt):

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}

Nachdem die App den Einmal-Passcode erfolgreich übermittelt hat, hängt der Registrierungsflow von den Szenarien ab, wie in der Tabelle dargestellt:

Antwort

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

Hier sind die möglichen Fehler, auf die Sie stoßen können (mögliche Werte der error Eigenschaft):

Wenn der Fehlerparameter den Wert invalid_grant aufweist, enthält Microsoft Entra eine suberror-Eigenschaft in der Antwort. Hier sind die möglichen Werte der suberror Eigenschaft für einen invalid_grant Fehler:

Damit die Kennwortanmeldeinformationen vom Benutzer gesammelt werden, muss die App einen Aufruf an den /signup/v1.0/challenge-Endpunkt durchführen, um die Anmeldeinformationen zu ermitteln, die der Benutzer bereitstellen muss.

Hier ist ein Beispiel für die Anforderung (zur besseren Lesbarkeit wird die Beispielanforderung in mehreren Zeilen dargestellt):

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…

Antwort bei Erfolg

Wenn das Kennwort die für den Benutzer im Microsoft Entra Admin Center konfigurierte Authentifizierungsmethode ist, wird eine Erfolgsantwort mit dem Fortsetzungstoken an die App zurückgegeben.

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

{
    "challenge_type": "password",
    "continuation_token": " AQABAAEAAAAty..."
}

Umleitungsantwort

Wenn die Client-App die Authentifizierungsmethode oder -funktionen, die Microsoft Entra erfordert, nicht unterstützt, ist ein Fallback auf den webbasierten Authentifizierungsfluss erforderlich. In diesem Szenario informiert Microsoft Entra die App durch Zurückgeben eines redirect Abfragetyps in der Antwort:

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

{     
    "challenge_type": "redirect" 
} 

Diese Antwort gilt als erfolgreich, die App muss jedoch zu einem webbasierten Authentifizierungsflow wechseln. In diesem Fall empfehlen wird Ihnen, eine von Microsoft erstellte und unterstützte Authentifizierungsbibliothek zu verwenden.

Schritt 4: Authentifizieren und Abrufen eines Tokens für die Registrierung

In diesem Fall muss die App die Anmeldeinformationen des Benutzers übermitteln, die im vorherigen Schritt angefordert Microsoft Entra. Die App muss eine Kennwortanmeldeinformation übermitteln, wenn sie dies nicht über den /signup/v1.0/start-Endpunkt getan hat. Die App macht eine Anforderung an den /signup/v1.0/continue-Endpunkt auf, um das Kennwort zu übermitteln. Da wir ein Kennwort übermitteln, ist ein password-Parameter erforderlich, und der grant_type-Parameter muss über einen Wert Kennwort verfügen.

Hier ist ein Beispiel für die Anforderung (zur besseren Lesbarkeit wird die Beispielanforderung in mehreren Zeilen dargestellt):

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}

Antwort bei Erfolg

Wenn die Anforderung erfolgreich ist, aber keine Attribute im Microsoft Entra Admin Center konfiguriert wurden oder alle erforderlichen Attribute über den endpunkt /signup/v1.0/start übermittelt wurden, erhält die App ein Fortsetzungstoken, ohne Attribute zu übermitteln. Die App kann das Fortsetzungstoken verwenden, um Sicherheitstoken anzufordern, wie in "Anforderung für Sicherheitstoken" gezeigt. Andernfalls gibt Microsoft Entra Antwort an, dass die App erforderliche Attribute übermitteln muss. Diese attribute, integriert oder benutzerdefiniert, wurden vom Mandantenadministrator im Microsoft Entra Admin Center konfiguriert.

Benutzerattribute erforderlich

Diese Antwort fordert die App an, Werte für Namen-, Alters- und Telefonattribute zu übermitteln.

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]*$"
            }
        }
    ],
}

Hier sind die möglichen Fehler, auf die Sie stoßen können (mögliche Werte der error Eigenschaft):

Umleitungsantwort

Wenn die Client-App die Authentifizierungsmethode oder -funktionen, die Microsoft Entra erfordert, nicht unterstützt, ist ein Fallback auf den webbasierten Authentifizierungsfluss erforderlich. In diesem Szenario informiert Microsoft Entra die App durch Zurückgeben eines redirect Abfragetyps in der Antwort:

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

{     
   "challenge_type": "redirect" 
} 

Diese Antwort gilt als erfolgreich, die App muss jedoch zu einem webbasierten Authentifizierungsflow wechseln. In diesem Fall empfehlen wird Ihnen, eine von Microsoft erstellte und unterstützte Authentifizierungsbibliothek zu verwenden.

Fehlerantwort

Beispiel:

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

Hier sind die möglichen Fehler, auf die Sie stoßen können (mögliche Werte der error Eigenschaft):

Wenn der Fehlerparameter den Wert invalid_grant aufweist, enthält Microsoft Entra eine suberror-Eigenschaft in der Antwort. Hier sind die möglichen Werte der suberror Eigenschaft:

Benutzerattribute übermitteln

Um den Flow fortzusetzen, muss die App einen Aufruf an den /signup/v1.0/continue-Endpunkt durchführen, um die erforderlichen Benutzerattribute zu übermitteln. Da Attribute übermittelt werden, ist ein attributes-Parameter erforderlich, und der grant_type-Parameter muss einen Wert aufweisen, der attributes entspricht.

Hier ist ein Beispiel für die Anforderung (zur besseren Lesbarkeit wird die Beispielanforderung in mehreren Zeilen dargestellt):

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}", "postalCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...

Antwort bei Erfolg

Wenn die Anforderung erfolgreich ist, meldet Microsoft Entra den Benutzer an, und gibt dann ein Fortsetzungstoken aus. Die App kann das Fortsetzungstoken verwenden, um Sicherheitstoken vom oauth/v2.0/token Endpunkt anzufordern.

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

{  
    "continuation_token": "AQABAAEAAAYn..."
} 

Umleitungsantwort

Wenn die Client-App die Authentifizierungsmethode oder -funktionen, die Microsoft Entra erfordert, nicht unterstützt, ist ein Fallback auf den webbasierten Authentifizierungsfluss erforderlich. In diesem Szenario informiert Microsoft Entra die App durch Zurückgeben eines redirect Abfragetyps in der Antwort:

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

{     
   "challenge_type": "redirect" 
} 

Diese Antwort gilt als erfolgreich, die App muss jedoch zu einem webbasierten Authentifizierungsflow wechseln. In diesem Fall empfehlen wird Ihnen, eine von Microsoft erstellte und unterstützte Authentifizierungsbibliothek zu verwenden.

Fehlerantwort

Beispiel:

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

Hier sind die möglichen Fehler, auf die Sie stoßen können (mögliche Werte der error Eigenschaft):

Wenn der Fehlerparameter den Wert invalid_grant aufweist, enthält Microsoft Entra eine suberror-Eigenschaft in der Antwort. Hier sind die möglichen Werte der suberror Eigenschaft für einen invalid_grant Fehler:

Schritt 5: Automatische Anmeldung nach der Registrierung

Wenn sich der Benutzer nach der Registrierung automatisch anmelden muss, sendet die App eine POST-Anforderung an den oauth/v2.0/token Endpunkt und stellt das Fortsetzungstoken bereit, das aus dem vorherigen Schritt abgerufen wurde, um Sicherheitstoken zu erwerben. Erfahren Sie , wie Sie den Tokenendpunkt aufrufen.

Übermitteln von Benutzerattributen an Endpunkte

Im Microsoft Entra Admin Center können Sie Benutzerattribute nach Bedarf oder optional konfigurieren. Diese Konfiguration bestimmt, wie Microsoft Entra reagiert, wenn Sie einen Anruf an die Endpunkte tätigen. Optionale Attribute sind zum Abschließen des Registrierungsflows nicht zwingend erforderlich. Wenn also alle Attribute optional sind, müssen sie vor der Überprüfung des Benutzernamens übermittelt werden. Andernfalls wird die Registrierung ohne die optionalen Attribute abgeschlossen.

In der folgenden Tabelle wird zusammengefasst, wann es möglich ist, Benutzerattribute an Microsoft Entra Endpunkte zu übermitteln.

Format von Benutzerattributwerten

Sie geben die Informationen an, die Sie vom Benutzer sammeln möchten, indem Sie die Benutzerflusseinstellungen im Microsoft Entra Admin Center konfigurieren. Verwenden Sie den Artikel Sammeln von benutzerdefinierten Benutzerattributen während der Registrierung, um zu erfahren, wie Werte sowohl für integrierte als auch für benutzerdefinierte Attribute gesammelt werden.

Sie können auch den Benutzereingabetyp für die von Ihnen konfigurierten Attribute angeben. In der folgenden Tabelle werden die unterstützten Benutzereingabetypen und das Übermitteln von Werten, die von den UI-Steuerelementen gesammelt werden, an Microsoft Entra zusammengefasst.

Hier ist eine Beispielanforderung, die zeigt, wie Sie die Werte der Attribute übermitteln:

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...

Weitere Informationen zu Benutzerattribut-Eingabetypen finden Sie im Artikel Benutzerdefinierte Benutzerattribut-Eingabetypen.

Verweisen auf Benutzerattribute

Wenn Sie einen Benutzerflow für die Registrierung erstellen, konfigurieren Sie Benutzerattribute, die Sie während der Registrierung vom Benutzer sammeln möchten. Die Namen der Benutzerattribute im Microsoft Entra Admin Center unterscheiden sich von ihrer Referenz in der systemeigenen Authentifizierungs-API.

Beispielsweise wird im Microsoft Entra Admin Center auf DisplayName in der API als displayName verwiesen.

Verwenden Sie den Artikel Benutzerprofilattribute, um zu erfahren, wie Sie sowohl integrierte als auch benutzerdefinierte Benutzerattribute in der nativen Authentifizierungs-API referenzieren.

API-Referenz für den Anmeldefluss

Benutzer müssen sich mit der Authentifizierungsmethode anmelden, die sie für die Registrierung verwenden. Wenn sich Benutzer beispielsweise mit der Authentifizierungsmethode „E-Mail mit Kennwort“ registrieren, müssen sie sich auch mit dieser Methode anmelden.

Um Sicherheitstoken anzufordern, interagiert Ihre App mit drei Endpunkten, oauth/v2.0/initiate, , oauth/v2.0/challenge, oauth/v2.0/tokenund optional oauth/v2.0/introspect.

API-Endpunkte für die Anmeldung

Anmeldeaufforderungstypen

Die API ermöglicht der App, die unterstützten Authentifizierungsmethoden anzukündigen, wenn sie einen Aufruf an Microsoft Entra sendet. Dazu verwendet die App den challenge_type-Parameter in ihren Anforderungen. Dieser Parameter enthält vordefinierte Werte, die unterschiedliche Authentifizierungsmethoden darstellen.

Bei einer bestimmten Authentifizierungsmethode sind die Abfragetypwerte, die eine App während des Registrierungsablaufs an Microsoft Entra sendet, identisch mit der Anmeldung der App. Beispielsweise verwendet die Authentifizierungsmethode „E-Mail mit Kennwort“ für den Captcha-Typ die Werte oob, password und redirect sowohl für den Registrierungs- als auch für den Anmeldungsflow.

Weitere Informationen zu den Captcha-Typen finden Sie im Artikel Aufforderungstypen für native Authentifizierung.

Details des Anmeldeflowprotokolls

Das Sequenzdiagramm veranschaulicht den Flow des Anmeldeprozesses. Der Anmeldefluss hängt von der Authentifizierungsmethode des Benutzers ab.

In den folgenden Abschnitten fassen wir den Anmeldefluss in drei grundlegende Schritte zusammen.

Schritt 1: Anfordern, den Anmeldeflow zu starten

Der Authentifizierungsflow beginnt mit der Anwendung, die eine POST-Anforderung an den /initiate-Endpunkt sendet, um den Anmeldeflow zu starten.

Hier ist ein Beispiel für die Anforderung (zur besseren Lesbarkeit wird die Beispielanforderung in mehreren Zeilen dargestellt):

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
&capabilities=registration_required mfa_required

Antwort bei Erfolg

Hier ist ein Beispiel für eine erfolgreiche Antwort:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

Umleitungsantwort

Wenn die Client-App die Authentifizierungsmethode oder -funktionen, die Microsoft Entra erfordert, nicht unterstützt, ist ein Fallback auf den webbasierten Authentifizierungsfluss erforderlich. In diesem Szenario informiert Microsoft Entra die App durch Zurückgeben eines redirect Abfragetyps in der Antwort:

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

{     
   "challenge_type": "redirect" 
} 

Diese Antwort gilt als erfolgreich, die App muss jedoch zu einem webbasierten Authentifizierungsflow wechseln. In diesem Fall empfehlen wird Ihnen, eine von Microsoft erstellte und unterstützte Authentifizierungsbibliothek zu verwenden.

Fehlerantwort

Beispiel:

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

Hier sind die möglichen Fehler, auf die Sie stoßen können (mögliche Werte der error Eigenschaft):

Wenn der Fehlerparameter den Wert invalid_client aufweist, enthält Microsoft Entra eine suberror-Eigenschaft in der Antwort. Hier sind die möglichen Werte der suberror Eigenschaft für einen invalid_client Fehler:

Schritt 2: Authentifizierungsmethode auswählen

Um den Ablauf fortzusetzen, verwendet die App das Fortsetzungstoken, das sie aus dem vorherigen Schritt erhält, um Microsoft Entra anzufordern, einen der unterstützten Abfragetypen auszuwählen, die der Benutzer authentifiziert oder eine MFA-Abfrage abgeschlossen hat. Die App sendet eine POST-Anforderung an den /oauth2/v2.0/challenge-Endpunkt.

Hier ist ein Beispiel für die Anforderung (zur besseren Lesbarkeit wird die Beispielanforderung in mehreren Zeilen dargestellt):

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... 

Antwort bei Erfolg

Die Erfolgsantwort hängt von der Authentifizierungsmethode des Benutzers ab.

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
} 

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

{   
   "continuation_token": "uY29tL2F1dGhlbnRpY",   
   "challenge_type": "password" 
} 

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
} 

Umleitungsantwort

In den folgenden Szenarien kann ein Fallback auf einen webbasierten Authentifizierungsfluss erforderlich sein:

• Die Client-App unterstützt nicht die Authentifizierungsmethode oder -funktionen, die Microsoft Entra erfordert.
• Der Benutzer versucht, SMS als starke Authentifizierungsmethode zu verwenden, aber betrugsschutz blockiert die Anforderung, wenn sie als hohes Risiko erachtet (nur in E-Mails mit Kennwortauthentifizierung).

In diesen Szenarien informiert Microsoft Entra die App durch Zurückgeben eines redirect Abfragetyps in der Antwort:

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

{     
   "challenge_type": "redirect" 
} 

Diese Antwort gilt als erfolgreich, die App muss jedoch zu einem webbasierten Authentifizierungsflow wechseln. In diesem Fall empfehlen wird Ihnen, eine von Microsoft erstellte und unterstützte Authentifizierungsbibliothek zu verwenden.

Fehlerantwort

Beispiel:

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

Hier sind die möglichen Fehler, auf die Sie stoßen können (mögliche Werte der error Eigenschaft):

Schritt 3: Anforderung für Sicherheitstoken

Die App sendet eine POST-Anforderung an den oauth2/v2.0/token Endpunkt und stellt die im vorherigen Schritt ausgewählten Anmeldeinformationen des Benutzers zum Abrufen von Sicherheitstoken bereit.

Hier ist ein Beispiel für die Anforderung (zur besseren Lesbarkeit wird die Beispielanforderung in mehreren Zeilen dargestellt):

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 

Erfolgreiche Antwort

Hier ist ein Beispiel für eine erfolgreiche Antwort:

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

Fehlerantwort

Beispiel:

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

Hier sind die möglichen Fehler, auf die Sie stoßen können (mögliche Werte der error Eigenschaft):

Wenn der Fehlerparameter den Wert invalid_grant aufweist, enthält Microsoft Entra eine suberror-Eigenschaft in der Antwort. Hier sind die möglichen Werte der suberror Eigenschaft für einen invalid_grant Fehler:

Umleitungsantwort

Wenn die Client-App die Authentifizierungsmethode oder -funktion, die Microsoft Entra erfordert, nicht unterstützt, ist ein Fallback auf den webbasierten Authentifizierungsfluss erforderlich. In diesem Szenario informiert Microsoft Entra die App durch Zurückgeben eines redirect Abfragetyps in der Antwort:

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

{     
    "challenge_type": "redirect",
    "redirect_reason": "Client is missing registration_required capability"
} 

Diese Antwort gilt als erfolgreich, die App muss jedoch zu einem webbasierten Authentifizierungsflow wechseln. In diesem Fall empfehlen wird Ihnen, eine von Microsoft erstellte und unterstützte Authentifizierungsbibliothek zu verwenden.

Abrufen von vom Benutzer registrierten methoden für die sichere Authentifizierung

Verwenden Sie den oauth2/v2.0/introspect Endpunkt, um die Liste der registrierten starken Authentifizierungsmethoden des Benutzers anzufordern.

Hier ist ein Beispiel für die Anforderung (zur besseren Lesbarkeit wird die Beispielanforderung in mehreren Zeilen dargestellt):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/introspect
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444

Antwort bei Erfolg

Beispiel:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "methods":[
        {
            "id":"0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c",
            "challenge_type":"oob",
            "challenge_channel":"email",
            "login_hint":"c***r@co**o**o.com"
        },
        {   
          "id": "1b1b1b1b-2222-cccc-3333-4d4d4d4d4d4d",   
          "challenge_type": "oob",   
          "challenge_channel": "sms",   
          "login_hint": "+1********6"
        }
    ]
}

Das MFA-Methodenobjekt verfügt über die folgenden Eigenschaften:

Umleitungsantwort

Wenn die Client-App die Authentifizierungsmethode oder -funktionen, die Microsoft Entra erfordert, nicht unterstützt, ist ein Fallback auf den webbasierten Authentifizierungsfluss erforderlich. In diesem Szenario informiert Microsoft Entra die App durch Zurückgeben eines redirect Abfragetyps in der Antwort:

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

{     
   "challenge_type": "redirect" 
} 

Fehlerantwort

Beispiel:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The continuation_token provided is not valid for this endpoint.\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"
} 

Hier sind die möglichen Fehler, auf die Sie stoßen können (mögliche Werte der error Eigenschaft):

Nachdem die Client-App erfolgreich eine Liste der für den Benutzer registrierten starken Authentifizierungsmethoden abgerufen hat, wählt der Benutzer eine Methode aus, die er zum Abschließen der MFA-Herausforderung verwenden möchte. Der Ablauf wird dann wie folgt fortgesetzt:

1. Die Client-App ruft das /oauth2/v2.0/challenge Fortsetzungstoken auf und enthält das von der /oauth2/v2.0/introspect MFA-Methode id der Wahl abgerufene Fortsetzungstoken:

   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
   &id=0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c 
   &continuation_token=uY29tL2F1dGhlbnRpY... 
   

2. Microsoft Entra sendet einen Abfragecode an den Abfragekanal des Benutzers, z. B. E-Mail, und antwortet dann mit einem Fortsetzungstoken und den MFA-Abfragedetails zurück auf die Client-App:

   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
   } 
   

3. Die App kann nun eine POST-Anforderung an den /oauth2/v2.0/token Endpunkt senden und ein Fortsetzungstoken, einen korrekten Erteilungstyp und entsprechende Grant-Typwerte zum Abrufen von Sicherheitstoken enthält. Siehe erwartete Antwort in Anforderung für Sicherheitstoken:

   POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
   Content-Type: application/x-www-form-urlencoded    
   client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
   &continuation_token=uY29tL2F1dGhlbnRpY...   
   &grant_type=mfa_oob  
   &oob={otp_code}
   &scope=openid offline_access
   

Registrieren einer API-Referenz für sichere Authentifizierungsmethoden

Die systemeigene Authentifizierung unterstützt die Registrierung einer starken Authentifizierungsmethode. Wenn die App den /oauth2/v2.0/token-Endpunkt aufruft und MFA erforderlich ist, der Benutzer jedoch keine registrierte starke Methode hat, weist die Antwort, registeration_required, der App an, den Benutzer registrieren zu lassen, bevor Token ausgestellt werden können.

Nachdem die Client-App den Fluss zum Registrieren einer starken Authentifizierungsmethode abgeschlossen hat, ruft sie den /oauth2/v2.0/token Endpunkt auf, um Sicherheitstoken anzufordern.

Registrierungsendpunkte für starke Authentifizierungsmethoden

Um die Registrierungs-API für starke Authentifizierungsmethoden zu verwenden, verwendet die App den in der folgenden Tabelle gezeigten Endpunkt:

Schritt 1: Abrufen der Liste der starken Authentifizierungsmethoden

Der Registrierungsablauf beginnt, wenn die App die Liste der starken Authentifizierungsmethoden anfordert, die der Benutzer registrieren darf.

Hier ist ein Beispiel für die Anforderung (zur besseren Lesbarkeit wird die Beispielanforderung in mehreren Zeilen dargestellt):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/introspect
Content-Type: application/x-www-form-urlencoded
?continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444  

Antwort bei Erfolg

Hier ist ein Beispiel für eine erfolgreiche Antwort:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "methods":[
        {
            "id":"email",
            "challenge_type":"oob",
            "challenge_channel":"email",
            "login_hint":"caseyjensen@contoso.com"
        },
        {   
          "id": "sms",   
          "challenge_type": "oob",   
          "challenge_channel": "sms"
        }
    ]
}

Das Objekt der starken Authentifizierungsmethoden weist die folgenden Eigenschaften auf:

Fehlerantwort

Beispiel:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The continuation_token provided is not valid for this endpoint.\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"
} 

Hier sind die möglichen Fehler, auf die Sie stoßen können (mögliche Werte der error Eigenschaft):

Schritt 2: Auswählen einer starken Authentifizierungsmethode

Übermitteln Sie in diesem Schritt die starke Authentifizierungsmethode, die der Benutzer registrieren möchte. Microsoft Entra sendet dann eine Abfrage, z. B. eine Einmalige E-Mail-Kennung, an den Benutzer.

Hier ist ein Beispiel für die Anforderung (zur besseren Lesbarkeit wird die Beispielanforderung in mehreren Zeilen dargestellt):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/challenge 

?continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444  
&challenge_type=oob  
&challenge_channel=email 
&challenge_target=contoso-consumer@contoso.com 

Antwort bei Erfolg

Hier ist ein Beispiel für eine erfolgreiche Antwort.

Beispiel 1:

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

{ 
  "continuation_token": "uY29tL2F1dGhlbnRpY...", 
  "challenge_type": "oob", 
  "binding_method": "prompt", 
  "challenge_target": "contoso-consumer@contoso.com", 
  "challenge_channel": "email", 
  "code_length": 8 
} 

Beispiel 2:

Wenn der Registrierungsfluss dem Registrierungsfluss mit einer starken Authentifizierungsmethode vorausgeht und die an den /register/v1.0/challenge Endpunkt übermittelten E-Mails mit dem im Registrierungsablauf überprüften übereinstimmen, registriert die systemeigene Authentifizierungs-API die Methode, ohne eine Abfrage an den Benutzer zu senden. In diesem Fall sieht die Antwort ähnlich wie der folgende Codeausschnitt aus:

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

{ 
  "continuation_token": "uY29tL2F1dGhlbnRpY...",
  "challenge_type": "preverified" 
}

Fehlerantwort

Die folgenden Fehler ähneln denen, die beim Aufrufen des Endpunkts /register/v1.0/introspect auftreten können. Wenn die Telefonnummer jedoch als hohes Risiko eingestuft wird, kann die Anforderung blockiert werden, wenn die Telefonnummer registriert wird.

Hier sind die möglichen Fehler, die auftreten können, wenn die Anforderung blockiert wird:

Wenn der Fehlerparameter den Wert access_denied aufweist, enthält Microsoft Entra eine Subfehlereigenschaft in der Antwort. Hier sind die möglichen Werte der Suberror-Eigenschaft für einen invalid_grant Fehler:

Schritt 3: Absenden einer Herausforderung

Führen Sie in diesem Schritt einen Aufruf des /register/v1.0/continue Endpunkts durch, um die Registrierung der starken Authentifizierungsmethode abzuschließen.

Hier ist ein Beispiel für die Anforderung (zur besseren Lesbarkeit wird die Beispielanforderung in mehreren Zeilen dargestellt):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/continue 

?continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444  
&grant_type=oob  
&oob={otp_code}

Antwort bei Erfolg

Hier ist ein Beispiel für eine erfolgreiche Antwort:

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

{ 
  "continuation_token": "uY29tL2F1dGhlbnRpY..."
} 

Fehlerantwort

Beispiel:

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

Hier sind die möglichen Fehler, auf die Sie stoßen können (mögliche Werte der error Eigenschaft):

Wenn der Fehlerparameter den Wert invalid_grant aufweist, enthält Microsoft Entra eine suberror-Eigenschaft in der Antwort. Hier sind die möglichen Werte der suberror Eigenschaft für einen invalid_grant Fehler:

Self-Service-Kennwortzurücksetzung (SSPR)

Verwenden Sie für Benutzer, deren primäre Authentifizierungsmethode E-Mail mit Kennwort ist, die Self-Service Password Reset (SSPR)-API, um Kundenbenutzern das Zurücksetzen ihres Kennworts zu ermöglichen. Sie können diese API für vergessene Kennwort- oder Änderungskennwortszenarien verwenden.

API-Endpunkte für Self-Service-Passwort-Reset

Um diese API zu verwenden, verwendet die App den in der folgenden Tabelle gezeigten Endpunkt:

Aufforderungstypen für die Self-Service-Kennwortzurücksetzung

Die API ermöglicht der App, die unterstützten Authentifizierungsmethoden anzukündigen, wenn sie einen Aufruf an Microsoft Entra sendet. Dazu verwendet die App den challenge_type-Parameter in ihren Anforderungen. Dieser Parameter enthält vordefinierte Werte, die unterschiedliche Authentifizierungsmethoden darstellen.

Die Aufforderungstypwerte für den SSPR-Flow lauten oob und redirect.

Weitere Informationen zu den Aufforderungstypen finden Sie unter Aufforderungstypen für native Authentifizierung.

Details zum Protokoll der Self-Service-Kennwortzurücksetzung

Das Sequenzdiagramm veranschaulicht den Flow für den Kennwortzurücksetzungsprozess.

Dieses Diagramm gibt an, dass die App den Benutzernamen (E-Mail) und das Kennwort vom Benutzer zu unterschiedlichen Zeiten (und möglicherweise auf separaten Bildschirmen) sammelt. Sie können Ihre App jedoch so entwerfen, dass der Benutzername (E-Mail) und das neue Kennwort auf demselben Bildschirm erfasst werden. In diesem Fall enthält die App das Kennwort und sendet es dann über den /resetpassword/v1.0/submit-Endpunkt, an dem es erforderlich ist.

Schritt 1: Anfordern zum Start des Flows der Self-Service-Kennwortzurücksetzung

Der Flow der Kennwortzurücksetzung beginnt mit der App, die eine POST-Anforderung an den /resetpassword/v1.0/start-Endpunkt sendet, um den Flow der Self-Service-Kennwortzurücksetzung zu starten.

Hier ist ein Beispiel für die Anforderung (zur besseren Lesbarkeit wird die Beispielanforderung in mehreren Zeilen dargestellt):

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 

Antwort bei Erfolg

Beispiel:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

Umleitungsantwort

Wenn die Client-App die Authentifizierungsmethode oder -funktionen, die Microsoft Entra erfordert, nicht unterstützt, ist ein Fallback auf den webbasierten Authentifizierungsfluss erforderlich. In diesem Szenario informiert Microsoft Entra die App durch Zurückgeben eines redirect Abfragetyps in der Antwort:

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

{     
   "challenge_type": "redirect" 
} 

Diese Antwort gilt als erfolgreich, die App muss jedoch zu einem webbasierten Authentifizierungsflow wechseln. In diesem Fall empfehlen wird Ihnen, eine von Microsoft erstellte und unterstützte Authentifizierungsbibliothek zu verwenden.

Fehlerantwort

Beispiel:

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

Hier sind die möglichen Fehler, auf die Sie stoßen können (mögliche Werte der error Eigenschaft):

Wenn der Fehlerparameter den Wert invalid_client aufweist, enthält Microsoft Entra eine suberror-Eigenschaft in der Antwort. Hier sind die möglichen Werte der suberror Eigenschaft für einen invalid_client Fehler:

Schritt 2: Authentifizierungsmethode auswählen

Um den Ablauf fortzusetzen, verwendet die App das aus dem vorherigen Schritt erworbene Fortsetzungstoken, um Microsoft Entra anzufordern, einen der unterstützten Abfragetypen auszuwählen, mit denen der Benutzer sich authentifizieren kann. Die App sendet eine POST-Anforderung an den /resetpassword/v1.0/challenge-Endpunkt. Wenn diese Anforderung erfolgreich ist, sendet Microsoft Entra eine einmalkennung an die E-Mail-Adresse des Benutzerkontos. Derzeit unterstützen wir nur die E-Mail-OTP.

Hier ist ein Beispiel (zur besseren Lesbarkeit wird die Beispielanforderung in mehreren Zeilen dargestellt):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&continuation_token=uY29tL2F1dGhlbnRpY... 

Antwort bei Erfolg

Beispiel:

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
} 

Umleitungsantwort

Wenn die Client-App die Authentifizierungsmethode oder -funktionen, die Microsoft Entra erfordert, nicht unterstützt, ist ein Fallback auf den webbasierten Authentifizierungsfluss erforderlich. In diesem Szenario informiert Microsoft Entra die App durch Zurückgeben eines redirect Abfragetyps in der Antwort:

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

{     
   "challenge_type": "redirect" 
} 

Diese Antwort gilt als erfolgreich, die App muss jedoch zu einem webbasierten Authentifizierungsflow wechseln. In diesem Fall empfehlen wird Ihnen, eine von Microsoft erstellte und unterstützte Authentifizierungsbibliothek zu verwenden.

Fehlerantwort

Beispiel:

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

Hier sind die möglichen Fehler, auf die Sie stoßen können (mögliche Werte der error Eigenschaft):

Schritt 3: Übermitteln eines Einmal-Passcodes

Die App sendet dann eine POST-Anforderung an den /resetpassword/v1.0/continue-Endpunkt. In der Anforderung muss die App die im vorherigen Schritt ausgewählten Anmeldeinformationen des Benutzers und das vom /resetpassword/v1.0/challenge-Endpunkt ausgegebene Fortsetzungstoken enthalten.

Hier ist ein Beispiel für die Anforderung (zur besseren Lesbarkeit wird die Beispielanforderung in mehreren Zeilen dargestellt):

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}

Antwort bei Erfolg

Beispiel:

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

{ 
    "expires_in": 600,
    "continuation_token": "czZCaGRSa3F0MzpnW...",
} 

Fehlerantwort

Beispiel:

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

Hier sind die möglichen Fehler, auf die Sie stoßen können (mögliche Werte der error Eigenschaft):

Wenn der Fehlerparameter den Wert invalid_grant aufweist, enthält Microsoft Entra eine suberror-Eigenschaft in der Antwort. Hier sind die möglichen Werte der suberror Eigenschaft für einen invalid_grant Fehler:

Schritt 4: Übermitteln eines neuen Kennworts

Die App sammelt ein neues Kennwort vom Benutzer und verwendet dann das vom -Endpunkt ausgestellte /resetpassword/v1.0/continue, um das Kennwort zu übermitteln, indem eine POST-Anforderung an den /resetpassword/v1.0/submit-Endpunkt erstellt wird.

Hier ist ein Beispiel (zur besseren Lesbarkeit wird die Beispielanforderung in mehreren Zeilen dargestellt):

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}

Antwort bei Erfolg

Beispiel:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "poll_interval": 2
}

Fehlerantwort

Beispiel:

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

Hier sind die möglichen Fehler, auf die Sie stoßen können (mögliche Werte der error Eigenschaft):

Wenn der Fehlerparameter den Wert invalid_grant aufweist, enthält Microsoft Entra eine suberror-Eigenschaft in der Antwort. Hier sind die möglichen Werte der suberror Eigenschaft:

Schritt 5: Abrufen des Status der Kennwortzurücksetzung

Schließlich kann die App, da die Aktualisierung der Konfiguration des Benutzers mit dem neuen Kennwort zu einer Verzögerung kommt, den endpunkt /resetpassword/v1.0/poll_completion verwenden, um Microsoft Entra für den Kennwortzurücksetzungsstatus abzufragen. Die Mindestzeit in Sekunden, welche die App zwischen Abrufanforderungen warten sollte, wird vom /resetpassword/v1.0/submit-Endpunkt im poll_interval-Parameter zurückgegeben.

Hier ist ein Beispiel (zur besseren Lesbarkeit wird die Beispielanforderung in mehreren Zeilen dargestellt):

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... 

Antwort bei Erfolg

Beispiel:

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

{
    "status": "succeeded",
    "continuation_token":"czZCaGRSa3F0..."
} 

Hier sind die möglichen Status, die Microsoft Entra zurückgeben (mögliche Werte des Parameters status):

Fehlerantwort

Beispiel:

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

Hier sind die möglichen Fehler, auf die Sie stoßen können (mögliche Werte der error Eigenschaft):

Automatische Anmeldung nach der Kennwortzurücksetzung

Wenn sich der Benutzer nach einer erfolgreichen Kennwortzurücksetzung anmelden muss. Die App muss den /oauth2/v2.0/token Endpunkt aufrufen. Erfahren Sie , wie Sie den Tokenendpunkt aufrufen.

Zugehöriger Inhalt

• Konfigurieren eines benutzerdefinierten Anspruchsanbieters.