Azure Active Directory B2C カスタムポリシーで Microsoft Entra 技術プロファイルを定義する

[アーティクル]
01/11/2024

Note

Azure Active Directory B2C で、カスタムポリシーは、主に、複雑なシナリオに取り組む用途向けに設計されています。ほとんどのシナリオで、組み込みユーザーフローを使用することをお勧めします。まだ行っていない場合は、Active Directory B2C でのカスタムポリシーの概要に関する記事で、カスタムポリシースターターパックの詳細を確認してください。

Azure Active Directory B2C (Azure AD B2C) は、Microsoft Entra ユーザー管理をサポートしています。この記事では、この標準化されたプロトコルをサポートするクレームプロバイダーとやりとりするための、技術プロファイルの詳細について説明します。

Protocol

Protocol 要素の Name 属性は Proprietary に設定する必要があります。 handler 属性には、プロトコルハンドラーアセンブリ Web.TPEngine.Providers.AzureActiveDirectoryProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null の完全修飾名が含まれている必要があります。

次のカスタムポリシースターターパック Microsoft Entra 技術プロファイルには、AAD-Common 技術プロファイルが含まれています。 Microsoft Entra 技術プロファイルではプロトコルが指定されていません。これは、プロトコルが AAD-Common 技術プロファイルで構成されているためです。

AAD-UserReadUsingAlternativeSecurityId および AAD-UserReadUsingAlternativeSecurityId-NoError - ディレクトリ内のソーシャルアカウントを検索します。
AAD-UserWriteUsingAlternativeSecurityId - 新しいソーシャルアカウントを作成します。
AAD-UserReadUsingEmailAddress - ディレクトリ内のローカルアカウントを検索します。
AAD-UserWriteUsingLogonEmail - 新しいローカルアカウントを作成します。
AAD-UserWritePasswordUsingObjectId - ローカルアカウントのパスワードを更新します。
AAD-UserWriteProfileUsingObjectId - ローカルまたはソーシャルアカウントのユーザープロファイルを更新します。
AAD-UserReadUsingObjectId - ローカルまたはソーシャルアカウントのユーザープロファイルを読み取ります。
AAD-UserWritePhoneNumberUsingObjectId - ローカルまたはソーシャルアカウントの MFA 電話番号を書き込みます。

次の例は、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

InputClaims 要素には、ディレクトリ内のアカウントを検索したり、新しいものを作成したりするために使用される要求が含まれています。すべての Microsoft Entra 技術プロファイルには、InputClaim 要素が入力要求コレクションに 1 つだけ存在する必要があります。ポリシーで定義されている要求の名前を、Microsoft Entra ID で定義されている名前にマップする必要がある場合があります。

既存のユーザーアカウントの読み取り、更新、または削除を行う場合、入力要求は Microsoft Entra ディレクトリ内のアカウントを一意に識別するキーです。たとえば、objectId、userPrincipalName、signInNames.emailAddress、signInNames.userName、alternativeSecurityId などです。

新しいユーザーアカウントを作成する場合、入力要求はローカルまたはフェデレーションアカウントを一意に識別するキーです。たとえば、ローカルアカウントの場合、signInNames.emailAddress や signInNames.userName です。フェデレーションアカウントの場合は、alternativeSecurityId です。

InputClaimsTransformations 要素には、入力要求を変更したり新しいものを生成するために使用される、入力要求変換の要素のコレクションを含めることができます。

OutputClaims

OutputClaims 要素には、Microsoft Entra ID 技術プロファイルによって返された要求の一覧が含まれています。ポリシーで定義されている要求の名前を、Microsoft Entra ID で定義されている名前にマップする必要がある場合があります。 DefaultValue 属性を設定している限り、Microsoft Entra ID によって返されない要求も含めることができます。

OutputClaimsTransformations 要素には、出力要求を修正したり新しい要求を生成するために使用される、OutputClaimsTransformation 要素のコレクションが含まれている場合があります。

たとえば、AAD-UserWriteUsingLogonEmail 技術プロファイルはローカルアカウントを作成し、以下の要求を返します。

objectId、新しいアカウントの識別子です
newUser、ユーザーが新規であるかどうかを示します
authenticationSource、認証を localAccountAuthentication に設定します
userPrincipalName、新しいアカウントのユーザープリンシパル名です
signInNames.emailAddress、アカウントのサインイン名で、email 入力要求に似ています

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

PersistedClaims

