Hinzufügen von API-Connectors zum Registrieren von Benutzerflüssen

2025-04-30

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.

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. Am Ende dieser exemplarischen Vorgehensweise können Sie einen Azure AD B2C-Benutzerfluss erstellen, der mit REST-API-Diensten interagiert, um Ihre Anmeldeerfahrungen zu ändern.

Sie können einen API-Endpunkt mithilfe eines unserer Beispiele erstellen.

In diesem Szenario fügen wir den Benutzern die Möglichkeit hinzu, eine Treuenummer auf der Azure AD B2C-Anmeldeseite einzugeben. Die REST-API überprüft, ob die Kombination aus E-Mail und Treuenummer einem Werbecode zugeordnet ist. Wenn die REST-API einen Werbecode für diesen Benutzer findet, wird sie an Azure AD B2C zurückgegeben. Schließlich wird der Aktionscode in die Tokenansprüche so eingefügt, dass er von der Anwendung genutzt werden kann.

Sie können die Interaktion auch als Orchestrierungsschritt entwerfen. Dies ist geeignet, wenn die REST-API keine Daten auf dem Bildschirm überprüft und immer Ansprüche zurückgibt. Weitere Informationen finden Sie unter Exemplarische Vorgehensweise: Integrieren von REST-API-Anspruchsbörsen in Ihre Azure AD B2C-Benutzerreise als Orchestrierungsschritt.

Voraussetzungen

Erstellen Sie einen Benutzerflow, damit sich Benutzer bei Ihrer Anwendung registrieren und anmelden können.
Registrieren Sie eine Webanwendung.

Führen Sie die Schritte in "Erste Schritte mit benutzerdefinierten Richtlinien in Active Directory B2C" aus. In diesem Lernprogramm erfahren Sie, wie Sie benutzerdefinierte Richtliniendateien für die Verwendung Ihrer Azure AD B2C-Mandantenkonfiguration aktualisieren.
Registrieren Sie eine Webanwendung.

Erstellen eines API-Connectors

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

Melden Sie sich beim Azure-Portal an.
Wählen Sie unter Azure-DiensteAzure AD B2C aus.
Wählen Sie API-Connectors aus, und wählen Sie dann "Neuer API-Connector" aus.
Geben Sie einen Anzeigenamen für den Aufruf an. Überprüfen Sie beispielsweise Benutzerinformationen.
Geben Sie die Endpunkt-URL für den API-Aufruf an.
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.
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": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "objectId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
 "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",
 "step": "<step-name>",
 "client_id":"00001111-aaaa-2222-bbbb-3333cccc4444",
 "ui_locales":"en-US"
}

Nur Benutzereigenschaften und benutzerdefinierte Attribute, die unterAzure AD B2C>Benutzerattribute aufgeführt sind, können in der Anforderung gesendet werden.

Benutzerdefinierte Attribute sind im Format extension_<extensions-app-id>_CustomAttribute im Verzeichnis 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 in Azure AD B2C.

Darüber hinaus werden in der Regel die folgenden 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.
Schritt ('step'): Der Schritt oder Punkt im Benutzerflow, für den der API-Connector aufgerufen wurde. Mögliche Werte sind:
- PostFederationSignup – entspricht „Nach dem Verbund mit einem Identitätsanbieter während der Registrierung“.
- PostAttributeCollection - entspricht "Vor dem Erstellen des Benutzers"
- PreTokenIssuance - entspricht "Vor dem Senden des Tokens (Vorschau)". Weitere Informationen zu diesem Schritt
Client-ID ('client_id') – Der appId Wert der Anwendung, für die ein Endbenutzer sich in einem Benutzerablauf authentifiziert. Dabei handelt es sich nicht um den appId-Wert der Ressourcenanwendung in Zugriffstoken.
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.

Von Bedeutung

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 sie explizit den Fall überprüft und behandelt, bei dem eine Anspruch nicht in der Anforderung enthalten ist.

Aktivieren des API-Connectors in einem Benutzerablauf

