共用方式為


在 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 00001111-aaaa-2222-bbbb-3333cccc4444 識別令牌的預定收件者。 物件是由令牌簽發者定義的任意字串。 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": "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 屬性即可。

中繼資料

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

屬性 必要 描述
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">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 連線 元數據端點和 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=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

下一步