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` クエリ文字列パラメーター。	00001111-aaaa-2222-bbbb-3333cccc4444
{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

コンテンツ定義

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

<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 カスタムポリシーでの要求リゾルバーについて

カルチャ

ポリシー

Context

Claims

OpenID Connect

OAuth2 のキー値パラメーター

SAML キー値パラメーター

SAML

OAuth2 ID プロバイダー

要求リゾルバーの使用

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

RESTful 技術プロファイル

動的 UI のカスタマイズ

コンテンツ定義

Application Insights の技術プロファイル

証明書利用者ポリシー

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

カルチャ

ポリシー

Context

Claims

OpenID Connect

OAuth2 のキー値パラメーター

SAML キー値パラメーター

SAML

OAuth2 ID プロバイダー

要求リゾルバーの使用

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

RESTful 技術プロファイル

直接サインイン

動的 UI のカスタマイズ

コンテンツ定義

Application Insights の技術プロファイル

証明書利用者ポリシー

次のステップ

フィードバック

その他のリソース

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