Integrieren von REST-API-Anspruchsaustauschvorgängen in Ihre benutzerdefinierte Azure AD B2C-RichtlinieIntegrate REST API claims exchanges in your Azure AD B2C custom policy

Hinweis

In Azure Active Directory B2C sind benutzerdefinierte Richtlinien in erster Linie für komplexe Szenarien konzipiert.In Azure Active Directory B2C, custom policies are designed primarily to address complex scenarios. Für die meisten Szenarien empfehlen wir die Verwendung von integrierten Benutzerflows.For most scenarios, we recommend that you use built-in user flows.

Das Identity Experience Framework (IEF), das Azure Active Directory B2C (Azure AD B2C) zugrunde liegt, kann im Rahmen einer User Journey mit RESTful-APIs integriert werden.The Identity Experience Framework, which underlies Azure Active Directory B2C (Azure AD B2C), can integrate with RESTful APIs within a user journey. In diesem Artikel wird gezeigt, wie Sie eine User Journey erstellen, die mithilfe eines technischen RESTful-Profils mit einem RESTful-Dienst interagiert.This article shows how to create a user journey that interacts with a RESTful service using a RESTful technical profile.

Mit Azure AD B2C können Sie einer User Journey Ihre eigene Geschäftslogik hinzufügen, indem Sie Ihren eigenen RESTful-Dienst aufrufen.Using Azure AD B2C, you can add your own business logic to a user journey by calling your own RESTful service. Das Identity Experience Framework kann Daten an Ihren RESTful-Dienst senden und von ihm empfangen, um Ansprüche auszutauschen.The Identity Experience Framework can send and receive data from your RESTful service to exchange claims. Beispielsweise können Sie folgende Aktionen ausführen:For example, you can:

  • Überprüfen von Benutzereingabedaten.Validate user input data. Sie können beispielsweise überprüfen, ob die vom Benutzer angegebene E-Mail-Adresse in Ihrer Kundendatenbank vorhanden ist. Und wenn dies nicht der Fall ist, können Sie einen Fehler ausgeben.For example, you can verify that the email address provided by the user exists in your customer's database, and if not, present an error.
  • Verarbeiten von Ansprüchen.Process claims. Wenn ein Benutzer seinen Vornamen vollständig in Kleinbuchstaben oder Großbuchstaben eingibt, kann die REST-API den Namen so formatieren, dass nur der erste Buchstabe groß geschrieben wird, und den Namen in dieser Form an Azure AD B2C zurückgeben.If a user enters their first name in all lowercase or all uppercase letters, your REST API can format the name with only the first letter capitalized and return it to Azure AD B2C.
  • Anreichern von Benutzerdaten durch eine stärkere Integration in die Branchenanwendungen des Unternehmens.Enrich user data by further integrating with corporate line-of-business applications. Ihr RESTful-Dienst kann die E-Mail-Adresse des Benutzers empfangen, die Kundendatenbank abfragen und die Treuenummer des Benutzers an Azure AD B2C zurückgeben.Your RESTful service can receive the user's email address, query the customer's database, and return the user's loyalty number to Azure AD B2C. Die Rückgabeansprüche können dann im Azure AD-Konto des Benutzers gespeichert, in den nächsten Orchestrierungsschritten ausgewertet oder in das Zugriffstoken eingebunden werden.Then return claims can be stored in the user's Azure AD account, evaluated in the next orchestration steps, or included in the access token.
  • Ausführen von benutzerdefinierter Geschäftslogik.Run custom business logic. Sie können Pushbenachrichtigungen senden, Unternehmensdatenbanken aktualisieren, einen Benutzermigrationsprozess ausführen, Berechtigungen verwalten, Datenbanken überwachen und andere Workflows ausführen.You can send push notifications, update corporate databases, run a user migration process, manage permissions, audit databases, and perform any other workflows.

Diagramm eines Anspruchsaustauschs über den RESTful-Dienst

Hinweis

