Azure Active Directory B2C カスタムポリシーでの要求リゾルバーについて

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

Azure Active Directory B2C (Azure AD B2C) カスタムポリシーでの要求リゾルバーは、ポリシー名、要求の相関 ID、ユーザーインターフェイス言語など、承認要求に関するコンテキスト情報を提供します。

入力要求または出力要求で要求リゾルバーを使用するには、ClaimsSchema 要素の下で文字列 ClaimType を定義した後、入力または出力の要求要素で DefaultValue を要求リゾルバーに設定します。 Azure AD B2C によって要求リゾルバーの値が読み取られて、技術プロファイルで使用されます。

次の例では、correlationId という名前の要求の種類が、string の DataType で定義されています。

<ClaimType Id="correlationId">
  <DisplayName>correlationId</DisplayName>
  <DataType>string</DataType>
  <UserHelpText>Request correlation Id</UserHelpText>
</ClaimType>

技術プロファイルでは、要求リゾルバーが要求の種類にマップされます。 Azure AD B2C では、要求リゾルバー {Context:CorrelationId} の値が要求 correlationId に設定されて、技術プロファイルに要求が送信されます。

<InputClaim ClaimTypeReferenceId="correlationId" DefaultValue="{Context:CorrelationId}" />

カルチャ

次の表に、要求リゾルバーと、承認要求で使用される言語に関する情報を示します。

要求	説明	例
{Culture:LanguageName}	言語に対する 2 文字の ISO コード。	en
{Culture:LCID}	言語コードの LCID。	1033
{Culture:RegionName}	リージョンに対する 2 文字の ISO コード。	US
{Culture:RFC5646}	RFC5646 言語コード。	ja-JP

このカルチャ要求リゾルバーのライブデモをご覧ください。

ポリシー

次の表に、要求リゾルバーと、承認要求で使用されるポリシーに関する情報を示します。

要求	説明	例
{Policy:PolicyId}	証明書利用者ポリシーの名前。	B2C_1A_signup_signin
{Policy:RelyingPartyTenantId}	証明書利用者ポリシーのテナント ID。	your-tenant.onmicrosoft.com
{Policy:TenantObjectId}	証明書利用者ポリシーのテナントオブジェクト ID。	00000000-0000-0000-0000-000000000000
{Policy:TrustFrameworkTenantId}	信頼フレームワークのテナント ID。	your-tenant.onmicrosoft.com

このポリシー要求リゾルバーのライブデモをご覧ください。

Context

次の表は、承認要求のコンテキスト要求リゾルバーを示しています。

要求	説明	例
{Context:BuildNumber}	Identity Experience Framework のバージョン (ビルド番号)。	1.0.507.0
{Context:CorrelationId}	関連付け ID。	00000000-0000-0000-0000-000000000000
{Context:DateTimeInUtc}	UTC での日時。	10/10/2021 12:00:00 PM
{Context:DeploymentMode}	ポリシーの展開モード。	Production
{Context:HostName}	現在の要求のホスト名。	contoso.b2clogin.com
{Context:IPAddress}	ユーザーの IP アドレス。	11.111.111.11
{Context:KMSI}	[サインインしたままにする] チェックボックスがオンになっているかどうかを示します。	true

このコンテキスト要求リゾルバーのライブデモをご覧ください。

Claims

このセクションでは、要求の値を要求リゾルバーとして取得する方法について説明します。

要求	説明	例
{Claim:claim type}	ポリシーファイルまたは親ポリシーファイルの ClaimsSchema セクションで定義済みの要求の種類の識別子。例: `{Claim:displayName}`、または `{Claim:objectId}`。	要求の種類の値。

OpenID Connect

次の表に、要求リゾルバーと、OpenID Connect 承認要求に関する情報を示します。

