Hinzufügen eines API-Connectors zu einem Benutzerflow

  • Artikel

Um einen API-Connector zu verwenden, erstellen Sie zunächst den API-Connector und aktivieren ihn anschließend in einem Benutzerflow.

Wichtig

Erstellen eines API-Connectors

Tipp

Die Schritte in diesem Artikel können je nach dem Portal, mit dem Sie beginnen, geringfügig variieren.

  1. Melden Sie sich beim Microsoft Entra Admin Center mindestens als Benutzeradministrator an.

  2. Browsen Sie zu Identität>External Identities>Übersicht.

  3. Wählen Sie Alle API-Connectors und dann Neuer API-Connector aus.

    Screenshot des Hinzufügens eines neuen API-Connectors zu External ID.

  4. Geben Sie einen Anzeigenamen für den Aufruf an, z. B. Genehmigungsstatus überprüfen.

  5. Geben Sie die Endpunkt-URL für den API-Aufruf an.

  6. Wählen Sie den Authentifizierungstyp aus, und konfigurieren Sie die Authentifizierungsinformationen zum Aufrufen Ihrer API. Erfahren Sie mehr über das Schützen Ihres API-Connectors.

    Screenshot des Konfigurierens eines API-Connectors.

  7. Wählen Sie Speichern aus.

An die API gesendete Anforderung

Ein API-Connector wird als HTTP POST-Anforderung dargestellt und sendet Benutzerattribute („Ansprüche“) als Schlüssel-Wert-Paare in einem JSON-Text. Attribute werden ähnlich wie Microsoft Graph-Benutzereigenschaften serialisiert.

Beispielanforderung

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

Nur Benutzereigenschaften und benutzerdefinierte Attribute, die unter Identität>Externe Identitäten>Übersicht>Benutzerdefinierte Benutzerattribute aufgeführt sind, können in der Anforderung gesendet werden.

Benutzerdefinierte Attribute sind im Verzeichnis im Format extension_<extensions-app-id>_AttributeName vorhanden. Die API sollte den Empfang von Ansprüchen in diesem serialisierten Format erwarten. Weitere Informationen zu benutzerdefinierten Attributen finden Sie unter Definieren von benutzerdefinierten Attributen für Self-Service-Registrierungsflows.

Darüber hinaus werden in der Regel die Ansprüche in allen Anforderungen gesendet:

  • UI-Gebietsschemas („ui_locales“): Die auf dem Gerät konfigurierten Gebietsschemas eines Endbenutzers. Kann von Ihrer API verwendet werden, um internationalisierte Antworten zurückzugeben.
  • E-Mail-Adresse („email“) oder Identitäten („identities“): Diese Ansprüche können von Ihrer API zum Identifizieren des Endbenutzers verwendet werden, der sich bei der Anwendung authentifiziert.

Wichtig

Wenn ein Anspruch zum Zeitpunkt des Aufrufs des API-Endpunkts keinen Wert enthält, wird der Anspruch nicht an die API gesendet. Ihre API sollte so entworfen sein, dass explizit geprüft wird, ob ein Anspruch in der Anforderung enthalten ist. Fehlt der Anspruch, sollte eine entsprechende Verarbeitung erfolgen.

Aktivieren des API-Connectors in einem Benutzerflow

Führen Sie die folgenden Schritte aus, um einem Benutzerflow für die Self-Service-Registrierung einen API-Connector hinzuzufügen.

  1. Melden Sie sich beim Microsoft Entra Admin Center mindestens als Benutzeradministrator an.

  2. Browsen Sie zu Identität>External Identities>Übersicht.

  3. Wählen Sie Benutzerflows und dann den Benutzerflow aus, dem Sie den API-Connector hinzufügen möchten.

  4. Wählen Sie API-Connectors und dann die API-Endpunkte aus, die bei den folgenden Schritten im Benutzerflow aufgerufen werden sollen:

    • Nach dem Verbund mit einem Identitätsanbieter während der Registrierung
    • Vor dem Erstellen des Benutzers

    Auswählen des API-Connectors, der für einen Schritt im Benutzerfluss, z. B. „Vor dem Erstellen des Benutzers“, verwendet werden soll

  5. Wählen Sie Speichern aus.

Nach dem Verbund mit einem Identitätsanbieter während der Registrierung

Ein API-Connector wird in diesem Schritt des Anmeldevorgangs unmittelbar nach der Authentifizierung des Benutzers bei einem Identitätsanbieter (wie Google, Facebook oder Microsoft Entra ID) aufgerufen. Dieser Schritt geht der Seite zur Attributsammlung voraus, die dem Benutzer zum Sammeln von Benutzerattributen angezeigt wird.

In diesem Schritt an die API gesendete Beispielanforderung

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "lastName":"Smith",
 "ui_locales":"en-US"
}