Wenn der RESTful-Dienst nur langsam reagiert oder gar keine Antwort an Azure AD B2C sendet, beträgt der Timeoutwert 30 Sekunden, und die Anzahl der Wiederholungsversuche ist auf „2“ festgelegt (d. h. es gibt insgesamt 3 Versuche).If there is slow or no response from the RESTful service to Azure AD B2C, the timeout is 30 seconds and the retry count is 2 times (meaning there are 3 tries in total). Die Einstellungen für das Timeout und die Anzahl der Wiederholungsversuche können derzeit nicht konfiguriert werden.The timeout and retry count settings are not currently configurable.

Aufrufen eines RESTful-DienstsCalling a RESTful service

Die Interaktion umfasst einen Anspruchsaustausch von Informationen zwischen den REST-API-Ansprüchen und Azure AD B2C.The interaction includes a claims exchange of information between the REST API claims and Azure AD B2C. Sie können die Integration in die RESTful-Dienste auf folgende Weise entwerfen:You can design the integration with the RESTful services in the following ways:

  • Technisches Validierungsprofil.Validation technical profile. Der Anruf des RESTful-Diensts erfolgt innerhalb eines technischen Validierungsprofils des angegebenen selbstbestätigten technischen Profils oder über ein Anzeigesteuerelement zur Überprüfung einer Anzeigesteuerung.The call to the RESTful service happens within a validation technical profile of the specified self-asserted technical profile, or a verification display control of a display control. Mit dem technischen Validierungsprofil werden die vom Benutzer bereitgestellten Daten überprüft, bevor die User Journey fortgesetzt wird.The validation technical profile validates the user-provided data before the user journey moves forward. Beim technischen Validierungsprofil haben Sie folgende Möglichkeiten:With the validation technical profile, you can:

    • Senden von Ansprüchen an Ihre REST-APISend claims to your REST API.
    • Überprüfen von Ansprüchen und Auslösen von benutzerdefinierten Fehlermeldungen, die dem Benutzer angezeigt werdenValidate claims, and throw custom error messages that are displayed to the user.
    • Zurücksenden von Ansprüchen von der REST-API an nachfolgende OrchestrierungsschritteSend back claims from the REST API to subsequent orchestration steps.
  • Anspruchsaustausch.Claims exchange. Ein direkter Anspruchsaustausch kann durch Aufrufen eines technischen REST-API-Profils direkt aus einem Orchestrierungsschritt in einer User Journey konfiguriert werden.A direct claims exchange can be configured by calling a REST API technical profile directly from an orchestration step of a user journey. Diese Definition ist auf folgende Vorgänge beschränkt:This definition is limited to:

    • Senden von Ansprüchen an Ihre REST-APISend claims to your REST API.
    • Überprüfen von Ansprüchen und Auslösen von benutzerdefinierten Fehlermeldungen, die an die Anwendung zurückgegeben werdenValidate claims, and throw custom error messages that are returned to the application.
    • Zurücksenden von Ansprüchen von der REST-API an nachfolgende OrchestrierungsschritteSend back claims from the REST API to subsequent orchestration steps.

Sie können einen Rest-API-Aufruf in jedem Schritt der User Journey hinzufügen, die durch eine benutzerdefinierte Richtlinie definiert ist.You can add a REST API call at any step in the user journey defined by a custom policy. Beispielsweise können Sie in folgenden Schritten eine Rest-API aufrufen:For example, you can call a REST API:

  • Während der Anmeldung, kurz bevor Azure AD B2C die Anmeldeinformationen überprüftDuring sign-in, just before Azure AD B2C validates the credentials.
  • Unmittelbar nach der AnmeldungImmediately after sign-in.
  • Bevor Azure AD B2C ein neues Konto im Verzeichnis erstelltBefore Azure AD B2C creates a new account in the directory.
  • Nachdem Azure AD B2C ein neues Konto im Verzeichnis erstellt hatAfter Azure AD B2C creates a new account in the directory.
  • Bevor Azure AD B2C ein Zugriffstoken ausgibtBefore Azure AD B2C issues an access token.

