Microsoft 身分識別平台和 OAuth 2.0 授權碼流程

OAuth 2.0 授權碼授與類型或驗證碼流程可讓用戶端應用程式取得受保護資源的授權存取權,例如 Web API。 驗證碼流程需要使用者代理程式,其可支援從授權伺服器 (Microsoft 身分識別平台) 重新導向至您的應用程式。 例如,由使用者操作的網頁瀏覽器、桌面或行動應用程式,以登入您的應用程式並存取其資料。

本文說明只有在手動製作和發出原始 HTTP 要求以執行流程時,才需要低階通訊協定詳細資料,我們建議這麼做。 相反地,請使用 Microsoft 建置且支援的驗證程式庫來取得安全性權杖,並在您的應用程式中呼叫受保護的 Web API。

支援驗證碼流程的應用程式

使用與「代碼交換的證明金鑰 (Proof Key for Code Exchange,PKCE)」和 OpenID Connect (OIDC) 配對的驗證碼流程,在這些類型的應用程式中取得存取權杖和識別碼權杖:

通訊協定詳細資料

如需 OAuth 2.0 授權碼流程的說明,請參閱 OAuth 2.0 規格的 4.1 節。 使用 OAuth 2.0 授權碼流程的應用程式會取得 access_token,以包含在受 Microsoft 身分識別平台保護的資源 (通常是 API) 的要求中。 應用程式也可以使用重新整理機制,為先前已驗證的實體要求新識別碼和存取權杖。

提示

嘗試在 Postman 中執行此要求
嘗試在 Postman 中執行此要求及其他操作 -- 別忘了取代權杖與識別碼!

此圖顯示驗證流程的高階檢視:

此圖顯示 OAuth 授權碼流程。本地應用程式和 Web API 使用權杖進行互動,如本文中所述。

單頁應用程式 (SPA) 的重新導向 URI

使用驗證碼流程的 SPA 的重新導向 URI 需要特殊設定。

spa 重新導向類型可與隱含流程回溯相容。 目前使用隱含流程來取得權杖的應用程式可移至 spa 重新導向 URI 類型,而不會發生問題,並可繼續使用隱含流程。

如果您嘗試使用授權碼流程,但未針對您的重新導向 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 端點。 在此要求中,用戶端會向使用者要求 openidoffline_accesshttps://graph.microsoft.com/mail.read 權限。

某些權限是由管理員限制,例如使用 Directory.ReadWrite.All 將資料寫入組織的目錄。 如果您的應用程式向組織使用者要求這其中一個權限的存取權,使用者將會收到錯誤訊息,指出他們未獲授權而無法對您應用程式的權限表示同意。 若要要求存取受管理員限制的範圍,您應該直接向全域管理員要求。 如需詳細資訊,請參閱管理員限制的權限

除非另有指定,否則選擇性參數沒有預設值。 不過,要求的預設行為會省略選擇性參數。 預設行為是登入唯一目前使用者,如果有多個使用者則顯示帳戶選擇器,如果沒有使用者登入則顯示登入頁面。

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&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

提示

選取下面的連結以執行此要求! 登入之後,您的瀏覽器應重新導向至在位址列中有 codehttp://localhost/myapp/https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

參數 必要條件/選擇性 描述
tenant 必要 要求路徑中的 {tenant} 值可用來控制可登入應用程式的人員。 有效值為 commonorganizationsconsumers 及租用戶識別碼。 針對您會將使用者從一個租用戶登入另一個租用戶的來賓案例,您必須提供租用戶識別碼,才能將其登入資源租用戶。 如需詳細資訊,請參閱端點
client_id required Azure 入口網站 - 應用程式註冊體驗指派給您應用程式的應用程式 (用戶端) 識別碼
response_type required 授權碼流程必須包含 code。 也可以包含 id_tokentoken (如果使用 混合式流程)。
redirect_uri 必要 應用程式的 redirect_uri,您的應用程式可以從中傳送及接收驗證回應。 其必須完全符合您在入口網站中註冊的其中一個重新導向 URI,否則就必須以 URL 編碼。 若為原生和行動應用程式,請使用其中一個建議值:https://login.microsoftonline.com/common/oauth2/nativeclient (適用於使用內嵌瀏覽器的應用程式),或 http://localhost (適用於使用系統瀏覽器的應用程式)。
scope required 您要使用者同意的 範圍 空格分隔清單。 針對要求的 /authorize 階段,此參數可以涵蓋多個資源。 此值可讓您的應用程式對想要呼叫的多個 Web API 取得同意。
response_mode 建議使用 指定身分識別平台如何將要求的權杖傳回您的應用程式。

支援的值:

- query:要求存取權杖時的預設值。 提供程式碼,以作為重新導向 URI 的查詢字串參數。 使用隱含流程來要求識別碼權杖時,不支援 query 參數。
- fragment:使用隱含流程要求識別碼權杖時的預設值。 要求程式碼則時也受到支援。
- form_post:會執行 POST,其中包含您重新導向 URI 的程式碼。 要求程式碼時受到支援。

state 建議使用 要求中包含的值,也會隨權杖回應傳回。 其可以是您想要之任何內容的字串。 隨機產生的唯一值通常用於 防止跨站台要求偽造攻擊。 在驗證要求出現之前,該值也會將應用程式中使用者狀態的相關資訊編碼。 例如,其可以對頁面或檢視進行編碼。
prompt 選用 表示必要的使用者互動類型。 有效值為 loginnoneconsentselect_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 身分識別平台同時支援 plainS256。 如需詳細資訊,請參閱 PKCE RFC。 此參數使用授權碼流程單頁應用程式所需的必要條件。

此時,系統會要求使用者輸入其認證並完成驗證。 Microsoft 身分識別平台也會確認使用者已經同意 scope 查詢參數所指出的權限。 如果使用者未曾同意這些權限的任何一項,就會要求使用者同意要求的權限。 如需詳細資訊,請參閱 Microsoft 身分識別平台中的權限和同意

一旦使用者驗證並同意,Microsoft 身分識別平台就會使用 response_mode 參數中指定的方法,將回應傳回至應用程式於指定的 redirect_uri 位置。

成功的回應

此範例顯示使用 response_mode=query 的成功回應:

GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
參數 Description
code 應用程式要求的 authorization_code。 應用程式可以使用授權碼來要求目標資源的存取權杖。 授權碼的存留期很短。 通常會在大約 10 分鐘後過期。
state 如果要求中包含 state 參數,則回應中應該會出現相同的值。 應用程式必須驗證要求與回應中的狀態值是否相同。

如果您要求一個識別碼權杖,並在您的應用程式註冊中啟用隱含授與,則您也可以接收識別碼權杖。 此行為有時稱為混合式流程。 這是由 ASP.NET 之類的架構所使用。

錯誤回應

錯誤回應可能也會傳送至 redirect_uri ,讓應用程式可以適當地處理:

GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication
參數 Description
error 可用於將錯誤分類的錯誤碼字串,並回應錯誤。 系統會提供錯誤的此部分,讓應用程式可以適當地回應錯誤,但不會深入說明發生錯誤的原因。
error_description 協助開發人員識別驗證錯誤原因的特定錯誤訊息。 錯誤的此部分包含有關為何發生錯誤的大部分實用資訊。

授權端點錯誤的錯誤碼

下表說明各種可能在錯誤回應的 error 參數中傳回的錯誤碼。

錯誤碼 描述 用戶端動作
invalid_request 通訊協定錯誤,例如遺漏必要的參數。 修正並重新提交要求。 此錯誤是通常會在初始測試期間擷取到的開發錯誤。
unauthorized_client 不允許用戶端應用程式要求授權碼。 這個錯誤通常會在用戶端應用程式未在 Azure AD 中註冊,或未加入至使用者的 Azure AD 租用戶時發生。 應用程式可以對使用者提示關於安裝應用程式,並將它加入至 Azure AD 的指示。
access_denied 資源擁有者拒絕同意 用戶端應用程式可以通知使用者除非使用者同意,否則其無法繼續進行。
unsupported_response_type 授權伺服器不支援要求中的回應類型。 修正並重新提交要求。 此錯誤是通常會在初始測試期間擷取到的開發錯誤。 在混合式流程中,此錯誤表示您必須啟用用戶端應用程式註冊上的識別碼權杖隱含授與設定。
server_error 伺服器發生非預期的錯誤。 重試要求。 這些錯誤可能是由暫時性狀況所引起。 用戶端應用程式可能會向使用者解釋其回應因暫時性錯誤而延遲。
temporarily_unavailable 伺服器暫時過於忙碌而無法處理要求。 重試要求。 用戶端應用程式可能會向使用者解釋其回應因暫時性狀況而延遲。
invalid_resource 目標資源無效,因為它不存在、Azure AD 無法找到它,或是它並未正確設定。 此錯誤表示尚未在租用戶中設定資源 (如果存在)。 應用程式可以對使用者提示關於安裝應用程式,並將它加入至 Azure AD 的指示。
login_required 找到太多使用者或找不到使用者。 用戶端已要求無訊息驗證 (prompt=none),但找不到單一使用者。 此錯誤可能表示工作階段中有多個作用中使用者,或沒有任何使用者。 此錯誤會將選擇的租用戶列入考慮。 例如,如果有兩個作用中的 Azure AD 帳戶和一個 Microsoft 帳戶,而且選擇了 consumers,則無訊息驗證可運作。
interaction_required 要求需要使用者互動。 必須進行其他驗證步驟或同意。 請在不使用 prompt=none 的情況下重試要求。

