Verwenden von API-Connectors zum Anpassen und Erweitern von Anmeldebenutzerflüssen und benutzerdefinierten Richtlinien mit externen Identitätsdatenquellen

Von Bedeutung

Ab dem 1. Mai 2025 steht Azure AD B2C nicht mehr für neue Kunden zur Verfügung. Weitere Informationen finden Sie in unseren HÄUFIG gestellten Fragen.

Bevor Sie beginnen, verwenden Sie die Auswahl eines Richtlinientyps oben auf dieser Seite, um den Typ der Richtlinie auszuwählen, die Sie einrichten. Azure Active Directory B2C bietet zwei Methoden zum Definieren der Benutzerinteraktion mit Ihren Anwendungen: vordefinierte Benutzerflows oder vollständig konfigurierbare benutzerdefinierte Richtlinien. Die Schritte, die in diesem Artikel erforderlich sind, unterscheiden sich für jede Methode.

Überblick

Als Entwickler oder IT-Administrator können Sie API-Connectors verwenden, um Ihre Anmeldebenutzerflüsse in REST-APIs zu integrieren, um die Anmeldeerfahrung anzupassen und in externe Systeme zu integrieren. API-Connectors bieten beispielsweise folgende Möglichkeiten:

• Überprüfen von Benutzereingabedaten. Überprüfen Sie auf fehlerhafte oder ungültige Benutzerdaten. Beispielsweise können Sie vom Benutzer bereitgestellte Daten im Vergleich mit vorhandenen Daten in einem externen Datenspeicher oder einer Liste zulässiger Werte überprüfen. Falls ungültig, können Sie einen Benutzer auffordern, gültige Daten anzugeben, oder den Benutzer daran hindern, den Registrierungsflow fortzusetzen.
• Überprüfen sie die Benutzeridentität. Verwenden Sie einen Identitätsüberprüfungsdienst oder externe Identitätsdatenquellen, um den Entscheidungen zur Kontoerstellung ein zusätzliches Maß an Sicherheit hinzuzufügen.
• Integration in einen benutzerdefinierten Genehmigungsworkflow. Verbinden mit einem benutzerdefinierten Genehmigungssystem zum Verwalten und Einschränken der Kontoerstellung.
• Erweitern Sie Token mit Attributen aus externen Quellen. Bereichern Sie Token mit Benutzerattributen aus Quellen, die sich außerhalb von Azure AD B2C befinden, z. B. Cloudsysteme, benutzerdefinierte Benutzerspeicher, benutzerdefinierte Berechtigungssysteme, ältere Identitätsdienste und vieles mehr.
• Überschreiben von Benutzerattributen. Sie können ein vom Benutzer erfasstes Attribut neu formatieren oder ihm einen Wert zuweisen. Wenn z.B. ein Benutzer den Vornamen vollständig in Kleinbuchstaben oder Großbuchstaben eingibt, können Sie den Namen so formatieren, dass nur der erste Buchstabe groß geschrieben wird.
• Ausführen von benutzerdefinierter Geschäftslogik. Sie können nachgelagerte Ereignisse in Ihren Cloudsystemen auslösen, um Pushbenachrichtigungen zu senden, Unternehmensdatenbanken zu aktualisieren, Berechtigungen zu verwalten, Datenbanken zu überwachen und andere benutzerdefinierte Aktionen auszuführen.

Ein API-Connector stellt Azure AD B2C mit den Informationen bereit, die zum Aufrufen des API-Endpunkts erforderlich sind, indem die HTTP-Endpunkt-URL und die Authentifizierung für den API-Aufruf definiert werden. Sobald Sie einen API-Connector konfiguriert haben, können Sie ihn für einen bestimmten Schritt in einem Benutzerflow aktivieren. Wenn ein Benutzer diesen Schritt im Registrierungsablauf erreicht, wird der API-Connector aufgerufen und als HTTP POST-Anforderung an Ihre API materialisiert und sendet Benutzerinformationen ("Ansprüche") als Schlüsselwertpaare in einem JSON-Textkörper. Die API-Antwort kann die Ausführung des Benutzerflows beeinträchtigen. Die API-Antwort kann z. B. die Registrierung eines Benutzers blockieren, den Benutzer auffordern, Informationen erneut einzugeben oder Benutzerattribute zu überschreiben.