要求	説明	例
{OIDC:AuthenticationContextReferences}	`acr_values` クエリ文字列パラメーター。	該当なし
{OIDC:ClientId}	`client_id` クエリ文字列パラメーター。	00000000-0000-0000-0000-000000000000
{OIDC:DomainHint}	`domain_hint` クエリ文字列パラメーター。	facebook.com
{OIDC:LoginHint}	`login_hint` クエリ文字列パラメーター。	someone@contoso.com
{OIDC:MaxAge}	`max_age`。	該当なし
{OIDC:Nonce}	`Nonce` クエリ文字列パラメーター。	defaultNonce
{OIDC:Password}	リソース所有者のパスワード資格情報フローユーザーのパスワード。	パスワード 1
{OIDC:Prompt}	`prompt` クエリ文字列パラメーター。	ログイン (login)
{OIDC:RedirectUri}	`redirect_uri` クエリ文字列パラメーター。	https://jwt.ms
{OIDC:Resource}	`resource` クエリ文字列パラメーター。	該当なし
{OIDC:Scope}	`scope` クエリ文字列パラメーター。	openid
{OIDC:Username}	リソース所有者のパスワード資格情報フローユーザーのユーザー名。	emily@contoso.com
{OIDC:IdToken}	`id token` クエリ文字列パラメーター。	該当なし

この OpenID Connect 要求リゾルバーのライブデモをご覧ください。

OAuth2 のキー値パラメーター

OIDC 要求または OAuth2 要求の一部に含まれているすべてのパラメーター名は、ユーザー体験の要求にマップできます。たとえば、アプリケーションからの要求には、app_session の名前、loyalty_number、またはカスタムクエリ文字列が指定されたクエリ文字列パラメーターが含まれる場合があります。

要求	説明	例
{OAUTH-KV:campaignId}	クエリ文字列パラメーター。	ハワイ
{OAUTH-KV:app_session}	クエリ文字列パラメーター。	A3C5R
{OAUTH-KV:loyalty_number}	クエリ文字列パラメーター。	1234
{OAUTH-KV:任意のカスタムクエリ文字列}	クエリ文字列パラメーター。	該当なし

SAML キー値パラメーター

SAML 認証要求では、要求に含まれているが、プロトコルに固有ではないパラメーター名 (SAMLRequest など) は、ユーザー体験の要求にマップできます。たとえば、要求には、次のような usernameカスタムパラメーターを含めることができます。これは、SP によって開始される SAML 要求と IDP によって開始される SAML 要求の両方に適用されます。

要求	説明	例
{SAML-KV:username}	クエリ文字列または POST 本文パラメーター。	username@domain.com
{SAML-KV:loyalty_number}	クエリ文字列または POST 本文パラメーター。	1234
{SAML-KV:any カスタムクエリ文字列}	クエリ文字列または POST 本文パラメーター。	該当なし

SAML

次の表に、要求リゾルバーと、SAML 承認要求に関する情報を示します。

要求	説明	例
{SAML:AuthnContextClassReferences}	SAML 要求からの `AuthnContextClassRef` 要素の値。	urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
{SAML:NameIdPolicyFormat}	SAML 要求の `NameIDPolicy` 要素からの `Format` 属性。	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
{SAML:Issuer}	SAML 要求の SAML `Issuer` 要素の値。	`https://contoso.com`
{SAML:AllowCreate}	SAML 要求の `NameIDPolicy` 要素からの `AllowCreate` 属性値。	True
{SAML:ForceAuthn}	SAML 要求の `AuthnRequest` 要素からの `ForceAuthN` 属性値。	True
{SAML:ProviderName}	SAML 要求の `AuthnRequest` 要素からの `ProviderName` 属性値。	Contoso.com
{SAML:RelayState}	`RelayState` クエリ文字列パラメーター。
{SAML:Subject}	SAML AuthN 要求の NameId 要素からの `Subject`。
{SAML:Binding}	SAML 要求の `AuthnRequest` 要素からの `ProtocolBinding` 属性値。	urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

この SAML 要求リゾルバーのライブデモをご覧ください。

OAuth2 ID プロバイダー

次の表に、OAuth2 ID プロバイダーの要求リゾルバーを示します。

