Microsoft 身分識別平台和 OAuth 2.0 授權碼流程
OAuth 2.0 授權碼授與類型或驗證碼流程可讓用戶端應用程式取得受保護資源的授權存取權，例如 Web API。 驗證碼流程需要使用者代理程式，其可支援從授權伺服器 (Microsoft 身分識別平台) 重新導向至您的應用程式。 例如，由使用者操作的網頁瀏覽器、桌面或行動應用程式，以登入您的應用程式並存取其資料。
本文說明只有在手動製作和發行原始 HTTP 要求以執行流程時才需要的低階通訊協定詳細資料，但「不」建議這麼做。 相反地，請使用 Microsoft 建置且支援的驗證程式庫來取得安全性權杖，並在您的應用程式中呼叫受保護的 Web API。
支援驗證碼流程的應用程式
使用與「代碼交換的證明金鑰 (Proof Key for Code Exchange，PKCE)」和 OpenID Connect (OIDC) 配對的驗證碼流程，在這些類型的應用程式中取得存取權杖和識別碼權杖：
通訊協定詳細資料
如需 OAuthh 2.0 授權碼流程的說明，請參閱 OAuth 2.0 規格的第 4.1 節。 使用 OAuth 2.0 授權碼流程的應用程式會取得 access_token，以包含在受 Microsoft 身分識別平台保護的資源 (通常是 API) 的要求中。 應用程式也可以使用重新整理機制，為先前已驗證的實體要求新識別碼和存取權杖。
此圖顯示驗證流程的高階檢視：
單頁應用程式 (SPA) 的重新導向 URI
使用驗證碼流程的 SPA 的重新導向 URI 需要特殊設定。
- 新增重新導向 URI，其支援使用 PKCE 和跨原始來源資源分享 (CORS)：遵循重新導向 URI：具有驗證碼流程的 MSAL.js 2.0中的步驟。
- 更新重新導向 URI：使用 Microsoft Entra 系統管理中心內的應用程式資訊清單編輯器，將重新導向 URI 的
type設定為spa。
spa 重新導向類型可與隱含流程回溯相容。 目前使用隱含流程來取得權杖的應用程式可移至 spa 重新導向 URI 類型，而不會發生問題，並可繼續使用隱含流程。 儘管有這種回溯相容性，但建議您搭配 PKCE for SPA 使用驗證碼流程。
如果您嘗試使用授權碼流程，但未針對您的重新導向 URI 設定 CORS，則將會在主控台中看到此錯誤：
access to XMLHttpRequest at 'https://login.microsoftonline.com/common/v2.0/oauth2/token' from origin 'yourApp.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
若是如此，您必須造訪您的應用程式註冊，並將應用程式的重新導向 URI 更新為使用 spa 類型。
應用程式無法使用搭配非 SPA 流程的 spa 重新導向 URI，例如原生應用程式或用戶端認證流程。 為了確保安全性和最佳做法，如果您嘗試使用不含 Origin 標頭的 spa 重新導向 URI，則 Microsoft 身分識別平台會傳回錯誤。 同樣地，Microsoft 身分識別平台也會在 Origin 標頭存在時，避免在所有流程中使用用戶端認證，以確保不會在瀏覽器中使用祕密。
要求授權碼
授權碼流程始於用戶端將使用者導向 /authorize 端點。 在此範例要求中，用戶端會向使用者要求 openid、offline_access 和 https://graph.microsoft.com/mail.read 權限。
某些權限是由管理員限制，例如使用 Directory.ReadWrite.All 將資料寫入組織的目錄。 如果應用程式向組織使用者要求存取其中一個權限，使用者會收到錯誤訊息，指出他們無權同意應用程式權限。 若要要求存取受管理員限制的範圍，您應該直接向全域管理員要求。 如需詳細資訊，請參閱管理員限制的權限。
除非另有指定，否則選擇性參數沒有預設值。 不過，要求的預設行為會省略選擇性參數。 預設行為是登入唯一目前使用者，如果有多個使用者則顯示帳戶選擇器，如果沒有使用者登入則顯示登入頁面。
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
| 參數 | 必要條件/選擇性 | 描述 |
|---|---|---|
tenant |
必要 | 要求路徑中的 {tenant} 值可用來控制可登入應用程式的人員。 有效值為 common、organizations、consumers 及租用戶識別碼。 針對您會將使用者從一個租用戶登入另一個租用戶的來賓案例，您必須提供租用戶識別碼，才能將其登入資源租用戶。 如需詳細資訊，請參閱端點。 |
client_id |
必要 | Microsoft Entra 系統管理中心 - 應用程式註冊體驗指派給您應用程式的「應用程式 (用戶端) 識別碼」。 |
response_type |
必要 | 授權碼流程必須包含 code。 也可以包含 id_token 或 token (如果使用 混合式流程)。 |
redirect_uri |
必要 | 應用程式的 redirect_uri，您的應用程式可以從中傳送及接收驗證回應。 其必須完全符合您在 Microsoft Entra 系統管理中心內所註冊的其中一個重新導向 URI，但必須進行 URL 編碼。 若為原生和行動應用程式，請使用其中一個建議值：https://login.microsoftonline.com/common/oauth2/nativeclient (適用於使用內嵌瀏覽器的應用程式)，或 http://localhost (適用於使用系統瀏覽器的應用程式)。 |
scope |
必要 | 您要使用者同意的 範圍 空格分隔清單。 針對要求的 /authorize 階段，此參數可以涵蓋多個資源。 此值可讓您的應用程式對想要呼叫的多個 Web API 取得同意。 |
response_mode |
建議使用 | 指定身分識別平台如何將要求的權杖傳回您的應用程式。 支援的值： - query：要求存取權杖時的預設值。 提供程式碼，以作為重新導向 URI 的查詢字串參數。 使用隱含流程來要求識別碼權杖時，不支援 query 參數。 - fragment：使用隱含流程來要求識別碼權杖時的預設值。 只要求程式碼則時也受到支援。- form_post：執行 POST，其中包含您重新導向 URI 的程式碼。 要求程式碼時受到支援。 |
state |
建議使用 | 要求中包含的值，也會隨權杖回應傳回。 其可以是任何內容的字串。 隨機產生的唯一值通常用於 防止跨站台要求偽造攻擊。 在驗證要求出現之前，該值也會將應用程式中使用者狀態的相關資訊編碼。 例如，其可以對頁面或檢視進行編碼。 |
prompt |
選用 | 表示必要的使用者互動類型。 有效值為 login、none、consent 和 select_account。- prompt=login 會強制使用者在該要求上輸入其認證，而不要進行單一登入。- prompt=none 則相反。 其會確保無論如何都不會對使用者顯示任何互動式提示。 如果無法透使用過單一登入以無訊息方式完成要求，Microsoft 身分識別平台就會傳回 interaction_required 錯誤。- prompt=consent 會在使用者登入之後觸發 OAuth 同意對話方塊，要求使用者將權限授與應用程式。- prompt=select_account 會中斷單一登入，其中會提供列出工作階段或任何已記住帳戶中所有帳戶的帳戶選取體驗，或提供選擇使用不同帳戶的選項。 |
login_hint |
選用 | 您可以使用此參數為使用者預先填入登入頁面的使用者名稱和電子郵件地址欄位。 應用程式可以在重新驗證期間使用此參數，在已從先前的登入擷取login_hint選擇性宣告之後。 |
domain_hint |
選用 | 如果包含，應用程式會略過使用者在登入頁面上所經歷以電子郵件為基礎的探索程序，進而提供略為更有效率的使用者體驗。 例如，將其傳送到其同盟身分識別提供者。 在重新驗證期間，應用程式可以藉由擷取上一次登入的 tid來使用此參數。 |
code_challenge |
建議 / 必要 | 用來使用「代碼交換的證明金鑰 (PKCE)」保護授權碼授與。 如果包含 code_challenge_method，則此為必要參數。 如需詳細資訊，請參閱 PKCE RFC。 此參數現在建議用於所有的應用程式類型 (公用和機密用戶端)，且 Microsoft 身分識別平台需要此參數來讓單頁應用程式使用授權碼流程。 |
code_challenge_method |
建議 / 必要 | 用來為 code_challenge 參數編碼 code_verifier 的方法。 這應該為 S256，但如果用戶端無法支援 SHA256，則規格允許使用 plain。 如果排除，則當包含 code_challenge 時，會假設 code_challenge 是純文字。 Microsoft 身分識別平台同時支援 plain 和 S256。 如需詳細資訊，請參閱 PKCE RFC。 此參數使用授權碼流程單頁應用程式所需的必要條件。 |
此時，系統會要求使用者輸入其認證並完成驗證。 Microsoft 身分識別平台也會確認使用者已經同意 scope 查詢參數所指出的權限。 如果使用者未曾同意這些權限的任何一項，就會要求使用者同意要求的權限。 如需詳細資訊，請參閱 Microsoft 身分識別平台中的權限和同意。
一旦使用者驗證並同意，Microsoft 身分識別平台就會使用 response_mode 參數中指定的方法，將回應傳回至應用程式於指定的 redirect_uri 位置。
成功回應
此範例顯示使用 response_mode=query 的成功回應：
GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
| 參數 | 描述 |
|---|---|
code |
應用程式要求的 authorization_code。 應用程式可以使用授權碼來要求目標資源的存取權杖。 授權碼的存留期很短。 通常會在大約 10 分鐘後過期。 |
state |
如果要求中包含 state 參數，則回應中應該會出現相同的值。 應用程式必須確認要求與回覆中的狀態值完全相同。 |
如果您要求一個識別碼權杖，並在您的應用程式註冊中啟用隱含授與，則您也可以接收識別碼權杖。 此行為有時稱為混合式流程。 這是由 ASP.NET 之類的架構所使用。
回覆錯誤
錯誤回應可能也會傳送至 redirect_uri ，讓應用程式可以適當地處理：
GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication
| 參數 | 描述 |
|---|---|
error |
可用於將錯誤分類的錯誤碼字串，並回應錯誤。 系統會提供錯誤的這個部分，讓應用程式可以適當地回應錯誤，但不會深入說明發生錯誤的原因。 |
error_description |
協助開發人員識別驗證錯誤原因的特定錯誤訊息。 錯誤的此部分包含有關為何發生錯誤的大部分實用資訊。 |
授權端點錯誤的錯誤碼
下表說明各種可能在錯誤回應的 error 參數中傳回的錯誤碼。
| 錯誤碼 | 描述 | 用戶端動作 |
|---|---|---|
invalid_request |
通訊協定錯誤，例如遺漏必要的參數。 | 修正並重新提交要求。 此錯誤是通常會在初始測試期間擷取到的開發錯誤。 |
unauthorized_client |
不允許用戶端應用程式要求授權碼。 | 此錯誤通常發生在用戶端應用程式未在 Microsoft Entra ID 中進行註冊時，或未新增至使用者的 Microsoft Entra 租用戶時。 應用程式可以對使用者提示關於安裝應用程式並其新增至 Microsoft Entra ID 的指示。 |
access_denied |
資源擁有者拒絕同意 | 用戶端應用程式可以通知使用者除非使用者同意，否則其無法繼續進行。 |
unsupported_response_type |
授權伺服器不支援要求中的回應類型。 | 修正並重新提交要求。 此錯誤是通常會在初始測試期間擷取到的開發錯誤。 在混合式流程中，此錯誤表示您必須啟用用戶端應用程式註冊上的識別碼權杖隱含授與設定。 |
server_error |
伺服器發生非預期的錯誤。 | 重試要求。 這些錯誤可能是由暫時性狀況所引起。 用戶端應用程式可能會向使用者解釋其回應因暫時性錯誤而延遲。 |
temporarily_unavailable |
伺服器暫時過於忙碌而無法處理要求。 | 重試要求。 用戶端應用程式可能會向使用者解釋其回應因暫時性狀況而延遲。 |
invalid_resource |
目標資源因不存在、Microsoft Entra ID 找不到或未正確設定而無效。 | 此錯誤表示尚未在租用戶中設定資源 (如果存在)。 應用程式可以對使用者提示關於安裝應用程式並其新增至 Microsoft Entra ID 的指示。 |
login_required |
找到太多使用者或找不到使用者。 | 用戶端已要求無訊息驗證 (prompt=none)，但找不到單一使用者。 此錯誤可能表示工作階段中有多個作用中使用者，或沒有任何使用者。 此錯誤會將選擇的租用戶列入考慮。 例如，如果有兩個使用中的 Microsoft Entra 帳戶和一個 Microsoft 帳戶，並且選擇 consumers，無訊息驗證即可運作。 |
interaction_required |
要求需要使用者互動。 | 必須進行其他驗證步驟或同意。 請在不使用 prompt=none 的情況下重試要求。 |
也要求識別碼權杖或混合式流程
若要在兌換授權碼之前了解使用者身分，應用程式通常應該在要求授權碼時，也要求識別碼權杖。 此方式稱為「混合式流程」，因為其混合使用 OIDC 與 OAuth2 授權碼流程。
混合式流程常用於讓 Web 應用程式轉譯使用者的頁面，而不會封鎖代碼兌換 (尤其是在 ASP.NET 中)。 單頁應用程式和傳統 Web 應用程式都受益於此模型的延遲降低優勢。
混合式流程與稍早所述的授權碼流程相同，但有三個新增項目。 需要這些新增項目才能要求識別碼權杖：新的範圍、新的 response_type，以及新的 nonce 查詢參數。
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code%20id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=fragment
&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&state=12345
&nonce=abcde
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
| 更新的參數 | 必要條件/選擇性 | 描述 |
|---|---|---|
response_type |
必要 | 新增 id_token 會向伺服器表示應用程式在端點的回應 /authorize 中想要有識別碼權杖。 |
scope |
必要 | 針對識別碼權杖，此參數必須更新以包含識別碼權杖範圍：openid 和選擇性的 profile 與 email。 |
nonce |
必要 | 包含在要求中的值 (由應用程式所產生)，將會包含在所得的 id_token 中來做為宣告。 然後，應用程式可以驗證此值，以減輕權杖重新執行所造成的攻擊。 此值通常是隨機的唯一字串，可以用來識別要求的來源。 |
response_mode |
建議使用 | 指定應該用來將所產生權杖傳回給應用程式的方法。 預設值query只針對授權碼，但如果fragment要求包含 id_token response_type OpenID 規格中指定的 。我們建議應用程式使用 form_post，特別是在使用 http://localhost 作為重新導向 URI 時。 |
使用 fragment 作為回應模式，會導致從重新導向讀取代碼的 Web 應用程式發生問題。 瀏覽器不會將片段傳遞給 Web 伺服器。 在這些情況下，應用程式應該使用 form_post 回應模式，以確保所有資料都會傳送至伺服器。
成功回應
此範例顯示使用 response_mode=fragment 的成功回應：
GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345
| 參數 | 描述 |
|---|---|
code |
應用程式所要求的授權碼。 應用程式可以使用授權碼來要求目標資源的存取權杖。 授權碼的有效期很短，通常約 10 分鐘後即到期。 |
id_token |
使用者的識別碼權杖，使用隱含授與發出。 包含在相同要求中是 code 雜湊的特殊 c_hash 宣告。 |
state |
如果要求中包含 state 參數，則回應中應該會出現相同的值。 應用程式必須確認要求與回覆中的狀態值完全相同。 |
兌換存取權杖的代碼
所有機密用戶端都可以選擇使用用戶端密碼或憑證認證。 對稱共用祕密是由 Microsoft 身分識別平台產生。 憑證認證是由開發人員所上傳的非對稱金鑰。 如需詳細資訊，請參閱 Microsoft 身分識別平台的應用程式驗證憑證認證。
為了達到最佳安全性，建議您使用憑證認證。 公用用戶端 (包括原生應用程式和單頁應用程式) 在兌換授權碼時，不能使用祕密或憑證。 務必確定您的重新導向 URI 包含應用程式的類型，而且是唯一的。
使用 client_secret 要求存取權杖
現在您已取得 authorization_code，並已獲得使用者授與的權限，您可以將 access_token 的 code 兌換為資源。 將 POST 要求傳送給 /token 端點，即可兌換 code：
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=11112222-bbbb-3333-cccc-4444dddd5555
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded.
| 參數 | 必要條件/選擇性 | 描述 |
|---|---|---|
tenant |
必要 | 要求路徑中的 {tenant} 值可用來控制可登入應用程式的人員。 有效值為 common、organizations、consumers 及租用戶識別碼。 如需詳細資訊，請參閱端點。 |
client_id |
必要 | Microsoft Entra 系統管理中心 - 應用程式註冊頁面指派給您應用程式的「應用程式 (用戶端) 識別碼」。 |
scope |
選用 | 以空格分隔的範圍清單。 範圍必須全部來自單一資源，以及 OIDC 範圍 (profile、openid、email)。 如需詳細資訊，請參閱 Microsoft 身分識別平台中的權限和同意。 此參數是授權碼流程的 Microsoft 擴充功能，目的是讓應用程式在權杖兌換期間宣告他們想要其權杖的資源。 |
code |
必要 | 您在流程中第一個階段取得的 authorization_code。 |
redirect_uri |
必要 | 用來取得 authorization_code 的相同 redirect_uri 值。 |
grant_type |
必要 | 必須是用於授權碼流程的 authorization_code。 |
code_verifier |
建議使用 | 用來取得 authorization_code 的相同 code_verifier。 如果在授權碼授與要求中使用 PKCE，則此為必要參數。 如需詳細資訊，請參閱 PKCE RFC。 |
client_secret |
機密 Web 應用程式所需 | 您在您應用程式的應用程式註冊入口網站中建立的應用程式密碼。 請勿在原生應用程式或單頁應用程式中使用應用程式密碼，因為 client_secret 無法可靠地儲存在裝置或網頁上。 Web Apps 和 Web API 都需要應用程式密碼，其能夠將 client_secret 安全地儲存在伺服器端。 如同這裡的所有參數，用戶端密碼必須先以 URL 編碼，才能傳送。 此步驟是透過 SDK 所完成。 如需有關 URI 編碼的詳細資訊，請參閱 URI 一般語法規格。 在授權標頭中，也支援根據 RFC 6749 提供認證的基本驗證模式。 |
使用憑證認證來要求存取權杖
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
| 參數 | 必要條件/選擇性 | 描述 |
|---|---|---|
tenant |
必要 | 要求路徑中的 {tenant} 值可用來控制可登入應用程式的人員。 有效值為 common、organizations、consumers 及租用戶識別碼。 如需詳細資訊，請參閱端點。 |
client_id |
必要 | Microsoft Entra 系統管理中心 - 應用程式註冊頁面指派給您應用程式的「應用程式 (用戶端) 識別碼」。 |
scope |
選用 | 以空格分隔的範圍清單。 範圍必須全部來自單一資源，以及 OIDC 範圍 (profile、openid、email)。 如需詳細資訊，請參閱權限、同意和範圍。 此參數是授權碼流程的 Microsoft 擴充功能。 此擴充功能可讓應用程式在權杖兌換期間宣告他們想要其權杖的資源。 |
code |
必要 | 您在流程中第一個階段取得的 authorization_code。 |
redirect_uri |
必要 | 用來取得 authorization_code 的相同 redirect_uri 值。 |
grant_type |
必要 | 必須是用於授權碼流程的 authorization_code。 |
code_verifier |
建議使用 | 用來取得 authorization_code 的相同 code_verifier。 如果在授權碼授與要求中使用 PKCE，則此為必要參數。 如需詳細資訊，請參閱 PKCE RFC。 |
client_assertion_type |
機密 Web 應用程式所需 | 此值必須設定為 urn:ietf:params:oauth:client-assertion-type:jwt-bearer，才能使用憑證認證。 |
client_assertion |
機密 Web 應用程式所需 | 您必須建立判斷提示 (也就是 JSON Web 權杖 (JWT))，並使用註冊的憑證來簽署，以作為應用程式的認證。 請參閱憑證認證，以了解如何註冊您的憑證與判斷提示的格式。 |
參數與共用祕密的要求相同，唯一的不同之處在於 client_secret 參數會被下列兩個參數取代：client_assertion_type 和 client_assertion。
成功回應
此範例顯示成功的權杖回應：
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
| 參數 | 描述 |
|---|---|
access_token |
要求的存取權杖。 應用程式可以使用此權杖來對受保護的資源 (例如 Web API) 進行驗證。 |
token_type |
指出權杖類型的值。 Microsoft Entra ID 唯一支援的類型是 Bearer。 |
expires_in |
存取權杖的有效期 (以秒為單位)。 |
scope |
access_token 有效的範圍。 選擇性。 此參數是非標準參數，而且如果省略，則權杖會用於流程初始階段所要求的範圍。 |
refresh_token |
OAuth 2.0 重新整理權杖。 應用程式可以使用這個權杖，在目前的存取權杖過期之後，取得其他的存取權杖。 重新整理權杖會長期存在。 他們可以在延長的期間內維護資源的存取權。 如需有關重新整理存取權杖的詳細資訊，請參閱本文稍後討論的重新整理存取權杖。 注意：只在要求 offline_access 範圍時提供。 |
id_token |
JSON Web 權杖。 應用程式可以將此權杖的區段解碼，以索取已登入使用者的相關資訊。 應用程式可以快取這些值並加以顯示，而機密用戶端可以使用此權杖來進行授權。 如需 id_tokens 的詳細資訊，請參閱 id_token reference。 注意：只在要求 openid 範圍時提供。 |
回覆錯誤
此範例為錯誤回應：
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| 參數 | 描述 |
|---|---|
error |
可用於將錯誤分類的錯誤碼字串，並回應錯誤。 |
error_description |
協助開發人員識別驗證錯誤原因的特定錯誤訊息。 |
error_codes |
有助於診斷的 STS 特定錯誤碼清單。 |
timestamp |
發生錯誤的時間。 |
trace_id |
有助於診斷的要求唯一識別碼。 |
correlation_id |
有助於跨元件診斷的要求唯一識別碼。 |
權杖端點錯誤的錯誤碼
| 錯誤碼 | 描述 | 用戶端動作 |
|---|---|---|
invalid_request |
通訊協定錯誤，例如遺漏必要的參數。 | 修正要求或應用程式註冊，然後重新提交要求。 |
invalid_grant |
授權碼或 PKCE 代碼驗證器無效或已過期。 | 嘗試向 /authorize 端點提出新的要求，並確認 code_verifier 參數正確。 |
unauthorized_client |
未授權驗證用戶端使用此授權授與類型。 | 此錯誤通常發生在用戶端應用程式未在 Microsoft Entra ID 中進行註冊時，或未新增至使用者的 Microsoft Entra 租用戶時。 應用程式可以對使用者提示關於安裝應用程式並其新增至 Microsoft Entra ID 的指示。 |
invalid_client |
用戶端驗證失敗。 | 用戶端認證無效。 若要修正，應用程式系統管理員會更新認證。 |
unsupported_grant_type |
授權伺服器不支援授權授與類型。 | 變更要求中的授與類型。 這種類型的錯誤應該只會在開發期間發生，並且會在初始測試期間偵測出來。 |
invalid_resource |
目標資源因不存在、Microsoft Entra ID 找不到或未正確設定而無效。 | 此代碼表示在資源存在的情況下，尚未在租用戶中加以設定。 應用程式可以對使用者提示關於安裝應用程式並其新增至 Microsoft Entra ID 的指示。 |
interaction_required |
非標準，因為 OIDC 規格只會在 /authorize 端點上呼叫此代碼。 要求需要使用者互動。 例如，必須進行另一個驗證步驟。 |
以相同範圍重試 /authorize 要求。 |
temporarily_unavailable |
伺服器暫時過於忙碌而無法處理要求。 | 在短暫延遲後重試要求。 用戶端應用程式可能會向使用者解釋其回應因暫時性狀況而延遲。 |
consent_required |
要求需要使用者同意。 此錯誤為非標準錯誤。 通常只會在每個 OIDC 規格的 /authorize 端點上傳回。 當用戶端應用程式沒有權限要求的程式碼兌換流程上使用 scope 參數時傳回。 |
用戶端應將使用者傳回 /authorize 具有正確範圍的端點，以觸發同意。 |
invalid_scope |
應用程式所要求的範圍無效。 | 將驗證要求中的 scope 參數值更新為有效的值。 |
注意
單頁應用程式可能會收到 invalid_request 錯誤，指出只允許「單頁應用程式」用戶端類型的跨原始來源權杖兌換。 這表示用來要求權杖的重新導向 URI 尚未標示為 spa 重新導向 URI。 關於如何啟用此流程，請參閱應用程式註冊步驟。
使用存取權杖
既然您已成功取得 access_token，就可以在 Authorization 標頭中包括權杖，以在對 Web API 的要求中使用權杖：
GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
重新整理存取權杖
存取權杖只會短暫存在。 到期後需重新整理，才能繼續存取資源。 方法是向 /token 端點送出另一個 POST 要求， 提供 refresh_token，而不是 code。 重新整理權杖適用於您用戶端已收到其同意的所有權限。 例如，針對 scope=mail.read 要求發出的重新整理權杖可以用來要求 scope=api://contoso.com/api/UseResource 的新存取權杖。
Web 應用程式和原生應用程式的重新整理權杖未指定存留期。 一般而言，重新整理權杖的存留期相對較長。 不過，在某些情況下，重新整理權杖會過期、遭到撤銷或對動作缺乏足夠的權限。 應用程式必須預期並處理權杖發行端點所傳回的錯誤。 單頁應用程式會取得具有 24小 時存留期的權杖，每日需要新的驗證。 當第三方 Cookie 啟用時，此動作可以在 iframe 中以無訊息方式完成。 其必須在沒有第三方 Cookie 的瀏覽器 (例如 Safari) 中的最上層框架 (完整頁面瀏覽或快顯視窗) 中執行。
使用重新整理權杖來取得新存取權杖時，並不會撤銷該重新整理權杖。 您應捨棄舊的重新整理權杖。 OAuth 2.0 規格指出：授權伺服器「可能」會發行新的重新整理權杖，在此情況下，用戶端「必須」捨棄舊的重新整理權杖，並將其取代為新的重新整理權杖。 授權伺服器「可能」會在對用戶端發出新的重新整理權杖之後，撤銷舊的重新整理權杖。」
重要
針對向註冊為 spa 的重新導向 URI 傳送的重新整理權杖，重新整理權杖會在 24 小時後到期。 使用初始重新整理權杖取得的其他重新整理權杖將會延續到該到期時間，因此應用程式必須準備好使用互動式驗證來重新執行授權碼流程，以每隔 24 小時取得新的重新整理權杖。 使用者不需要輸入其認證，而且通常甚至不會看到任何使用者體驗，只要重新載入應用程式即可。 瀏覽器必須造訪最上層框架中的登入頁面，才能看到登入工作階段。 這是因為瀏覽器的隱私權功能封鎖第三方 Cookie。
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded
| 參數 | 類型 | 描述 |
|---|---|---|
tenant |
必要 | 要求路徑中的 {tenant} 值可用來控制可登入應用程式的人員。 有效值為 common、organizations、consumers 及租用戶識別碼。 如需詳細資訊，請參閱端點。 |
client_id |
必要 | Microsoft Entra 系統管理中心 - 應用程式註冊體驗指派給您應用程式的「應用程式 (用戶端) 識別碼」。 |
grant_type |
必要 | 必須是用於此授權碼流程階段的 refresh_token。 |
scope |
選用 | 以空格分隔的範圍清單。 在此階段中要求的範圍必須相當於或為原始 authorization_code 要求階段所要求的範圍子集。 如果這個要求中指定的範圍遍及多個資源伺服器，Microsoft 身分識別平台就會傳回第一個範圍中所指定資源的權杖。 如需詳細資訊，請參閱 Microsoft 身分識別平台中的權限和同意。 |
refresh_token |
必要 | 您在流程中第二個階段取得的 refresh_token。 |
client_secret |
Web 應用程式的必要參數 | 您在您應用程式的應用程式註冊入口網站中建立的應用程式密碼。 此參數不應用於原生應用程式中，因為 client_secret 無法可靠地儲存在裝置上。 Web Apps 和 Web API 都需要應用程式密碼，其能夠將 client_secret 安全地儲存在伺服器端。 此密碼必須經過 URL 編碼。 如需詳細資訊，請參閱 URI 一般語法規格。 |
成功回應
此範例顯示成功的權杖回應：
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
| 參數 | 描述 |
|---|---|
access_token |
要求的存取權杖。 應用程式可以使用此權杖來對受保護的資源 (例如 Web API) 進行驗證。 |
token_type |
指出權杖類型的值。 Microsoft Entra ID 唯一支援的類型是持有人權杖。 |
expires_in |
存取權杖的有效期 (以秒為單位)。 |
scope |
access_token 有效的範圍。 |
refresh_token |
新的 OAuth 2.0 重新整理權杖。 請用新取得的重新整理權杖取代舊的重新整理權杖，以確定盡可能保持重新整理權杖有效的時間。 注意：只在要求 offline_access 範圍時提供。 |
id_token |
未簽署的 JSON Web Token。 應用程式可以將此權杖的區段解碼，以索取已登入使用者的相關資訊。 應用程式可以快取並顯示值，但不應依賴這些值來取得任何授權或安全性界限。 如需有關 id_token 的詳細資訊，請參閱 Microsoft 身分識別平台識別碼權杖。 注意：只在要求 openid 範圍時提供。 |
警告
請勿在程式碼中，嘗試驗證或讀取任何您未擁有的 API 的權杖 (包括此範例中的權杖)。 Microsoft 服務的權杖可以使用不會驗證為 JWT 的特殊格式，且可能為取用者 (Microsoft 帳戶) 使用者進行加密。 雖然讀取權杖是很實用的偵錯與學習工具，但請勿在程式碼中依賴此功能的相依性，或是假設並非用於您所控制 API 的權杖相關內容。
回覆錯誤
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| 參數 | 描述 |
|---|---|
error |
可用於將錯誤分類的錯誤碼字串，並回應錯誤。 |
error_description |
協助開發人員識別驗證錯誤根本原因的特定錯誤訊息。 |
error_codes |
有助於診斷的 STS 特定錯誤碼清單。 |
timestamp |
發生錯誤的時間。 |
trace_id |
有助於診斷的要求唯一識別碼。 |
correlation_id |
有助於跨元件診斷的要求唯一識別碼。 |
如需錯誤碼及建議的用戶端動作的說明，請參閱權杖端點錯誤的錯誤碼。
下一步
- 瀏覽所有 MSAL JS 範例以開始撰寫程式碼。
- 了解權杖交換案例。