使用 Azure DevOps OAuth 2.0 建立 Web 應用程式

Azure DevOps Services

Azure DevOps 是 OAuth 2.0 應用程式的識別提供者。 我們的 OAuth 2.0 實作可讓開發人員授權其應用程式給使用者，並取得 Azure DevOps 資源的存取令牌。

開始使用 Azure DevOps OAuth

1.註冊您的應用程式

1. 移至 以 https://app.vsaex.visualstudio.com/app/register 註冊您的應用程式。

2. 選取應用程式所需的範圍，然後在您授權應用程式時使用相同的範圍。 如果您使用預覽 API 註冊應用程式，請重新註冊，因為您所使用的範圍現在已被取代。

3. 選取 [ 建立應用程式]。

   應用程式設定頁面隨即顯示。

   

   • 當 Azure DevOps Services 向使用者顯示授權核准頁面時，它會使用您的公司名稱、應用程式名稱和描述。 它也會使用公司網站的 URL、應用程式網站，以及服務條款和隱私聲明。

     

   • 當 Azure DevOps Services 要求使用者的授權，而使用者授與授權時，使用者的瀏覽器會以授權碼重新導向至您的授權回呼 URL。 回呼 URL 必須是安全連線（https），才能將程式代碼傳輸回應用程式，並完全符合您應用程式中註冊的 URL。 如果沒有，則會顯示 400 錯誤頁面，而不是要求使用者將授權授與您的應用程式的頁面。

4. 當您想要讓使用者授權您的應用程式存取其組織時，請呼叫授權 URL 並傳遞您的應用程式識別碼和授權範圍。 當您想要取得存取令牌來呼叫 Azure DevOps Services REST API 時，請呼叫存取令牌 URL。

您註冊的每個應用程式設定都可從您的設定檔 https://app.vssps.visualstudio.com/profile/view取得。

2.授權您的應用程式

1. 如果使用者未授權您的應用程式存取其組織，請呼叫授權 URL。 如果使用者核准授權，它會以授權碼呼叫您。

https://app.vssps.visualstudio.com/oauth2/authorize
        ?client_id={app ID}
        &response_type={Assertion}
        &state={state}
        &scope={scope}
        &redirect_uri={callback URL}

2. 將連結或按鈕新增至您的網站，以將使用者帶到 Azure DevOps Services 授權端點：

https://app.vssps.visualstudio.com/oauth2/authorize
        ?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
        &response_type=Assertion
        &state=User1
        &scope=vso.work%20vso.code_write
        &redirect_uri=https://fabrikam.azurewebsites.net/myapp/oauth-callback

Azure DevOps Services 會要求使用者授權您的應用程式。

假設使用者接受，Azure DevOps Services 會將使用者的瀏覽器重新導向至您的回呼 URL，包括短期授權碼和授權 URL 中提供的狀態值：

https://fabrikam.azurewebsites.net/myapp/oauth-callback
        ?code={authorization code}
        &state=User1

3.取得使用者的存取權和重新整理令牌

使用授權碼來要求使用者的存取令牌（並重新整理令牌）。 您的服務必須對 Azure DevOps Services 提出服務對服務 HTTP 要求。

URL - 授權應用程式

POST https://app.vssps.visualstudio.com/oauth2/token

HTTP 要求標頭 - 授權應用程式

Content-Type: application/x-www-form-urlencoded

HTTP 要求本文 - 授權應用程式

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}

取代先前範例要求本文中的佔位元值：

• {0}：註冊應用程式時取得的 URL 編碼客戶端密碼
• {1}：透過查詢參數提供給回呼 URL 的 code URL 編碼“程序代碼”
• {2}：向應用程式註冊的回呼 URL

形成要求本文的 C# 範例 - 授權應用程式

public string GenerateRequestPostData(string appSecret, string authCode, string callbackUrl)
{
   return String.Format("client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}",
               HttpUtility.UrlEncode(appSecret),
               HttpUtility.UrlEncode(authCode),
               callbackUrl
        );
}

回應 - 授權應用程式

{
    "access_token": { access token for the user },
    "token_type": { type of token },
    "expires_in": { time in seconds that the token remains valid },
    "refresh_token": { refresh token to use to acquire a new access token }
}

4.使用存取令牌

若要使用存取令牌，請在 HTTP 要求的授權標頭中包含它作為持有人令牌：

Authorization: Bearer {access_token}

