共用方式為

在 Azure Active Directory 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 a489fc44-3cc0-4a78-92f6-e413cd853eae 識別令牌的預定收件者。 物件是由令牌簽發者定義的任意字串。 Azure AD B2C 會驗證此值，如果令牌不相符，則會拒絕令牌。
Issuer iss https://localhost 識別安全性令牌服務（令牌簽發者）。 簽發者是令牌簽發者所定義的任意 URI。 Azure AD B2C 會驗證此值，如果令牌不相符，則會拒絕令牌。
到期時間 exp 1600087315 令牌變成無效的時間，以 epoch 時間表示。 Azure AD B2C 會驗證此值，並在令牌過期時拒絕令牌。
不是之前 nbf 1599482515 令牌生效的時間，以 epoch 時間表示。 這次通常與令牌發行的時間相同。 Azure AD B2C 會驗證此值，並在令牌存留期無效時拒絕令牌。

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

{
  "alg": "HS256",
  "typ": "JWT"
}.{
  "displayName": " John Smith",
  "userId": "john.s@contoso.com",
  "nbf": 1599482515,
  "exp": 1600087315,
  "iss": "https://localhost",
  "aud": "a489fc44-3cc0-4a78-92f6-e413cd853eae"
}

通訊協定

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 屬性即可。

中繼資料

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

屬性 必要 描述
issuer Yes 識別安全性令牌服務（令牌簽發者）。 此值必須與 JWT 令牌宣告內的宣告相同 iss 。
IdTokenAudience Yes 識別令牌的預定收件者。 必須與 JWT 令牌宣告內的宣告相同 aud 。

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

屬性 必要 描述
METADATA Yes 指向令牌簽發者組態檔的URL，也稱為OpenID已知組態端點。
issuer No 識別安全性令牌服務（令牌簽發者）。 這個值可以用來覆寫元數據中設定的值，而且必須與 JWT 令牌宣告內的宣告相同 iss 。
IdTokenAudience No 識別令牌的預定收件者。 必須與 JWT 令牌宣告內的宣告相同 aud 。

重要

您的端點必須符合 Azure AD B2C 安全性需求。 舊版 TLS 和密碼已被取代。 如需詳細資訊，請參閱 Azure AD B2C TLS 和加密套件需求。

密碼編譯金鑰

使用對稱密鑰時， CryptographicKeys 元素包含下列屬性：

屬性 必要 描述
client_secret Yes 用來驗證 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 原則金鑰中建立。

  1. 登入 Azure 入口網站。
  2. 如果您有多個租使用者的存取權，請選取頂端功能表中的 [設定] 圖示，從 [目錄 + 訂用帳戶] 功能表切換至您的 Azure AD B2C 租使用者。
  3. 在 Azure 入口網站中，搜尋並選取 [Azure AD B2C]。
  4. 在 [概觀] 頁面的 [原則] 底下，選取 [身分識別體驗架構]。
  5. 選取 原則金鑰
  6. 選取 [ 手動]。
  7. 針對 [ 名稱]，請使用 IdTokenHintKey。
    可能會自動新增前置詞 B2C_1A_ 。
  8. 在 [ 秘密 ] 方塊中，輸入您稍早產生的登入密鑰。
  9. 針對金鑰 使用方式，請使用 加密。
  10. 選取建立。
  11. 確認您已建立金鑰 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">a489fc44-3cc0-4a78-92f6-e413cd853eae</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 連線 元數據端點和 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 別的協調流程步驟呼叫，而且需要指定信賴憑證者原則的輸入宣告。

  1. 將IdTokenHint_ExtractClaims技術配置檔新增至您的擴充原則。

  2. 將下列協調流程步驟新增至您的使用者旅程圖作為第一個專案。

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

  3. 在信賴憑證者原則中，重複您在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=63ba0d17-c4ba-47fd-89e9-31b3c2734339&nonce=defaultNonce&redirect_uri=https%3A%2F%2Fjwt.ms&scope=openid&response_type=id_token&prompt=login&id_token_hint=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkaXNwbGF5TmFtZSI6IiBKb2huIFNtaXRoIiwidXNlcklkIjoiam9obi5zQGNvbnRvc28uY29tIiwibmJmIjoxNTk5NDgyNTE1LCJleHAiOjE2MDAwODczMTUsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0IiwiYXVkIjoiYTQ4OWZjNDQtM2NjMC00YTc4LTkyZjYtZTQxM2NkODUzZWFlIn0.nPmLXydI83PQCk5lRBYUZRu_aX58pL1khahHyQuupig

下一步