OAuth 2.0 授權碼會授予使用者登入並取得授權權。 使用者透過瀏覽器登入,Microsoft Entra ID 會回傳一個短暫的授權碼,客戶端則在令牌端點兌換該碼。
代理程式 ID 解決方案可透過兩種方式使用授權:
| 用戶端類型 | 典型角色 | 客戶端憑證 | PKCE |
|---|---|---|---|
| 公共客戶端 | 本地代理程式會直接登入使用者。 | No | Required |
| 機密客戶 | 伺服器端網頁用戶端會在呼叫託管代理程式前登入使用者。 | Yes | Recommended |
使用 Microsoft 驗證資源庫 (MSAL) 或 Microsoft。直接使用 Identity.Web 而不是直接建立這些請求。 本文中的請求會顯示協議欄位供參考。
Warning
Microsoft 建議使用經核准的 SDK,例如 Microsoft.Identity.Web 和 Microsoft Entra ID Auth SDK(sidecar)程式庫,來實作這些通訊協定。 手動實施這些協定複雜且容易出錯,使用這些 SDK 有助於確保安全性與最佳實務的合規性。
Important
公用用戶端代理程式 ID 支援目前處於預覽階段。 此預覽版在沒有服務等級協議的情況下提供,不建議用於生產工作負載。 部分功能可能未被支援或功能受限。 欲了解更多資訊,請參閱 線上服務通用授權條款。
授權要求
兩種用戶端類型都會將使用者傳送至租戶的授權端點:
GET https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize?
client_id={client-id}
&response_type=code
&redirect_uri={encoded-redirect-uri}
&response_mode=query
&scope=openid%20profile%20offline_access%20api://{resource-client-id}/{scope}
&state={random-state}
&nonce={random-nonce}
&code_challenge={pkce-challenge}
&code_challenge_method=S256
-
client_id識別公開或機密客戶端。 基於 CIMD 的公開用戶端會使用其 HTTPS 中繼資料文件 URL 作為用戶端 ID。 -
redirect_uri必須完全匹配為用戶端設定的重新導向 URI。 -
scope包含用戶端所請求的委派權限。 當用戶端只需登入使用者時,請省略資源範圍。 -
state將回應綁定至啟動工作階段,並協助防止跨站請求偽造。 -
nonce將 OpenID Connect ID ID 令牌綁定到啟動工作階段。 -
code_challenge是利用 SHA-256 從高熵 PKCE 驗證器推導而來。
登入並取得同意後,Microsoft Entra ID 會將瀏覽器重新導向至已註冊的重新導向 URI:
GET {redirect-uri}?code={authorization-code}&state={state}
在兌換程式碼之前,請先驗證 state 並處理任何回傳到重新導向 URI 的 OAuth 錯誤。
公開用戶端令牌請求
公開用戶端無法保護用戶端憑證。 它會使用PKCE驗證器兌換代碼:
POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={agent-id-client-id-or-cimd-url}
&grant_type=authorization_code
&code={authorization-code}
&redirect_uri={redirect-uri}
&scope=openid profile offline_access api://{resource-client-id}/{scope}
&code_verifier={pkce-verifier}
請勿在此請求中傳送用戶端密鑰、憑證斷言或聯邦憑證。
註冊的公開用戶端代理程式 ID 必須使用 單一實例模式。 使用 用戶端 ID 元資料文件 的用戶端可以使用該文件的 HTTPS URL 作為用戶端 ID。 有關實作指引,請參閱 「從本機代理程式登入使用者」。
機密用戶端令牌請求
機密用戶端運行於可保護憑證的伺服器上。 授權碼是伺服器而非瀏覽器程式碼來兌換。 當授權請求使用 PKCE 時,請求包含用戶端憑證與 PKCE 驗證器:
POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={confidential-client-id}
&grant_type=authorization_code
&code={authorization-code}
&redirect_uri={redirect-uri}
&scope=openid profile offline_access api://{agent-blueprint-client-id}/{scope}
&code_verifier={pkce-verifier}
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion={signed-client-assertion}
範例使用憑證式用戶端斷言。 也支援用戶端密鑰,但盡可能使用憑證或工作負載身份聯盟。
在託管代理程式 ID 解決方案中,機密用戶端通常是上游的網頁應用程式,而非子代理程式 ID。 請求一個存取權杖,其受眾為託管代理程式的藍圖,將該存取權杖傳送至代理程式 API,並使用 On-Behalf-Of 流程 呼叫下游 API。
對於單一實例代理身份(預覽 <agent-blueprint-client-id> ),表示由藍圖與代理程式身份共用的用戶端 ID。 對於艦隊來說,它代表的是藍圖的客戶端 ID,而不是個別子代理的 ID。 在單一實例模式下,請透過 「在登入前授予上游用戶端存取 權」來設定上游用戶端的授權;瀏覽器同意不支援代理程式身份作為資源。
不要向託管代理 API 傳送授權碼或 ID 令牌。 機密用戶端模式中的子代理 ID 不會發起互動 /authorize 式請求。
權杖回應
如果請求成功,Microsoft Entra ID 會回傳如下的權杖:
{
"token_type": "Bearer",
"scope": "api://<resource-client-id>/<scope>",
"expires_in": 3599,
"access_token": "<access-token>",
"refresh_token": "<refresh-token>",
"id_token": "<id-token>"
}
具體回應取決於所要求的範圍:
- 僅對其
aud聲稱所識別的資源使用存取權杖。 - 使用 ID 權杖來建立使用者的登入會話,而非呼叫 API。
- 當請求與政策允許離線存取時,會回傳一個刷新權杖。
安全性需求
- 在公共用戶端使用 PKCE 搭配
S256challenge 方法。 當函式庫支援機密客戶端時,也請使用 PKCE。 - 在授權與令牌請求中,完全匹配重新導向 URI。
- 為每個授權請求產生新的
state、nonce及 PKCE 驗證器。 - 授權碼僅從發起請求的客戶端兌換一次,且僅限一次。
- 不要記錄授權碼、用戶端憑證、存取權杖、重新整理權杖或 ID 權杖。
- 驗證 API 中的存取權杖。 不要把擁有授權碼或 ID 令牌當作 API 授權。