在 Azure Active Directory B2C 自定義原則中定義標識碼令牌提示技術配置檔

發行項
2025-05-08

這很重要

自 2025 年 5 月 1 日起，Azure AD B2C 將不再可供新客戶購買。在我們的常見問題中深入瞭解。

Azure AD B2C 可讓信賴憑證者應用程式在 OAuth2 授權要求中傳送輸入 JWT。 JWT 可由信賴憑證者應用程式或識別提供者發出，而且可以傳遞使用者或授權要求的提示。 Azure AD B2C 會驗證簽章、簽發者名稱和令牌物件，並從輸入令牌擷取宣告。

使用案例

您可以使用此解決方案將資料傳送至封裝在單一 JWT 中的 Azure AD B2C。系統管理員Signup with email invitation可以將已簽署的邀請傳送給使用者的解決方案是以id_token_hint為基礎。只有具有邀請電子郵件存取權的使用者才能在目錄中建立帳戶。

令牌簽署方法

使用id_token_hint，令牌簽發者（信賴憑證者應用程式或識別提供者）會組成令牌，然後使用簽署密鑰來簽署令牌，以證明令牌來自受信任的來源。簽署金鑰可以是對稱或非對稱金鑰。對稱密碼編譯或私鑰密碼編譯會使用共用密碼來簽署和驗證簽章。非對稱密碼編譯或公鑰密碼編譯是使用私鑰和公鑰的密碼編譯系統。只有令牌簽發者知道私鑰，而且用來簽署令牌。公鑰會與 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`	令牌變成無效的時間，以 epoch 時間表示。 Azure AD B2C 會驗證此值，並在令牌過期時拒絕令牌。
不是之前	`nbf`	`1599482515`	令牌生效的時間，以時間紀元表示。此時間通常與憑證發行的時間相同。 Azure AD B2C 會驗證此值，並在令牌存留期無效時拒絕令牌。

下列令牌是有效識別碼令牌的範例：

{
  "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 中定義的名稱。您也可以包含 JWT 未傳回的宣告，只要您設定 DefaultValue 屬性即可。

後設資料

使用對稱金鑰時，下列元數據相關。

屬性	為必填項目	說明
發行者	是的	識別安全性令牌服務（令牌簽發者）。此值必須與 JWT 宣告內的宣告相同 `iss` 。
IdTokenAudience	是的	識別權杖的預定接收者。必須與 JWT 宣告內的宣告相同 `aud` 。

使用非對稱金鑰時，下列元數據是相關的。

屬性	為必填項目	說明
中繼資料	是的	指向令牌簽發者組態檔的URL，也稱為OpenID已知組態端點。
發行者	否	識別安全性令牌服務（令牌簽發者）。這個值可以用來覆寫元數據中設定的值，而且必須與 JWT 宣告內的宣告相同 `iss` 。
IdTokenAudience	否	識別權杖的預定接收者。必須與 JWT 宣告內的宣告相同 `aud` 。

這很重要

您的端點必須符合 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 入口網站。
如果您有多個租用戶的存取權，請使用頂端功能表中的 [設定] 圖示，從 [目錄 + 訂用帳戶] 功能表切換至您的 Azure AD B2C 租用戶。
在 Azure 入口網站中，搜尋並選取 [Azure AD B2C]。
在概觀頁面上，在 [原則] 底下，選取 [身分識別體驗架構]。
選取 原則金鑰
選取 [手動]。
針對 [名稱]，請使用 IdTokenHintKey。
可能會自動新增前置詞 B2C_1A_ 。
在 [ 秘密 ] 方塊中，輸入您稍早產生的登入密鑰。
針對 金鑰使用方式，請使用加密。
選取 ，創建。
確認您已建立金鑰 B2C_1A_IdTokenHintKey。

步驟 3：新增標識元令牌提示技術配置檔

下列技術配置檔會驗證令牌並擷取宣告。

<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 範例是一個 ASP.NET Web 應用程式和控制台應用程式，其會產生使用對稱密鑰簽署的標識元令牌。

發行具有非對稱金鑰的令牌

使用非對稱金鑰時，令牌會使用 RSA 憑證簽署。此應用程式會裝載 Azure AD B2C 用來驗證標識元令牌簽章的 OpenID Connect 元數據端點和 JSON Web 金鑰（JWKs）端點。

權杖簽發者必須提供下列端點：

/.well-known/openid-configuration - 具有令牌相關信息的已知組態端點，例如令牌簽發者名稱和 JWK 端點的連結。
/.well-known/keys - JSON Web 金鑰（JWK）端點，其中包含用來簽署密鑰的公鑰（使用憑證的私鑰部分）。

TokenMetadataController.cs 請參閱 .NET MVC 控制器範例。

步驟 1：準備自我簽署憑證

如果您還沒有憑證，您可以使用自我簽署憑證來進行本作指南。在 Windows 上，您可以使用 PowerShell 的 New-SelfSignedCertificate Cmdlet 來產生憑證。

執行此 PowerShell 命令以產生自我簽署憑證。 -Subject視您的應用程式和 Azure AD B2C 租使用者名稱適當修改自變數。您也可以調整 -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：新增標識元令牌提示技術配置檔

下列技術配置檔會驗證令牌並擷取宣告。將元數據 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 應用程式會產生標識碼令牌，並裝載在 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 存放庫上，使用邀請電子郵件解決方案來檢查註冊。

共用方式為