Definieren eines selbstbestätigten technischen Profils in einer benutzerdefinierten Richtlinie in Azure Active Directory B2C

  • Artikel

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.

Alle Interaktionen in Azure Active Directory B2C (Azure AD B2C), bei denen vom Benutzer eine Eingabe erwartet wird, sind selbstbestätigte technische Profile. Beispiele: Registrierungsseite, Anmeldeseite oder Seite für die Kennwortzurücksetzung.

Protocol

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

Das folgende Beispiel zeigt ein selbstbestätigtes technisches Profil für eine Registrierung per E-Mail:

<TechnicalProfile Id="LocalAccountSignUpWithLogonEmail">
  <DisplayName>Email signup</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />

Eingabeansprüche

In einem selbstbestätigten technischen Profil können Sie die Elemente InputClaims und InputClaimsTransformations verwenden, um den Wert der Ansprüche vorab mit Daten aufzufüllen, die auf der selbstbestätigten Seite angezeigt werden (Anzeigeansprüche). In der Richtlinie zur Profilbearbeitung liest beispielsweise die User Journey zunächst das Benutzerprofil aus dem Azure AD B2C-Verzeichnisdienst. Anschließend legt das selbstbestätigte technische Profil die Eingabeansprüchen mit den im Benutzerprofil gespeicherten Daten fest. Diese Ansprüche werden aus dem Benutzerprofil gesammelt und anschließend dem Benutzer vorgelegt, der die vorhandenen Daten dann bearbeiten kann.

<TechnicalProfile Id="SelfAsserted-ProfileUpdate">
...
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="alternativeSecurityId" />
    <InputClaim ClaimTypeReferenceId="userPrincipalName" />
    <InputClaim ClaimTypeReferenceId="givenName" />
    <InputClaim ClaimTypeReferenceId="surname" />
  </InputClaims>

Anzeigeansprüche

Das DisplayClaims-Element enthält eine Liste mit anzuzeigenden Ansprüchen zum Erfassen von Daten vom Benutzer. Um Anzeigeansprüche vorab mit Werten aufzufüllen, verwenden Sie die zuvor beschriebenen Eingabeansprüche. Das Element kann darüber hinaus auch einen Standardwert enthalten.

Die Reihenfolge der Ansprüche in DisplayClaims bestimmt die Reihenfolge, in der Azure AD B2C die Ansprüche auf dem Bildschirm rendert. Um den Benutzer zur Eingabe eines Werts für einen bestimmten Anspruch zu zwingen, legen Sie das Attribut Required des DisplayClaim-Elements auf true fest.

Das ClaimType-Element in der DisplayClaims-Sammlung muss das UserInputType-Element auf einen von Azure AD B2C unterstützten Benutzereingabetyp festlegen. Zum Beispiel: TextBox oder DropdownSingleSelect.

Hinzufügen eines Verweises auf ein DisplayControl-Element

In die Sammlung der Anzeigeansprüche können Sie einen Verweis auf ein DisplayControl-Element einbeziehen, das Sie erstellt haben. Ein Anzeigesteuerelement ist ein Benutzeroberflächenelement mit spezieller Funktionalität, das mit dem Azure AD B2C-Back-End-Dienst interagiert. Es ermöglicht dem Benutzer das Durchführen von Aktionen auf der Seite, die ein technisches Validierungsprofil auf dem Back-End aufrufen. Beispielsweise das Überprüfen einer E-Mail-Adresse, Telefonnummer oder Kundentreuenummer.

Das folgende Beispiel TechnicalProfile veranschaulicht die Verwendung von Anzeigeansprüchen mit Anzeigesteuerelementen.

  • Der erste Anzeigeanspruch verweist auf das emailVerificationControl-Anzeigesteuerelement, das die E-Mail-Adresse erfasst und überprüft.
  • Der zweite Anzeigeanspruch verweist auf das captchaChallengeControl Anzeigesteuerelement, das CAPTCHA-Code generiert und überprüft.
  • Der sechste Anzeigeanspruch verweist auf das phoneVerificationControl Anzeigesteuerelement, das eine Telefonnummer sammelt und überprüft.
  • Die anderen Anzeigeansprüche sind ClaimTypes, die vom Benutzer erfasst werden sollen.
