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

Artikel
01/22/2024

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:

Erstellen Sie die JSON-Nutzlast mit der GenerateJson-Anspruchstransformation.
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: