Definieren eines RESTful-technischen Profils in einer benutzerdefinierten Azure Active Directory B2C-Richtlinie

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.

Hinweis

In Azure Active Directory B2C sind benutzerdefinierte Richtlinien in erster Linie für komplexe Szenarien konzipiert. Für die meisten Szenarien empfehlen wir die Verwendung von integrierten Benutzerflows. Informieren Sie sich, sofern noch nicht geschehen, unter Tutorial: Erstellen von Benutzerflows und benutzerdefinierten Richtlinien in Azure Active Directory B2C über das Starter Pack für benutzerdefinierte Richtlinien.

Azure Active Directory B2C (Azure AD B2C) bietet Unterstützung für die Integration Ihres eigenen RESTful-Diensts. Azure AD B2C sendet Daten an den RESTful-Dienst in einer Sammlung von Eingabeansprüchen und empfängt Daten zurück in einer Ausgabeanspruchsauflistung. Weitere Informationen finden Sie unter Integrieren von REST-API-Anspruchsbörsen in Ihre benutzerdefinierte Azure AD B2C-Richtlinie.

Protokoll

Das Name-Attribut des Protocol-Elements muss auf Proprietary festgelegt werden. Das Handler-Attribut muss den vollqualifizierten Namen der Protokollhandlerassembly enthalten, die von Azure AD B2C verwendet wird: Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null.

Das folgende Beispiel zeigt ein RESTful-technisches Profil:

<TechnicalProfile Id="REST-UserMembershipValidator">
  <DisplayName>Validate user input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  ...

Eingabeansprüche

Das InputClaims-Element enthält eine Liste der Ansprüche, die an die REST-API gesendet werden sollen. Sie können auch den Namen Ihres Anspruchs dem in der REST-API definierten Namen zuordnen. Das folgende Beispiel zeigt die Zuordnung zwischen Ihrer Richtlinie und der REST-API. Der GivenName-Anspruch wird als Vorname an die REST-API gesendet, während nachname als Nachname gesendet wird. Der E-Mail-Anspruch wird wie folgt festgelegt.

<InputClaims>
  <InputClaim ClaimTypeReferenceId="email" />
  <InputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="firstName" />
  <InputClaim ClaimTypeReferenceId="surname" PartnerClaimType="lastName" />
</InputClaims>

Das InputClaimsTransformations-Element kann eine Sammlung von InputClaimsTransformation-Elementen enthalten, die verwendet werden, um die Eingabeansprüche zu ändern oder neue zu generieren, bevor sie an die REST-API gesendet werden.

Senden einer JSON-Nutzlast

Mit dem technischen REST-API-Profil können Sie eine komplexe JSON-Nutzlast an einen Endpunkt senden.

So senden Sie eine komplexe JSON-Nutzlast:

1. Erstellen Sie Ihre JSON-Nutzlast mit der GenerateJson-Anspruchstransformation.
2. Im technischen Profil der REST-API:
   1. Fügen Sie eine Eingabeansprüchetransformation mit einem Verweis auf die GenerateJson Anspruchstransformation hinzu.
   2. Festlegen der SendClaimsIn Metadatenoption auf body
   3. Legen Sie die ClaimUsedForRequestPayload Metadatenoption auf den Namen des Anspruchs fest, der die JSON-Nutzlast enthält.
   4. Fügen Sie im Eingabeanspruch einen Verweis auf den Eingabeanspruch hinzu, der die JSON-Nutzlast enthält.

Im folgenden Beispiel TechnicalProfile wird eine Überprüfungs-E-Mail mithilfe eines Drittanbieter-E-Mail-Diensts (in diesem Fall SendGrid) gesendet.

<TechnicalProfile Id="SendGrid">
  <DisplayName>Use SendGrid's email API to send the code to the user</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://api.sendgrid.com/v3/mail/send</Item>
    <Item Key="AuthenticationType">Bearer</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="ClaimUsedForRequestPayload">sendGridReqBody</Item>
    <Item Key="DefaultUserMessageIfRequestFailed">Cannot process your request right now, please try again later.</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_SendGridApiKey" />
  </CryptographicKeys>
  <InputClaimsTransformations>
    <InputClaimsTransformation ReferenceId="GenerateSendGridRequestBody" />
  </InputClaimsTransformations>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="sendGridReqBody" />
  </InputClaims>
</TechnicalProfile>

Ausgabeansprüche

Das OutputClaims-Element 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 von der REST-API zurückgegeben werden, solange Sie das DefaultValue Attribut festlegen.

Das OutputClaimsTransformations-Element kann eine Auflistung von OutputClaimsTransformation-Elementen enthalten, die verwendet werden, um die Ausgabeansprüche zu ändern oder neue zu generieren.

Das folgende Beispiel zeigt den Anspruch, der von der REST-API zurückgegeben wird:

• Der MembershipId-Anspruch , der dem Namen des LoyaltyNumber-Anspruchs zugeordnet ist.

Das technische Profil gibt auch Ansprüche zurück, die nicht vom Identitätsanbieter zurückgegeben werden:

• Der LoyaltyNumberIsNew-Anspruch , der einen Standardwert aufweist, auf den truefestgelegt ist.

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="MembershipId" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumberIsNew" DefaultValue="true" />
</OutputClaims>

Metadaten

Merkmal	Erforderlich	BESCHREIBUNG
ServiceUrl (Englisch)	Ja	Die URL des REST-API-Endpunkts.
Authentifizierungsart	Ja	Der Typ der Authentifizierung, die vom RESTful-Anspruchsanbieter ausgeführt wird. Mögliche Werte: None, , Basic, Bearer, , ClientCertificateoder ApiKeyHeader. Der None Wert gibt an, dass die REST-API anonym ist. Der Basic Wert gibt an, dass die REST-API mit der HTTP-Standardauthentifizierung gesichert ist. Nur überprüfte Benutzer, einschließlich Azure AD B2C, können auf Ihre API zugreifen. Der ClientCertificate (empfohlene) Wert gibt an, dass die REST-API den Zugriff mithilfe der Clientzertifikatauthentifizierung einschränkt. Nur Dienste mit den entsprechenden Zertifikaten, z. B. Azure AD B2C, können auf Ihre API zugreifen. Der Bearer Wert gibt an, dass die REST-API den Zugriff mithilfe des Client-OAuth2 Bearer-Tokens einschränkt. Der ApiKeyHeader Wert gibt an, dass die REST-API mit DEM API-Schlüssel-HTTP-Header gesichert ist, z. B. x-functions-key.
AllowInsecureAuthInProduction	Nein	Gibt an, ob die AuthenticationType Einstellung in der Produktionsumgebungnone (der DeploymentMode auf oder nicht angegeben) festgelegt Production werden kann. Mögliche Werte: true oder false (Standard).
SendClaimsIn	Nein	Gibt an, wie die Eingabeansprüche an den RESTful-Anspruchsanbieter gesendet werden. Mögliche Werte: Body (Standard), Form, , Headeroder UrlQueryString . Der Body Wert ist der Eingabeanspruch, der im Anforderungstext im JSON-Format gesendet wird. Der Form Wert ist der Eingabeanspruch, der im Anforderungstext in einem durch Und-Zeichen getrennten Schlüsselwertformat gesendet wird. Der Header Wert ist der Eingabeanspruch, der im Anforderungsheader gesendet wird. Der Url Wert ist der Eingabeanspruch, der in der URL gesendet wird, https://api.example.com/{claim1}/{claim2}?{claim3}={claim4}z. B. . Der Hostnamenteil der URL darf keine Ansprüche enthalten. Der QueryString Wert ist der Eingabeanspruch, der in der Anforderungsabfragezeichenfolge gesendet wird. Die von jedem aufgerufenen HTTP-Verben sind wie folgt: Body:BEREITSTELLEN Form:BEREITSTELLEN Header:ERHALTEN Url:ERHALTEN QueryString:ERHALTEN
Anspruchsformat	Nein	Derzeit nicht verwendet, kann ignoriert werden.
ClaimUsedForRequestPayload	Nein	Name eines Zeichenfolgenanspruchs, der die Nutzlast enthält, die an die REST-API gesendet werden soll.
Debug-Modus	Nein	Führt das technische Profil im Debugmodus aus. Mögliche Werte sind true oder false (Standardwert). Im Debugmodus kann die REST-API weitere Informationen zurückgeben. Weitere Informationen finden Sie im Abschnitt " Fehlermeldung zurückgeben ".
IncludeClaimResolvingInClaimsHandling	Nein	Gibt für Eingabe- und Ausgabeansprüche an, ob die Forderungsauflösung im technischen Profil enthalten ist. Mögliche Werte sind true oder false (Standardwert). Wenn Sie einen Anspruchslöser im technischen Profil verwenden möchten, legen Sie dies auf true.
ResolveJsonPathsInJsonTokens	Nein	Gibt an, ob das technische Profil JSON-Pfade aufgelöst. Mögliche Werte sind true oder false (Standardwert). Verwenden Sie diese Metadaten, um Daten aus einem geschachtelten JSON-Element zu lesen. Legen Sie in einem OutputClaim das PartnerClaimType JSON-Pfadelement fest, das Sie ausgeben möchten. Beispiel: firstName.localized oder data[0].to[0].email
UseClaimAsBearerToken	Nein	Der Name des Anspruchs, der das Bearertoken enthält.

Fehlerbehandlung

Die folgenden Metadaten können verwendet werden, um die Fehlermeldungen zu konfigurieren, die bei REST-API-Fehlern angezeigt werden. Die Fehlermeldungen können lokalisiert werden.

Merkmal	Erforderlich	BESCHREIBUNG
DefaultUserMessageIfRequestFailed	Nein	Eine standardmäßige angepasste Fehlermeldung für alle REST-API-Ausnahmen.
UserMessageIfCircuitOpen	Nein	Fehlermeldung, wenn die REST-API nicht erreichbar ist. Wenn nicht angegeben, wird die DefaultUserMessageIfRequestFailed zurückgegeben.
UserMessageIfDnsResolutionFailed	Nein	Fehlermeldung für die AUSNAHME der DNS-Auflösung. Wenn nicht angegeben, wird die DefaultUserMessageIfRequestFailed zurückgegeben.
UserMessageIfRequestTimeout	Nein	Fehlermeldung, wenn die Verbindung timeout ist. Wenn nicht angegeben, wird die DefaultUserMessageIfRequestFailed zurückgegeben.

Kryptografieschlüssel

Wenn der Authentifizierungstyp auf None"CryptographicKeys" festgelegt ist, wird das CryptographicKeys-Element nicht verwendet.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
</TechnicalProfile>

Wenn der Authentifizierungstyp auf Basic"CryptographicKeys" festgelegt ist, enthält das CryptographicKeys-Element die folgenden Attribute:

Merkmal	Erforderlich	BESCHREIBUNG
BasicAuthenticationBenutzername	Ja	Der Benutzername, der für die Authentifizierung verwendet wird.
BasicAuthenticationPassword	Ja	Das Kennwort, das für die Authentifizierung verwendet wird.

Das folgende Beispiel zeigt ein technisches Profil mit Standardauthentifizierung:

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">Basic</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BasicAuthenticationUsername" StorageReferenceId="B2C_1A_B2cRestClientId" />
    <Key Id="BasicAuthenticationPassword" StorageReferenceId="B2C_1A_B2cRestClientSecret" />
  </CryptographicKeys>
</TechnicalProfile>

Wenn der Authentifizierungstyp auf ClientCertificate"CryptographicKeys" festgelegt ist, enthält das CryptographicKeys-Element das folgende Attribut:

Merkmal	Erforderlich	BESCHREIBUNG
Client-Zertifikat	Ja	Das für die Authentifizierung zu verwendende X509-Zertifikat (RSA-Schlüsselsatz).

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">ClientCertificate</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="ClientCertificate" StorageReferenceId="B2C_1A_B2cRestClientCertificate" />
  </CryptographicKeys>
</TechnicalProfile>