PersistedClaims 要素には、ポリシー内の ClaimsSchema セクションに既に定義されている要求の種類と Microsoft Entra 属性名の間の可能なマッピング情報と共に、Microsoft Entra ID によって保持される必要があるすべての値が含まれています。

新しいローカルアカウントを作成する AAD-UserWriteUsingLogonEmail 技術プロファイルは、以下の要求を保持します。

  <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>

要求の名前は、Microsoft Entra 属性名を含む PartnerClaimType 属性が指定されている場合を除き、Microsoft Entra 属性の名前です。

操作の要件

すべての Microsoft Entra 技術プロファイルには、InputClaim 要素が要求バッグに 1 つだけ存在する必要があります。
ユーザープロファイル属性に関する記事では、入力要求、出力要求、および永続化された要求で使用できる、サポートされている Azure AD B2C ユーザープロファイル属性について説明しています。
操作が Write または DeleteClaims の場合は、PersistedClaims 要素にも表示する必要があります。
userPrincipalName 要求の値の形式は、user@tenant.onmicrosoft.com である必要があります。
displayName 要求は必須であり、空の文字列にすることはできません。

Microsoft Entra 技術プロファイルの操作

読み取り

読み取り操作は、単一のユーザーアカウントに関するデータを読み取ります。以下の技術プロファイルは、ユーザーの objectId を使用してユーザーアカウントに関するデータを読み取ります。

<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>

Write

書き込み操作は、単一のユーザーアカウントを作成または更新します。以下の技術プロファイルは、新しいソーシャルアカウントを作成します。

<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

DeleteClaims 操作は、提供された要求の一覧から情報を消去します。以下の技術プロファイルは、要求を削除します。

<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

DeleteClaimsPrincipal 操作は、ディレクトリから単一のユーザーアカウントを削除します。以下の技術プロファイルは、ユーザープリンシパル名を使用してディレクトリからユーザーアカウントを削除します。

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

以下の技術プロファイルは、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>

Metadata

属性	必須	説明
Operation	はい	実行する操作。指定できる値: `Read`、`Write`、`DeleteClaims`、または `DeleteClaimsPrincipal`。
RaiseErrorIfClaimsPrincipalDoesNotExist	いいえ	ユーザーオブジェクトがディレクトリに存在しない場合、エラーを発生させます。指定できる値: `true` または `false`。
RaiseErrorIfClaimsPrincipalAlreadyExists	いいえ	ユーザーオブジェクトが既に存在する場合、エラーを発生させます。指定できる値: `true` または `false`。このメタデータは、書き込み操作にのみ適用されます。
ApplicationObjectId	いいえ	拡張属性のアプリケーションオブジェクト識別子。値:アプリケーションの ObjectId。詳細については、カスタム属性を使用する方法に関する記事を参照してください。
ClientId	いいえ	サードパーティとしてテナントにアクセスするためのクライアント識別子。詳細については、「カスタムプロファイル編集ポリシーのカスタム属性を使用」を参照してください。
IncludeClaimResolvingInClaimsHandling	いいえ	入力と出力の要求について、要求の解決を技術プロファイルに含めるかどうかを指定します。指定できる値: `true` または `false` (既定値)。技術プロファイルで要求リゾルバーを使用する場合は、これを `true` に設定します。

UI 要素

次の設定を使用して、失敗したときに表示されるエラーメッセージを構成できます。メタデータは、セルフアサート技術プロファイルで構成する必要があります。エラーメッセージは、ローカライズできます。

属性	必須	説明
UserMessageIfClaimsPrincipalAlreadyExists	いいえ	エラーが発生する場合 (RaiseErrorIfClaimsPrincipalAlreadyExists 属性の説明を参照)、ユーザーオブジェクトが既に存在する場合にユーザーに表示するメッセージを指定します。
UserMessageIfClaimsPrincipalDoesNotExist	いいえ	エラーが発生する場合 (RaiseErrorIfClaimsPrincipalDoesNotExist 属性の説明を参照)、ユーザーオブジェクトが存在しない場合にユーザーに表示するメッセージを指定します。

次のステップ

Microsoft Entra 技術プロファイルの使用例については、次の記事を参照してください。

Azure Active Directory B2C のカスタムポリシーを使用した要求の追加とユーザー入力のカスタマイズ

Azure Active Directory B2C カスタム ポリシーで Microsoft Entra 技術プロファイルを定義する