Microsoft 身分識別平台的應用程式驗證憑證認證

發行項
10/25/2024

Microsoft 身分識別平台可讓應用程式使用自己的認證在可以使用用戶端密的任何地點進行驗證；例如，在 OAuth 2.0 用戶端認證授與 (部分機器翻譯) 流程和代理者 (OBO) (部分機器翻譯) 流程中。

應用程式可用於驗證的認證形式之一，是以應用程式擁有的憑證簽署的 JSON Web 權杖 (JWT) (部分機器翻譯) 判斷提示。這會在用戶端驗證選項的OpenID Connect規格 private_key_jwt 中說明。

如果您想要使用另一個身分識別提供者所簽發的 JWT 作為應用程式的認證，請參閱工作負載身分識別同盟，了解如何設定同盟原則。

判斷提示格式

若要計算判斷提示，您可以使用本身所選語言中的眾多 JWT 程式庫之一 - MSAL 使用 .WithCertificate() 支援此功能。權杖會在其標頭、宣告和簽章中攜帶這項資訊。

參數	備註
`alg`	應該是 PS256
`typ`	應該是 JWT
`x5t#s256`	X.509 憑證 DER 編碼的Base64url編碼SHA-256指紋。

宣告 (承載)

宣告類型	值	Description
`aud`	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`	"aud" (對象) 宣告會識別 JWT 的目標收件者 (此處為 Microsoft Entra ID)，請參閱 RFC 7519，第 4.1.3 節 (英文)。在此情況下，該收件者是登入伺服器 (`login.microsoftonline.com`)。
`exp`	1601519414	"exp" (到期時間) 宣告會識別到期時間，等於或晚於此時間都不得接受 JWT 以進行處理。請參閱 RFC 7519，第 4.1.4 節。如此一來，判斷提示在此時間內都可使用，因此在 `nbf` 之後請保持簡短的 5-10 分鐘。 Microsoft Entra ID 目前沒有限制 `exp` 時間。
`iss`	{ClientID}	"iss" (簽發者) 宣告可識別發出 JWT 的主體，在此案例中是您的用戶端應用程式。使用 GUID 應用程式識別碼。
`jti`	(GUID)	"jti" (JWT 識別碼) 宣告會提供 JWT 的唯一識別碼。指派識別碼值的方式「必須」確保不會將相同的值不慎指派給不同的資料物件。如果應用程式使用多個簽發者，則「必須」防止不同簽發者所產生的值之間發生衝突。 "jti" 值是區分大小寫的字串。 RFC 7519，第 4.1.7 節
`nbf`	1601519114	"nbf" (生效時間) 宣告會識別生效時間，在此時間之前不得接受 JWT 以進行處理。 RFC 7519，第 4.1.5 節。使用目前時間是適當的選擇。
`sub`	{ClientID}	"sub" (主體) 宣告會識別 JWT 的主體，在此案例中也是您的應用程式。使用與 `iss` 相同的值。
`iat`	1601519114	"iat" (簽發時間) 宣告會識別發出 JWT 的時間。此宣告可用於判斷 JWT 的存留期。 RFC 7519，第 4.1.5 節。

簽章

簽章是使用 JSON Web 權杖 RFC7519 規格中所述的憑證計算的。使用 PSS 填補。

已解碼的 JWT 判斷提示範例

{
  "alg": "PS256",
  "typ": "JWT",
  "x5t#sha256": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
}
.
{
  "aud": "https: //login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/token",
  "exp": 1484593341,
  "iss": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "jti": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "nbf": 1484592741,
  "sub": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
}
.
"A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u..."

已編碼的 JWT 判斷提示範例

下列字串是已編碼判斷提示的範例。如果您仔細看，會發現三個以點 (.) 分隔的區段：(.)：

第一個區段編碼標頭
第二個區段編碼宣告 (承載)
最後一個區段則是使用前兩個區段的內容中包含的憑證計算出來的簽章

"eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJhdWQiOiJodHRwczpcL1wvbG9naW4ubWljcm9zb2Z0b25saW5lLmNvbVwvam1wcmlldXJob3RtYWlsLm9ubWljcm9zb2Z0LmNvbVwvb2F1dGgyXC90b2tlbiIsImV4cCI6MTQ4NDU5MzM0MSwiaXNzIjoiOTdlMGE1YjctZDc0NS00MGI2LTk0ZmUtNWY3N2QzNWM2ZTA1IiwianRpIjoiMjJiM2JiMjYtZTA0Ni00MmRmLTljOTYtNjVkYmQ3MmMxYzgxIiwibmJmIjoxNDg0NTkyNzQxLCJzdWIiOiI5N2UwYTViNy1kNzQ1LTQwYjYtOTRmZS01Zjc3ZDM1YzZlMDUifQ.
Gh95kHCOEGq5E_ArMBbDXhwKR577scxYaoJ1P{a lot of characters here}KKJDEg"

向 Microsoft 身分識別平台註冊憑證

您可使用以下任一種方法，透過 Microsoft Entra 系統管理中心在 Microsoft 身分識別平台中建立憑證認證與用戶端應用程式之間的關聯：

上傳憑證檔案

在用戶端應用程式的 [應用程式註冊] 索引標籤中：

選取 [憑證與祕密] > [憑證]。
選取 [上傳憑證]，然後選取要上傳的憑證檔案。
選取 [新增]。上傳憑證之後，會顯示指紋、開始日期和到期值。

更新應用程式資訊清單

取得憑證之後，請計算下列值：

$base64Thumbprint -Base64 編碼的憑證雜湊值
$base64Value - Base64 編碼的憑證未經處理資料值

提供 GUID 來識別應用程式資訊清單中的金鑰 ($keyId)。

在用戶端應用程式的 Azure 應用程式註冊中：

選取 [資訊清單]，以開啟應用程式資訊清單。

使用下列結構描述，將 keyCredentials 屬性取代為您新的憑證資訊。

"keyCredentials": [
    {
        "customKeyIdentifier": "$base64Thumbprint",
        "keyId": "$keyid",
        "type": "AsymmetricX509Cert",
        "usage": "Verify",
        "value":  "$base64Value"
    }
]

儲存對應用程式資訊清單所做的編輯，然後將資訊清單上傳到 Microsoft 身分識別平台。

keyCredentials 屬性是多重值，因此您可以上傳多個憑證以進行更豐富的金鑰管理。

使用用戶端判斷提示

用戶端判斷提示可以在使用用戶端密碼的任何地方使用。例如，在授權碼流程 (部分機器翻譯) 中，您可以傳入 client_secret，以證明要求是來自您的應用程式。您可以使用 client_assertion 和 client_assertion_type 參數來取代此參數。

參數	數值	Description
`client_assertion_type`	`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`	這是固定值，表示您使用的是憑證認證。
`client_assertion`	`JWT`	這是上面建立的 JWT。

下一步

MSAL.NET 程式庫會以一行程式碼處理此案例。

使用 GitHub 上 Microsoft 身分識別平台的 .NET 精靈主控台應用程式程式碼範例 (英文) 顯示應用程式如何使用自己的認證進行驗證。此外也說明如何使用 New-SelfSignedCertificate PowerShell Cmdlet 建立自我簽署憑證。您也可以使用範例存放庫中的應用程式建立指令碼來建立憑證、計算指紋，和執行其他作業。

共用方式為