Führen Sie die folgenden Schritte aus, um einem Registrierungsbenutzerablauf einen API-Connector hinzuzufügen.

Melden Sie sich beim Azure-Portal an.
Wählen Sie unter Azure-DiensteAzure AD B2C aus.
Wählen Sie Benutzerflows und dann den Benutzerflow aus, dem Sie den API-Connector hinzufügen möchten.
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
- Vor dem Senden des Tokens (Vorschau)
Wählen Sie Speichern aus.

Diese Schritte sind nur für die Registrierung und Anmeldung (empfohlen) und Registrierung (empfohlen) vorhanden, gelten jedoch nur für den Registrierungsteil der Erfahrung.

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). Dieser Schritt geht der Seite zur Attributsammlung voraus, die dem Benutzer zum Sammeln von Benutzerattributen angezeigt wird. Dieser Schritt wird nicht aufgerufen, wenn ein Benutzer sich mit einem lokalen Konto registriert.

In diesem Schritt an die API gesendete Beispielanforderung

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

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "step": "PostFederationSignup",
 "client_id":"<guid>",
 "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 bedeutet, dass der Benutzerfluss mit dem nächsten Schritt fortgesetzt werden soll: der Seite zur Attributsammlung.

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 immer aufgerufen, bevor ein Benutzerkonto erstellt wird.

In diesem Schritt an die API gesendete Beispielanforderung

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

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "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",
 "step": "PostAttributeCollection",
 "client_id":"00001111-aaaa-2222-bbbb-3333cccc4444",
 "ui_locales":"en-US"
}

Die Ansprüche, die an die API gesendet werden, hängen von den Informationen ab, die vom Benutzer erfasst werden 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:

Überschreibt alle Werte, die bereits von einem Benutzer auf der Attributauflistungsseite bereitgestellt wurden.

Um Ansprüche in das Verzeichnis bei der Registrierung zu schreiben, die nicht vom Benutzer erfasst werden sollen, sollten Sie weiterhin die Ansprüche unter "Benutzerattribute des Benutzerablaufs " auswählen, die den Benutzer standardmäßig um Werte bitten, aber Sie können benutzerdefiniertes JavaScript oder CSS verwenden, um die Eingabefelder eines Endbenutzers auszublenden.

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

Blockierungsantwort

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

Validierungsfehlerantwort

Wenn die API mit einer Überprüfungsfehlerantwort antwortet, verbleibt der Benutzerfluss auf der Attributsammlungsseite und dem Benutzer wird ein 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.

Vor dem Senden des Tokens (Vorschau)

Von Bedeutung

API-Konnektoren, die in diesem Schritt verwendet werden, befinden sich in der Vorschau. Weitere Informationen zu Vorschauen finden Sie unter Produktbedingungen für Onlinedienste.

Ein API-Connector in diesem Schritt wird aufgerufen, wenn ein Token während der Anmeldungen und Registrierungen ausgestellt werden soll. Ein API-Connector für diesen Schritt kann verwendet werden, um das Token mit Anspruchswerten aus externen Quellen zu bereichern.

In diesem Schritt an die API gesendete Beispielanforderung

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

{
 "clientId": "11112222-bbbb-3333-cccc-4444dddd5555",
 "step": "PreTokenApplicationClaims",
 "ui_locales":"en-US",
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
}

Die Ansprüche, die an die API gesendet werden, hängen von den für den Benutzer definierten Informationen ab.

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

Fortsetzungsantwort

Eine Fortsetzungsantwort gibt an, dass der Benutzerablauf mit dem nächsten Schritt fortgesetzt werden soll: Stellen Sie das Token aus.

In einer Fortsetzungsantwort kann die API zusätzliche Ansprüche zurückgeben. Ein anspruch, der von der API zurückgegeben wird, die Sie im Token zurückgeben möchten, muss ein integrierter Anspruch oder ein benutzerdefiniertes Attribut sein und muss in der Anwendungsanspruchskonfiguration des Benutzerablaufs ausgewählt werden.

Der Anspruchswert im Token ist der von der API zurückgegebene Wert, nicht der Wert im Verzeichnis. Einige Anspruchswerte können von der API-Antwort nicht überschrieben werden. Ansprüche, die von der API zurückgegeben werden können, entsprechen den Ansprüchen unter Benutzerattribute (mit Ausnahme von email).

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

Hinweis

Die API wird nur während einer anfänglichen Authentifizierung aufgerufen. Wenn Sie Aktualisierungstoken verwenden, um still neue Zugriffs- oder ID-Token zu erhalten, enthält das Token die Werte, die während der anfänglichen Authentifizierung ausgewertet wurden.

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	Typ	Erforderlich	BESCHREIBUNG
Version	Schnur	Ja	Die Version Ihrer API
Aktion	Schnur	Ja	Der Wert muss `Continue` sein.
<integriertesBenutzerattribut>	<Attributtyp>	Nein	Zurückgegebene Werte können Werte überschreiben, die von einem Benutzer gesammelt wurden.
<extension_{extensions-app-id}_benutzerdefiniertesAttribut>	<Attributtyp>	Nein	Der Anspruch muss `_<extensions-app-id>_` nicht enthalten sein, es 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 a problem with your request. You are not able to sign up at this time. Please contact your system administrator",
}

Parameter	Typ	Erforderlich	BESCHREIBUNG
Version	Schnur	Ja	Die Version Ihrer API
Aktion	Schnur	Ja	Der Wert muss `ShowBlockPage` sein.
Benutzernachricht	Schnur	Ja	Meldung, die dem Benutzer angezeigt wird.

Endbenutzererfahrung mit einer Blockierungsantwort

Beispiel für eine Blockierungsantwort

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	Typ	Erforderlich	BESCHREIBUNG
Version	Schnur	Ja	Die Version Ihrer API
Aktion	Schnur	Ja	Der Wert muss `ValidationError` sein.
Zustand	Integer / Zeichenkette	Ja	Für eine Validierungsfehlerantwort muss der Wert `400` oder `"400"` sein.
Benutzernachricht	Schnur	Ja	Meldung, die dem Benutzer angezeigt wird.

Hinweis

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

Anzeige einer Validierungsfehlerantwort für den Endbenutzende

Beispiel für eine Überprüfungsfehlerantwort

Vorbereiten eines REST-API-Endpunkts

Für diese exemplarische Vorgehensweise sollten Sie über eine REST-API verfügen, die überprüft, ob eine E-Mail-Adresse in Ihrem Back-End-System mit einer Treue-ID registriert ist. Bei der Registrierung sollte die REST-API einen Registrierungsaktionscode zurückgeben, den der Kunde zum Kauf von Waren innerhalb Ihrer Anwendung verwenden kann. Andernfalls sollte die REST-API eine HTTP 409-Fehlermeldung zurückgeben: "Treue-ID '{Treue-ID}' ist nicht mit der E-Mail-Adresse '{email}' verknüpft.".

Der folgende JSON-Code veranschaulicht die Daten, die Azure AD B2C an Ihren REST-API-Endpunkt senden.

{
    "email": "User email address",
    "language": "Current UI language",
    "loyaltyId": "User loyalty ID"
}

Nachdem Ihre REST-API die Daten überprüft hat, muss sie einen HTTP 200 (OK) mit den folgenden JSON-Daten zurückgeben:

{
    "promoCode": "24534"
}

Wenn die Überprüfung fehlgeschlagen ist, muss die REST-API einen HTTP 409 (Conflict) mit dem userMessage JSON-Element zurückgeben. Das IEF erwartet die userMessage Anforderung, die die REST-API zurückgibt. Dieser Anspruch wird dem Benutzer als Zeichenfolge angezeigt, wenn die Überprüfung fehlschlägt.

{
    "version": "1.0.1",
    "status": 409,
    "userMessage": "LoyaltyId ID '1234' is not associated with 'david@contoso.com' email address."
}

Das Setup des REST-API-Endpunkts liegt außerhalb des Umfangs dieses Artikels. Wir haben ein Azure Functions-Beispiel erstellt. Sie können auf den vollständigen Azure-Funktionscode auf GitHub zugreifen.

Definieren von Ansprüchen

Ein Anspruch bietet eine temporäre Speicherung von Daten während der Ausführung einer Azure AD B2C-Richtlinie. Sie können Ansprüche im Abschnitt "Anspruchsschema " deklarieren.

Öffnen Sie die Erweiterungsdatei Ihrer Richtlinie. Beispiel: SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
Suchen Sie nach dem BuildingBlocks-Element . Wenn das Element nicht vorhanden ist, fügen Sie es hinzu.
Suchen Sie das ClaimsSchema-Element . Wenn das Element nicht vorhanden ist, fügen Sie es hinzu.
Fügen Sie dem ClaimsSchema-Element die folgenden Ansprüche hinzu.

<ClaimType Id="loyaltyId">
  <DisplayName>Your loyalty ID</DisplayName>
  <DataType>string</DataType>
  <UserInputType>TextBox</UserInputType>
</ClaimType>
<ClaimType Id="promoCode">
  <DisplayName>Your promo code</DisplayName>
  <DataType>string</DataType>
  <UserInputType>Paragraph</UserInputType>
</ClaimType>
  <ClaimType Id="userLanguage">
  <DisplayName>User UI language (used by REST API to return localized error messages)</DisplayName>
  <DataType>string</DataType>
</ClaimType>

Hinzufügen des technischen Profils der RESTful-API

Ein RESTful-technisches Profil bietet Unterstützung für die Interoperabilität mit Ihrem eigenen RESTful-Dienst. Azure AD B2C sendet Daten an den RESTful-Dienst in einer InputClaims Sammlung und empfängt Daten zurück in einer OutputClaims Sammlung. Suchen Sie das ClaimsProviders-Element , und fügen Sie einen neuen Anspruchsanbieter wie folgt hinzu:

<ClaimsProvider>
  <DisplayName>REST APIs</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="REST-ValidateProfile">
      <DisplayName>Check loyaltyId Azure Function web hook</DisplayName>
      <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
      <Metadata>
        <!-- Set the ServiceUrl with your own REST API endpoint -->
        <Item Key="ServiceUrl">https://your-account.azurewebsites.net/api/ValidateProfile?code=your-code</Item>
        <Item Key="SendClaimsIn">Body</Item>
        <!-- Set AuthenticationType to Basic or ClientCertificate in production environments -->
        <Item Key="AuthenticationType">None</Item>
        <!-- REMOVE the following line in production environments -->
        <Item Key="AllowInsecureAuthInProduction">true</Item>
      </Metadata>
      <InputClaims>
        <!-- Claims sent to your REST API -->
        <InputClaim ClaimTypeReferenceId="loyaltyId" />
        <InputClaim ClaimTypeReferenceId="email" />
        <InputClaim ClaimTypeReferenceId="userLanguage" PartnerClaimType="lang" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
      </InputClaims>
      <OutputClaims>
        <!-- Claims parsed from your REST API -->
        <OutputClaim ClaimTypeReferenceId="promoCode" />
      </OutputClaims>
      <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

In diesem Beispiel wird userLanguage innerhalb der JSON-Nutzlast als lang an den REST-Dienst gesendet. Der Wert des userLanguage Anspruchs enthält die aktuelle Benutzersprachen-ID. Weitere Informationen finden Sie unter Claim Resolver.

Konfigurieren des technischen PROFILs der RESTful-API

Legen Sie nach der Bereitstellung Der REST-API die Metadaten des REST-ValidateProfile technischen Profils so fest, dass sie Ihre eigene REST-API widerspiegeln, einschließlich:

ServiceUrl verwenden. Legen Sie die URL des REST-API-Endpunkts fest.
SendClaimsIn. Geben Sie an, wie die Eingabeansprüche an den RESTful-Anspruchsanbieter gesendet werden.
AuthenticationType. Legen Sie den Typ der Authentifizierung fest, die vom RESTful-Anspruchsanbieter ausgeführt wird.
AllowInsecureAuthInProduction. Sorgen Sie in einer Produktionsumgebung dafür, dass diese Metadaten auf true festgelegt werden.

Weitere Konfigurationen finden Sie in den METADATEN des RESTful-technischen Profils .

Die obigen AuthenticationType Kommentare und AllowInsecureAuthInProduction angeben Änderungen, die Sie vornehmen sollten, wenn Sie zu einer Produktionsumgebung wechseln. Informationen zum Sichern Ihrer RESTful-APIs für die Produktion finden Sie unter Secure RESTful API.

Überprüfen der Benutzereingabe

Um die Treuenummer des Benutzers während der Registrierung zu erhalten, müssen Sie dem Benutzer erlauben, diese Daten auf dem Bildschirm einzugeben. Fügen Sie den Ausgabeanspruch loyaltyId zur Anmeldeseite hinzu, indem Sie ihn dem Element OutputClaims des bestehenden technischen Registrierungsprofilabschnitts hinzufügen. Geben Sie die gesamte Liste der Ausgabeansprüche an, um die Reihenfolge zu steuern, in der die Ansprüche auf dem Bildschirm angezeigt werden.

Fügen Sie den Verweis auf das technische Überprüfungsprofil dem technischen Profil für die Registrierung hinzu, das REST-ValidateProfile aufruft. Das neue technische Profil der Validierung wird am Anfang der in der Grundrichtlinie definierten <ValidationTechnicalProfiles> Sammlung hinzugefügt. Dieses Verhalten bedeutet, dass Azure AD B2C erst nach erfolgreicher Überprüfung das Konto im Verzeichnis erstellt.

Suchen Sie das ClaimsProviders-Element . Fügen Sie einen neuen Anspruchsanbieter wie folgt hinzu:

<ClaimsProvider>
  <DisplayName>Local Account</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="LocalAccountSignUpWithLogonEmail">
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="Verified.Email" Required="true"/>
        <OutputClaim ClaimTypeReferenceId="newPassword" Required="true"/>
        <OutputClaim ClaimTypeReferenceId="reenterPassword" Required="true"/>
        <OutputClaim ClaimTypeReferenceId="displayName"/>
        <OutputClaim ClaimTypeReferenceId="givenName"/>
        <OutputClaim ClaimTypeReferenceId="surName"/>
        <!-- Required to present the text box to collect the data from the user -->
        <OutputClaim ClaimTypeReferenceId="loyaltyId"/>
        <!-- Required to pass the promoCode returned from "REST-ValidateProfile" 
        to subsequent orchestration steps and token issuance-->
        <OutputClaim ClaimTypeReferenceId="promoCode" />
      </OutputClaims>
      <ValidationTechnicalProfiles>
        <ValidationTechnicalProfile ReferenceId="REST-ValidateProfile" />
      </ValidationTechnicalProfiles>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>
<ClaimsProvider>
  <DisplayName>Self Asserted</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="SelfAsserted-Social">
      <InputClaims>
        <InputClaim ClaimTypeReferenceId="email" />
      </InputClaims>
        <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" />
        <OutputClaim ClaimTypeReferenceId="displayName"/>
        <OutputClaim ClaimTypeReferenceId="givenName"/>
        <OutputClaim ClaimTypeReferenceId="surname"/>
        <!-- Required to present the text box to collect the data from the user -->
        <OutputClaim ClaimTypeReferenceId="loyaltyId"/>
        <!-- Required to pass the promoCode returned from "REST-ValidateProfile" 
        to subsequent orchestration steps and token issuance-->
        <OutputClaim ClaimTypeReferenceId="promoCode" />
      </OutputClaims>
      <ValidationTechnicalProfiles>
        <ValidationTechnicalProfile ReferenceId="REST-ValidateProfile"/>
      </ValidationTechnicalProfiles>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

Einschließen eines Anspruchs in das Token

Um den Anspruch „Aktionscode“ an die Anwendung der vertrauenden Seite zurückzugeben, fügen Sie der Datei „SocialAndLocalAccounts/SignUpOrSignIn.xml“ einen Ausgabeanspruch hinzu. Der Ausgabeanspruch ermöglicht es, den Anspruch nach einer erfolgreichen User Journey in das Token einzufügen, der dann an die Anwendung gesendet wird. Ändern Sie im Abschnitt für die vertrauende Seite das Element des technischen Profils, um promoCode als Ausgabeanspruch hinzuzufügen.

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="OpenIdConnect" />
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="displayName" />
      <OutputClaim ClaimTypeReferenceId="givenName" />
      <OutputClaim ClaimTypeReferenceId="surname" />
      <OutputClaim ClaimTypeReferenceId="email" />
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="identityProvider" />
      <OutputClaim ClaimTypeReferenceId="tenantId" AlwaysUseDefaultValue="true" DefaultValue="{Policy:TenantObjectId}" />
      <OutputClaim ClaimTypeReferenceId="promoCode" DefaultValue="" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

Testen der benutzerdefinierten Richtlinie

Melden Sie sich beim Azure-Portal an.
Wenn Sie Zugriff auf mehrere Mandanten haben, wählen Sie im oberen Menü das Symbol "Einstellungen " aus, um im Menü "Verzeichnisse + Abonnements " zu Ihrem Microsoft Entra ID-Mandanten zu wechseln.
Wählen Sie "Alle Dienste " in der oberen linken Ecke des Azure-Portals aus, und suchen Sie dann nach App-Registrierungen, und wählen Sie sie aus.
Wählen Sie "Identity Experience Framework" aus.
Wählen Sie " Benutzerdefinierte Richtlinie hochladen" aus, und laden Sie dann die geänderten Richtliniendateien hoch: TrustFrameworkExtensions.xmlund SignUpOrSignin.xml.
Wählen Sie die Registrierungs- oder Anmelderichtlinie aus, die Sie hochgeladen haben, und klicken Sie auf die Schaltfläche " Jetzt ausführen ".
Sie sollten sich mit einer E-Mail-Adresse registrieren können.
Klicken Sie auf den Link "Jetzt registrieren ".
Geben Sie in der Treue-ID "1234" ein, und klicken Sie auf "Weiter". An diesem Punkt sollten Sie eine Fehlermeldung zur Überprüfung erhalten.
Wechseln Sie zu einem anderen Wert, und klicken Sie auf "Weiter".
Das an Ihre Anwendung zurückgesendete Token enthält den promoCode Claim.

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1584295703,
  "nbf": 1584292103,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/",
  "aud": "22223333-cccc-4444-dddd-5555eeee6666",
  "acr": "b2c_1a_signup_signin",
  "nonce": "defaultNonce",
  "iat": 1584292103,
  "auth_time": 1584292103,
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "given_name": "Emily",
  "family_name": "Smith",
  "promoCode": "84362"
  ...
}

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.
- Azure AD B2C wartet maximal 10 Sekunden , um eine Antwort zu erhalten. Wird keine empfangen, wird ein weiterer Versuch (Wiederholung) unternommen, die API aufzurufen.
- Wenn Sie eine serverlose Funktion oder einen skalierbaren Webdienst verwenden, wählen Sie in der Produktion einen Hostingplan, der dafür sorgt, dass die API „wach“ oder „warm“ bleibt. Für Azure Functions wird empfohlen, mindestens den Premium-Plan in der Produktion 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.

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.

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 bei Bedarf in der Entwicklung aggressivere Protokollierungsebenen (z. B. „trace“ oder „debug“).
Überwachen Sie Ihre API hinsichtlich langer Antwortzeiten.

Darüber hinaus protokolliert Azure AD B2C Metadaten zu den API-Transaktionen, die während der Benutzerauthentifizierung über einen Benutzerablauf auftreten. Um diese zu finden:

Wechseln Sie zu Azure AD B2C.
Wählen Sie unter "Aktivitäten" die Option "Überwachungsprotokolle" aus.
Filtern Sie die Listenansicht: Wählen Sie für "Datum" das gewünschte Zeitintervall aus, und wählen Sie für "Aktivität" eine API aus, die als Teil eines Benutzerablaufs aufgerufen wurde.
Prüfen Sie einzelne Protokolle. Jede Zeile stellt einen API-Connector dar, der versucht, während eines Benutzerablaufs aufgerufen zu werden. Wenn ein API-Aufruf fehlschlägt und ein Wiederholungsversuch durchgeführt wird, wird er weiterhin als einzelne Zeile dargestellt. Dies numberOfAttempts gibt an, wie oft Ihre API aufgerufen wurde. Dieser Wert kann sein 1oder 2. Weitere Informationen zum API-Aufruf finden Sie in den Protokollen.

Beispiel für eine API-Connectortransaktion während der Benutzerauthentifizierung

Verwenden von serverlosen Cloudfunktionen

Serverlose Cloudfunktionen, z. B. HTTP-Trigger in Azure-Funktionen, bieten eine einfache, hochverwendbare, leistungsfähige Möglichkeit zum Erstellen von API-Endpunkten, die als API-Connectors verwendet werden.

Bewährte Methoden

Stellen Sie Folgendes sicher:

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.
- Wenn Sie eine serverlose Funktion oder einen skalierbaren Webdienst verwenden, wählen Sie in der Produktion einen Hostingplan, der dafür sorgt, dass die API „wach“ oder „warm“ bleibt. Für Azure Functions wird zumindest die Verwendung des Premium-Plans empfohlen.
Stellen Sie die Hochverfügbarkeit Ihrer API sicher.
Überwachen und optimieren Sie die Leistung von nachgelagerten APIs, Datenbanken oder anderen Abhängigkeiten Ihrer API.

Von Bedeutung

Verwenden von Protokollierung

Ü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 bei Bedarf in der Entwicklung aggressivere Protokollierungsebenen (z. B. „trace“ oder „debug“).
Überwachen Sie Ihre API hinsichtlich langer Antwortzeiten.

Nächste Schritte

Erste Schritte mit unseren Beispielen.
Sichern Sie Ihren API-Connector

Freigeben über

Hinzufügen eines API-Connectors zu einem Registrierungsprozess

Voraussetzungen

Erstellen eines API-Connectors

An die API gesendete Anforderung

Aktivieren des API-Connectors in einem Benutzerablauf

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

In diesem Schritt an die API gesendete Beispielanforderung

Von der Web-API in diesem Schritt erwartete Antworttypen

Fortsetzungsantwort

Blockierungsantwort

Vor dem Erstellen des Benutzers

In diesem Schritt an die API gesendete Beispielanforderung

Von der Web-API in diesem Schritt erwartete Antworttypen

Fortsetzungsantwort

Blockierungsantwort

Validierungsfehlerantwort

Vor dem Senden des Tokens (Vorschau)

In diesem Schritt an die API gesendete Beispielanforderung

Von der Web-API in diesem Schritt erwartete Antworttypen

Fortsetzungsantwort

Beispielantworten

Beispiel für eine Fortsetzungsantwort

Beispiel für eine Blockierungsantwort

Beispiel für eine Validierungsfehlerantwort

Vorbereiten eines REST-API-Endpunkts

Definieren von Ansprüchen

Hinzufügen des technischen Profils der RESTful-API

Konfigurieren des technischen PROFILs der RESTful-API

Überprüfen der Benutzereingabe

Einschließen eines Anspruchs in das Token

Testen der benutzerdefinierten Richtlinie

Bewährte Methoden und Problembehandlungen

Verwenden von serverlosen Cloudfunktionen

Bewährte Methoden

Verwenden von Protokollierung

Verwenden von serverlosen Cloudfunktionen

Bewährte Methoden

Verwenden von Protokollierung

Nächste Schritte

Feedback

Zusätzliche Ressourcen