Die genauen Ansprüche, die an die API gesendet werden, hängen von den Informationen ab, die vom Identitätsanbieter bereitgestellt werden. Der Anspruch „email“ wird immer gesendet.

Von der Web-API in diesem Schritt erwartete Antworttypen

Wenn die Web-API während eines Benutzerflows eine HTTP-Anforderung von Microsoft Entra ID empfängt, kann sie folgende Antworten zurückgeben:

  • Fortsetzungsantwort
  • Blockierungsantwort

Fortsetzungsantwort

Eine Fortsetzungsantwort gibt an, dass der Benutzerflow mit dem nächsten Schritt fortgesetzt werden soll: Attributerfassungsseite.

In einer Fortsetzungsantwort kann die API Ansprüche zurückgeben. Wenn ein Anspruch von der API zurückgegeben wird, passiert mit dem Anspruch Folgendes:

  • Das Eingabefeld auf der Attributerfassungsseite wird vorab aufgefüllt.

Sehen Sie sich ein Beispiel für eine Fortsetzungsantwort an.

Blockierungsantwort

Eine Blockierungsantwort beendet den Benutzerflow. Sie kann von der API absichtlich ausgegeben werden, um die Fortsetzung des Benutzerflows zu beenden, indem für den Benutzer eine Blockierungsseite angezeigt wird. Auf der Blockierungsseite wird die von der API angegebene userMessage angezeigt.

Sehen Sie sich ein Beispiel für eine Blockierungsantwort an.

Vor dem Erstellen des Benutzers

Ein API-Connector in diesem Schritt des Registrierungsprozesses wird nach der Seite zur Attributsammlung aufgerufen, sofern vorhanden. Dieser Schritt wird stets aufgerufen, ehe ein Benutzerkonto in Microsoft Entra ID erstellt wird.

In diesem Schritt an die API gesendete Beispielanforderung

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

Die genauen Ansprüche, die an die API gesendet werden, hängen von den Informationen ab, die vom Benutzer gesammelt oder vom Identitätsanbieter bereitgestellt werden.

Von der Web-API in diesem Schritt erwartete Antworttypen

Wenn die Web-API während eines Benutzerflows eine HTTP-Anforderung von Microsoft Entra ID empfängt, kann sie folgende Antworten zurückgeben:

  • Fortsetzungsantwort
  • Blockierungsantwort
  • Überprüfungsantwort

Fortsetzungsantwort

Eine Fortsetzungsantwort gibt an, dass der Benutzerflow mit dem nächsten Schritt fortgesetzt werden soll: Erstellen des Benutzers im Verzeichnis.

In einer Fortsetzungsantwort kann die API Ansprüche zurückgeben. Wenn ein Anspruch von der API zurückgegeben wird, passiert mit dem Anspruch Folgendes:

  • Alle Werte, die dem Anspruch über die Attributerfassungsseite bereits zugewiesen wurden, werden überschrieben.

Sehen Sie sich ein Beispiel für eine Fortsetzungsantwort an.

Blockierungsantwort

Eine Blockierungsantwort beendet den Benutzerflow. Sie kann von der API absichtlich ausgegeben werden, um die Fortsetzung des Benutzerflows zu beenden, indem für den Benutzer eine Blockierungsseite angezeigt wird. Auf der Blockierungsseite wird die von der API angegebene userMessage angezeigt.

Sehen Sie sich ein Beispiel für eine Blockierungsantwort an.

Validierungsfehlerantwort

Wenn die API eine Validierungsfehlerantwort ausgibt, wird der Benutzerflow auf der Attributsammlungsseite angehalten, und dem Benutzer wird eine userMessage angezeigt. Der Benutzer kann dann das Formular bearbeiten und erneut senden. Diese Antwort kann für die Eingabevalidierung verwendet werden.

Sehen Sie sich ein Beispiel für eine Validierungsfehlerantwort an.

Beispielantworten

Beispiel für eine Fortsetzungsantwort

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

{
    "version": "1.0.0",
    "action": "Continue",
    "postalCode": "12349", // return claim
    "extension_<extensions-app-id>_CustomAttribute": "value" // return claim
}
Parameter Type Erforderlich Beschreibung
version String Ja Die Version Ihrer API
action String Ja Der Wert muss Continue sein.
<builtInUserAttribute> <attribute-type> Nein Werte können im Verzeichnis gespeichert werden, wenn sie als zu empfangender Anspruch in der API-Connector-Konfiguration und als Benutzerattribute für einen Benutzerflow ausgewählt sind. Werte können im Token zurückgegeben werden, wenn sie als Anwendungsanspruch ausgewählt sind.
<extension_{extensions-app-id}_CustomAttribute> <attribute-type> Nein Der Anspruch muss _<extensions-app-id>_ nicht enthalten, dies ist optional. Zurückgegebene Werte können Werte überschreiben, die von einem Benutzer gesammelt wurden.

Beispiel für eine Blockierungsantwort

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

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "There was an error with your request. Please try again or contact support.",
}
Parameter Type Erforderlich Beschreibung
version String Ja Die Version Ihrer API
action String Ja Der Wert muss ShowBlockPage sein.
userMessage String Ja Meldung, die für den Benutzer angezeigt wird.

Anzeige einer Blockierungsantwort für den Endbenutzer

Eine Beispielabbildung der Endbenutzererfahrung, nachdem eine API eine Blockierungsantwort zurückgegeben hat

Beispiel für eine Validierungsfehlerantwort

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

{
    "version": "1.0.0",
    "status": 400,
    "action": "ValidationError",
    "userMessage": "Please enter a valid Postal Code.",
}
Parameter Type Erforderlich Beschreibung
version String Ja Die Version Ihrer API
action String Ja Der Wert muss ValidationError sein.
status Integer / Zeichenkette Ja Für eine Validierungsfehlerantwort muss der Wert 400 oder "400" sein.
userMessage String Ja Meldung, die für den Benutzer angezeigt wird.

Hinweis

Der HTTP-Statuscode muss „400“ lauten, und der Antworttext muss den Wert „status“ enthalten.

Anzeige einer Validierungsfehlerantwort für den Endbenutzer

Eine Beispielabbildung der Endbenutzererfahrung, nachdem eine API eine Validierungsfehlerantwort zurückgegeben hat

Bewährte Methoden und Problembehandlungen

Verwenden von serverlosen Cloudfunktionen

Serverlose Funktionen (z. B. HTTP-Trigger in Azure Functions) bieten eine Möglichkeit zum Erstellen von API-Endpunkten, die mit dem API-Connector verwendet werden. Sie können die serverlosen Cloudfunktionen beispielsweise verwenden, um Validierungslogik auszuführen und Registrierungen auf bestimmte E-Mail-Domänen zu beschränken. Mit den serverlosen Cloudfunktionen können auch andere Web-APIs, Datenspeicher und andere Clouddienste für komplexere Szenarien aufgerufen werden.

Bewährte Methoden

Stellen Sie Folgendes sicher:

  • Ihre API entspricht den API-Anforderungs- und -Antwortverträgen, wie dies weiter oben beschrieben ist.
  • Die Endpunkt-URL des API-Connectors verweist auf den richtigen API-Endpunkt.
  • In Ihrer API wird explizit auf NULL-Werte der empfangenen notwendigen Ansprüche geprüft.
  • Ihre API implementiert eine Authentifizierungsmethode, die unter Schützen Ihres API-Connectors beschrieben ist.
  • Ihre API antwortet so schnell wie möglich, um eine flüssige Darstellung für den Benutzer zu gewährleisten.
    • Microsoft Entra ID wartet maximal 20 Sekunden auf den Empfang einer Antwort. Wird keine empfangen, wird ein weiterer Versuch (Wiederholung) unternommen, die API aufzurufen.
    • Verwenden Sie in der Produktion einen Hostingplan, der dafür sorgt, dass die API aktiv bleibt, wenn Sie eine serverlose Funktion oder einen skalierbaren Webdienst verwenden. Für Azure Functions empfehlen wir, mindestens den Premium-Plan zu verwenden.
  • Stellen Sie die Hochverfügbarkeit Ihrer API sicher.
  • Überwachen und optimieren Sie die Leistung von nachgelagerten APIs, Datenbanken oder anderen Abhängigkeiten Ihrer API.
  • Ihre Endpunkte müssen die TLS- und Verschlüsselungsanforderungen von Microsoft Entra erfüllen. Weitere Informationen finden Sie unter Anforderungen an TLS und Verschlüsselungssammlungen.

Verwenden von Protokollierung

Üblicherweise ist es nützlich, die von Ihrem Web-API-Dienst aktivierten Protokollierungstools, etwa Application Insights, zu verwenden, um Ihre API auf unerwartete Fehlercodes, Ausnahmen und schlechte Leistung zu überwachen.

  • Überwachen Sie auf HTTP-Statuscodes, die weder HTTP 200 noch 400 sind.
  • Der HTTP-Statuscode 401 oder 403 kennzeichnet in der Regel, dass ein Problem mit Ihrer Authentifizierung vorliegt. Überprüfen Sie die Authentifizierungsschicht Ihrer API und die entsprechende Konfiguration im API-Connector.
  • Verwenden Sie in der Entwicklung ggf. höhere Protokolliergrade (z. B. „trace“ oder „debug“).
  • Überwachen Sie Ihre API hinsichtlich langer Antwortzeiten.

Nächste Schritte