警告
此內容適用於較舊的 Azure AD v1.0 端點。 針對新專案使用 Microsoft身分識別平臺。
備註
如果您未告知伺服器您打算呼叫的資源，則伺服器將不會觸發該資源的條件式存取原則。 因此，若要觸發多因素驗證 (MFA)，您必須在 URL 中包含一個資源。
Azure Active Directory （Azure AD） 使用 OAuth 2.0，可讓您授權存取 Azure AD 租使用者中的 Web 應用程式和 Web API。 本指南與語言無關，並說明如何在不使用任何 開放原始碼連結庫的情況下傳送和接收 HTTP 訊息。
如需 OAuthh 2.0 授權碼流程的說明，請參閱 OAuth 2.0 規格的第 4.1 節。 它用來在大部分的應用程式類型中執行驗證和授權，包括 Web 應用程式和原生安裝的應用程式。
向AD租戶註冊您的應用程式
首先，向 Azure Active Directory （Azure AD） 租用戶註冊您的應用程式。 這會提供您應用程式的應用程式識別碼，並讓它接收令牌。
登入 Azure 入口網站。
選擇您的帳戶，位於頁面右上角，然後選取切換目錄導覽，接著選取合適的租用戶，以選擇您的 Azure AD 租用戶。
- 如果您帳戶下只有一個 Azure AD 租使用者，或已選取適當的 Azure AD 租使用者，請略過此步驟。
在 Azure 入口網站中，搜尋並選取 [Azure Active Directory]。
在 Azure Active Directory 左側選單中，選取 [ 應用程式註冊]，然後選取 [ 新增註冊]。
遵循提示並建立新的應用程式。 本教程中，無論是 Web 應用程式或公眾客戶端應用程式（行動和桌面），都沒有區別。但如果您想要關於 Web 應用程式或公眾客戶端應用程式的特定範例，請參閱我們的 快速入門。
- 名稱 是應用程式名稱，並將您的應用程式描述給使用者。
- 在 [支援的帳戶類型] 底下，選取 [任何組織目錄中的帳戶及個人的 Microsoft 帳戶]。
- 提供 重新導向 URI。 對於 Web 應用程式，這是使用者可以登入的應用程式基底 URL。 例如：
http://localhost:12345。 針對公用用戶端（行動裝置和桌面版），Azure AD 會使用它來傳回令牌回應。 輸入應用程式特定的值。 例如：http://MyFirstAADApp。
完成註冊之後，Azure AD 會將應用程式指派唯一的用戶端標識碼（ 應用程式識別符）。 在下一節中，您需要此值，因此請從應用程式頁面複製此值。
若要在 Azure 入口網站中尋找您的應用程式，請選取 [ 應用程式註冊]，然後選取 [ 檢視所有應用程式]。
OAuth 2.0 授權流程
概括而言，應用程式的整個授權流程看起來有點像這樣：
要求授權碼
授權碼流程始於用戶端將使用者導向 /authorize 端點。 在此要求中，用戶端會指出它需要從使用者取得的許可權。 您可以在 Azure 入口網站中選取 [ 應用程式註冊 > 端點 ]，以取得租使用者的 OAuth 2.0 授權端點。
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%3A12345
&response_mode=query
&resource=https%3A%2F%2Fservice.contoso.com%2F
&state=12345
| 參數 | 類型 | 說明 |
|---|---|---|
| 租戶 | 必須的 | 要求路徑中的 {tenant} 值可用來控制可登入應用程式的人員。 允許的值是租用戶標識碼，例如，8eaef023-2b34-4da1-9baa-8bc8c9d6a490 或 contoso.onmicrosoft.com 或 common，適用於租用戶獨立的令牌。 |
| client_id (客戶識別碼) | 必須的 | 當您向 Azure AD 註冊應用程式時，指派給應用程式的應用程式識別碼。 您可以在 Azure 入口網站中找到此專案。 按兩下服務提要欄中的 [Azure Active Directory ]，按兩下 [ 應用程式註冊]，然後選擇應用程式。 |
| response_type（回應類型） | 必須的 | 授權代碼流程必須包含 code。 |
| 重新導向_URI | 建議 | 應用程式的 redirect_uri，是您的應用程式可以傳送和接收驗證回應的位置。 它必須與您在平台裡註冊的其中一個 `redirect_uris` 完全相符，但必須進行 URL 編碼。 預設值 https://login.microsoftonline.com/common/oauth2/nativeclient 是適用於原生和行動應用程式的。 |
| 回應模式 | 自選 | 指定應該用來將所產生權杖傳回給應用程式的方法。 可以是 query、fragment 或 form_post。
query 提供程式代碼作為重新導向 URI 上的查詢字串參數。 如果您要使用隱含流程來要求標識元令牌，就無法如 OpenID 規格中所指定使用query。如果您只要求程式代碼，您可以使用query、 fragment或 form_post。
form_post 會執行包含程式碼的 POST，並將其發送到您的重新導向 URI。 默認為 query 程式代碼流程。 |
| 狀態 | 建議 | 要求中包含的值，也會在權杖回應中返回。 隨機產生的唯一值通常用於 防止跨站台要求偽造攻擊。 此狀態也可用來在驗證要求發生之前，將使用者狀態的相關資訊編碼，例如他們所在的頁面或檢視。 |
| 資源 | 建議 | 目標 Web API 的應用程式識別碼 URI（受保護的資源）。 若要尋找應用程式標識碼 URI，請在 Azure 入口網站中，按兩下 [Azure Active Directory]，按兩下 [ 應用程式註冊]，開啟應用程式的 [設定 ] 頁面， 然後按兩下 [ 內容]。 它也可能是外部資源，例如 https://graph.microsoft.com。 這在其中一個授權或令牌要求中是必要的。 若要確保驗證提示較少，請將它放在授權要求中，以確保收到來自使用者的同意。 |
| 範圍 | 忽視 | 針對 v1 Azure AD 應用程式，必須在 Azure 入口網站中靜態設定範圍，並位於 [應用程式 設定]、[ 必要許可權] 底下。 |
| 提示 | 自選 | 指出所需的使用者互動類型。 有效值為： login：應該提示使用者重新驗證。 select_account：系統會提示用戶選取帳戶，中斷單一登錄。 用戶可以選取現有的登入帳戶、輸入已記住帳戶的認證，或選擇完全使用不同的帳戶。 同意：已授與使用者同意，但必須更新。 應提示使用者同意。 admin_consent：應提示系統管理員代表組織中的所有使用者同意 |
| 登入提示 | 自選 | 如果您事先知道使用者的使用者名稱，可以用此項目來預先填入使用者登入頁面上的使用者名稱/電子郵件地址欄位。 應用程式通常會在重新驗證期間使用此參數，且已使用 preferred_username 宣告從先前登入擷取用戶名稱。 |
| 領域提示 | 自選 | 提供有關使用者應該用來登入租戶或網域的建議提示。 domain_hint的值是租戶的已註冊的網域名稱。 如果租戶與內部目錄同盟，AAD 會重導到指定的租戶同盟伺服器。 |
| 程式挑戰方法 | 建議 | 用於編碼 code_verifier 的 code_challenge 參數的方法。 可以是plain或S256其中之一。 如果排除，則當包含 code_challenge 時，會假設 code_challenge 是純文字。 Azure AAD v1.0 同時支援 plain 和 S256。 如需詳細資訊，請參閱 PKCE RFC。 |
| 程式碼挑戰 | 建議 | 從原生或公用用戶端使用 PKCE（程式碼交換證明密鑰）來保護授權碼授與。 如果包含 code_challenge_method，則此為必要參數。 如需詳細資訊，請參閱 PKCE RFC。 |
備註
如果使用者是組織的一部分，組織的系統管理員可以代表使用者同意或拒絕，或允許使用者同意。 只有在系統管理員允許時，使用者才會獲得同意的選項。
此時，系統會要求使用者輸入其認證，並同意應用程式在 Azure 入口網站中要求的許可權。 一旦使用者驗證並授與同意，Azure AD 就會使用程式代碼，在 redirect_uri 要求中的位址將回應傳送至您的應用程式。
成功回應
成功的回應看起來像這樣：
GET HTTP/1.1 302 Found
Location: http://localhost:12345/?code= AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA&session_state=7B29111D-C220-4263-99AB-6F6E135D75EF&state=D79E5777-702E-4260-9A62-37F75FF22CCE
| 參數 | 說明 |
|---|---|
| 管理員同意 | 如果系統管理員同意同意同意要求提示，則值為 True。 |
| 程式碼 | 應用程式所要求的授權碼。 應用程式可以使用授權碼來要求目標資源的存取令牌。 |
| session_state | 識別目前使用者工作階段的唯一值。 這個值是 GUID，但應視為不檢查即傳遞的不透明值。 |
| 狀態 | 如果要求中包含 state 參數，則回應中應該會出現相同的值。 應用程式最好先確認要求和回應中的狀態值在使用回應之前完全相同。 這有助於偵測針對用戶端的 跨網站偽造要求 （CSRF） 攻擊 。 |
錯誤回應
錯誤回應也可能傳送至 redirect_uri ，讓應用程式可以適當地處理它們。
GET http://localhost:12345/?
error=access_denied
&error_description=the+user+canceled+the+authentication
| 參數 | 說明 |
|---|---|
| 錯誤 | OAuth 2.0 Authorization Framework 第 5.2 節中定義的錯誤碼值。 下表描述 Azure AD 傳回的錯誤碼。 |
| 錯誤描述 | 更詳細的錯誤描述。 此訊息並非以使用者友善為設計目的。 |
| 狀態 | 狀態值是隨機產生的非重複使用值，會在要求中傳送，並在響應中傳回，以防止跨網站偽造要求 （CSRF） 攻擊。 |
授權端點錯誤的錯誤代碼
下表說明各種可能在錯誤回應的 error 參數中傳回的錯誤碼。
| 錯誤碼 | 說明 | 用戶端動作 |
|---|---|---|
| 無效請求 | 通訊協定錯誤，例如遺漏必要的參數。 | 修正並重新提交要求。 這是開發錯誤，通常會在初始測試過程中發現。 |
| 未授權的客戶端 | 不允許用戶端應用程式要求授權碼。 | 這通常是在用戶端應用程式未在 Azure AD 中註冊，或未新增至使用者的 Azure AD 租使用者時發生。 應用程式可以提示使用者指示安裝應用程式，並將其新增至 Azure AD。 |
| 拒絕存取 | 資源擁有者拒絕同意 | 除非使用者同意，否則用戶端應用程式可以通知使用者無法繼續。 |
| 不支援的回應類型 | 授權伺服器不支援要求中的回應類型。 | 修正並重新提交要求。 這是開發錯誤，通常會在初始測試過程中發現。 |
| 伺服器錯誤 | 伺服器發生非預期的錯誤。 | 再次嘗試請求。 這些錯誤可能是由暫時性狀況所引起。 用戶端應用程式可能會向使用者說明其回應因暫時錯誤而延遲。 |
| 暫時無法使用 | 伺服器暫時過於忙碌而無法處理要求。 | 再次嘗試請求。 用戶端應用程式可能會向使用者說明其回應因暫時性狀況而延遲。 |
| 無效資源 | 目標資源無效，因為它不存在、Azure AD 找不到或設定不正確。 | 這表示資源若存在，則尚未在租用戶中設定。 應用程式可以提示使用者指示安裝應用程式，並將其新增至 Azure AD。 |
使用授權碼來要求存取令牌
既然您已取得授權碼，並已獲使用者授與許可權，您可以藉由將POST要求傳送至端點，將存取令牌的程式代碼兌換為 /token 所需的資源：
// Line breaks for legibility only
POST /{tenant}/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA
&redirect_uri=https%3A%2F%2Flocalhost%3A12345
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=p@ssw0rd
//NOTE: client_secret only required for web apps
| 參數 | 類型 | 說明 |
|---|---|---|
| 租戶 | 必須的 | 要求路徑中的 {tenant} 值可用來控制可登入應用程式的人員。 允許的值是租使用者標識碼，例如，8eaef023-2b34-4da1-9baa-8bc8c9d6a490或contoso.onmicrosoft.comcommon租用戶無關的令牌 |
| client_id (客戶識別碼) | 必須的 | 當您向 Azure AD 註冊應用程式時，指派給應用程式的應用程式識別碼。 您可以在 Azure 入口網站中找到此專案。 應用程式識別碼會顯示在應用程式註冊的設定中。 |
| grant_type (授權類型) | 必須的 | 授權碼流程中必須使用 authorization_code。 |
| 程式碼 | 必須的 |
authorization_code您在上一節中取得的 |
| 重新導向_URI | 必須的 |
redirect_uri已在用戶端應用程式上註冊。 |
| 用戶端密鑰 | Web 應用程式的必要專案，公用用戶端不允許 | 您在 Azure 入口網站中，於金鑰下建立的應用程式密碼。 它不能用於原生應用程式（公用用戶端），因為client_secrets無法可靠地儲存在裝置上。 Web 應用程式和 Web API（所有機密客戶端）需要此功能，這些客戶端能夠在伺服器端安全地儲存 client_secret。 傳送之前，client_secret應該先以URL編碼。 |
| 資源 | 建議 | 目標 Web API 的應用程式識別碼 URI（受保護的資源）。 若要尋找應用程式標識碼 URI，請在 Azure 入口網站中，按兩下 [Azure Active Directory]，按兩下 [ 應用程式註冊]，開啟應用程式的 [設定 ] 頁面， 然後按兩下 [ 內容]。 它也可能是外部資源，例如 https://graph.microsoft.com。 這在其中一個授權或令牌要求中是必要的。 若要確保驗證提示較少，請將它放在授權要求中，以確保收到來自使用者的同意。 如果同時在授權要求和令牌要求中，資源的參數必須相符。 |
| 驗證碼 | 自選 | 用於獲取授權碼的相同驗證碼。 如果在授權碼授與要求中使用 PKCE，則此為必要參數。 如需詳細資訊，請參閱 PKCE RFC |
若要尋找應用程式標識碼 URI，請在 Azure 入口網站中，按兩下 [Azure Active Directory]，按兩下 [ 應用程式註冊]，開啟應用程式的 [設定 ] 頁面， 然後按兩下 [ 內容]。
成功回應
Azure AD 會在成功回應時傳回 存取令牌 。 若要將用戶端應用程式的網路呼叫及其相關聯的延遲降到最低，用戶端應用程式應該快取 OAuth 2.0 回應中所指定令牌存留期的存取令牌。 若要判斷令牌存留期，請使用 expires_in 或 expires_on 參數值。
如果 Web API 資源傳 invalid_token 回錯誤碼，這可能表示資源已判斷令牌已過期。 如果客戶端和系統的時鐘時間不同（稱為「時間差」），系統可能會在用戶端快取清除令牌之前，認為該令牌已過期。 如果發生這種情況，請清除快取中的令牌，即使它仍在其計算存留期內也一樣。
成功的回應看起來像這樣：
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
"token_type": "Bearer",
"expires_in": "3600",
"expires_on": "1388444763",
"resource": "https://service.contoso.com/",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA",
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83ZmU4MTQ0Ny1kYTU3LTQzODUtYmVjYi02ZGU1N2YyMTQ3N2UvIiwiaWF0IjoxMzg4NDQwODYzLCJuYmYiOjEzODg0NDA4NjMsImV4cCI6MTM4ODQ0NDc2MywidmVyIjoiMS4wIiwidGlkIjoiN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlIiwib2lkIjoiNjgzODlhZTItNjJmYS00YjE4LTkxZmUtNTNkZDEwOWQ3NGY1IiwidXBuIjoiZnJhbmttQGNvbnRvc28uY29tIiwidW5pcXVlX25hbWUiOiJmcmFua21AY29udG9zby5jb20iLCJzdWIiOiJKV3ZZZENXUGhobHBTMVpzZjd5WVV4U2hVd3RVbTV5elBtd18talgzZkhZIiwiZmFtaWx5X25hbWUiOiJNaWxsZXIiLCJnaXZlbl9uYW1lIjoiRnJhbmsifQ."
}
| 參數 | 說明 |
|---|---|
| access_token（存取憑證） | 要求的存取憑證。 這是不透明的字串 - 這取決於資源預期接收的內容，而且不適合用戶端查看。 應用程式可以使用此權杖來對受保護的資源 (例如 Web API) 進行驗證。 |
| 令牌類型 | 表示令牌類型值。 Azure AD 支援的唯一類型是 Bearer。 如需持有人令牌的詳細資訊，請參閱 OAuth2.0 授權架構：持有人令牌使用方式（RFC 6750） |
| 有效期限 | 存取權杖的有效時間 (以秒為單位)。 |
| 到期日 | 存取令牌到期的時間。 日期會以 1970-01-01T0：0：0Z UTC 到到期時間之前的秒數表示。 這個值用來判斷快取令牌的存留期。 |
| 資源 | Web API 的應用程式識別碼 URI（受保護的資源）。 |
| 範圍 | 授與用戶端應用程式的模擬許可權。 預設權限為 user_impersonation。 受保護資源的擁有者可以在 Azure AD 中註冊其他值。 |
| 刷新令牌 | OAuth 2.0 更新權杖。 應用程式可以使用此令牌，在目前的存取令牌到期之後取得其他存取令牌。 刷新權杖是長期有效的，可以用來長時間保有資源的存取權。 |
| id_token（驗證令牌） | 表示 ID 令牌的未簽署的 JSON Web 令牌（JWT）。 應用程式可以使用base64Url解碼此令牌的區段，以請求有關登入使用者的資訊。 應用程式可以快取並顯示這些數值，但不應依賴這些數值作為任何授權或安全界限的依據。 |
如需 JSON Web 令牌的詳細資訊，請參閱 JWT IETF 草稿規格。 若要深入瞭解 id_tokens，請參閱 v1.0 OpenID Connect 流程。
錯誤回應
令牌發行端點錯誤是 HTTP 錯誤碼，因為用戶端會直接呼叫令牌發行端點。 除了 HTTP 狀態代碼之外，Azure AD 令牌發行端點也會傳回 JSON 檔，其中包含描述錯誤的物件。
範例錯誤回應可能如下所示：
{
"error": "invalid_grant",
"error_description": "AADSTS70002: Error validating credentials. AADSTS70008: The provided authorization code or refresh token is expired. Send a new interactive authorization request for this user and resource.\r\nTrace ID: 3939d04c-d7ba-42bf-9cb7-1e5854cdce9e\r\nCorrelation ID: a8125194-2dc8-4078-90ba-7b6592a7f231\r\nTimestamp: 2016-04-11 18:00:12Z",
"error_codes": [
70002,
70008
],
"timestamp": "2016-04-11 18:00:12Z",
"trace_id": "3939d04c-d7ba-42bf-9cb7-1e5854cdce9e",
"correlation_id": "a8125194-2dc8-4078-90ba-7b6592a7f231"
}
| 參數 | 說明 |
|---|---|
| 錯誤 | 一個錯誤碼字串，可以用來分類發生的錯誤類型並對錯誤做出回應。 |
| 錯誤描述 | 協助開發人員識別驗證錯誤根本原因的特定錯誤訊息。 |
| 錯誤代碼 | 有助於診斷的 STS 特定錯誤碼清單。 |
| 時間戳 | 發生錯誤的時間。 |
| trace_id | 能協助診斷的請求唯一識別碼。 |
| 關聯識別碼 | 這是一個要求的唯一識別碼，有助於跨元件診斷。 |
HTTP 狀態碼
下表列出令牌發行端點傳回的 HTTP 狀態代碼。 在某些情況下，錯誤碼就足以描述回應，但如果發生錯誤，您需要剖析隨附的 JSON 檔並檢查其錯誤碼。
| HTTP 程式代碼 | 說明 |
|---|---|
| 400 | 默認 HTTP 程式代碼。 在大部分情況下使用 ，通常是因為格式不正確的要求。 修正並重新提交要求。 |
| 401 | 驗證失敗。 例如，要求遺漏 client_secret 參數。 |
| 403 | 授權失敗。 例如，用戶沒有存取資源的許可權。 |
| 500 | 服務發生內部錯誤。 再次嘗試請求。 |
令牌端點錯誤的錯誤碼
| 錯誤碼 | 說明 | 用戶端動作 |
|---|---|---|
| 無效請求 | 通訊協定錯誤，例如遺漏必要的參數。 | 修正並重新提交要求 |
| 無效授權 | 授權碼無效或已過期。 | 嘗試對 /authorize 端點提出新的要求 |
| 未授權的客戶端 | 已驗證的用戶端未獲授權使用此授權授與類型。 | 這通常是在用戶端應用程式未在 Azure AD 中註冊，或未新增至使用者的 Azure AD 租使用者時發生。 應用程式可以提示使用者指示安裝應用程式，並將其新增至 Azure AD。 |
| invalid_client | 用戶端驗證失敗。 | 用戶端認證無效。 若要修正，應用程式管理員會更新認證。 |
| unsupported_grant_type | 授權伺服器不支援授權授與類型。 | 變更要求中的授與類型。 這種類型的錯誤應該只會在開發期間發生，並且會在初始測試期間偵測出來。 |
| 無效資源 | 目標資源無效，因為它不存在、Azure AD 找不到或設定不正確。 | 這表示資源若存在，則尚未在租用戶中設定。 應用程式可以提示使用者指示安裝應用程式，並將其新增至 Azure AD。 |
| interaction_required | 要求需要使用者互動。 例如，需要額外的驗證步驟。 | 使用相同資源的互動式授權要求重試，而不是非互動式要求。 |
| 暫時無法使用 | 伺服器暫時過於忙碌而無法處理要求。 | 再次嘗試請求。 用戶端應用程式可能會向使用者說明其回應因暫時性狀況而延遲。 |
使用存取令牌來存取資源
既然您已成功取得 access_token，您可以在請求 Web API 時使用該令牌，將其包含在 Authorization 標頭中。
RFC 6750 規格說明如何在 HTTP 要求中使用持有人令牌來存取受保護的資源。
範例要求
GET /data HTTP/1.1
Host: service.contoso.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ
錯誤回應
實作 RFC 6750 的安全資源會發出 HTTP 狀態代碼。 如果要求不包含驗證認證或遺失令牌，回應會包含 WWW-Authenticate 標頭。 當要求失敗時，資源伺服器會以 HTTP 狀態代碼和錯誤碼回應。
當用戶端要求不包含持有人令牌時，以下是失敗回應的範例：
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer authorization_uri="https://login.microsoftonline.com/contoso.com/oauth2/authorize", error="invalid_token", error_description="The access token is missing.",
錯誤參數
| 參數 | 說明 |
|---|---|
| 授權_URI | 授權伺服器的 URI（實體端點）。 此值也會作為查閱索引鍵，以從探索端點取得伺服器的詳細資訊。 用戶端必須驗證授權伺服器是否受信任。 當資源受到 Azure AD 保護時，確認 URL 是否以 |
| 錯誤 | OAuth 2.0 Authorization Framework 第 5.2 節中定義的錯誤碼值。 |
| 錯誤描述 | 錯誤的更加詳盡描述。 此消息並非使用者友好。 |
| 資源識別碼 | 傳回資源的唯一標識碼。 用戶端應用程式在要求資源的令牌時，可以使用此標識碼作為 resource 參數的值。 用戶端應用程式必須確認此值，否則惡意服務可能會引發特權提升攻擊 防止攻擊的建議策略是確認 |
承載者方案錯誤碼
RFC 6750 規格針對在回應中使用 WWW-Authenticate 標頭和 Bearer 方案的資源定義了以下錯誤。
| HTTP 狀態代碼 | 錯誤碼 | 說明 | 用戶端動作 |
|---|---|---|---|
| 400 | 無效請求 | 要求的格式不正確。 例如，它可能遺漏參數，或使用相同參數兩次。 | 修正錯誤，然後重試要求。 這種類型的錯誤應該只在開發期間發生，並在初始測試中偵測到。 |
| 401 | 無效的憑證 | 存取令牌遺失、無效或已撤銷。 error_description 參數的值會提供其他詳細數據。 | 從授權伺服器要求新的令牌。 如果新的令牌失敗，則發生非預期的錯誤。 將錯誤訊息傳送給使用者，並在隨機延遲之後重試。 |
| 403 | 範圍不足 | 存取令牌不包含存取資源所需的模擬許可權。 | 將新的授權要求傳送至授權端點。 如果回應包含 scope 參數，請在要求中使用範圍值並將其應用於資源。 |
| 403 | 存取不足 | 令牌的主體沒有存取資源所需的許可權。 | 提示使用者使用不同的帳戶，或要求指定資源的許可權。 |
重新整理存取令牌
存取令牌是短期的，而且必須在存取令牌到期后重新整理，才能繼續存取資源。 您可以透過將另一個 POST 請求提交至 /token 端點來更新 access_token，但這次提供 refresh_token 而不是 code。 重新整理令牌對於用戶端已經同意可以存取的所有資源都是有效的，因此，針對 resource=https://graph.microsoft.com 的請求發出的重新整理令牌可以用來請求 resource=https://contoso.com/api 的新存取令牌。
重新整理令牌沒有指定的存留期。 一般而言，刷新令牌的有效期通常較長。 不過，在某些情況下，刷新權杖可能會過期、被撤銷，或者沒有執行所需動作的足夠的權限。 您的應用程式必須預期並正確處理權杖發行端點所傳回的錯誤。
當您收到重新整理令牌錯誤的回應時，請捨棄目前的重新整理令牌，並要求新的授權碼或存取令牌。 特別是當您在授權碼授與流程中使用重新整理令牌時，如果您收到具有 interaction_required 或 invalid_grant 錯誤碼的回應，請捨棄重新整理令牌並要求新的授權碼。
對 租使用者特定 端點的範例要求（您也可以使用 通用 端點）使用重新整理令牌取得新的存取令牌，如下所示：
// Line breaks for legibility only
POST /{tenant}/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for web apps
成功回應
成功的權令牌回應看起來如下：
{
"token_type": "Bearer",
"expires_in": "3600",
"expires_on": "1460404526",
"resource": "https://service.contoso.com/",
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
"refresh_token": "AwABAAAAv YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl PM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfmVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA"
}
| 參數 | 說明 |
|---|---|
| 令牌類型 | 令牌類型。 唯一支援的值是 持有人。 |
| 有效期限 | 令牌的剩餘存留期，以秒為單位。 一般值為 3600 （一小時）。 |
| 到期日 | 令牌到期的日期和時間。 日期會以 1970-01-01T0：0：0Z UTC 到到期時間之前的秒數表示。 |
| 資源 | 識別存取令牌可用來存取的安全資源。 |
| 範圍 | 授與原生用戶端應用程式的冒充許可權。 默認許可權為 user_impersonation。 目標資源的擁有者可以在 Azure AD 中註冊替代值。 |
| access_token（存取憑證） | 要求的新存取令牌。 |
| 刷新令牌 | 新的 OAuth 2.0 更新權杖，可在此回應中的存取令牌到期後用於申請新的存取權杖。 |
錯誤回應
範例錯誤回應可能如下所示：
{
"error": "invalid_resource",
"error_description": "AADSTS50001: The application named https://foo.microsoft.com/mail.read was not found in the tenant named 295e01fc-0c56-4ac3-ac57-5d0ed568f872. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You might have sent your authentication request to the wrong tenant.\r\nTrace ID: ef1f89f6-a14f-49de-9868-61bd4072f0a9\r\nCorrelation ID: b6908274-2c58-4e91-aea9-1f6b9c99347c\r\nTimestamp: 2016-04-11 18:59:01Z",
"error_codes": [
50001
],
"timestamp": "2016-04-11 18:59:01Z",
"trace_id": "ef1f89f6-a14f-49de-9868-61bd4072f0a9",
"correlation_id": "b6908274-2c58-4e91-aea9-1f6b9c99347c"
}
| 參數 | 說明 |
|---|---|
| 錯誤 | 一個錯誤碼字串，可以用來分類發生的錯誤類型並對錯誤做出回應。 |
| 錯誤描述 | 協助開發人員識別驗證錯誤根本原因的特定錯誤訊息。 |
| 錯誤代碼 | 有助於診斷的 STS 特定錯誤碼清單。 |
| 時間戳 | 發生錯誤的時間。 |
| trace_id 追蹤識別碼 | 能協助診斷的請求唯一識別碼。 |
| 關聯識別碼 | 這是一個要求的唯一識別碼，有助於跨元件診斷。 |
如需了解錯誤碼和建議的用戶端動作，請參閱令牌端點錯誤的錯誤碼的說明。
後續步驟
若要深入瞭解 Azure AD v1.0 端點，以及如何將驗證和授權新增至 Web 應用程式和 Web API，請參閱 範例應用程式。