Azure Active Directory B2C:カスタム プロファイル編集ポリシーでカスタム属性を使用するAzure Active Directory B2C: Use custom attributes in a custom profile edit policy

注意

Azure Active Directory B2C で、カスタム ポリシーは、主に、複雑なシナリオに取り組む用途向けに設計されています。In Azure Active Directory B2C, custom policies are designed primarily to address complex scenarios. ほとんどのシナリオで、組み込みユーザー フローを使用することをお勧めします。For most scenarios, we recommend that you use built-in user flows.

この記事では、Azure Active Directory B2C (Azure AD B2C) ディレクトリにカスタム属性を作成します。In this article, you create a custom attribute in your Azure Active Directory B2C (Azure AD B2C) directory. この新しい属性は、プロファイル編集ユーザー体験でのカスタム要求として使用します。You'll use this new attribute as a custom claim in the profile edit user journey.

前提条件Prerequisites

Azure Active Directory B2C: カスタム ポリシーの概要」に記載の手順に従ってください。Follow the steps in the article Azure Active Directory B2C: Get started with custom policies.

カスタム属性を使用すると、カスタム ポリシーにより Azure AD B2C の顧客に関する情報が収集されます。Use custom attributes to collect information about your customers in Azure AD B2C by using custom policies

Azure AD B2C ディレクトリには、組み込みの属性セットが付属します。Your Azure AD B2C directory comes with a built-in set of attributes. たとえば、Given NameSurnameCityPostal CodeuserPrincipalName などがあります。Examples are Given Name, Surname, City, Postal Code, and userPrincipalName. 多くの場合は、次に示したような独自の属性を作成する必要があります。You often need to create your own attributes like these examples:

  • 顧客向けアプリケーションは、LoyaltyNumber のような属性に対して維持される必要があります。A customer-facing application needs to persist for an attribute like LoyaltyNumber.
  • ID プロバイダーは、uniqueUserGUID のような、保存する必要がある一意のユーザー識別子を保持しています。An identity provider has a unique user identifier like uniqueUserGUID that must be saved.
  • カスタム ユーザー体験は、migrationStatus のような、ユーザーの状態に対して維持される必要があります。A custom user journey needs to persist for a state of a user like migrationStatus.

Azure AD B2C では、各ユーザー アカウントで保存される属性セットを拡張できます。Azure AD B2C extends the set of attributes stored on each user account. また、 Azure AD Graph APIを使用してこれらの属性を読み書きすることもできます。You can also read and write these attributes by using the Azure AD Graph API.

拡張プロパティは、ディレクトリ内のユーザー オブジェクトのスキーマを拡張します。Extension properties extend the schema of the user objects in the directory. 用語の拡張機能プロパティカスタム属性、およびカスタム要求では、この記事のコンテキストと同じ内容を参照します。The terms extension property, custom attribute, and custom claim refer to the same thing in the context of this article. 名前は、アプリケーション、オブジェクト、ポリシーなどのコンテキストによって異なります。The name varies depending on the context, such as application, object, or policy.

拡張プロパティは、ユーザーに関するデータを保持できる場合でも、アプリケーション オブジェクトにしか登録できません。Extension properties can only be registered on an application object even though they might contain data for a user. プロパティは、アプリケーションに関連付けられます。The property is attached to the application. アプリケーション オブジェクトは、拡張プロパティを登録するための書き込みアクセス権を持っている必要があります。The application object must have write access to register an extension property. 1 つのオブジェクトに対して、100 個の拡張プロパティ (すべての型とすべてのアプリケーションでの合計) を書き込むことができます。A hundred extension properties, across all types and all applications, can be written to any single object. 拡張プロパティは、対象のディレクトリ タイプに追加され、Azure AD B2C ディレクトリ テナント内ですぐに利用できる状態になります。Extension properties are added to the target directory type and become immediately accessible in the Azure AD B2C directory tenant. アプリケーションを削除すると、このような拡張プロパティも、それらに含まれている、すべてのユーザーに関するデータと共に削除されます。If the application is deleted, those extension properties along with any data contained in them for all users are also removed. 拡張プロパティは、アプリケーションによって削除されると、対象ディレクトリ オブジェクトで削除され、その値も削除されます。If an extension property is deleted by the application, it's removed on the target directory objects, and the values are deleted.

拡張プロパティは、テナント内の登録されたアプリケーションのコンテキストにのみ存在します。Extension properties exist only in the context of a registered application in the tenant. そのアプリケーションのオブジェクト ID は、それを使用する TechnicalProfile に含まれている必要があります。The object ID of that application must be included in the TechnicalProfile that uses it.

注意

Azure AD B2C ディレクトリには、通常、b2c-extensions-app という名前の Web アプリが含まれています。The Azure AD B2C directory typically includes a web app named b2c-extensions-app. このアプリケーションは、主に、Azure Portal で作成されたカスタム要求用の B2C 組み込みポリシーによって使用されます。This application is primarily used by the B2C built-in policies for the custom claims created via the Azure portal. このアプリケーションを使用して拡張プロパティを B2C カスタム ポリシーに登録することは、上級ユーザーのみにお勧めします。We recommend that only advanced users register extensions for B2C custom policies by using this application. 手順については、この記事の「次のステップ」のセクションをご覧ください。Instructions are included in the Next steps section in this article.

拡張プロパティを格納するための新しいアプリケーションを作成するCreate a new application to store the extension properties

  1. ブラウズ セッションを開いて Azure Portal に移動します。Open a browsing session and navigate to the Azure portal. 構成する B2C ディレクトリの管理者資格情報を使用してサインインします。Sign in with the administrative credentials of the B2C directory you want to configure.
  2. 左側のナビゲーション メニューで、 [Azure Active Directory] を選択します。Select Azure Active Directory on the left navigation menu. [その他のサービス] をクリックしないと表示されない場合があります。You might need to find it by selecting More services.
  3. [アプリの登録] を選択します。Select App registrations. [新しいアプリケーションの登録] を選択します。Select New application registration.
  4. 次のエントリを指定します。Provide the following entries:
    • Web アプリケーションの名前: WebApp-GraphAPI-DirectoryExtensionsA name for the web application: WebApp-GraphAPI-DirectoryExtensions.
    • アプリケーションの種類: Web アプリ/APIThe application type: Web app/API.
    • サインオン URL: https://{tenantName}.onmicrosoft.com/WebApp-GraphAPI-DirectoryExtensionsThe sign-on URL: https://{tenantName}.onmicrosoft.com/WebApp-GraphAPI-DirectoryExtensions.
  5. 作成 を選択します。Select Create.
  6. 新しく作成された Web アプリケーションを選択します。Select the newly created web application.
  7. [設定] > [必要なアクセス許可] の順に選択します。Select Settings > Required permissions.
  8. API Windows Azure Active Directory を選択します。Select the API Windows Azure Active Directory.
  9. [アプリケーションのアクセス許可] の [ディレクトリ データの読み取りと書き込み] チェック ボックスをオンにします。Enter a checkmark in Application Permissions: Read and write directory data. 次に、 [保存] を選択します。Then select Save.
  10. [アクセス許可の付与] を選択し、確認のために [はい] をクリックします。Choose Grant permissions and confirm Yes.
  11. 次の識別子をクリップボードにコピーして保存します。Copy the following identifiers to your clipboard and save them:
    • アプリケーション IDApplication ID. 例: 103ee0e6-f92d-4183-b576-8c3739027780.Example: 103ee0e6-f92d-4183-b576-8c3739027780.
    • オブジェクト IDObject ID. 例: 80d8296a-da0a-49ee-b6ab-fd232aa45201.Example: 80d8296a-da0a-49ee-b6ab-fd232aa45201.

カスタム ポリシーを変更して ApplicationObjectId を追加するModify your custom policy to add the ApplicationObjectId

