Microsoft 身分識別平台和 OAuth 2.0 授權碼流程
OAuth 2.0 授權碼授與類型或 驗證碼流程可讓用戶端應用程式取得 Web API 等受保護資源的授權存取權。 驗證碼流程需要支援從授權伺服器 （Microsoft 身分識別平台） 重新導向到應用程式的使用者代理程式。 例如，由使用者操作的網頁瀏覽器、桌面或行動應用程式，以登入您的應用程式並存取其數據。
本文說明只有在手動製作和發出原始 HTTP 要求以執行流程時，才需要低階通訊協定詳細數據，不建議這麼做。 請改用 Microsoft 建置且支援的驗證連結庫 來取得安全性令牌，並在您的應用程式中呼叫受保護的 Web API。
支援驗證碼流程的應用程式
使用與程式代碼交換證明密鑰 （PKCE） 和 OpenID 連線 （OIDC） 配對的驗證碼流程，在下列類型的應用程式中取得存取令牌和識別碼令牌：
通訊協議詳細數據
如需 OAuthh 2.0 授權碼流程的說明，請參閱 OAuth 2.0 規格的第 4.1 節。 使用 OAuth 2.0 授權碼流程的應用程式會取得 ，access_token以包含在 Microsoft 身分識別平台 所保護之資源的要求中（通常是 API）。 應用程式也可以使用重新整理機制，為先前驗證的實體要求新的標識符和存取令牌。
下圖顯示驗證流程的高階檢視：
單頁應用程式 (SPA) 的重新導向 URI
使用驗證碼流程之 SPA 的重新導向 URI 需要特殊設定。
- 新增支援使用 PKCE 和跨原始來源資源分享的驗證碼流程的重新導向 URI：遵循重新導向 URI：使用驗證碼流程MSAL.js 2.0 中的步驟。
- 更新重新導向 URI：使用 Microsoft Entra 系統管理中心的應用程式指令清單編輯器，將重新導向 URI
typespa設定為 。
重新 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，例如原生應用程式或客戶端認證流程。 為了確保安全性和最佳做法，如果您嘗試使用spa沒有Origin標頭的重新導向 URI，Microsoft 身分識別平台 會傳回錯誤。 同樣地，Microsoft 身分識別平台 也會防止在標頭存在Origin的所有流程中使用客戶端認證，以確保不會在瀏覽器中使用秘密。
要求授權碼
授權碼流程從將用戶導向端點的 /authorize 客戶端開始。 在此要求中，用戶端會向使用者要求 openid、 offline_access和 https://graph.microsoft.com/mail.read 許可權。
某些許可權受到系統管理員限制，例如，使用 Directory.ReadWrite.All將數據寫入組織的目錄。 如果應用程式向組織使用者要求存取其中一個權限，使用者會收到錯誤訊息，指出他們無權同意應用程式權限。 若要要求存取受系統管理員限制的範圍，您應該直接從全域 管理員 istrator 要求它們。 如需詳細資訊，請參閱 管理員 限制的許可權。
除非另有指定，否則選擇性參數沒有預設值。 不過，要求省略選擇性參數的默認行為。 默認行為是登入唯一的目前使用者、如果有多個使用者，則顯示帳戶選擇器，如果沒有任何使用者登入，則顯示登入頁面。
// 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_verifier 的方法 code_challenge 。 這 應該是S256，但如果用戶端不支援SHA256，則此規格允許使用 plain 。 如果排除， code_challenge 則假設為純文本，如果 code_challenge 包含的話。 Microsoft 身分識別平台 同時plain支援 和 S256。 如需詳細資訊，請參閱 PKCE RFC。 使用授權碼流程的單頁應用程式需要此參數。 |
此時，系統會要求使用者輸入其認證並完成驗證。 Microsoft 身分識別平台 也可確保使用者已同意查詢參數中所scope指出的許可權。 如果使用者尚未同意上述任何許可權，則會要求使用者同意所需的許可權。 如需詳細資訊，請參閱 Microsoft 身分識別平台 中的許可權和同意。
一旦使用者驗證並授與同意，Microsoft 身分識別平台 會使用 參數中指定的方法，在指定的 redirect_uri處傳回應用程式回應response_mode。
成功回應
此範例示範使用 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 識別符中註冊，或未新增至使用者的 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_tokenresponse_type OpenID 規格中指定的 。我們建議應用程式使用 form_post，特別是在使用 http://localhost 作為重新導向 URI 時。 |
使用 fragment 作為回應模式會導致從重新導向讀取程式代碼的 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 |
用戶標識元令牌，使用 隱含授與所發出。 包含特殊 c_hash 宣告，該宣告是相同要求中的 哈希 code 。 |
state |
如果要求中包含 state 參數，則回應中應該會出現相同的值。 應用程式必須確認要求與回覆中的狀態值完全相同。 |
兌換存取令牌的代碼
所有機密用戶端都可以選擇使用用戶端密碼或憑證認證。 對稱共享密碼是由 Microsoft 身分識別平台 所產生。 憑證認證是開發人員上傳的非對稱金鑰。 如需詳細資訊，請參閱 Microsoft 身分識別平台 應用程式驗證憑證認證。
為了獲得最佳安全性，我們建議使用憑證認證。 公用用戶端，包括原生應用程式和單頁應用程式，在兌換授權碼時不得使用秘密或憑證。 請務必確定您的重新導向 URI 包含應用程式類型且 是唯一的。
要求具有client_secret的存取令牌
既然您已取得 authorization_code 並已獲使用者授與許可權，您可以兌換 code 給 access_token 資源的 。 code將要求傳送POST至/token端點來兌換 ：
// 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、 、 openidemail 如需詳細資訊，請參閱 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 應用程式和 Web API 需要此 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、 、 openidemail 如需詳細資訊，請參閱 許可權、同意和範圍。 此參數是授權碼流程的 Microsoft 延伸模組。 此延伸模組可讓應用程式在令牌兌換期間宣告他們想要令牌的資源。 |
code |
必要 | 您在流程中第一個階段取得的 authorization_code。 |
redirect_uri |
必要 | 用來取得 authorization_code 的相同 redirect_uri 值。 |
grant_type |
必要 | 必須是用於授權碼流程的 authorization_code。 |
code_verifier |
建議使用 | 用來取得的相同 code_verifierauthorization_code。 如果在授權碼授與要求中使用 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 |
指出權杖類型的值。 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 識別符中註冊，或未新增至使用者的 Microsoft Entra 租使用者時，通常會發生此錯誤。 應用程式可以提示使用者指示安裝應用程式，並將它新增至 Microsoft Entra ID。 |
invalid_client |
用戶端驗證失敗。 | 用戶端認證無效。 若要修正，應用程式 管理員 istrator 會更新認證。 |
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，您可以在對 Web API 的要求中使用令牌，方法是將令牌包含在標頭中 Authorization ：
GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
重新整理存取權杖
存取令牌的存留期很短。 在資源到期后重新整理它們，以繼續存取資源。 您可以藉由將另一個 POST 要求提交至端點來執行 /token 此動作。 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 應用程式和 Web API 需要此 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 支援的唯一類型是 Bearer。 |
expires_in |
存取令牌的有效時間，以秒為單位。 |
scope |
有效的範圍 access_token 。 |
refresh_token |
新的 OAuth 2.0 重新整理令牌。 以這個新取得的重新整理令牌取代舊的重新整理令牌，以確保您的重新整理令牌盡可能保持有效。 注意： 只有在要求範圍時才 offline_access 提供。 |
id_token |
未簽署的 JSON Web 令牌。 應用程式可以將此權杖的區段解碼，以索取已登入使用者的相關資訊。 應用程式可以快取並顯示值，但不應依賴這些值來取得任何授權或安全性界限。 如需 的詳細資訊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 範例 ，以開始撰寫程式代碼。
- 瞭解 令牌交換案例。