要求	説明	例
{oauth2:access_token}	OAuth2 id プロバイダーのアクセストークン。 `access_token` 属性。	`eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...`
{oauth2:token_type}	アクセストークンの型。 `token_type` 属性。	Bearer
{oauth2:expires_in}	アクセストークンが有効な時間の長さ (秒単位)。 `expires_in` 属性。出力要求のデータ型は`int`または`long`である必要があります。	960000
{oauth2:refresh_token}	OAuth2 id プロバイダーの更新トークン。 `refresh_token` 属性。	`eyJraWQiOiJacW9pQlp2TW5pYVc2MUY...`

OAuth2 id プロバイダーの要求リゾルバーを使用するには、出力要求の PartnerClaimType 属性を要求リゾルバーに設定します。次の例は、外部 id プロバイダーの要求を取得する方法を示しています。

<ClaimsProvider>
  <DisplayName>Contoso</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="Contoso-OAUTH">
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="identityProviderAccessToken" PartnerClaimType="{oauth2:access_token}" />
        <OutputClaim ClaimTypeReferenceId="identityProviderAccessTokenType" PartnerClaimType="{oauth2:token_type}" />
        <OutputClaim ClaimTypeReferenceId="identityProviderAccessTokenExpiresIn" PartnerClaimType="{oauth2:expires_in}" />
        <OutputClaim ClaimTypeReferenceId="identityProviderRefreshToken" PartnerClaimType="{oauth2:refresh_token}" />
      </OutputClaims>
      ...
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

要求リゾルバーの使用

次の要素を使用して、要求リゾルバーを使用できます。

アイテム	要素	設定
Application Insights の技術プロファイル	`InputClaim`
Microsoft Entra 技術プロファイル	`InputClaim`, `OutputClaim`	1、2
OAuth2 の技術プロファイル	`InputClaim`, `OutputClaim`	1、2
OpenID Connect の技術プロファイル	`InputClaim`, `OutputClaim`	1、2
要求変換の技術プロファイル	`InputClaim`, `OutputClaim`	1、2
RESTful プロバイダーの技術プロファイル	`InputClaim`	1、2
SAML ID プロバイダーの技術プロファイル	`OutputClaim`	1、2
セルフアサートの技術プロファイル	`InputClaim`, `OutputClaim`	1、2
ContentDefinition	`LoadUri`
ContentDefinitionParameters	`Parameter`
RelyingParty の技術プロファイル	`OutputClaim`	2

設定:

IncludeClaimResolvingInClaimsHandling メタデータを true に設定する必要があります。
入力要求または出力要求の属性 AlwaysUseDefaultValue は、trueに設定する必要があります。

要求リゾルバーのサンプル

RESTful 技術プロファイル

RESTful 技術プロファイルでは、ユーザーの言語、ポリシー名、スコープ、クライアント ID を送信したいことがありますこれらの要求に基づいて、REST API はカスタムビジネスロジックを実行できます。また必要に応じて、ローカライズされたエラーメッセージを発生させることができます。

このシナリオを使用する RESTful 技術プロファイルの例を次に示します。

<TechnicalProfile Id="REST">
  <DisplayName>Validate user input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="policyName" DefaultValue="{Policy:PolicyId}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="scope" DefaultValue="{OIDC:Scope}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="clientId" DefaultValue="{OIDC:ClientId}" AlwaysUseDefaultValue="true" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

要求リゾルバーを使用すると、サインイン名を事前入力したり、Facebook、LinkedIn、Microsoft アカウントなどの特定のソーシャル ID プロバイダーに直接サインインしたりできます。詳しくは、「Azure Active Directory B2C を使用した直接サインインの設定」をご覧ください。

動的 UI のカスタマイズ

Azure AD B2C を使用すると、HTML コンテンツ定義エンドポイントにクエリ文字列パラメーターを渡して、ページの内容を動的にレンダリングできます。たとえば、この機能を利用すると、 Web またはモバイルアプリケーションから渡すカスタムパラメーターに基づいて、Azure AD B2C サインアップまたはサインインページの背景イメージを変更することができます。詳しくは、Azure Active Directory B2C でのカスタムポリシーを使用した UI の動的な構成に関するページをご覧ください。言語パラメーターに基づいて HTML ページをローカライズしたり、クライアント ID に基づいて内容を変更したりすることもできます。

次の例では、名前が campaignId で値が Hawaii のクエリ文字列パラメーター、language コード en-US、およびクライアント ID を表す app を渡しています。

<UserJourneyBehaviors>
  <ContentDefinitionParameters>
    <Parameter Name="campaignId">{OAUTH-KV:campaignId}</Parameter>
    <Parameter Name="language">{Culture:RFC5646}</Parameter>
    <Parameter Name="app">{OIDC:ClientId}</Parameter>
  </ContentDefinitionParameters>
</UserJourneyBehaviors>

結果として、Azure AD B2C によって HTML コンテンツページに上記のパラメーターが送信されます。

/selfAsserted.aspx?campaignId=hawaii&language=en-US&app=0239a9cc-309c-4d41-87f1-31288feb2e82

コンテンツ定義

ContentDefinitionLoadUriでは、使用されるパラメーターに基づいて、さまざまな場所からコンテンツをプルする要求リゾルバーを送信できます。

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>https://contoso.blob.core.windows.net/{Culture:LanguageName}/myHTML/unified.html</LoadUri>
  ...
</ContentDefinition>

Application Insights の技術プロファイル

Azure Application Insights と要求リゾルバーを使用すると、ユーザーの動作に関する分析情報を取得できます。 Application Insights の技術プロファイルでは、Azure Application Insights に保持される入力要求を送信します。詳しくは、「Application Insights を使用した Azure AD B2C 体験でのユーザー動作の追跡」をご覧ください。次の例では、ポリシー ID、相関 ID、言語、クライアント ID を Azure Application Insights に送信しています。

<TechnicalProfile Id="AzureInsights-Common">
  <DisplayName>Alternate Email</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.Insights.AzureApplicationInsightsProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  ...
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="PolicyId" PartnerClaimType="{property:Policy}" DefaultValue="{Policy:PolicyId}" />
    <InputClaim ClaimTypeReferenceId="CorrelationId" PartnerClaimType="{property:CorrelationId}" DefaultValue="{Context:CorrelationId}" />
    <InputClaim ClaimTypeReferenceId="language" PartnerClaimType="{property:language}" DefaultValue="{Culture:RFC5646}" />
    <InputClaim ClaimTypeReferenceId="AppId" PartnerClaimType="{property:App}" DefaultValue="{OIDC:ClientId}" />
  </InputClaims>
</TechnicalProfile>

証明書利用者ポリシー

証明書利用者ポリシー技術プロファイルでは、テナント ID または関連付け ID を JWT 内の証明書利用者アプリケーションに送信することができます。

<RelyingParty>
    <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
    <TechnicalProfile Id="PolicyProfile">
      <DisplayName>PolicyProfile</DisplayName>
      <Protocol Name="OpenIdConnect" />
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="displayName" />
        <OutputClaim ClaimTypeReferenceId="givenName" />
        <OutputClaim ClaimTypeReferenceId="surname" />
        <OutputClaim ClaimTypeReferenceId="email" />
        <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
        <OutputClaim ClaimTypeReferenceId="identityProvider" />
        <OutputClaim ClaimTypeReferenceId="tenantId" AlwaysUseDefaultValue="true" DefaultValue="{Policy:TenantObjectId}" />
        <OutputClaim ClaimTypeReferenceId="correlationId" AlwaysUseDefaultValue="true" DefaultValue="{Context:CorrelationId}" />
      </OutputClaims>
      <SubjectNamingInfo ClaimType="sub" />
    </TechnicalProfile>
  </RelyingParty>

次のステップ

その他の要求リゾルバーのサンプルについては、Azure AD B2C コミュニティの GitHub リポジトリをご覧ください

Azure Active Directory B2C カスタム ポリシーでの要求リゾルバーについて