例如，要 取得專案最近組建 的 HTTP 要求：

GET https://dev.azure.com/myaccount/myproject/_apis/build-release/builds?api-version=3.0
Authorization: Bearer {access_token}

5.重新整理過期的存取令牌

如果使用者的存取令牌過期，您可以使用他們在授權流程中取得的重新整理令牌來取得新的存取令牌。 就像交換存取和重新整理令牌授權碼的原始程序一樣。

URL - 重新整理令牌

POST https://app.vssps.visualstudio.com/oauth2/token

HTTP 要求標頭 - 重新整理令牌

Content-Type: application/x-www-form-urlencoded
Content-Length: 1654

HTTP 要求本文 - 重新整理令牌

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=refresh_token&assertion={1}&redirect_uri={2}

取代先前範例要求本文中的佔位元值：

• {0}：註冊應用程式時取得的 URL 編碼客戶端密碼
• {1}：使用者 URL 編碼的重新整理令牌
• {2}：向應用程式註冊的回呼 URL

回應 - 重新整理令牌

{
    "access_token": { access token for this user },
    "token_type": { type of token },
    "expires_in": { time in seconds that the token remains valid },
    "refresh_token": { new refresh token to use when the token has timed out }
}

範例

您可以在 C# OAuth GitHub 範例中找到 實作 OAuth 的 C# 範例，以呼叫 Azure DevOps Services REST API。

重新產生客戶端密碼

每五年，您的應用程式秘密就會過期。 重新產生您的應用程式密碼，以繼續建立和使用存取令牌和重新整理令牌。 若要這樣做，請選取 [重新產生秘密]，然後確認您想要完成此動作。

當您確認要重新產生時，上一個應用程式秘密已不再運作，且所有與此秘密一起縮排的先前令牌也會停止運作。 請務必讓此用戶端秘密輪替順利進行，以將任何客戶停機時間降到最低。

刪除您的應用程式

如果您不再需要您的應用程式，請從配置檔中刪除它。

1. 移至您的設定檔： https://app.vssps.visualstudio.com/profile/view。

2. 請從提要欄位中名稱底下的下拉功能表中選取 ，確定您位於正確的租用戶頁面上。

3. 在左側提要欄位的 [應用程式和服務] 標頭下尋找應用程式。

4. 在應用程式註冊頁面上選取 [刪除]。 模式隨即出現，以確認您的刪除。

   

5. 刪除應用程式註冊之後，應用程式會中斷，我們停止挖掘新的令牌，或接受此應用程式的縮排令牌。

常見問題集 (FAQ)

問：是否可以將 OAuth 與我的行動電話應用程式搭配使用？

A: 不可以。 Azure DevOps Services 僅支援 Web 伺服器流程，因此無法實作 OAuth，因為您無法安全地儲存應用程式密碼。

問：我需要在程式代碼中處理哪些錯誤或特殊狀況？

答：請確定您處理下列條件：

• 如果您的使用者拒絕應用程式存取權，則不會傳回任何授權碼。 請勿在沒有檢查拒絕的情況下使用授權碼。
• 如果使用者撤銷應用程式的授權，存取令牌就不再有效。 當您的應用程式使用令牌來存取數據時，會傳回 401 錯誤。 再次要求授權。

問：我想在本機對 Web 應用程式進行偵錯。 當我註冊應用程式時，是否可以將localhost用於回呼URL？

A: 可以。 Azure DevOps Services 現在可在回呼 URL 中允許 localhost。 當您註冊應用程式時，請務必使用 https://localhost 作為回呼 URL 的開頭。

問：當我嘗試取得存取令牌時，我會收到 HTTP 400 錯誤。 可能出了什麼問題？

答：請檢查您是否在要求標頭中將內容類型設定為 application/x-www-form-urlencoded。

問：當我使用 OAuth 型存取令牌時，我會收到 HTTP 401 錯誤，但具有相同範圍的 PAT 運作正常。 為什麼？

答：確認貴組織的系統管理員未透過 OAuth https://dev.azure.com/{your-org-name}/_settings/organizationPolicy停用第三方應用程式存取。 在此案例中，授權應用程式併產生存取令牌的流程可運作，但所有 REST API 只會傳回錯誤，例如 TF400813: The user "<GUID>" is not authorized to access this resource.

相關文章

• 選擇正確的驗證方法
• 使用 Microsoft Entra ID OAuth
• Azure DevOps 的預設權限和存取權
• 管理授權