<TechnicalProfile Id="Id">
  <DisplayClaims>
    <DisplayClaim DisplayControlReferenceId="emailVerificationControl" />
    <DisplayClaim DisplayControlReferenceId="captchaChallengeControl" />
    <DisplayClaim ClaimTypeReferenceId="displayName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="givenName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="surName" Required="true" />
    <DisplayClaim DisplayControlReferenceId="phoneVerificationControl" />
    <DisplayClaim ClaimTypeReferenceId="newPassword" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="reenterPassword" Required="true" />
  </DisplayClaims>
</TechnicalProfile>

Wie bereits erwähnt, kann ein Anzeigeanspruch mit einem Verweis auf ein Anzeigesteuerelement seine eigene Überprüfung durchführen, z.B. die Überprüfung der E-Mail-Adresse. Außerdem unterstützt die selbstbestätigte Seite die Verwendung eines technischen Validierungsprofils, um die gesamte Seite einschließlich aller Benutzereingaben (Anspruchstypen oder Anzeigesteuerelemente) zu validieren, bevor Sie mit dem nächsten Orchestrierungsschritt fortfahren.

Kombinieren Sie die Verwendung von Anzeigeansprüchen und Ausgabeansprüchen sorgfältig

Wenn Sie mindestens ein DisplayClaim-Element in einem selbstbestätigten technischen Profil angeben, müssen Sie einen DisplayClaim für jeden Anspruch verwenden, der auf dem Bildschirm angezeigt und vom Benutzer erfasst werden soll. Von einem selbstbestätigten technischen Profil, das mindestens einen Anzeigeanspruch enthält, werden keine Ausgabeansprüche angezeigt.

Sehen Sie sich das folgende Beispiel an, in dem ein age-Anspruch als Ausgabeanspruch in einer Basisrichtlinie definiert wird. Bevor dem selbstbestätigten technischen Profil Anzeigeansprüche hinzugefügt werden, wird der age-Anspruch auf dem Bildschirm für die Datensammlung angezeigt, die vom Benutzer erfasst wurde:

<TechnicalProfile Id="id">
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="age" />
  </OutputClaims>
</TechnicalProfile>

Wenn eine Blattrichtlinie, die diese Basis nachfolgend erbt, officeNumber als Anzeigeanspruch angibt:

<TechnicalProfile Id="id">
  <DisplayClaims>
    <DisplayClaim ClaimTypeReferenceId="officeNumber" />
  </DisplayClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="officeNumber" />
  </OutputClaims>
</TechnicalProfile>

Der age Anspruch in der Basisrichtlinie wird dem Benutzer nicht mehr auf dem Bildschirm angezeigt – er ist effektiv "ausgeblendet". Um den age Anspruch anzuzeigen und den Alterswert vom Benutzer zu erfassen, müssen Sie einen age DisplayClaim hinzufügen.

Ausgabeansprüche

Das OutputClaims-Element enthält eine Liste mit an den nächsten Orchestrierungsschritt zurückzugebenden Ansprüchen. Das DefaultValue-Attribut wird erst wirksam, wenn der Anspruch noch nie festgelegt wurde. Wenn er in einem vorherigen Orchestrierungsschritt festgelegt wurde, wird der Standardwert selbst dann nicht wirksam, wenn der Benutzer den Wert leer lässt. Um die Verwendung eines Standardwerts zu erzwingen, legen Sie das Attribut AlwaysUseDefaultValue auf true fest.

Aus Sicherheitsgründen ist ein Kennwortanspruchswert (UserInputType auf Passwordfestgelegt) nur für die technischen Validierungsprofile des selbstbestätigten technischen Profils verfügbar. Der Kennwortanspruch kann in den nächsten Orchestrierungsschritten nicht verwendet werden.

Hinweis

In früheren Versionen von Identity Experience Framework (IEF) wurden Ausgabeansprüche verwendet, um Daten vom Benutzer zu erfassen. Verwenden Sie zum Erfassen von Daten vom Benutzer stattdessen eine DisplayClaims-Sammlung.

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