Wenn der Authentifizierungstyp auf Bearer"CryptographicKeys" festgelegt ist, enthält das CryptographicKeys-Element das folgende Attribut:

Merkmal	Erforderlich	BESCHREIBUNG
BearerAuthenticationToken	Nein	Das OAuth 2.0-Bearertoken.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">Bearer</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_B2cRestClientAccessToken" />
  </CryptographicKeys>
</TechnicalProfile>

Wenn der Authentifizierungstyp auf ApiKeyHeader"CryptographicKeys" festgelegt ist, enthält das CryptographicKeys-Element das folgende Attribut:

Merkmal	Erforderlich	BESCHREIBUNG
Der Name des HTTP-Headers, z x-functions-key. B. oder x-api-key.	Ja	Der Schlüssel, der für die Authentifizierung verwendet wird.

Hinweis

Derzeit unterstützt Azure AD B2C nur einen HTTP-Header für die Authentifizierung. Wenn Ihr RESTful-Aufruf mehrere Header benötigt, z. B. eine Client-ID und einen geheimen Clientschlüsselwert, müssen Sie die Anforderung auf irgendeine Weise proxyn.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">ApiKeyHeader</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="x-functions-key" StorageReferenceId="B2C_1A_RestApiKey" />
  </CryptographicKeys>
</TechnicalProfile>

Fehlermeldung zur Rückgabe der Gültigkeitsprüfung

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 4xx-Fehlermeldung zurückgeben, z. B. 400 (ungültige Anforderung) oder 409 (Konflikt)-Antwortstatuscode. Der Antworttext enthält eine in JSON formatierte Fehlermeldung:

{
  "version": "1.0.0",
  "status": 409,
  "code": "API12345",
  "requestId": "50f0bd91-2ff4-4b8f-828f-00f170519ddb",
  "userMessage": "Message for the user",
  "developerMessage": "Verbose description of problem and how to fix it.",
  "moreInfo": "https://restapi/error/API12345/moreinfo"
}

Merkmal	Erforderlich	BESCHREIBUNG
Ausgabe	Ja	Ihre REST-API-Version. Beispiel: 1.0.1
Status	Ja	Eine HTTP-Antwortstatuscode-ähnliche Zahl und muss 409 sein. Ihr REST-Dienst kann einen HTTP 4XX-Statuscode zurückgeben, aber der Wert des status im JSON-formatierten Antworttexts abgelegten Datei muss sein 409.
Code	Nein	Ein Fehlercode des RESTful-Endpunktanbieters, der angezeigt wird, wenn DebugMode diese aktiviert ist.
requestId	Nein	Ein Anforderungsbezeichner des RESTful-Endpunktanbieters, der angezeigt wird, wenn DebugMode er aktiviert ist.
Benutzernachricht	Ja	Eine Fehlermeldung, die dem Benutzer angezeigt wird.
developerNachricht	Nein	Die ausführliche Beschreibung des Problems und dessen Behebung, die angezeigt wird, wenn DebugMode aktiviert ist.
mehrInfo	Nein	Ein URI, der auf zusätzliche Informationen verweist, die angezeigt werden, wenn DebugMode diese aktiviert sind.

Das folgende Beispiel zeigt eine C#-Klasse, die eine Fehlermeldung zurückgibt:

public class ResponseContent
{
  public string Version { get; set; }
  public int Status { get; set; }
  public string Code { get; set; }
  public string UserMessage { get; set; }
  public string DeveloperMessage { get; set; }
  public string RequestId { get; set; }
  public string MoreInfo { get; set; }
}

Nächste Schritte

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

• Integrieren von REST-API-Anspruchsbörsen in Ihre benutzerdefinierte Azure AD B2C-Richtlinie
• Exemplarische Vorgehensweise: Hinzufügen eines API-Connectors zu einem Registrierungsbenutzerablauf
• Exemplarische Vorgehensweise: Hinzufügen von REST-API-Anspruchswechseln zu benutzerdefinierten Richtlinien in Azure Active Directory B2C
• Sichern Ihrer REST-API-Dienste