Wann ein API-Connector in einem Benutzerflow aktiviert werden kann

Es gibt drei Stellen in einem Benutzerablauf, an denen Sie einen API-Connector aktivieren können:

• Nach dem Verbund mit einem Identitätsanbieter während der Registrierung (gilt nur für Registrierungen)
• Vor dem Erstellen des Benutzers – gilt nur für Anmeldeerfahrungen
• Vor dem Senden des Tokens (Vorschau) – gilt für Registrierungen und Anmeldungen

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

Ein API-Connector in diesem Schritt im Registrierungsprozess wird unmittelbar aufgerufen, nachdem sich der Benutzer bei einem Identitätsanbieter authentifiziert hat (z. B. Google, Facebook und Microsoft Entra ID). In diesem Schritt wird die Attributauflistungsseite vorangestellt, bei der es sich um das Formular handelt, das dem Benutzer zum Sammeln von Benutzerattributen angezeigt wird. Dieser Schritt wird nicht aufgerufen, wenn sich ein Benutzer mit einem lokalen Konto registriert. Im Folgenden finden Sie Beispiele für Szenarien mit API-Connectors, die Sie in diesem Schritt aktivieren können:

• Verwenden Sie die E-Mail- oder Verbundidentität, die der Benutzer angegeben hat, um Ansprüche in einem bestehenden System nachzuschlagen. Geben Sie diese Ansprüche aus dem bestehenden System zurück, füllen Sie die Seite zur Attributsammlung vorab aus, und stellen Sie sie zur Rückgabe im Token zur Verfügung.
• Implementieren Sie eine Zulassungs- oder Sperrliste basierend auf der sozialen Identität.

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 immer aufgerufen, bevor ein Benutzerkonto erstellt wird. Es folgen Beispiele für Szenarien, die Sie an dieser Stelle während der Registrierung aktivieren könnten:

• Überprüfen eingegebener Benutzerdaten und Aufforderung an einen Benutzer, Daten erneut zu übermitteln
• Sperren einer Benutzerregistrierung auf Grundlage der vom Benutzer eingegebenen Daten
• Verifizieren Sie die Benutzeridentität.
• Abfragen externer Systeme nach vorhandenen Daten zum Benutzer, um diese im Anwendungstoken zurückzugeben oder in Microsoft Entra ID zu speichern.

Vor dem Senden des Tokens (Vorschau)

Hinweis

Dieses Feature befindet sich in der öffentlichen Vorschau.

Ein API-Connector in diesem Schritt im Registrierungs- oder Anmeldevorgang wird aufgerufen, bevor ein Token ausgestellt wird. Im Folgenden finden Sie Beispiele für Szenarien, die Sie in diesem Schritt aktivieren können:

• Das Anreichern des Tokens mit Attributen für den Benutzer von anderen Quellen als dem Verzeichnis, einschließlich älteren Identitätssystemen, HR-Systemen, externen Benutzerspeichern und mehr.
• Erweitern des Tokens mit Gruppen- oder Rollenattributen, die Sie in Ihrem eigenen Berechtigungssystem speichern und verwalten.
• Anwenden von Anspruchstransformationen oder Manipulationen auf Werte von Ansprüchen im Verzeichnis.

Die Plattform „Identity Experience Framework“, die Azure Active Directory B2C (Azure AD B2C) zugrunde liegt, kann im Rahmen einer User Journey in RESTful-APIs integriert werden. In diesem Artikel wird gezeigt, wie Sie mithilfe eines RESTful-technischen Profils eine Benutzerreise erstellen, die mit einem RESTful-Dienst interagiert.

Mithilfe von Azure AD B2C können Sie Einer Benutzerreise Ihre eigene Geschäftslogik hinzufügen, indem Sie Ihren eigenen RESTful-Dienst aufrufen. Das Identity Experience Framework kann Daten von Ihrem RESTful-Dienst senden und empfangen, um Ansprüche auszutauschen. Beispielsweise können Sie folgende Aktionen ausführen:

• Verwenden Sie externe Identitätsdaten, um Benutzereingabedaten zu überprüfen. Sie können beispielsweise überprüfen, ob die vom Benutzer angegebene E-Mail-Adresse in der Datenbank Ihres Kunden vorhanden ist und andernfalls einen Fehler darstellt. Sie können sich API-Connectors auch als eine Möglichkeit vorstellen, ausgehende Webhooks zu unterstützen, da der Aufruf stattfindet, wenn ein Ereignis auftritt, z. B. eine Registrierung.
• Verarbeiten von Ansprüchen. Wenn ein Benutzer seinen Vornamen in allen Klein- oder Großbuchstaben eingibt, kann Ihre REST-API den Namen nur mit großgeschriebenem ersten Buchstaben formatieren und an Azure AD B2C zurückgeben. Wenn Sie jedoch eine benutzerdefinierte Richtlinie verwenden, wird ClaimsTransformations gegenüber dem Aufrufen einer RESTful-API bevorzugt.
• Dynamisches Anreichern von Benutzerdaten durch eine weitere Integration in Unternehmensanwendungen. Ihr RESTful-Dienst kann die E-Mail-Adresse des Benutzers erhalten, die Datenbank des Kunden abfragen und die Treuenummer des Benutzers an Azure AD B2C zurückgeben. Anschließend können Rückgabeansprüche im Microsoft Entra-Konto des Benutzers gespeichert, in den nächsten Orchestrierungsschritten ausgewertet oder im Zugriffstoken enthalten sein.
• Ausführen von benutzerdefinierter Geschäftslogik. Sie können Pushbenachrichtigungen senden, Unternehmensdatenbanken aktualisieren, einen Benutzermigrationsprozess ausführen, Berechtigungen verwalten, Datenbanken überwachen und andere Workflows ausführen.

Hinweis

HTTP-Anforderungen werden möglicherweise abgebrochen, wenn eine langsame oder keine Antwort vom RESTful-Dienst auf Azure AD B2C vorhanden ist. Das Standardtimeout beträgt 10 Sekunden für benutzerdefinierte Richtlinien und 5 Sekunden für Benutzerflüsse. Die Standardmäßige Wiederholungsanzahl ist eine (d. h., es gibt insgesamt 2 Versuche).

Aufrufen eines RESTful-Diensts

Die Interaktion umfasst einen Anspruchsaustausch von Informationen zwischen den REST-API-Ansprüchen und Azure AD B2C. Sie können die Integration mit den RESTful-Diensten auf folgende Weise entwerfen:

• Technisches Validierungsprofil. Der Aufruf des RESTful-Diensts erfolgt innerhalb eines Überprüfungstechnischen Profils des angegebenen selbstausgeprüften technischen Profils oder eines Überprüfungsanzeigesteuerelements eines Anzeigesteuerelements. Das technische Validierungsprofil überprüft die vom Benutzer bereitgestellten Daten, bevor die Benutzerreise voranschreitet. Mit dem technischen Profil der Validierung können Sie:

  • Senden Sie Ansprüche an Ihre REST-API.
  • Überprüfen von Ansprüchen und Auslösen von benutzerdefinierten Fehlermeldungen, die Benutzenden angezeigt werden
  • Zurücksenden von Ansprüchen von der REST-API an die nächsten Orchestrierungsschritte

• Forderungsaustausch. Ein direkter Anspruchsaustausch kann durch Aufrufen eines technischen REST-API-Profils direkt aus einem Orchestrierungsschritt einer User Journey konfiguriert werden. Diese Definition ist auf Folgendes beschränkt:

  • Senden Sie Ansprüche an Ihre REST-API.
  • Überprüfen Sie Ansprüche, und lösen Sie benutzerdefinierte Fehlermeldungen aus, die an die Anwendung zurückgegeben werden.
  • Zurücksenden von Ansprüchen von der REST-API an die nächsten Orchestrierungsschritte

Sie können einen REST-API-Aufruf in jedem Schritt in der Benutzerreise hinzufügen, die von einer benutzerdefinierten Richtlinie definiert wird. Sie können beispielsweise eine REST-API aufrufen:

• Während der Anmeldung, kurz bevor Azure AD B2C die Anmeldeinformationen überprüft
• Unmittelbar nach der Anmeldung.
• Bevor Azure AD B2C ein neues Konto im Verzeichnis erstellt.
• Nachdem Azure AD B2C ein neues Konto im Verzeichnis erstellt hat.
• Bevor Azure AD B2C ein Zugriffstoken ausgibt.

Senden von Daten

Im TECHNISCHEn PROFIL VON RESTful enthält das InputClaims Element eine Liste der Ansprüche, die an Ihren RESTful-Dienst gesendet werden sollen. Sie können den Namen Ihres Anspruchs dem im RESTful-Dienst definierten Namen zuordnen, einen Standardwert festlegen und Anspruchslöser verwenden.

Sie können konfigurieren, wie die Eingabeansprüche mithilfe des SendClaimsIn-Attributs an den RESTful-Anspruchsanbieter gesendet werden. Mögliche Werte sind:

• Body, gesendet im HTTP POST-Anforderungstext im JSON-Format.
• Form: Wird im HTTP POST-Anforderungstext in einem durch kaufmännische Und-Zeichen (&) getrennten Schlüsselwertformat gesendet.
• Header, gesendet im HTTP GET-Anforderungsheader.
• QueryString, gesendet in der HTTP GET-Anforderungsabfragezeichenfolge.

Wenn die Option "Textkörper" konfiguriert ist, können Sie mit dem technischen Profil der REST-API eine komplexe JSON-Nutzlast an einen Endpunkt senden. Weitere Informationen finden Sie unter Senden einer JSON-Nutzlast.

Empfangen von Daten

Das OutputClaims Element des technischen PROFILs RESTful enthält eine Liste der Ansprüche, die von der REST-API zurückgegeben werden. Möglicherweise müssen Sie den Namen des in Ihrer Richtlinie definierten Anspruchs dem in der REST-API definierten Namen zuordnen. Sie können auch Ansprüche einschließen, die nicht vom REST-API-Identitätsanbieter zurückgegeben werden, solange Sie das DefaultValue-Attribut festlegen.

Bei den Ausgabeansprüchen, die vom RESTful-Anspruchsanbieter analysiert werden, wird immer das Parsen einer einfachen JSON-Textantwort erwartet. Beispiel:

{
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "loyaltyNumber":  1234
}

Die Ausgabeansprüche sollten wie der folgende XML-Codeausschnitt aussehen:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" />
</OutputClaims>

Behandlung von NULL-Werten

Ein NULL-Wert in einer Datenbank wird verwendet, wenn der Wert in einer Spalte unbekannt oder fehlt. Fügen Sie keine JSON-Schlüssel mit einem null Wert ein. Im folgenden Beispiel gibt die E-Mail den Wert zurück null :

{
  "name": "Emily Smith",
  "email": null,
  "loyaltyNumber":  1234
}

Wenn ein Element NULL ist, haben Sie folgende Möglichkeiten:

• Lassen Sie das Schlüssel-Wert-Paar aus dem JSON-Code aus.
• Gibt einen Wert zurück, der dem Azure AD B2C-Anspruchsdatentyp entspricht. Geben Sie z. B. für einen string Datentyp eine leere Zeichenfolge ""zurück. Geben Sie für einen integer Datentyp einen Nullwert 0zurück. Geben Sie für einen dateTime Datentyp einen Minimalwert 0001-01-01T00:00:00.0000000Zzurück.

Im folgenden Beispiel wird veranschaulicht, wie ein Nullwert behandelt wird. Die E-Mail wird aus dem JSON-Code weggelassen:

{
  "name": "Emily Smith",
  "loyaltyNumber":  1234
}

Analysieren eines geschachtelten JSON-Texts

Zum Parsen einer geschachtelten JSON-Textantwort müssen Sie die Metadaten „ResolveJsonPathsInJsonTokens“ auf „true“ festlegen. Legen Sie im Ausgabeanspruch den PartnerClaimType auf das JSON-Pfadelement fest, das Sie ausgeben möchten.

"contacts": [
  {
    "id": "MAINCONTACT_1",
    "person": {
      "name": "Emily Smith",
      "loyaltyNumber":  1234,
      "emails": [
        {
          "id": "EMAIL_1",
          "type": "WORK",
          "email": "email@domain.com"
        }
      ]
    }
  }
],

Die Ausgabeansprüche sollten wie der folgende XML-Codeausschnitt aussehen:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="contacts[0].person.name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="contacts[0].person.emails[0].email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="contacts[0].person.loyaltyNumber" />
</OutputClaims>

Lokalisieren der REST-API

In einem RESTful-technischen Profil können Sie die Sprache/das Gebietsschema der aktuellen Sitzung senden und ggf. eine lokalisierte Fehlermeldung auslösen. Mithilfe des Anspruchslösers können Sie einen kontextbezogenen Anspruch senden, z. B. die Benutzersprache. Das folgende Beispiel zeigt ein RESTful-technisches Profil, das dieses Szenario veranschaulicht.

<TechnicalProfile Id="REST-ValidateUserData">
  <DisplayName>Validate user input data</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="emailAddress" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

Behandeln von Fehlermeldungen

Ihre REST-API muss möglicherweise eine Fehlermeldung zurückgeben, z. B. "Der Benutzer wurde im CRM-System nicht gefunden.". Wenn ein Fehler auftritt, sollte die REST-API eine HTTP 409-Fehlermeldung (Konfliktantwortstatuscode) zurückgeben. Weitere Informationen finden Sie im technischen Profil von RESTful.

Dieses Verhalten kann nur durch Aufrufen eines technischen REST-API-Profils aus einem technischen Validierungsprofil erreicht werden. Der Benutzer kann die Daten auf der Seite korrigieren und die Überprüfung bei der Seitenübermittlung erneut ausführen.

Wenn Sie direkt von einer Benutzerreise aus auf ein technisches REST-API-Profil verweisen, wird der Benutzer mit der entsprechenden Fehlermeldung zurück zur Anwendung der vertrauenden Seite umgeleitet.

Entwicklung Ihrer REST-API

Ihre REST-API kann auf jeder Plattform entwickelt und in jeder Programmiersprache geschrieben werden, sofern sie sicher ist und Ansprüche im JSON-Format senden und empfangen kann.

Die Anforderung an Ihren REST-API-Dienst stammt von Azure AD B2C-Servern. Der REST-API-Dienst muss auf einem öffentlich zugänglichen HTTPS-Endpunkt veröffentlicht werden. Der REST-API-Aufruf wird von einer IP-Adresse des Azure-Rechenzentrums empfangen.

Sie können serverlose Cloudfunktionen wie HTTP-Trigger in Azure Functions verwenden, um die Entwicklung zu vereinfachen.

Sie sollten ihren REST-API-Dienst und die zugrunde liegenden Komponenten (z. B. die Datenbank und das Dateisystem) so entwerfen, dass sie hoch verfügbar sind.

Von Bedeutung

Ihre Endpunkte müssen die Azure AD B2C-Sicherheitsanforderungen erfüllen. Ältere TLS-Versionen und Verschlüsselungen sind veraltet. Weitere Informationen finden Sie unter Azure AD B2C TLS- und Verschlüsselungssuiteanforderungen.

Nächste Schritte

• Erfahren Sie, wie Sie einen API-Connector hinzufügen, um die Anmeldeerfahrungen zu ändern.
• Erfahren Sie, wie Sie einen API-Connector hinzufügen, um Token mit externen Ansprüchen zu bereichern.
• Erfahren Sie, wie Sie Ihren API-Connector sichern.
• Erste Schritte mit unseren Beispielen

Beispiele für die Verwendung eines technischen RESTful-Profils finden Sie in den folgenden Artikeln:

• Anleitung: Hinzufügen eines API-Connectors zu einem Registrierungsprozess
• Schritt-für-Schritt-Anleitung: Hinzufügen von REST-API-Anspruchsaustauschen zu benutzerdefinierten Richtlinien in Azure Active Directory B2C
• Sichern Ihrer REST-API-Dienste
• Aufrufen einer REST-API mithilfe einer benutzerdefinierten Azure Active Directory B2C-Richtlinie

• Erfahren Sie, wie Sie Resilienz beim Interfacing mit externen Prozessen erstellen.
• Erfahren Sie, wie Sie Resilienz durch bewährte Methoden für Entwickler erstellen.