也要求識別碼權杖或混合式流程

若要在兌換授權碼之前了解使用者身分,應用程式通常應該在要求授權碼時,也要求識別碼權杖。 這種方法稱為混合式流程,因為混用隱含授與與授權碼流程。

混合式流程常用於讓 Web 應用程式轉譯使用者的頁面,而不會封鎖代碼兌換 (尤其是在 ASP.NET 中)。 單頁應用程式和傳統 Web 應用程式都受益於此模型的延遲降低優勢。

混合式流程與稍早所述的授權碼流程相同,但有三個新增項目。 需要這些新增項目才能要求識別碼權杖:新的範圍、新的 response_type,以及新的 nonce 查詢參數。

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&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 required 新增 id_token 會向伺服器表示應用程式在端點的回應 /authorize 中想要有識別碼權杖。
scope 必要 針對識別碼權杖,此參數必須更新以包含識別碼權杖範圍:openid 和選擇性的 profileemail
nonce 必要 包含在要求中的值 (由應用程式所產生),將會包含在所得的 id_token 中來做為宣告。 然後,應用程式可以驗證此值,以減輕權杖重新執行所造成的攻擊。 此值通常是隨機的唯一字串,可以用來識別要求的來源。
response_mode 建議使用 指定將產生的權杖送回到應用程式所應該使用的方法。 針對僅有授權碼的預設值是 query,但是如果要求包含 id_tokenresponse_type (如同在 OpenID 規格中所指定) 則為 fragment。建議應用程式使用 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
參數 Description
code 應用程式所要求的授權碼。 應用程式可以使用授權碼要求目標資源的存取權杖。 授權碼的有效期很短,通常約 10 分鐘後即到期。
id_token 使用者的識別碼權杖,使用隱含授與發出。 包含在相同要求中是 code 雜湊的特殊 c_hash 宣告。
state 如果要求中包含 state 參數,則回應中應該會出現相同的值。 應用程式必須驗證要求與回應中的狀態值是否相同。

兌換存取權杖的代碼

所有機密用戶端都可以選擇使用用戶端密碼或憑證認證。 對稱共用祕密是由 Microsoft 身分識別平台產生。 憑證認證是由開發人員所上傳的非對稱金鑰。 如需詳細資訊,請參閱 Microsoft 身分識別平台的應用程式驗證憑證認證

為了達到最佳安全性,建議您使用憑證認證。 公用用戶端 (包括原生應用程式和單頁應用程式) 在兌換授權碼時,不能使用祕密或憑證。 務必確定您的重新導向 URI 包含應用程式的類型,而且是唯一的

使用 client_secret 要求存取權杖

現在您已取得 authorization_code,並已獲得使用者授與的權限,您可以將 access_tokencode 兌換為資源。 將 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=6731de76-14a6-49ae-97bc-6eba6914391e
&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=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps. This secret needs to be URL-Encoded.
參數 必要條件/選擇性 描述
tenant 必要 要求路徑中的 {tenant} 值可用來控制可登入應用程式的人員。 有效值為 commonorganizationsconsumers 及租用戶識別碼。 如需詳細資訊,請參閱端點
client_id 必要 Azure 入口網站 - 應用程式註冊頁面指派給您應用程式的應用程式 (用戶端) 識別碼
scope 選用 以空格分隔的範圍清單。 範圍必須全部來自單一資源,以及 OIDC 範圍 (profileopenidemail)。 如需詳細資訊,請參閱 Microsoft 身分識別平台中的權限和同意。 此參數是授權碼流程的 Microsoft 擴充功能,目的是讓應用程式在權杖兌換期間宣告他們想要其權杖的資源。
code 必要 您在流程中第一個階段取得的 authorization_code
redirect_uri 必要 用來取得 authorization_code 的相同 redirect_uri 值。
grant_type required 必須是授權碼流程的 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 提供認證的基本驗證模式。

使用憑證認證來要求存取權杖

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&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} 值可用來控制可登入應用程式的人員。 有效值為 commonorganizationsconsumers 及租用戶識別碼。 如需詳細資訊,請參閱端點
client_id 必要 Azure 入口網站 - 應用程式註冊頁面指派給您應用程式的應用程式 (用戶端) 識別碼
scope 選用 以空格分隔的範圍清單。 範圍必須全部來自單一資源,以及 OIDC 範圍 (profileopenidemail)。 如需詳細資訊,請參閱權限、同意和範圍。 此參數是授權碼流程的 Microsoft 擴充功能。 此擴充功能可讓應用程式在權杖兌換期間宣告他們想要其權杖的資源。
code 必要 您在流程中第一個階段取得的 authorization_code
redirect_uri 必要 用來取得 authorization_code 的相同 redirect_uri 值。
grant_type required 必須是授權碼流程的 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_typeclient_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 指出權杖類型的值。 Azure AD 唯一支援的類型是 Bearer
expires_in 存取權杖的有效期 (以秒為單位)。
scope access_token 有效的範圍。 選擇性。 此參數是非標準參數,而且如果省略,則權杖會用於流程初始階段所要求的範圍。
refresh_token OAuth 2.0 重新整理權杖。 應用程式可以使用這個權杖,在目前的存取權杖過期之後,取得其他的存取權杖。 重新整理權杖是長期權杖。 他們可以在延長的期間內維護資源的存取權。 如需有關重新整理存取權杖的詳細資訊,請參閱本文稍後討論的重新整理存取權杖
注意:只在要求 offline_access 範圍時提供。
id_token JSON Web 權杖。 應用程式可以將此權杖的區段解碼,以索取已登入使用者的相關資訊。 應用程式可以快取這些值並加以顯示,而機密用戶端可以使用此權杖來進行授權。 如需有關 id_token 的詳細資訊,請參閱 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: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
參數 Description
error 可用於將錯誤分類的錯誤碼字串,並回應錯誤。
error_description 協助開發人員識別驗證錯誤原因的特定錯誤訊息。
error_codes 有助於診斷的 STS 特定錯誤碼清單。
timestamp 發生錯誤的時間。
trace_id 有助於診斷的要求唯一識別碼。
correlation_id 有助於跨元件診斷的要求唯一識別碼。

權杖端點錯誤的錯誤碼

錯誤碼 描述 用戶端動作
invalid_request 通訊協定錯誤,例如遺漏必要的參數。 修正要求或應用程式註冊,然後重新提交要求。
invalid_grant 授權碼或 PKCE 代碼驗證器無效或已過期。 嘗試向 /authorize 端點提出新的要求,並確認 code_verifier 參數正確。
unauthorized_client 未授權驗證用戶端使用此授權授與類型。 這個錯誤通常會在用戶端應用程式未在 Azure AD 中註冊,或未加入至使用者的 Azure AD 租用戶時發生。 應用程式可以對使用者提示關於安裝應用程式,並將它加入至 Azure AD 的指示。
invalid_client 用戶端驗證失敗。 用戶端認證無效。 若要修正,應用程式系統管理員必須更新認證。
unsupported_grant_type 授權伺服器不支援授權授與類型。 變更要求中的授與類型。 這種類型的錯誤應該只會在開發期間發生,並且會在初始測試期間偵測出來。
invalid_resource 目標資源無效,因為它不存在、Azure AD 無法找到它,或是它並未正確設定。 此代碼表示在資源存在的情況下,尚未在租用戶中加以設定。 應用程式可以對使用者提示關於安裝應用程式,並將它加入至 Azure AD 的指示。
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=535fb089-9ff3-47b6-9bfb-4f1264799865
&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} 值可用來控制可登入應用程式的人員。 有效值為 commonorganizationsconsumers 及租用戶識別碼。 如需詳細資訊,請參閱端點
client_id required Azure 入口網站 - 應用程式註冊體驗指派給您應用程式的應用程式 (用戶端) 識別碼
grant_type required 必須是授權碼流程此階段的 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 指出權杖類型的值。 Azure AD 唯一支援的類型是 Bearer。
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: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
參數 Description
error 可用於將錯誤分類的錯誤碼字串,並回應錯誤。
error_description 協助開發人員識別驗證錯誤根本原因的特定錯誤訊息。
error_codes 有助於診斷的 STS 特定錯誤碼清單。
timestamp 發生錯誤的時間。
trace_id 有助於診斷的要求唯一識別碼。
correlation_id 有助於跨元件診斷的要求唯一識別碼。

如需錯誤碼及建議的用戶端動作的說明,請參閱權杖端點錯誤的錯誤碼

後續步驟