OAuth 2.0 授權代碼授予

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 搭配 S256 challenge 方法。 當函式庫支援機密客戶端時,也請使用 PKCE。
  • 在授權與令牌請求中,完全匹配重新導向 URI。
  • 為每個授權請求產生新的 state、 nonce及 PKCE 驗證器。
  • 授權碼僅從發起請求的客戶端兌換一次,且僅限一次。
  • 不要記錄授權碼、用戶端憑證、存取權杖、重新整理權杖或 ID 權杖。
  • 驗證 API 中的存取權杖。 不要把擁有授權碼或 ID 令牌當作 API 授權。