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

Artikel
01/11/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 Microsoft Entra-Benutzerverwaltung. In diesem Artikel werden die Einzelheiten eines technischen Profils für die Interaktion mit einem Anspruchsanbieter thematisiert, der dieses standardisierte Protokoll unterstützt.

Protocol

Das Name-Attribut des Protocol-Elements muss auf Proprietary festgelegt werden. Das handler-Attribut muss den vollqualifizierten Namen der Protokollhandlerassembly Web.TPEngine.Providers.AzureActiveDirectoryProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null enthalten.

Entsprechend dem Starter Pack für benutzerdefinierte Richtlinien enthalten alle technischen Microsoft Entra-Profile das technische Profil AAD-Common. Die folgenden technischen Microsoft Entra-Profile geben das Protokoll nicht an, da es im technischen Profil AAD-Common konfiguriert ist:

AAD-UserReadUsingAlternativeSecurityId und AAD-UserReadUsingAlternativeSecurityId-NoError: Suchen eines Social Media-Kontos im Verzeichnis.
AAD-UserWriteUsingAlternativeSecurityId: Erstellen eines neuen Social Media-Kontos.
AAD-UserReadUsingEmailAddress: Suchen eines lokalen Kontos im Verzeichnis.
AAD-UserWriteUsingLogonEmail: Erstellen eines neuen lokalen Kontos.
AAD-UserWritePasswordUsingObjectId: Aktualisieren des Kennworts eines lokalen Kontos.
AAD-UserWriteProfileUsingObjectId: Aktualisieren eines Benutzerprofils eines lokalen oder Social Media-Kontos.
AAD-UserReadUsingObjectId: Lesen eines Benutzerprofils eines lokalen oder Social Media-Kontos.
AAD-UserWritePhoneNumberUsingObjectId: Schreiben der MFA-Telefonnummer eines lokalen oder Social Media-Kontos

Das folgende Beispiel zeigt das technische Profil AAD-Common:

<TechnicalProfile Id="AAD-Common">
  <DisplayName>Azure Active Directory</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureActiveDirectoryProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />

  <CryptographicKeys>
    <Key Id="issuer_secret" StorageReferenceId="B2C_1A_TokenSigningKeyContainer" />
  </CryptographicKeys>

  <!-- We need this here to suppress the SelfAsserted provider from invoking SSO on validation profiles. -->
  <IncludeInSso>false</IncludeInSso>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

InputClaims

Das „Input Claims“-Element enthält einen Anspruch, der verwendet wird, um im Verzeichnis nach einem Konto zu suchen oder ein neues Konto zu erstellen. In der Auflistung der Eingabeansprüche für alle technischen Microsoft Entra-Profile muss genau ein Element „Eingabeanspruch“ vorhanden sein. Sie müssen den Namen des in Ihrer Richtlinie definierten Anspruchs möglicherweise dem in Microsoft Entra ID definierten Namen zuordnen.

Beim Lesen, Aktualisieren oder Löschen eines vorhandenen Benutzerkontos ist der Eingabeanspruch ein Schlüssel, der das Konto in Microsoft Entra-Verzeichnis eindeutig identifiziert. Zum Beispiel: objectId, userPrincipalName, signInNames.emailAddress, signInNames.userName oder alternativeSecurityId.

Beim Erstellen eines neuen Benutzerkontos ist der Eingabeanspruch ein Schlüssel, der ein lokales oder Verbundkonto eindeutig identifiziert. Zum Beispiel bei einem lokalen Konto: signInNames.emailAddress oder signInNames.userName. Bei einem Verbundkonto: alternativeSecurityId.

Das InputClaimsTransformations-Element kann eine Sammlung von Eingabeanspruchstransformations-Elementen enthalten, die zum Ändern des Eingabeanspruchs oder zum Generieren eines neuen Eingabeanspruchs verwendet werden.

OutputClaims

Das OutputClaims-Element enthält eine Liste von Ansprüchen, die vom technischen Microsoft Entra-Profil zurückgegeben werden. Sie müssen den Namen des in Ihrer Richtlinie definierten Anspruchs möglicherweise dem in Microsoft Entra ID definierten Namen zuordnen. Sie können auch Ansprüche einfügen, die nicht von der Microsoft Entra ID 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.

Das technische Profil AAD-UserWriteUsingLogonEmail erstellt z.B. ein lokales Konto und gibt die folgenden Ansprüche zurück:

objectId ist der Bezeichner des neuen Kontos.
newUser gibt an, ob der Benutzer neu ist.
authenticationSource legt die Authentifizierung auf localAccountAuthentication fest.
userPrincipalName ist der Benutzerprinzipalname des neuen Kontos.
signInNames.emailAddress ist der Anmeldename des Kontos, ähnlich dem email-Eingabeanspruch.

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="objectId" />
  <OutputClaim ClaimTypeReferenceId="newUser" PartnerClaimType="newClaimsPrincipalCreated" />
  <OutputClaim ClaimTypeReferenceId="authenticationSource" DefaultValue="localAccountAuthentication" />
  <OutputClaim ClaimTypeReferenceId="userPrincipalName" />
  <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" />
</OutputClaims>

PersistedClaims

Das Element PersistedClaims enthält alle Werte, die vom Microsoft Entra ID-Profil dauerhaft gespeichert werden sollen, sowie mögliche Zuordnungsinformationen zwischen einem Anspruchstyp, der bereits im Abschnitt ClaimsSchema in der Richtlinie definiert ist, und dem Microsoft Entra-Attributnamen.

Das technische Profil AAD-UserWriteUsingLogonEmail erstellt ein lokales Konto und behält die folgenden Ansprüche bei:

  <PersistedClaims>
    <!-- Required claims -->
    <PersistedClaim ClaimTypeReferenceId="email" PartnerClaimType="signInNames.emailAddress" />
    <PersistedClaim ClaimTypeReferenceId="newPassword" PartnerClaimType="password"/>
    <PersistedClaim ClaimTypeReferenceId="displayName" DefaultValue="unknown" />
    <PersistedClaim ClaimTypeReferenceId="passwordPolicies" DefaultValue="DisablePasswordExpiration" />

    <!-- Optional claims. -->
    <PersistedClaim ClaimTypeReferenceId="givenName" />
    <PersistedClaim ClaimTypeReferenceId="surname" />
  </PersistedClaims>

Der Name des Anspruchs ist der Name des Microsoft Entra-Attributs, sofern nicht das PartnerClaimType-Attribut angegeben wurde, das den Namen des Microsoft Entra-Attributs enthält.

Anforderungen für einen Vorgang

Es muss genau ein InputClaim-Element im Anspruchsbehälter für alle technischen Microsoft Entra-Profile vorhanden sein.
Im Artikel Benutzerprofilattribute werden die unterstützten Azure AD B2C-Benutzerprofilattribute beschrieben, die Sie in den Eingabe-, Ausgabe- und persistenten Ansprüchen verwenden können.
Wenn der Vorgang Write oder DeleteClaims ist, muss er auch im PersistedClaims-Element enthalten sein.
Der Wert des userPrincipalName-Anspruchs muss das Format user@tenant.onmicrosoft.com aufweisen.
Der displayName-Anspruch ist erforderlich und darf keine leere Zeichenfolge sein.

Vorgänge des Microsoft Entra technischen Profils

Lesen

Der Read-Vorgang liest die Daten zu einem einzelnen Benutzerkonto. Das folgende technische Profil liest Daten über ein Benutzerkonto mithilfe der Objekt-ID des Benutzers:

<TechnicalProfile Id="AAD-UserReadUsingObjectId">
  <Metadata>
    <Item Key="Operation">Read</Item>
    <Item Key="RaiseErrorIfClaimsPrincipalDoesNotExist">true</Item>
  </Metadata>
  <IncludeInSso>false</IncludeInSso>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="objectId" Required="true" />
  </InputClaims>
  <OutputClaims>

    <!-- Required claims -->
    <OutputClaim ClaimTypeReferenceId="strongAuthenticationPhoneNumber" />

    <!-- Optional claims -->
    <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" />
    <OutputClaim ClaimTypeReferenceId="displayName" />
    <OutputClaim ClaimTypeReferenceId="otherMails" />
    <OutputClaim ClaimTypeReferenceId="givenName" />
    <OutputClaim ClaimTypeReferenceId="surname" />
  </OutputClaims>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

Schreiben

Der Write-Vorgang erstellt oder aktualisiert ein einzelnes Benutzerkonto. Das folgende technische Profil erstellt neues Social Media-Konto:

<TechnicalProfile Id="AAD-UserWriteUsingAlternativeSecurityId">
  <Metadata>
    <Item Key="Operation">Write</Item>
    <Item Key="RaiseErrorIfClaimsPrincipalAlreadyExists">true</Item>
    <Item Key="UserMessageIfClaimsPrincipalAlreadyExists">You are already registered, please press the back button and sign in instead.</Item>
  </Metadata>
  <IncludeInSso>false</IncludeInSso>
  <InputClaimsTransformations>
    <InputClaimsTransformation ReferenceId="CreateOtherMailsFromEmail" />
  </InputClaimsTransformations>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="AlternativeSecurityId" PartnerClaimType="alternativeSecurityId" Required="true" />
  </InputClaims>
  <PersistedClaims>
    <!-- Required claims -->
    <PersistedClaim ClaimTypeReferenceId="alternativeSecurityId" />
    <PersistedClaim ClaimTypeReferenceId="userPrincipalName" />
    <PersistedClaim ClaimTypeReferenceId="mailNickName" DefaultValue="unknown" />
    <PersistedClaim ClaimTypeReferenceId="displayName" DefaultValue="unknown" />

    <!-- Optional claims -->
    <PersistedClaim ClaimTypeReferenceId="otherMails" />
    <PersistedClaim ClaimTypeReferenceId="givenName" />
    <PersistedClaim ClaimTypeReferenceId="surname" />
  </PersistedClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="objectId" />
    <OutputClaim ClaimTypeReferenceId="newUser" PartnerClaimType="newClaimsPrincipalCreated" />
    <OutputClaim ClaimTypeReferenceId="otherMails" />
  </OutputClaims>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-AAD" />
</TechnicalProfile>

DeleteClaims

Der DeleteClaims-Vorgang löscht die Informationen aus einer angegebenen Liste von Ansprüchen. Das folgende technische Profil löscht Ansprüche:

<TechnicalProfile Id="AAD-DeleteClaimsUsingObjectId">
  <Metadata>
    <Item Key="Operation">DeleteClaims</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="objectId" Required="true" />
  </InputClaims>
  <PersistedClaims>
    <PersistedClaim ClaimTypeReferenceId="objectId" />
    <PersistedClaim ClaimTypeReferenceId="Verified.strongAuthenticationPhoneNumber" PartnerClaimType="strongAuthenticationPhoneNumber" />
  </PersistedClaims>
  <OutputClaims />
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

DeleteClaimsPrincipal

Der DeleteClaimsPrincipal-Vorgang löscht ein einzelnes Benutzerkonto aus dem Verzeichnis. Das folgende technische Profil löscht ein Benutzerkonto anhand des Benutzerprinzipalnamens aus dem Verzeichnis:

<TechnicalProfile Id="AAD-DeleteUserUsingObjectId">
  <Metadata>
    <Item Key="Operation">DeleteClaimsPrincipal</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="objectId" Required="true" />
  </InputClaims>
  <OutputClaims/>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

Das folgende technische Profil löscht ein Social Media-Benutzerkonto mit alternativeSecurityId:

<TechnicalProfile Id="AAD-DeleteUserUsingAlternativeSecurityId">
  <Metadata>
    <Item Key="Operation">DeleteClaimsPrincipal</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="alternativeSecurityId" Required="true" />
  </InputClaims>
  <OutputClaims/>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

Metadaten

attribute	Erforderlich	BESCHREIBUNG
Vorgang	Ja	Der Vorgang, der ausgeführt werden soll. Mögliche Werte: `Read`, `Write`, `DeleteClaims` oder `DeleteClaimsPrincipal`.
RaiseErrorIfClaimsPrincipalDoesNotExist	Nein	Es wird ein Fehler ausgelöst, wenn das Benutzerobjekt im Verzeichnis nicht vorhanden ist. Mögliche Werte: `true` oder `false`.
RaiseErrorIfClaimsPrincipalAlreadyExists	Nein	Es wird ein Fehler ausgelöst, wenn das Benutzerobjekt bereits vorhanden ist. Mögliche Werte: `true` oder `false`. Diese Metadaten gelten nur für den Schreibvorgang.
ApplicationObjectId	Nein	Die Anwendungsobjekt-ID für vorhandene Attribute. Wert: ObjectId einer Anwendung. Weitere Informationen finden Sie unter Benutzerdefinierte Attribute.
ClientId	Nein	Die Client-ID für den Zugriff auf den Mandanten als Drittanbieter. Weitere Informationen finden Sie unter Verwenden von benutzerdefinierten Attributen in einer benutzerdefinierten Richtlinie für die Profilbearbeitung.
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.

Benutzeroberflächenelemente

Die folgenden Einstellungen können verwendet werden, um die Fehlermeldung zu konfigurieren, die bei einem Fehler angezeigt wird. Die Metadaten sollten im selbstbestätigten technischen Profil konfiguriert werden. Die Fehlermeldungen können lokalisiert werden.

attribute	Erforderlich	BESCHREIBUNG
UserMessageIfClaimsPrincipalAlreadyExists	Nein	Wenn ein Fehler ausgelöst werden soll (siehe Beschreibung zum RaiseErrorIfClaimsPrincipalAlreadyExists-Attribut), geben Sie die Meldung an, die dem Benutzer angezeigt werden soll, wenn das Benutzerobjekt bereits vorhanden ist.
UserMessageIfClaimsPrincipalDoesNotExist	Nein	Wenn ein Fehler ausgelöst werden soll (siehe Beschreibung zum RaiseErrorIfClaimsPrincipalDoesNotExist-Attribut), geben Sie die Meldung an, die dem Benutzer angezeigt werden soll, wenn das Benutzerobjekt nicht vorhanden ist.

Nächste Schritte

Im folgenden Artikel finden Sie ein Beispiel für die Verwendung eines technischen Profils für einen Microsoft Entra:

Hinzufügen von Ansprüchen und Anpassen von Benutzereingaben mit benutzerdefinierten Richtlinien in Azure Active Directory B2C