Microsoft 身分識別平台和 OAuth 2.0 授權碼流程
OAuth 2.0 授權碼授與類型或 驗證碼流程可讓用戶端應用程式取得 Web API 等受保護資源的授權存取權。 驗證碼流程需要支援從授權伺服器 (Microsoft 身分識別平台) 重新導向至應用程式的使用者代理程式。 例如,由使用者操作的網頁瀏覽器、桌面或行動應用程式,以登入您的應用程式並存取其數據。
本文說明只有在手動製作和發出原始 HTTP 要求以執行流程時,才需要低階通訊協定詳細數據,不建議這麼做。 請改用 Microsoft建置且支持的驗證連結庫 來取得安全性令牌,並在您的應用程式中呼叫受保護的Web API。
支援驗證碼流程的應用程式
使用與程式代碼交換證明密鑰 (PKCE) 和 OpenID Connect (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
type
設定為spa
。
重新 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
將數據寫入組織的目錄。 如果應用程式向組織使用者要求存取其中一個權限,使用者會收到錯誤訊息,指出他們無權同意應用程式權限。 若要要求存取受系統管理員限制的範圍,您應該直接從全域管理員要求它們。 如需詳細資訊,請參閱 系統管理員限制的許可權。
除非另有指定,否則選擇性參數沒有預設值。 不過,要求省略選擇性參數的默認行為。 默認行為是登入唯一的目前使用者、如果有多個使用者,則顯示帳戶選擇器,如果沒有任何使用者登入,則顯示登入頁面。
// 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 |
不允許用戶端應用程式要求授權碼。 | 當用戶端應用程式未在 entra 識別符中註冊,或未新增至使用者的 Microsoft 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 應用程式發生問題。 瀏覽器不會將片段傳遞至網頁伺服器。 在這些情況下,應用程式應該使用 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 、 、 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 應用程式和 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 、 、 openid email 如需詳細資訊,請參閱 許可權、同意和範圍。 此參數是授權碼流程的Microsoft延伸模組。 此延伸模組可讓應用程式在令牌兌換期間宣告他們想要令牌的資源。 |
code |
必要 | 您在流程中第一個階段取得的 authorization_code 。 |
redirect_uri |
必要 | 用來取得 authorization_code 的相同 redirect_uri 值。 |
grant_type |
必要 | 必須是用於授權碼流程的 authorization_code 。 |
code_verifier |
建議使用 | 用來取得的相同 code_verifier authorization_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_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 |
未授權驗證用戶端使用此授權授與類型。 | 當用戶端應用程式未在 entra 識別符中註冊,或未新增至使用者的 Microsoft 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
,您可以在對 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 支援的唯一類型是 持有人。 |
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 範例以開始撰寫程式碼。
- 瞭解 令牌交換案例。