Unter welchen Umständen Ausgabeansprüche verwendet werden sollten

In einem selbstbestätigten technischen Profil gibt die Sammlung der Ausgabeansprüche die Ansprüche an den nächsten Orchestrierungsschritt zurück.

Verwenden Sie die Ausgabeansprüche in folgenden Fällen:

  • Ansprüche werden von der Ausgabeanspruchstransformation ausgegeben.
  • Festlegen eines Standardwerts in einem Ausgabeanspruch: Ohne Daten vom Benutzer zu erfassen oder die Daten aus dem technischen Validierungsprofil zurückgeben. Das selbstbestätigte technische Profil LocalAccountSignUpWithLogonEmail legt den Anspruch executed-SelfAsserted-Input auf true fest.
  • Ein technisches Validierungsprofil gibt die Ausgabeansprüche zurück: Ihr technisches Profil ruft möglicherweise ein technisches Validierungsprofil auf, das einige Ansprüche zurückgibt. Sie sollten die Ansprüche sammeln und an die nächsten Orchestrierungsschritte in der User Journey zurückzugeben. Bei der Anmeldung mit einem lokalen Konto ruft beispielsweise das selbstbestätigte technische Profil mit dem Namen SelfAsserted-LocalAccountSignin-Email das technische Validierungsprofil mit dem Namen login-NonInteractive auf. Dieses technische Profil überprüft die Anmeldeinformationen des Benutzers und gibt das Benutzerprofil zurück. Beispiele: „userPrincipalName“, „displayName“, „givenName“ und „surName“.
  • Ein Anzeigesteuerelement gibt die Ausgabeansprüche zurück: Ihr technisches Profil weist möglicherweise einen Verweis auf ein Anzeigesteuerelement auf. Das Anzeigesteuerelement gibt einige Ansprüche zurück, beispielsweise die überprüfte E-Mail-Adresse. Sie sollten die Ansprüche sammeln und an die nächsten Orchestrierungsschritte in der User Journey zurückzugeben.

Im folgenden Beispiel wird die Verwendung eines selbstbestätigten technischen Profils veranschaulicht, das sowohl Anzeigeansprüche als auch Ausgabeansprüche verwendet.

<TechnicalProfile Id="LocalAccountSignUpWithLogonEmail">
  <DisplayName>Email signup</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="IpAddressClaimReferenceId">IpAddress</Item>
    <Item Key="ContentDefinitionReferenceId">api.localaccountsignup</Item>
    <Item Key="language.button_continue">Create</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="email" />
  </InputClaims>
  <DisplayClaims>
    <DisplayClaim DisplayControlReferenceId="emailVerificationControl" />
    <DisplayClaim DisplayControlReferenceId="SecondaryEmailVerificationControl" />
    <DisplayClaim ClaimTypeReferenceId="displayName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="givenName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="surName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="newPassword" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="reenterPassword" Required="true" />
  </DisplayClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="email" Required="true" />
    <OutputClaim ClaimTypeReferenceId="objectId" />
    <OutputClaim ClaimTypeReferenceId="executed-SelfAsserted-Input" DefaultValue="true" />
    <OutputClaim ClaimTypeReferenceId="authenticationSource" />
    <OutputClaim ClaimTypeReferenceId="newUser" />
  </OutputClaims>
  <ValidationTechnicalProfiles>
    <ValidationTechnicalProfile ReferenceId="AAD-UserWriteUsingLogonEmail" />
  </ValidationTechnicalProfiles>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-AAD" />
</TechnicalProfile>

Hinweis

Wenn Sie den Kennwortanspruchswert im selbstbestätigten technischen Profil sammeln, ist dieser Wert nur innerhalb desselben technischen Profils oder innerhalb eines technischen Validierungsprofils verfügbar, auf welches dasselbe selbstbestätigte technische Profil verweist. Wenn die Ausführung dieses selbst bestätigten technischen Profils abgeschlossen ist und zu einem anderen technischen Profil wechselt, geht der Wert des Kennworts verloren. Folglich kann der Kennwortanspruch nur im Orchestrierungsschritt gespeichert werden, in dem er erfasst wird.

Ausgabeansprüche für eine Registrierungs- oder Anmeldeseite

Bei einer kombinierten Registrierungs- und Anmeldeseite müssen Sie Folgendes beachten, wenn Sie ein DataUri-Element für die Inhaltsdefinition verwenden, das den Seitentyp unifiedssp oder unifiedssd festlegt:

  • Nur die Ansprüche für den Benutzernamen und das Kennwort werden gerendert.
  • Bei den ersten zwei Ausgabeansprüchen muss es sich um den Benutzernamen und das Kennwort handeln (in dieser Reihenfolge).
  • Alle anderen Ansprüche werden nicht gerendert. Für diese Ansprüche müssen Sie entweder defaultValue festlegen oder ein technisches Profil für die Validierung des Anspruchsformulars aufrufen.

Beibehalten von Ansprüchen

Das PersistedClaims-Element wird nicht verwendet. Das selbstbestätigte technische Profil speichert die Daten nicht in Azure AD B2C. Stattdessen wird ein technisches Validierungsprofil aufgerufen, das für die Beibehaltung der Daten verantwortlich ist. So verwendet beispielsweise die Registrierungsrichtlinie das selbstbestätigte technische Profil LocalAccountSignUpWithLogonEmail, um das neue Benutzerprofil zu erfassen. Das technische Profil LocalAccountSignUpWithLogonEmail ruft das technische Validierungsprofil auf, um das Konto in Azure AD B2C zu erstellen.

Verwenden von technischen Validierungsprofilen

Ein technisches Validierungsprofil wird zur Überprüfung von einigen oder allen Ausgabeansprüchen des verweisenden technischen Profils verwendet. Die Eingabeansprüche des technischen Validierungsprofils müssen in den Ausgabeansprüchen des selbstbestätigten technischen Profils enthalten sein. Das technische Validierungsprofil überprüft die Benutzereingabe und kann einen Fehler an den Benutzer zurückgeben.

Das technische Validierungsprofil kann ein technisches Profil in der Richtlinie sein. Beispiele hierfür sind Microsoft Entra ID oder ein technisches REST-API-Profil. Im vorherigen Beispiel überprüft das technische Profil LocalAccountSignUpWithLogonEmail, ob der „signinName“ im Verzeichnis vorhanden ist. Ist dies nicht der Fall, erstellt das technische Validierungsprofil ein lokales Konto und gibt „objectId“, „authenticationSource“ und „newUser“ zurück. Das technische Profil SelfAsserted-LocalAccountSignin-Email ruft das technische Validierungsprofil login-NonInteractive auf, um die Anmeldeinformationen des Benutzers zu überprüfen.

Mit Ihrer Geschäftslogik können Sie durch eine weitere Integration in die Branchenanwendung auch ein technisches REST-API-Profil aufrufen, Eingabeansprüche überschreiben oder Benutzerdaten erweitern. Weitere Informationen finden Sie unter Technisches Validierungsprofil.

Hinweis

Ein technisches Validierungsprofil wird nur ausgelöst, wenn eine Eingabe vom Benutzer vorliegt. Sie können kein leeres selbstbestätigtes technisches Profil zum Aufrufen eines technischen Validierungsprofils erstellen, nur um das ContinueOnError-Attribut eines ValidationTechnicalProfile-Elements zu nutzen. Sie können nur ein technisches Validierungsprofil aus einem selbstbestätigten technischen Profil, das eine Eingabe des Benutzers anfordert, oder aus einem Orchestrierungsschritt in einer User Journey aufrufen.

Metadaten

attribute Erforderlich BESCHREIBUNG
setting.operatingMode 1 Nein Bei einer Anmeldeseite steuert diese Eigenschaft das Verhalten des Benutzernamensfelds also z.B. die Eingabeüberprüfung und Fehlermeldungen. Erwartete Werte: Username oder Email. Sehen Sie sich die Livedemo dieser Metadaten an.
AllowGenerationOfClaimsWithNullValues Nein Ermöglicht das Generieren eines Anspruchs mit Nullwert. Beispielsweise für den Fall, dass ein Benutzer ein Kontrollkästchen nicht aktiviert.
ContentDefinitionReferenceId Ja Der Bezeichner der Inhaltsdefinition, die diesem technischen Profil zugeordnet ist.
EnforceEmailVerification Nein Für die Registrierungs- oder Profilbearbeitung, erzwingt eine E-Mail-Überprüfung. Mögliche Werte: true (Standard) oder false.
setting.retryLimit Nein Legt fest, wie viele Versuche ein Benutzer zur Eingabe der Daten hat, die anhand des technischen Validierungsprofils überprüft werden. Beispielsweise versucht ein Benutzer, sich mit einem Konto zu registrieren, das bereits vorhanden ist, und versucht weiterhin, bis das Limit erreicht wurde. Sehen Sie sich die Livedemo dieser Metadaten an.
SignUpTarget 1 Nein Der Austauschbezeichner für das Registrierungsziel Wenn der Benutzer auf die Schaltfläche „Registrieren“ klickt, führt Azure AD B2C den angegebenen Austauschbezeichner aus.
setting.showCancelButton Nein Zeigt die Schaltfläche „Abbrechen“ an. Mögliche Werte: true (Standard) oder false. Sehen Sie sich die Livedemo dieser Metadaten an.
setting.showContinueButton Nein Zeigt die Schaltfläche „Weiter“ an. Mögliche Werte: true (Standard) oder false. Sehen Sie sich die Livedemo dieser Metadaten an.
setting.showSignupLink 2 Nein Zeigt die Schaltfläche „Registrieren“ an. Mögliche Werte: true (Standard) oder false. Sehen Sie sich die Livedemo dieser Metadaten an.
setting.forgotPasswordLinkLocation 2 Nein Zeigt den Link „Kennwort vergessen“ an. Mögliche Werte: AfterLabel (Standard) zeigt den Link direkt nach der Beschriftung oder nach dem Kennworteingabefeld an, wenn keine Beschriftung vorhanden ist, AfterInput zeigt den Link nach dem Kennworteingabefeld an, AfterButtons zeigt den Link am unteren Rand des Formulars nach den Schaltflächen an oder None entfernt den Link "Kennwort vergessen". Sehen Sie sich die Livedemo dieser Metadaten an.
setting.enableRememberMe 2 Nein Zeigt das Kontrollkästchen Angemeldet bleiben an. Mögliche Werte: true oder false (Standardwert). Livedemo dieser Metadaten.
setting.inputVerificationDelayTimeInMilliseconds 3 Nein Verbessert die Benutzererfahrung, indem gewartet wird, bis der Benutzer die Eingabe beendet hat. Dann wird der Wert überprüft. Der Standardwert ist 2.000 Millisekunden. Sehen Sie sich die Livedemo dieser Metadaten an.
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.
setting.forgotPasswordLinkOverride 4 Nein Eine Kennwortzurücksetzung beansprucht einen auszuführenden Austausch. Weitere Informationen finden Sie unter Self-Service-Kennwortzurücksetzung.
setting.enableCaptchaChallenge No Gibt an, ob CAPTCHA-Abfragecode angezeigt werden soll. Mögliche Werte: true oder false (Standardwert). Damit diese Einstellung funktioniert, muss auf das CAPTCHA-Anzeigesteuerelement in den Anzeigeansprüchen des selbst bestätigten technischen Profils verwiesen werden. DAS CAPTCHA-Feature befindet sich in der öffentlichen Vorschau.
setting.showHeading No Gibt an, ob das Überschriftenelement "Benutzerdetails " sichtbar sein soll. Mögliche Werte: true (Standard) oder false.

Hinweise:

  1. Verfügbar für die Inhaltsdefinition: DataUri, Typ unifiedssp oder unifiedssd.
  2. Verfügbar für die Inhaltsdefinition: DataUri, Typ unifiedssp oder unifiedssd. Seitenlayoutversion 1.1.0 und höher.
  3. Verfügbar für die Seitenlayoutversion 1.2.0 und höher.
  4. Verfügbar für die Inhaltsdefinition: DataUri vom Typ unifiedssp. Seitenlayoutversion 2.1.2 und höher

Kryptografische Schlüssel

Das Element CryptographicKeys wird nicht verwendet.