Azure Active Directory B2C: カスタム ポリシーの概要」の手順に従った場合は、TrustFrameworkBase.xmlTrustFrameworkExtensions.xmlSignUpOrSignin.xmlProfileEdit.xmlPasswordReset.xml という名前のサンプル ファイルをダウンロードして変更しました。When you followed the steps in Azure Active Directory B2C: Get started with custom policies, you downloaded and modified sample files named TrustFrameworkBase.xml, TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xml, and PasswordReset.xml. この手順では、これらのファイルにさらに変更を加えます。In this step, you make more modifications to those files.

  • 次の例のように、TrustFrameworkBase.xml ファイルを開いて Metadata セクションを追加します。Open the TrustFrameworkBase.xml file and add the Metadata section as shown in the following example. ApplicationObjectId の値には以前に記録したオブジェクト ID、ClientId の値には以前に記録したアプリケーション ID を挿入します。Insert the object ID that you previously recorded for the ApplicationObjectId value and the application ID that you recorded for the ClientId value:

    <ClaimsProviders>
      <ClaimsProvider>
        <DisplayName>Azure Active Directory</DisplayName>
        <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" />
    
          <!-- Provide objectId and appId before using extension properties. -->
          <Metadata>
            <Item Key="ApplicationObjectId">insert objectId here</Item>
            <Item Key="ClientId">insert appId here</Item>
          </Metadata>
          <!-- End of changes -->
    
          <CryptographicKeys>
            <Key Id="issuer_secret" StorageReferenceId="TokenSigningKeyContainer" />
          </CryptographicKeys>
          <IncludeInSso>false</IncludeInSso>
          <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
        </TechnicalProfile>
      </ClaimsProvider>
    </ClaimsProviders>
    

注意

TechnicalProfile が新しく作成された拡張プロパティに初めて書き込むときに、1 回限りのエラーが発生することがあります。When the TechnicalProfile writes for the first time to the newly created extension property, you might experience a one-time error. 拡張機能プロパティは、初めて使われるときに作成されます。The extension property is created the first time it's used.

ユーザー体験で新しい拡張機能プロパティまたはカスタム属性を使用するUse the new extension property or custom attribute in a user journey

  1. ProfileEdit.xml ファイルを開きます。Open the ProfileEdit.xml file.

  2. カスタム要求 loyaltyId を追加します。Add a custom claim loyaltyId. カスタム要求は、<RelyingParty> 要素に含めることで、アプリケーション用のトークンに含まれます。By including the custom claim in the <RelyingParty> element, it's included in the token for the application.

    <RelyingParty>
      <DefaultUserJourney ReferenceId="ProfileEdit" />
      <TechnicalProfile Id="PolicyProfile">
        <DisplayName>PolicyProfile</DisplayName>
        <Protocol Name="OpenIdConnect" />
        <OutputClaims>
          <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
          <OutputClaim ClaimTypeReferenceId="city" />
    
          <!-- Provide the custom claim identifier -->
          <OutputClaim ClaimTypeReferenceId="extension_loyaltyId" />
          <!-- End of changes -->
        </OutputClaims>
        <SubjectNamingInfo ClaimType="sub" />
      </TechnicalProfile>
    </RelyingParty>
    
  3. TrustFrameworkExtensions.xml ファイルを開き、<ClaimsSchema> 要素とその子要素を BuildingBlocks 要素に追加します。Open the TrustFrameworkExtensions.xml file and add the<ClaimsSchema> element and its child elements to the BuildingBlocks element:

    <BuildingBlocks>
      <ClaimsSchema>
        <ClaimType Id="extension_loyaltyId">
          <DisplayName>Loyalty Identification Tag</DisplayName>
          <DataType>string</DataType>
          <UserHelpText>Your loyalty number from your membership card</UserHelpText>
          <UserInputType>TextBox</UserInputType>
        </ClaimType>
      </ClaimsSchema>
    </BuildingBlocks>
    
  4. 同じ ClaimType 定義を TrustFrameworkBase.xml に追加します。Add the same ClaimType definition to TrustFrameworkBase.xml. ClaimType 定義は、基本ファイルと拡張ファイルの両方に追加する必要はありません。It's not necessary to add a ClaimType definition in both the base and the extensions files. しかし、次の手順で基本ファイルの TechnicalProfileextension_loyaltyId を追加します。However, the next steps add the extension_loyaltyId to TechnicalProfiles in the base file. そのため、この定義がないと、ポリシー検証で基本ファイルのアップロードが拒否されます。So the policy validator rejects the upload of the base file without it. TrustFrameworkBase.xml ファイルの ProfileEdit という名前のユーザー体験の実行を追跡すると役立つ場合があります。It might be useful to trace the execution of the user journey named ProfileEdit in the TrustFrameworkBase.xml file. エディターで同じ名前のユーザー体験を検索します。Search for the user journey with the same name in your editor. オーケストレーション手順 5 で TechnicalProfileReferenceID="SelfAsserted-ProfileUpdate が呼び出されることを確認します。Observe that Orchestration step 5 invokes the TechnicalProfileReferenceID="SelfAsserted-ProfileUpdate. この TechnicalProfile を検索して調査すると、処理の流れについて理解が深まります。Search and inspect this TechnicalProfile to familiarize yourself with the flow.

  5. TrustFrameworkBase.xml ファイルを開き、TechnicalProfile の SelfAsserted-ProfileUpdate に、入力および出力要求として loyaltyId を追加します。Open the TrustFrameworkBase.xml file and add loyaltyId as an input and output claim in the TechnicalProfile SelfAsserted-ProfileUpdate:

    <TechnicalProfile Id="SelfAsserted-ProfileUpdate">
      <DisplayName>User ID signup</DisplayName>
      <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
      <Metadata>
        <Item Key="ContentDefinitionReferenceId">api.selfasserted.profileupdate</Item>
      </Metadata>
      <IncludeInSso>false</IncludeInSso>
      <InputClaims>
        <InputClaim ClaimTypeReferenceId="alternativeSecurityId" />
        <InputClaim ClaimTypeReferenceId="userPrincipalName" />
        <InputClaim ClaimTypeReferenceId="givenName" />
        <InputClaim ClaimTypeReferenceId="surname" />
    
        <!-- Add the loyalty identifier -->
        <InputClaim ClaimTypeReferenceId="extension_loyaltyId"/>
        <!-- End of changes -->
      </InputClaims>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="executed-SelfAsserted-Input" DefaultValue="true" />
        <OutputClaim ClaimTypeReferenceId="givenName" />
        <OutputClaim ClaimTypeReferenceId="surname" />
    
        <!-- Add the loyalty identifier -->
        <OutputClaim ClaimTypeReferenceId="extension_loyaltyId"/>
        <!-- End of changes -->
    
      </OutputClaims>
      <ValidationTechnicalProfiles>
        <ValidationTechnicalProfile ReferenceId="AAD-UserWriteProfileUsingObjectId" />
      </ValidationTechnicalProfiles>
    </TechnicalProfile>
    
  6. TrustFrameworkBase.xmlファイルで、loyaltyId 要求を TechnicalProfile の AAD-UserWriteProfileUsingObjectId に追加します。In the TrustFrameworkBase.xml file, add the loyaltyId claim to TechnicalProfile AAD-UserWriteProfileUsingObjectId. この追加により、ディレクトリ内の現在のユーザーに関する拡張プロパティ内の要求の値が保持されます。This addition persists the value of the claim in the extension property for the current user in the directory:

    <TechnicalProfile Id="AAD-UserWriteProfileUsingObjectId">
      <Metadata>
        <Item Key="Operation">Write</Item>
        <Item Key="RaiseErrorIfClaimsPrincipalAlreadyExists">false</Item>
        <Item Key="RaiseErrorIfClaimsPrincipalDoesNotExist">true</Item>
      </Metadata>
      <IncludeInSso>false</IncludeInSso>
      <InputClaims>
        <InputClaim ClaimTypeReferenceId="objectId" Required="true" />
      </InputClaims>
      <PersistedClaims>
        <PersistedClaim ClaimTypeReferenceId="objectId" />
        <PersistedClaim ClaimTypeReferenceId="givenName" />
        <PersistedClaim ClaimTypeReferenceId="surname" />
    
        <!-- Add the loyalty identifier -->
        <PersistedClaim ClaimTypeReferenceId="extension_loyaltyId" />
        <!-- End of changes -->
    
      </PersistedClaims>
      <IncludeTechnicalProfile ReferenceId="AAD-Common" />
    </TechnicalProfile>
    
  7. TrustFrameworkBase.xml ファイルで、ユーザーがサインインするたびに拡張属性の値を読み取る loyaltyId 要求を TechnicalProfile の AAD-UserReadUsingObjectId に追加します。In the TrustFrameworkBase.xml file, add the loyaltyId claim to TechnicalProfile AAD-UserReadUsingObjectId to read the value of the extension attribute every time a user signs in. ここまで、TechnicalProfile は、ローカル アカウントのフローだけで変更されてきました。So far, the TechnicalProfiles have been changed in the flow of local accounts only. ソーシャルまたはフェデレーション アカウントのフローで新しい属性が必要な場合は、TechnicalProfile の別のセットを変更する必要があります。If you want the new attribute in the flow of a social or federated account, a different set of TechnicalProfiles needs to be changed. 次のステップ」セクションを参照してください。See the Next steps section.

    <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>
        <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" />
        <OutputClaim ClaimTypeReferenceId="displayName" />
        <OutputClaim ClaimTypeReferenceId="otherMails" />
        <OutputClaim ClaimTypeReferenceId="givenName" />
        <OutputClaim ClaimTypeReferenceId="surname" />
    
        <!-- Add the loyalty identifier -->
        <OutputClaim ClaimTypeReferenceId="extension_loyaltyId" />
        <!-- End of changes -->
    
      </OutputClaims>
      <IncludeTechnicalProfile ReferenceId="AAD-Common" />
    </TechnicalProfile>
    

カスタム ポリシーをテストするTest the custom policy

  1. [Azure AD B2C] ブレードを開き、 [Identity Experience Framework] > [カスタム ポリシー] の順に移動します。Open the Azure AD B2C blade and navigate to Identity Experience Framework > Custom policies.
  2. アップロードしたカスタム ポリシーを選択します。Select the custom policy that you uploaded. [今すぐ実行] を選択します。Select Run now.
  3. メール アドレスを使用してサインアップします。Sign up by using an email address.

アプリケーションに送り返される ID トークンには、extension_loyaltyId で始まるカスタム要求として新しい拡張プロパティが含まれます。The ID token sent back to your application includes the new extension property as a custom claim preceded by extension_loyaltyId. 次の例を参照してください。See the following example:

{
  "exp": 1493585187,
  "nbf": 1493581587,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/f06c2fe8-709f-4030-85dc-38a4bfd9e82d/v2.0/",
  "sub": "a58e7c6c-7535-4074-93da-b0023fbaf3ac",
  "aud": "4e87c1dd-e5f5-4ac8-8368-bc6a98751b8b",
  "acr": "b2c_1a_trustframeworkprofileedit",
  "nonce": "defaultNonce",
  "iat": 1493581587,
  "auth_time": 1493581587,
  "extension_loyaltyId": "abc",
  "city": "Redmond"
}

