Definieren benutzerdefinierter Attribute in Azure Active Directory B2C

Artikel
03/13/2023

Vorbereitung: Wählen Sie mithilfe des Selektors Choose a policy type (Richtlinientyp auswählen) den Typ der einzurichtenden Richtlinie aus. Azure Active Directory B2C bietet zwei Methoden zum Definieren der Benutzerinteraktion mit Ihren Anwendungen: vordefinierte Benutzerflows oder vollständig konfigurierbare benutzerdefinierte Richtlinien. Die Schritte, die in diesem Artikel erforderlich sind, unterscheiden sich für jede Methode.

Im Artikel Hinzufügen von Ansprüchen und Anpassen von Benutzereingaben mit benutzerdefinierten Richtlinien erfahren Sie, wie Sie integrierte Benutzerprofilattribute verwenden können. In diesem Artikel aktivieren Sie in Ihrem Azure Active Directory B2C-Verzeichnis (Azure AD B2C) ein benutzerdefiniertes Attribut. Später können Sie das neue Attribut als benutzerdefinierten Anspruch gleichzeitig in Benutzerflows oder benutzerdefinierten Richtlinien verwenden.

Ihr Azure AD B2C-Verzeichnis verfügt über mehrere integrierte Attribute. Sie müssen jedoch oftmals für die Verwaltung Ihres spezifischen Szenarios eigene Attribute erstellen, z. B. in den folgenden Fällen:

Für eine Kundenanwendung muss ein Attribut wie loyaltyId persistent gespeichert werden.
Ein Identitätsanbieter hat eine eindeutige Benutzer-ID, die persistent gespeichert werden muss, z. B. uniqueUserGUID.
Für eine benutzerdefinierte User Journey muss der Status eines Benutzers persistent gespeichert werden, z. B. migrationStatus.

Die Begriffe Erweiterungseigenschaft, benutzerdefiniertes Attribut und benutzerdefinierter Anspruch beziehen sich im Kontext dieses Artikels auf die gleiche Sache. Der Name variiert je nach Kontext (Anwendung, Objekt, Richtlinie).

Azure AD B2C ermöglicht Ihnen, die für die einzelnen Benutzerkonten gespeicherte Gruppe von Attributen zu erweitern. Außerdem können Sie diese Attribute mit der Microsoft Graph-API lesen und schreiben.

Voraussetzungen

Erstellen Sie einen Benutzerflow, damit sich Benutzer bei Ihrer Anwendung registrieren und anmelden können.
Registrieren Sie eine Webanwendung.

Führen Sie die unter Erste Schritte mit benutzerdefinierten Richtlinien in Active Directory B2C beschriebenen Schritte aus.
Registrieren Sie eine Webanwendung.

Erstellen eines benutzerdefinierten Attributs

Melden Sie sich beim Azure-Portal als globaler Administrator Ihres Azure AD B2C-Mandanten an.
Stellen Sie sicher, dass Sie das Verzeichnis verwenden, das Ihren Azure AD B2C-Mandanten enthält:
1. Wählen Sie auf der Symbolleiste des Portals das Symbol Verzeichnisse und Abonnements aus.
2. Suchen Sie auf der Seite Portaleinstellungen > Verzeichnisse und Abonnements Ihr Azure AD B2C-Verzeichnis in der Verzeichnisliste, und wählen Sie dann Wechseln aus.
Klicken Sie links oben im Azure-Portal auf Alle Dienste, suchen Sie nach Azure AD B2C, und klicken Sie darauf.
Wählen Sie Benutzerattribute und dann Hinzufügen aus.
Geben Sie einen Namen für das benutzerdefinierte Attribut an (z.B. „ShoeSize“).
Wählen Sie einen Datentyp aus. Es stehen nur Zeichenfolge, Boolescher Wert und Int zur Verfügung.
Geben Sie optional eine Beschreibung zu Informationszwecken ein.
Klicken Sie auf Erstellen.

Das benutzerdefinierte Attribut steht jetzt in der Liste der Benutzerattribute zur Verfügung und kann in den Benutzerflows verwendet werden. Ein benutzerdefiniertes Attribut wird nur erstellt, wenn es in einem Benutzerflow zum ersten Mal verwendet wird, und nicht, wenn Sie es der Liste der Benutzerattribute hinzufügen.

Verwenden eines benutzerdefinierten Attributs in einem Benutzerflow

Wählen Sie in Ihrem Azure AD B2C-Mandanten die Option Benutzerflows aus.
Wählen Sie eine Richtlinie aus (z.B. „B2C_1_SignupSignin“), um sie zu öffnen.
Wählen Sie Benutzerattribute und dann das benutzerdefinierte Attribut aus (z.B. „ShoeSize“). Wählen Sie Speichern aus.
Wählen Sie Anwendungsansprüche und dann das benutzerdefinierte Attribut aus.
Wählen Sie Speichern aus.

Nachdem Sie einen neuen Benutzer mithilfe des Benutzerflows erstellt haben, können Sie das Feature Benutzerflow ausführen für den Benutzerflow verwenden, um die Kundenumgebung zu überprüfen. ShoeSize sollte jetzt in der Liste der Attribute, die während der Registrierung erfasst werden, sowie in dem Token angezeigt werden, das zurück an die Anwendung gesendet wird.

Erweiterungs-App für Azure AD B2C

Erweiterungsattribute können nur für ein Anwendungsobjekt registriert werden, obwohl sie Daten für einen Benutzer enthalten können. Das Erweiterungsattribut wird an die Anwendung namens b2c-extensions-app angefügt. Nehmen Sie keine Änderungen an dieser Anwendung vor. Sie wird von Azure AD B2C zum Speichern von Benutzerdaten verwendet. Sie finden diese Anwendung unter Azure AD B2C, App-Registrierungen.

Abrufen der Anwendungs-ID der Erweiterungs-App

Melden Sie sich beim Azure-Portal an.
Stellen Sie sicher, dass Sie das Verzeichnis verwenden, das Ihren Azure AD B2C-Mandanten enthält:
1. Wählen Sie auf der Symbolleiste des Portals das Symbol Verzeichnisse und Abonnements aus.
2. Suchen Sie auf der Seite Portaleinstellungen > Verzeichnisse und Abonnements das Azure AD B2C-Verzeichnis in der Liste Verzeichnisname, und klicken Sie dann auf Wechseln.
Wählen Sie im linken Menü die Option Azure AD B2C aus. Oder wählen Sie Alle Dienste aus, suchen Sie nach dem Eintrag Azure AD B2C, und wählen Sie ihn aus.
Wählen Sie App-Registrierungen und dann Alle Anwendungen aus.
Wählen Sie die Anwendung b2c-extensions-app. Do not modify. Used by AADB2C for storing user data. aus.
Kopieren Sie die Anwendungs-ID. Beispiel: 11111111-1111-1111-1111-111111111111.

Abrufen der Anwendungseigenschaften der Erweiterungs-App

Melden Sie sich beim Azure-Portal an.
Stellen Sie sicher, dass Sie das Verzeichnis verwenden, das Ihren Azure AD B2C-Mandanten enthält:
1. Wählen Sie auf der Symbolleiste des Portals das Symbol Verzeichnisse und Abonnements aus.
2. Suchen Sie auf der Seite Portaleinstellungen > Verzeichnisse und Abonnements das Azure AD B2C-Verzeichnis in der Liste Verzeichnisname, und klicken Sie dann auf Wechseln.
Wählen Sie im linken Menü die Option Azure AD B2C aus. Oder wählen Sie Alle Dienste aus, suchen Sie nach dem Eintrag Azure AD B2C, und wählen Sie ihn aus.
Wählen Sie App-Registrierungen und dann Alle Anwendungen aus.
Wählen Sie die Anwendung b2c-extensions-app. Do not modify. Used by AADB2C for storing user data. (b2c-extensions-app. Nicht ändern. Wird von AADB2C zum Speichern von Benutzerdaten verwendet.) aus.
Kopieren Sie die folgenden Bezeichner in die Zwischenablage, und speichern Sie sie:
- Anwendungs-ID. Beispiel: 11111111-1111-1111-1111-111111111111.
- Objekt-ID Beispiel: 22222222-2222-2222-2222-222222222222.

Ändern der benutzerdefinierten Richtlinie

Um benutzerdefinierte Attribute in Ihrer Richtlinie zu aktivieren, geben Sie die Anwendungs-ID und Objekt-ID der Anwendung in den Metadaten des technischen Profils AAD-Common an. Das technische Profil AAD-Common befindet sich im technischen Basisprofil Azure Active Directory und bietet Unterstützung für die Benutzerverwaltung in Azure AD. Andere technische Profile von Azure AD enthalten AAD-Common, um dessen Konfiguration zu verwenden. Überschreiben Sie das technische Profil AAD-Common in der Erweiterungsdatei.

Öffnen Sie die Erweiterungsdatei Ihrer Richtlinie. Beispiel: SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
Wechseln Sie zum ClaimsProviders-Element. Fügen Sie dem ClaimsProviders-Element ein neues ClaimsProvider-Element hinzu.
Fügen Sie die zuvor erfasste Anwendungs-ID zwischen dem öffnenden und dem schließenden Element (<Item Key="ClientId"> und </Item>) ein.

Fügen Sie die zuvor erfasste Anwendungsobjekt-ID zwischen dem öffnenden und dem schließenden Element (<Item Key="ApplicationObjectId"> und </Item>) ein.

<!-- 
<ClaimsProviders> -->
  <ClaimsProvider>
    <DisplayName>Azure Active Directory</DisplayName>
    <TechnicalProfiles>
      <TechnicalProfile Id="AAD-Common">
        <Metadata>
          <!--Insert b2c-extensions-app application ID here, for example: 11111111-1111-1111-1111-111111111111-->  
          <Item Key="ClientId"></Item>
          <!--Insert b2c-extensions-app application ObjectId here, for example: 22222222-2222-2222-2222-222222222222-->
          <Item Key="ApplicationObjectId"></Item>
        </Metadata>
      </TechnicalProfile>
    </TechnicalProfiles> 
  </ClaimsProvider>
<!-- 
</ClaimsProviders> -->

Hochladen der benutzerdefinierten Richtlinie

Melden Sie sich beim Azure-Portal an.
Stellen Sie sicher, dass Sie das Verzeichnis verwenden, das Ihren Azure AD B2C-Mandanten enthält:
1. Wählen Sie auf der Symbolleiste des Portals das Symbol Verzeichnisse und Abonnements aus.
2. Suchen Sie auf der Seite Portaleinstellungen > Verzeichnisse und Abonnements das Azure AD B2C-Verzeichnis in der Liste Verzeichnisname, und klicken Sie dann auf Wechseln.
Klicken Sie links oben im Azure-Portal auf Alle Dienste, suchen Sie nach App-Registrierungen, und wählen Sie dann diese Option aus.
Wählen Sie Framework für die Identitätsfunktion aus.
Wählen Sie Benutzerdefinierte Richtlinie hochladen aus, und laden Sie dann die geänderten Richtliniendateien des Typs „TrustFrameworkExtensions.xml“ hoch.

Hinweis

Wenn das technische Azure AD-Profil zum ersten Mal den Anspruch auf das Verzeichnis persistent speichert, prüft es, ob das benutzerdefinierte Attribut existiert. Andernfalls wird das benutzerdefinierte Attribut erstellt.

Erstellen eines benutzerdefinierten Attributs im Azure-Portal

Von integrierten und benutzerdefinierten Profilen werden dieselben Erweiterungsattribute genutzt. Beim Hinzufügen benutzerdefinierter Attribute auf der Portaloberfläche werden diese Attribute mithilfe von der in jedem B2C-Mandanten vorhandenen b2c-extensions-app registriert.

Sie können diese Attribute auf der Portalbenutzeroberfläche erstellen, bevor Sie sie in Ihren benutzerdefinierten Richtlinien einsetzen. Wenn Sie im Portal das Attribut loyaltyId erstellen, müssen Sie wie folgt darauf verweisen:

Name	Verwendung in
`extension_loyaltyId`	Benutzerdefinierte Richtlinie
`extension_<b2c-extensions-app-guid>_loyaltyId`	Microsoft Graph-API

Hinweis

Wenn Sie ein benutzerdefiniertes Attribut in benutzerdefinierten Richtlinien verwenden, müssen Sie der Anspruchstyp-ID extension_ voranstellen, damit die richtige Datenzuordnung im Azure AD B2C-Verzeichnis erfolgt.

Das folgende Beispiel veranschaulicht die Verwendung benutzerdefinierter Attribute in einer benutzerdefinierten Azure AD B2C-Anspruchsdefinition für eine Richtlinie.

<BuildingBlocks>
  <ClaimsSchema>
    <ClaimType Id="extension_loyaltyId">
      <DisplayName>Loyalty Identification</DisplayName>
      <DataType>string</DataType>
      <UserHelpText>Your loyalty number from your membership card</UserHelpText>
      <UserInputType>TextBox</UserInputType>
    </ClaimType>
  </ClaimsSchema>
