Freigeben über


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

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 erhält Daten in einer Sammlung von Ausgabeansprüchen zurück. Weitere Informationen finden Sie unter Integrieren von REST-API-Anspruchsaustauschvorgängen in Ihre benutzerdefinierte Azure AD B2C-Richtlinie.

Protocol

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

Das folgende Beispiel zeigt ein technisches RESTful-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 von Ansprüchen, 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 firstName und der surname-Anspruch wird als lastName an die REST-API gesendet. Der email-Anspruch wird unverändert festgelegt.

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

Das InputClaimsTransformations-Element darf eine Sammlung von InputClaimsTransformation-Elementen, die zum Ändern der Eingabeansprüche oder zum Generieren neuer verwendet werden, enthalten, bevor es an die REST-API gesendet wird.

Senden einer JSON-Nutzlast

Das technische REST-API-Profil ermöglicht es Ihnen, eine komplexe JSON-Nutzlast an einen Endpunkt zu senden.

So senden Sie eine komplexe JSON-Nutzlast:

  1. Erstellen Sie die JSON-Nutzlast mit der GenerateJson-Anspruchstransformation.
  2. Im technischen Profil der REST-API:
    1. Fügen Sie eine Eingabeanspruchstransformation mit einem Verweis auf die GenerateJson-Anspruchstransformation hinzu.
    2. Legen Sie die SendClaimsIn-Metadatenoption auf body fest.
    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 TechnicalProfile-Beispiel wird eine Überprüfungs-E-Mail mit einem Drittanbieter-E-Mail-Dienst (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 von Ansprüchen, die von der REST-API zurückgegeben wurden. Sie müssen den Namen des Anspruchs, der in Ihrer Richtlinie definiert ist, dem Namen, der in der REST-API definiert wurde, zuordnen. Sie können auch Ansprüche einfügen, die nicht von der REST-API zurückgegeben werden, sofern Sie das DefaultValue-Attribut festlegen.

Das OutputClaimsTransformations-Element darf eine Sammlung von OutputClaimsTransformation-Elementen, die zum Ändern der Ausgabeansprüche oder zum Generieren neuer verwendet werden, enthalten.

Im folgenden Beispiel wird der von der REST-API zurückgegebene Anspruch gezeigt:

  • Der MembershipId-Anspruch wird dem Namen des loyaltyNumber-Anspruchs zugeordnet.

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

  • Der loyaltyNumberIsNew-Anspruch hat den Standardwert true.
<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="MembershipId" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumberIsNew" DefaultValue="true" />
</OutputClaims>

Metadaten

attribute Erforderlich BESCHREIBUNG
ServiceUrl Ja Die URL des REST-API-Endpunkts.
AuthenticationType Ja Der Typ der Authentifizierung, die vom RESTful-Anspruchsanbieter ausgeführt wird. Mögliche Werte: None, Basic, Bearer, ClientCertificate oder ApiKeyHeader.
  • Der Wert None gibt an, dass die REST-API anonym ist.
  • Der Wert Basic gibt an, dass die REST-API mit HTTP-Standardauthentifizierung geschützt ist. Nur verifizierte Benutzer, einschließlich Azure AD B2C, haben Zugriff auf Ihre API.
  • Der (empfohlene) Wert ClientCertificate gibt an, dass die REST-API den Zugriff mithilfe von Clientzertifikatauthentifizierung einschränkt. Nur Dienste mit den richtigen Zertifikaten (z.B. Azure AD B2C) erhalten Zugriff auf Ihre API.
  • Der Wert Bearer gibt an, dass die REST-API den Zugriff mithilfe des OAuth2-Bearertokens des Clients beschränkt.
  • Der Wert ApiKeyHeader gibt an, dass die REST-API mit einem API-Schlüssel im HTTP-Header (z. B. x-functions-key) gesichert ist.
AllowInsecureAuthInProduction Nein Gibt an, ob der AuthenticationType in der Produktionsumgebung auf none festgelegt werden kann (DeploymentMode von TrustFrameworkPolicy ist auf Production festgelegt oder nicht angegeben). Mögliche Werte: TRUE oder FALSE (Standard).
SendClaimsIn Nein Gibt an, wie Eingabeansprüche an den RESTful-Anspruchsanbieter gesendet werden. Mögliche Werte: Body (Standard), Form, Header, Url oder QueryString.
Der Wert Body ist der Eingabeanspruch, der im Anforderungstext im JSON-Format gesendet wird.
Der Wert Form ist der Eingabeanspruch, der im Anforderungstext in einem durch kaufmännische Und-Zeichen (&) getrenntes Schlüssel-Wert-Format gesendet wird.
Der Wert Header ist der Eingabeanspruch, der im Anforderungsheader gesendet wird.
Der Wert Url ist der Eingabeanspruch, der in der URL gesendet wird, z. B. https://api.example.com/{claim1}/{claim2}?{claim3}={claim4}. Der Teil der URL mit dem Hostnamen darf keine Ansprüche enthalten.
Der Wert QueryString ist der Eingabeanspruch, der in der Abfragezeichenfolge der Anforderung gesendet wird.
Die jeweils aufgerufenen HTTP-Verben lauten wie folgt:
  • Body: POST
  • Form: POST
  • Header: GET
  • Url: GET
  • QueryString: GET
ClaimsFormat Nein Derzeit nicht verwendet, kann ignoriert werden.
ClaimUsedForRequestPayload Nein Der Name eines Zeichenfolgenanspruchs, der die an die REST-API zu sendende Nutzlast enthält.
DebugMode Nein Führt das technische Profil im Debugmodus aus. Mögliche Werte sind true oder false (Standardwert). Im Debugmodus kann die REST-API mehr Informationen zurückgeben. Die entsprechenden Informationen finden Sie im Abschnitt Zurückgegebene Fehlermeldung.
IncludeClaimResolvingInClaimsHandling Nein Gibt bei Eingabe- und Ausgabeansprüchen an, ob die Anspruchsauflösung im technischen Profil enthalten ist. Mögliche Werte sind true oder false (Standardwert). Wenn Sie im technischen Profil eine Anspruchsauflösung verwenden möchten, legen Sie für diese Einstellung den Wert true fest.
ResolveJsonPathsInJsonTokens Nein Gibt an, ob das technische Profil JSON-Pfade auflö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 Ausgabeanspruch (OutputClaim) den Partneranspruchstyp (PartnerClaimType) auf das auszugebende JSON-Pfadelement fest. 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 einem REST-API-Fehler angezeigt wird. Die Fehlermeldungen können lokalisiert werden.

attribute Erforderlich BESCHREIBUNG
DefaultUserMessageIfRequestFailed Nein Eine angepasste Standardfehlermeldung für alle REST-API-Ausnahmen.
UserMessageIfCircuitOpen Nein Fehlermeldung bei Nichterreichbarkeit der REST-API. Wenn hier nichts angegeben ist, wird die DefaultUserMessageIfRequestFailed-Meldung zurückgegeben.
UserMessageIfDnsResolutionFailed Nein Fehlermeldung für eine Ausnahme bei der DNS-Auflösung. Wenn hier nichts angegeben ist, wird die DefaultUserMessageIfRequestFailed-Meldung zurückgegeben.
UserMessageIfRequestTimeout Nein Fehlermeldung bei einem Timeout der Verbindung. Wenn hier nichts angegeben ist, wird die DefaultUserMessageIfRequestFailed-Meldung zurückgegeben.

Kryptografische Schlüssel

Wenn als Typ der Authentifizierung None 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 als Typ der Authentifizierung Basic festgelegt ist, enthält das CryptographicKeys-Element die folgenden Attribute:

attribute Erforderlich BESCHREIBUNG
BasicAuthenticationUsername Ja Der zur Authentifizierung verwendete Benutzername.
BasicAuthenticationPassword Ja Das zur Authentifizierung verwendete Kennwort.

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 als Typ der Authentifizierung ClientCertificate festgelegt ist, enthält das CryptographicKeys-Element das folgende Attribut:

attribute Erforderlich BESCHREIBUNG
ClientCertificate Ja Das X509 Zertifikat (RSA-Schlüsselsatz) für die Authentifizierung.
<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 als Typ der Authentifizierung Bearer festgelegt ist, enthält das CryptographicKeys-Element das folgende Attribut:

attribute 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 als Typ der Authentifizierung ApiKeyHeader festgelegt ist, enthält das CryptographicKeys-Element das folgende Attribut:

attribute Erforderlich BESCHREIBUNG
Der Name des HTTP-Headers, z. B. x-functions-key oder x-api-key. Ja Der zur Authentifizierung verwendete Schlüssel.

Hinweis

Aktuell wird von Azure AD B2C nur ein einzelner HTTP-Header für die Authentifizierung unterstützt. Wenn für Ihren RESTful-Aufruf mehrere Header (z. B. eine Client-ID und der Wert eines geheimen Clientschlüssels) erforderlich sind, benötigen Sie irgendwie eine Proxyweiterleitung der Anforderung.

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

Rückgabe einer Validierungsfehlermeldung

Ihre REST-API muss möglicherweise eine Fehlermeldung zurückgeben (z.B. „Der Benutzer wurde nicht im CRM-System gefunden“). Wenn ein Fehler auftritt, sollte die REST-API eine HTTP-Fehlermeldung mit dem Antwortstatuscode 4xx zurückgeben, z B. 400 (Ungültige Anforderung) oder 409 (Konflikt). Der Antworttext enthält eine Fehlermeldung im JSON-Format:

{
  "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"
}
attribute Erforderlich Beschreibung
version Ja Die Version Ihrer REST-API. 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 vom RESTful-Endpunktanbieter, der angezeigt wird, wenn DebugMode aktiviert ist.
requestId Nein Eine Anforderungs-ID vom RESTful-Endpunktanbieter, die angezeigt wird, wenn DebugMode aktiviert ist.
userMessage Ja Eine Fehlermeldung, die dem Benutzer angezeigt wird.
developerMessage Nein Die ausführliche Beschreibung des Problems und Informationen zur Behebung, die angezeigt werden, wenn DebugMode aktiviert ist.
moreInfo Nein Ein URI, der auf zusätzliche Informationen verweist, die angezeigt werden, wenn DebugMode aktiviert ist.

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

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