Erfassung über das technische Validierungsprofil

Senden von DatenSending data

Das InputClaims-Element im technischen RESTful-Profil enthält eine Liste der Ansprüche, die an den RESTful-Dienst gesendet werden sollen.In the RESTful technical profile, the InputClaims element contains a list of claims to send to your RESTful service. Sie können den Namen Ihres Anspruchs dem im RESTful-Dienst definierten Namen zuordnen, einen Standardwert festlegen und Anspruchskonfliktlöser verwenden.You can map the name of your claim to the name defined in the RESTful service, set a default value, and use claims resolvers.

Mit dem Attribut „SendClaimsIn“ können Sie konfigurieren, wie die Eingabeansprüche an den RESTful-Anspruchsanbieter gesendet werden.You can configure how the input claims are sent to the RESTful claims provider by using the SendClaimsIn attribute. Mögliche Werte:The possible values are:

  • Body: Wird im JSON-Format im HTTP POST-Anforderungstext gesendet.Body, sent in the HTTP POST request body in JSON format.
  • Form: Wird im HTTP POST-Anforderungstext in einem durch kaufmännische Und-Zeichen (&) getrennten Schlüsselwertformat gesendet.Form, sent in the HTTP POST request body in an ampersand '&' separated key value format.
  • Header: Wird im HTTP GET-Anforderungsheader gesendet.Header, sent in the HTTP GET request header.
  • QueryString: Wird in der Abfragezeichenfolge der HTTP GET-Anforderung gesendet.QueryString, sent in the HTTP GET request query string.

Wenn die Option Body konfiguriert wird, können Sie mit dem technischen REST-API-Profil eine komplexe JSON-Nutzlast an einen Endpunkt senden.When the Body option is configured, the REST API technical profile allows you to send a complex JSON payload to an endpoint. Weitere Informationen finden Sie unter Senden einer JSON-Nutzlast.For more information, see Send a JSON payload.

Empfangen von DatenReceiving data

Das OutputClaims-Element des technischen RESTful-Profils enthält eine Liste von Ansprüchen, die von der REST-API zurückgegeben werden.The OutputClaims element of the RESTful technical profile contains a list of claims returned by the REST API. Sie müssen den Namen des Anspruchs, der in Ihrer Richtlinie definiert ist, dem Namen, der in der REST-API definiert wurde, zuordnen.You may need to map the name of the claim defined in your policy to the name defined in the REST API. Sie können auch Ansprüche einfügen, die nicht vom REST-API-Identitätsanbieter zurückgegeben werden, wenn Sie das Attribut „DefaultValue“ festlegen.You can also include claims that aren't returned by the REST API identity provider, as long as you set the DefaultValue attribute.

Bei den Ausgabeansprüchen, die vom RESTful-Anspruchsanbieter analysiert werden, wird immer die Analyse einer einfachen JSON-Textantwort erwartet. Beispiel:The output claims parsed by the RESTful claims provider always expect to parse a flat JSON Body response, such as:

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

Die Ausgabeansprüche sollten wie folgt aussehen:The output claims should look like the following:

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

Zum Analysieren einer geschachtelten JSON-Textantwort müssen Sie die Metadaten „ResolveJsonPathsInJsonTokens“ auf „true“ festlegen.To parse a nested JSON Body response, set the ResolveJsonPathsInJsonTokens metadata to true. Legen Sie im Ausgabeanspruch den Wert für „PartnerClaimType“ auf das auszugebende JSON-Pfadelement fest.In the output claim, set the PartnerClaimType to the JSON path element you want to output.

"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 folgt aussehen:The output claims should look like following:

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

SicherheitshinweiseSecurity considerations

Sie müssen ihren REST-API-Endpunkt schützen, damit nur authentifizierte Clients mit ihm kommunizieren können.You must protect your REST API endpoint so that only authenticated clients can communicate with it. Die REST-API muss einen HTTPS-Endpunkt verwenden.The REST API must use an HTTPS endpoint. Legen Sie die Metadaten „AuthenticationType“ auf eine der folgenden Authentifizierungsmethoden fest:Set the AuthenticationType metadata to one of the following authentication methods:

REST-API-PlattformREST API platform

Ihre REST-API kann auf jeder beliebigen Plattform aufsetzen und in einer beliebigen Programmiersprache geschrieben werden, solange sie sicher ist und Ansprüche senden und empfangen kann, wie im technischen RESTful-Profil angegeben.Your REST API can be based on any platform and written in any programing language, as long as it's secure and can send and receive claims as specified in RESTful technical profile.

Lokalisieren der REST-APILocalize the REST API

In einem technischen RESTful-Profil empfiehlt es sich, die Sprache bzw. das Gebietsschema der aktuellen Sitzung zu senden und bei Bedarf eine lokalisierte Fehlermeldung auszugeben.In a RESTful technical profile, you may want to send the current session's language/locale, and if necessary, raise a localized error message. Mit dem Anspruchskonfliktlöser können Sie einen kontextbezogenen Anspruch (z. B. die Benutzersprache) senden.Using the claims resolver, you can send a contextual claim, such as the user language. Das folgende Beispiel zeigt ein technisches RESTful-Profil mit diesem Szenario.The following example shows a RESTful technical profile demonstrating this scenario.

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

Verarbeiten von FehlermeldungenHandling error messages

Ihre REST-API muss möglicherweise eine Fehlermeldung zurückgeben (z. B. „Der Benutzer wurde nicht im CRM-System gefunden“).Your REST API may need to return an error message, such as "The user was not found in the CRM system." Wenn ein Fehler auftritt, sollte die REST-API die HTTP-Fehlermeldung 409 (Antwortstatuscode „Konflikt“) zurückgeben.If an error occurs, the REST API should return an HTTP 409 error message (Conflict response status code). Weitere Informationen finden Sie unter Technisches RESTful-Profil.For more information, see the RESTful technical profile.

Dies kann nur durch Aufrufen eines technischen REST-API-Profils aus einem technischen Validierungsprofil erreicht werden.This can only be achieved by calling a REST API technical profile from a validation technical profile. Dadurch kann der Benutzer die Daten auf der Seite korrigieren und die Validierung bei der Seitenübermittlung erneut ausführen.This allows the user to correct the data on the page and run the validation again upon page submission.

Die HTTP-Antwort 409 ist erforderlich, um in diesem Orchestrierungsschritt die Verarbeitung aller nachfolgenden technischen Validierungsprofile zu verhindern.An HTTP 409 response is required to prevent the processing of any subsequent validation technical profiles within this orchestration step.

Wenn Sie direkt aus einer User Journey auf ein technisches REST-API-Profil verweisen, wird der Benutzer mit der entsprechenden Fehlermeldung wieder an die Anwendung der vertrauenden Seite zurückgeleitet.If you reference a REST API technical profile directly from a user journey, the user is redirected back to the relying party application with the relevant error message.

Veröffentlichen Ihrer REST-APIPublishing your REST API

Die Anforderung an Ihren REST-API-Dienst kommt von Azure AD B2C-Servern.The request to your REST API service comes from Azure AD B2C servers. Der REST-API-Dienst muss auf einem öffentlich zugänglichen HTTPS-Endpunkt veröffentlicht werden.The REST API service must be published to a publicly accessible HTTPS endpoint. Die REST-API-Aufrufe gehen von der IP-Adresse eines Azure-Rechenzentrums ein.The REST API calls will arrive from an Azure data center IP address.

Achten Sie beim Entwurf Ihres REST-API-Diensts und der zugrundeliegenden Komponenten (z. B. Datenbank und Dateisystem) auf Hochverfügbarkeit.Design your REST API service and its underlying components (such as the database and file system) to be highly available.

Nächste SchritteNext steps

In den folgenden Artikeln finden Sie Beispiele für die Verwendung eines technischen RESTful-Profils:See the following articles for examples of using a RESTful technical profile: