Azure Active Directory B2C カスタムポリシーで ID トークンヒント技術プロファイルを定義する

2025-05-09

Von Bedeutung

2025 年 5 月 1 日より、Azure AD B2C は新規のお客様向けに購入できなくなります。詳細については、FAQ を参照してください。

Azure AD B2C を使用すると、証明書利用者アプリケーションは OAuth2 承認要求の一部として受信 JWT を送信できます。 JWT は、証明書利用者アプリケーションまたは ID プロバイダーによって発行でき、ユーザーまたは承認要求に関するヒントを渡すことができます。 Azure AD B2C は、署名、発行者名、トークン対象ユーザーを検証し、受信トークンから要求を抽出します。

活用事例

このソリューションを使用すると、1 つの JWT にカプセル化された Azure AD B2C にデータを送信できます。システム管理者が署名付き招待をユーザーに送信できる Signup with email invitation ソリューションは、id_token_hintに基づいています。ディレクトリにアカウントを作成できるのは、招待メールにアクセスできるユーザーだけです。

トークン署名のアプローチ

id_token_hintでは、トークン発行者 (証明書利用者アプリまたは ID プロバイダー) がトークンを作成し、署名キーを使用して署名し、トークンが信頼できるソースから取得されたかどうかを証明します。署名キーには、対称キーまたは非対称キーを使用できます。対称暗号化 (秘密キー暗号化) は、共有シークレットを使用して署名と検証の両方を行います。非対称暗号化 (公開キー暗号化) は、秘密キーと公開キーの両方を使用する暗号化システムです。秘密キーはトークン発行者にのみ認識され、トークンの署名に使用されます。公開キーは、トークンの署名を検証するために Azure AD B2C ポリシーと共有されます。

トークンの形式

id_token_hintは有効な JWT である必要があります。次の表に、必須の要求を示します。追加の要求は省略可能です。

名前	主張	値の例	説明
聴衆	`aud`	`00001111-aaaa-2222-bbbb-3333cccc4444`	トークンの受信者を示します。対象ユーザーは、トークン発行者によって定義された任意の文字列です。 Azure AD B2C はこの値を検証し、一致しない場合はトークンを拒否します。
発行者	`iss`	`https://localhost`	セキュリティトークンサービス (トークン発行者) を識別します。発行者は、トークン発行者によって定義された任意の URI です。 Azure AD B2C はこの値を検証し、一致しない場合はトークンを拒否します。
期限切れ日時	`exp`	`1600087315`	トークンが無効になる時刻 (エポック時間で表されます)。 Azure AD B2C はこの値を検証し、トークンの有効期限が切れている場合はトークンを拒否します。
期間の開始時刻	`nbf`	`1599482515`	トークンが有効になる時刻をエポック時間で表します。この時間は通常、トークンが発行された時刻と同じです。 Azure AD B2C はこの値を検証し、トークンの有効期間が無効な場合はトークンを拒否します。

有効な ID トークンの例を次に示します。

{
  "alg": "HS256",
  "typ": "JWT"
}.{
  "displayName": " John Smith",
  "userId": "john.s@contoso.com",
  "nbf": 1599482515,
  "exp": 1600087315,
  "iss": "https://localhost",
  "aud": "00001111-aaaa-2222-bbbb-3333cccc4444"
}

プロトコル

Protocol 要素の Name 属性は None に設定する必要があります。たとえば、 IdTokenHint_ExtractClaims 技術プロファイルのプロトコルは None。

<TechnicalProfile Id="IdTokenHint_ExtractClaims">
  <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
  <Protocol Name="None" />
  ...

技術プロファイルは、 GetClaimsの種類を持つオーケストレーションステップから呼び出されます。

<OrchestrationStep Order="1" Type="GetClaims" CpimIssuerTechnicalProfileReferenceId="IdTokenHint_ExtractClaims" />

出力クレーム

OutputClaims 要素には、JWT から抽出される要求の一覧が含まれています。ポリシーで定義されている要求の名前を JWT で定義された名前にマップすることが必要な場合があります。 DefaultValue属性を設定している限り、JWT によって返されない要求を含めることもできます。

メタデータ

対称キーを使用する場合は、次のメタデータが関連します。

特性	必須	説明
発行者	イエス	セキュリティトークンサービス (トークン発行者) を識別します。この値は、JWT 要求内の `iss` 要求と同じである必要があります。
IdTokenAudienceの	イエス	トークンの受信者を示します。 JWT 要求内の `aud` 要求と同じである必要があります。

非対称キーを使用する場合は、次のメタデータが関連します。

特性	必須	説明
メタデータ	イエス	トークン発行者の構成ドキュメント (OpenID の既知の構成エンドポイントとも呼ばれます) を指す URL。
発行者	いいえ	セキュリティトークンサービス (トークン発行者) を識別します。この値は、メタデータで構成された値を上書きするために使用でき、JWT 要求内の `iss` 要求と同じである必要があります。
IdTokenAudienceの	いいえ	トークンの受信者を示します。 JWT 要求内の `aud` 要求と同じである必要があります。

Von Bedeutung

エンドポイントは、Azure AD B2C のセキュリティ要件に準拠している必要があります。古い TLS バージョンと暗号は非推奨です。詳細については、 Azure AD B2C TLS と暗号スイートの要件に関するページを参照してください。

暗号化キー

対称キーを使用する場合、 CryptographicKeys 要素には次の属性が含まれます。

特性	必須	説明
クライアントシークレット	イエス	JWT 署名の検証に使用される暗号化キー。

ハウツーガイド

対称キーを使用してトークンを発行する

手順 1: 共有キーを作成する

トークンの署名に使用できるキーを作成します。たとえば、次の PowerShell コードを使用してキーを生成します。

$bytes = New-Object Byte[] 32
$rand = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$rand.GetBytes($bytes)
$rand.Dispose()
$newClientSecret = [System.Convert]::ToBase64String($bytes)
$newClientSecret

このコードは、 VK62QTn0m1hMcn0DQ3RPYDAr6yIiSvYgdRwjZtU5QhI=のようなシークレット文字列を作成します。

手順 2: 署名キーを Azure AD B2C に追加する

トークン発行者が使用するのと同じキーを Azure AD B2C ポリシーキーに作成する必要があります。

Azure portal にサインインします。
複数のテナントにアクセスできる場合、上部のメニューの [設定] アイコンを選択し、[ディレクトリとサブスクリプション] メニューからお使いの Azure AD B2C テナントに切り替えます。
Azure portal で、 [Azure AD B2C] を検索して選択します。
概要ページの Policiesで、Identity Experience Frameworkを選択します。
ポリシーキーの選択
[Manual] \(手動) を選択します。
[名前] には、IdTokenHintKeyを使用します。
プレフィックス B2C_1A_ は自動的に追加される場合があります。
[ シークレット ] ボックスに、前に生成したサインインキーを入力します。
キーを使用する場合は、暗号化を使用します。
を選択してを作成します。
キー B2C_1A_IdTokenHintKeyが作成されたことを確認します。

手順 3: ID トークンヒント技術プロファイルを追加する

次の技術プロファイルは、トークンを検証し、要求を抽出します。

<ClaimsProvider>
  <DisplayName>My ID Token Hint ClaimsProvider</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="IdTokenHint_ExtractClaims">
      <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
      <Protocol Name="None" />
      <Metadata>
        <Item Key="IdTokenAudience">00001111-aaaa-2222-bbbb-3333cccc4444</Item>
        <Item Key="issuer">https://localhost</Item>
      </Metadata>
      <CryptographicKeys>
        <Key Id="client_secret" StorageReferenceId="B2C_1A_IdTokenHintKey" />
      </CryptographicKeys>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
      </OutputClaims>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

手順 4: ポリシーを準備する

[ポリシーの構成] 手順を完了します。

手順 5: コードを準備する

GitHub サンプルは、対称キーを使用して署名された ID トークンを生成する ASP.NET Web アプリケーションおよびコンソールアプリです。

非対称キーを使用してトークンを発行する

非対称キーを使用すると、トークンは RSA 証明書を使用して署名されます。このアプリケーションは、Azure AD B2C が ID トークンの署名を検証するために使用する OpenID Connect メタデータエンドポイントと JSON Web キー (JWK) エンドポイントをホストします。

トークン発行者は、次のエンドポイントを提供する必要があります。

/.well-known/openid-configuration - トークン発行者名や JWK エンドポイントへのリンクなど、トークンに関する関連情報を含む既知の構成エンドポイント。
/.well-known/keys - (証明書の秘密キー部分を使用して) キーの署名に使用される公開キーを持つ JSON Web キー (JWK) エンドポイント。

TokenMetadataController.cs .NET MVC コントローラーのサンプルを参照してください。

手順 1: 自己署名証明書を準備する

証明書がまだない場合は、このハウツーガイドに自己署名証明書を使用できます。 Windows では、PowerShell の New-SelfSignedCertificate コマンドレットを使用して証明書を生成できます。

この PowerShell コマンドを実行して、自己署名証明書を生成します。アプリケーションと Azure AD B2C テナント名に応じて、 -Subject 引数を変更します。また、証明書に別の有効期限を指定するように -NotAfter 日付を調整することもできます。

New-SelfSignedCertificate `
    -KeyExportPolicy Exportable `
    -Subject "CN=yourappname.yourtenant.onmicrosoft.com" `
    -KeyAlgorithm RSA `
    -KeyLength 2048 `
    -KeyUsage DigitalSignature `
    -NotAfter (Get-Date).AddMonths(12) `
    -CertStoreLocation "Cert:\CurrentUser\My"

手順 2: ID トークンヒント技術プロファイルを追加する

次の技術プロファイルは、トークンを検証し、要求を抽出します。メタデータ URI をトークン発行者の既知の構成エンドポイントに変更します。

<ClaimsProvider>
  <DisplayName>My ID Token Hint ClaimsProvider</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="IdTokenHint_ExtractClaims">
      <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
      <Protocol Name="None" />
      <Metadata>
        <!-- Replace with your endpoint location -->
        <Item Key="METADATA">https://your-app.azurewebsites.net/.well-known/openid-configuration</Item>
        <Item Key="IdTokenAudience">your_optional_audience</Item>
        <!-- <Item Key="issuer">your_optional_token_issuer_override</Item> -->
      </Metadata>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
      </OutputClaims>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

手順 3: ポリシーを準備する

[ポリシーの構成] 手順を完了します。

手順 4: コードを準備する

この GitHub サンプル ASP.NET Web アプリケーションは、ID トークンを生成し、Azure AD B2C で "id_token_hint" パラメーターを使用するために必要なメタデータエンドポイントをホストします。

ポリシーを構成する

対称アプローチと非対称アプローチの両方で、 id_token_hint 技術プロファイルは、種類が GetClaims のオーケストレーションステップから呼び出され、証明書利用者ポリシーの入力要求を指定する必要があります。

IdTokenHint_ExtractClaims技術プロファイルを拡張機能ポリシーに追加します。

最初の項目として、次のオーケストレーション手順をユーザー体験に追加します。

<OrchestrationStep Order="1" Type="GetClaims" CpimIssuerTechnicalProfileReferenceId="IdTokenHint_ExtractClaims" />

証明書利用者ポリシーで、IdTokenHint_ExtractClaims技術プロファイルで構成したのと同じ入力要求を繰り返します。例えば次が挙げられます。

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUp" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="OpenIdConnect" />
    <InputClaims>
      <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
    </InputClaims>
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="displayName" />
      <OutputClaim ClaimTypeReferenceId="givenName" />
      <OutputClaim ClaimTypeReferenceId="surname" />
      <OutputClaim ClaimTypeReferenceId="email" />
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="identityProvider" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

ビジネス要件によっては、電子メールアドレスの形式を確認するなど、トークンの検証を追加する必要がある場合があります。これを行うには、要求変換技術プロファイルを呼び出すオーケストレーション手順を追加します。また、セルフアサート技術プロファイルを追加して、エラーメッセージを表示します。

トークンを作成して署名する

GitHub サンプルでは、このようなトークンを作成して JWT を発行し、後で id_token_hint クエリ文字列パラメーターとして送信する方法を示します。パラメーターを使用した承認要求の例id_token_hint次に示します。

https://tenant-name.b2clogin.com/tenant-name.onmicrosoft.com/B2C_1A_signup_signin/oauth2/v2.0/authorize?client_id=11112222-bbbb-3333-cccc-4444dddd5555&nonce=defaultNonce&redirect_uri=https%3A%2F%2Fjwt.ms&scope=openid&response_type=id_token&prompt=login&id_token_hint=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkaXNwbGF5TmFtZSI6IiBKb2huIFNtaXRoIiwidXNlcklkIjoiam9obi5zQGNvbnRvc28uY29tIiwibmJmIjoxNTk5NDgyNTE1LCJleHAiOjE2MDAwODczMTUsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0IiwiYXVkIjoiYTQ4OWZjNDQtM2NjMC00YTc4LTkyZjYtZTQxM2NkODUzZWFlIn0.nPmLXydI83PQCk5lRBYUZRu_aX58pL1khahHyQuupig

次のステップ

Azure AD B2C コミュニティ GitHub リポジトリで、招待メールソリューションでサインアップを確認します。