</BuildingBlocks>

Das folgende Beispiel veranschaulicht die Verwendung eines benutzerdefinierten Attributs in der benutzerdefinierten Azure AD B2C-Richtlinie in einem technischen Profil, einer Eingabe, einer Ausgabe und persistent gespeicherten Ansprüchen.

<InputClaims>
  <InputClaim ClaimTypeReferenceId="extension_loyaltyId"  />
</InputClaims>
<PersistedClaims>
  <PersistedClaim ClaimTypeReferenceId="extension_loyaltyId" />
</PersistedClaims>
<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="extension_loyaltyId" />
</OutputClaims>

Verwalten von Erweiterungsattributen über Microsoft Graph

Sie können Microsoft Graph verwenden, um benutzerdefinierte Attribute zu erstellen und zu verwalten, und dann die Werte für einen Benutzer festlegen. Erweiterungsattribute werden auch als Verzeichnis- oder Azure AD-Erweiterungen bezeichnet.

Benutzerdefinierte Attribute (Verzeichniserweiterungen) in der Microsoft Graph-API werden gemäß der Konvention extension_{appId-without-hyphens}_{extensionProperty-name} benannt. Dabei ist {appId-without-hyphens} die vereinfachte Version von appId (im Azure AD B2C-Portal als Client-ID bezeichnet) für b2c-extensions-app. Diese vereinfachte Version umfasst nur die Zeichen 0–9 und A–Z. Wenn die b2c-extensions-app-Anwendung die App-ID (appId) 25883231-668a-43a7-80b2-5685c3f874bc hat und der Attributname loyaltyIdlautet, erhält das benutzerdefinierte Attribut den Namen extension_25883231668a43a780b25685c3f874bc_loyaltyId.

Unter Verwalten von Erweiterungsattributen in Ihrem Azure AD B2C-Mandanten finden Sie weitere Informationen zur Verwaltung der Attribute mit der Microsoft Graph-API.

Entfernen von Erweiterungsattributen

Im Gegensatz zu integrierten Attributen können benutzerdefinierte Attribute entfernt werden. Die Werte der Erweiterungsattribute können ebenfalls entfernt werden.

Wichtig

Legen Sie vor dem Entfernen des benutzerdefinierten Attributs für jedes Konto im Verzeichnis den Wert des Erweiterungsattributs auf null fest. Auf diese Weise entfernen Sie explizit die Werte des Erweiterungsattributs. Entfernen Sie anschließend das Erweiterungsattribut selbst. Benutzerdefinierte Attribute können mithilfe der Microsoft Graph-API abgefragt werden.

Führen Sie die folgenden Schritte aus, um ein benutzerdefiniertes Attribut aus einem Benutzerflow in Ihrem Mandaten zu entfernen:

Melden Sie sich beim Azure-Portal als globaler Administrator Ihres Azure AD B2C-Mandanten an.
Stellen Sie sicher, dass Sie das Verzeichnis verwenden, das Ihren Azure AD B2C-Mandanten enthält:
1. Wählen Sie auf der Symbolleiste des Portals das Symbol Verzeichnisse und Abonnements aus.
2. Suchen Sie auf der Seite Portaleinstellungen > Verzeichnisse und Abonnements Ihr Azure AD B2C-Verzeichnis in der Verzeichnisliste, und wählen Sie dann Wechseln aus.
Klicken Sie links oben im Azure-Portal auf Alle Dienste, suchen Sie nach Azure AD B2C, und klicken Sie darauf.
Wählen Sie Benutzerattribute und dann das zu löschende Benutzerattribut aus.
Wählen Sie Löschen und dann Ja aus, um den Löschvorgang zu bestätigen.

Verwenden Sie die Microsoft Graph-API, um die benutzerdefinierten Attribute zu verwalten.

Nächste Schritte

Weitere Informationen zur Vorgehensweise finden Sie unter Hinzufügen von Ansprüchen und Anpassen von Benutzereingaben mit benutzerdefinierten Richtlinien. In diesem Beispiel wird der integrierte Anspruch „city“ verwendet. Um ein benutzerdefiniertes Attribut zu verwenden, ersetzen Sie „city“ durch Ihre eigenen benutzerdefinierten Attribute.