次の手順Next steps

  1. TechnicalProfile に従って変更することで、ソーシャル アカウントにサインインするフローに新しい要求を追加します。Add the new claim to the flows to sign in to social accounts by changing the following TechnicalProfiles. ソーシャル アカウントおよびフェデレーション アカウントでは、次の 2 つの TechnicalProfile を使用してサインインします。Social and federated accounts use these two TechnicalProfiles to sign in. これらは、ユーザー オブジェクトのロケーターとして alternativeSecurityId を使用してユーザー データの書き込みおよび読み取りを行います。They write and read user data by using the alternativeSecurityId as the locator of the user object.

     <TechnicalProfile Id="AAD-UserWriteUsingAlternativeSecurityId">
    
     <TechnicalProfile Id="AAD-UserReadUsingAlternativeSecurityId">
    
  2. 組み込みポリシーとカスタム ポリシー間で同じ拡張属性を使用します。Use the same extension attributes between built-in and custom policies. ポータルのエクスペリエンスを使用して拡張属性 (カスタム属性とも呼ばれます) を追加すると、これらの属性が、すべての B2C テナントに存在する b2c-extensions-app を使用して登録されます。When you add extension, or custom, attributes via the portal experience, those attributes are registered by using the b2c-extensions-app that exists in every B2C tenant. カスタム ポリシーで拡張属性を使用するには、次の手順を行います。Take the following steps to use extension attributes in your custom policy:

    a.a. portal.azure.com の B2C テナント内で、 [Azure Active Directory] に移動し、 [アプリの登録] を選択します。Within your B2C tenant in portal.azure.com, navigate to Azure Active Directory and select App registrations. b.b. 自分の b2c-extensions-app を検索して選択します。Find your b2c-extensions-app and select it. c.c. Essentials で、アプリケーション IDオブジェクト ID を入力します。Under Essentials, enter the Application ID and the Object ID. d.d. これらを、以下のように AAD-Common TechnicalProfile メタデータに含めます。Include them in your AAD-Common TechnicalProfile metadata:

       <ClaimsProviders>
         <ClaimsProvider>
           <DisplayName>Azure Active Directory</DisplayName>
           <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" />
             <!-- Provide objectId and appId before using extension properties. -->
             <Metadata>
               <Item Key="ApplicationObjectId">insert objectId here</Item> <!-- This is the "Object ID" from the "b2c-extensions-app"-->
               <Item Key="ClientId">insert appId here</Item> <!--This is the "Application ID" from the "b2c-extensions-app"-->
             </Metadata>
    
  3. ポータルのエクスペリエンスとの整合性を保ちます。Stay consistent with the portal experience. カスタム ポリシーで使用する前に、ポータルの UI を使用してこれらの属性を作成します。Create these attributes by using the portal UI before you use them in your custom policies. ポータルで属性 ActivationStatus を作成するときに、次のようにこの属性を参照する必要があります。When you create an attribute ActivationStatus in the portal, you must refer to it as follows:

    extension_ActivationStatus in the custom policy.
    extension_<app-guid>_ActivationStatus via Graph API.
    

リファレンスReference

拡張プロパティの詳細については、記事「ディレクトリ スキーマ拡張機能 | Graph API の概念」を参照してください。For more information on extension properties, see the article Directory schema extensions | Graph API concepts.

注意

  • TechnicalProfile は、エンドポイントの名前、メタデータ、およびプロトコルを定義する要素の種類 (または関数) です。A TechnicalProfile is an element type, or function, that defines an endpoint’s name, metadata, and protocol. TechnicalProfile には、Identity Experience Framework によって実行される要求の交換が詳細に示されています。The TechnicalProfile details the exchange of claims that the Identity Experience Framework performs. この関数がオーケストレーションの手順または別の TechnicalProfile から呼び出されると、InputClaimsOutputClaims が呼び出し元によってパラメーターとして指定されます。When this function is called in an orchestration step or from another TechnicalProfile, the InputClaims and OutputClaims are provided as parameters by the caller.
  • Graph API の拡張属性には、extension_ApplicationObjectID_attributename という規則を使って名前が付けられます。Extension attributes in the Graph API are named by using the convention extension_ApplicationObjectID_attributename.
  • カスタム ポリシーでは、拡張属性を extension_attributename として参照します。Custom policies refer to extension attributes as extension_attributename. この参照では、XML での ApplicationObjectId が省略されます。This reference omits the ApplicationObjectId in XML.
  • どこから参照されていても、属性 ID は次の形式 extension_attributename で指定する必要があります。You have to specify the attribute ID in the following format extension_attributename wherever it is being referenced.