Bagikan melalui

Menggunakan Azure DevOps OAuth 2.0 untuk membuat aplikasi web

Layanan Azure DevOps

Penting

Azure DevOps OAuth dijadwalkan untuk penghentian pada tahun 2026. Informasi ini hanya untuk aplikasi Azure DevOps OAuth yang ada. Untuk membuat aplikasi baru, gunakan Microsoft Entra ID OAuth untuk berintegrasi dengan Azure DevOps. Mulai April 2025, kami berhenti menerima aplikasi OAuth Azure DevOps baru. Pelajari lebih lanjut di posting blog kami.

Azure DevOps adalah penyedia identitas untuk aplikasi OAuth 2.0. Implementasi OAuth 2.0 kami memungkinkan pengembang mengotorisasi aplikasi mereka untuk pengguna dan mendapatkan token akses untuk sumber daya Azure DevOps.

Mulai menggunakan Azure DevOps OAuth

1. Daftarkan aplikasi Anda

  1. Pergi ke https://app.vsaex.visualstudio.com/app/register untuk mendaftarkan aplikasi Anda.

  2. Pilih cakupan yang dibutuhkan aplikasi Anda, lalu gunakan cakupan yang sama saat Anda mengotorisasi aplikasi Anda. Jika Anda mendaftarkan aplikasi menggunakan API pratinjau, daftar ulang karena cakupan yang Anda gunakan sekarang tidak digunakan lagi.

  3. Pilih Buat aplikasi.

    Halaman pengaturan aplikasi ditampilkan.

    Cuplikan layar memperlihatkan pengaturan Aplikasi untuk aplikasi Anda.

    • Saat Azure DevOps Services menyajikan halaman persetujuan otorisasi kepada pengguna Anda, layanan tersebut menggunakan nama perusahaan, nama aplikasi, dan deskripsi Anda. Ini juga menggunakan URL untuk situs web perusahaan Anda, situs web aplikasi, serta ketentuan layanan dan pernyataan privasi.

      Cuplikan layar memperlihatkan halaman otorisasi Visual Studio Codespaces dengan informasi perusahaan dan aplikasi Anda.

    • Saat Azure DevOps Services meminta otorisasi pengguna, dan pengguna memberikannya, browser pengguna akan diarahkan ke URL panggilan balik otorisasi Anda dengan kode otorisasi. URL panggilan balik harus berupa koneksi aman (https) untuk mentransfer kode kembali ke aplikasi dan sama persis dengan URL yang terdaftar di aplikasi Anda. Jika tidak, halaman kesalahan 400 ditampilkan alih-alih halaman yang meminta pengguna untuk memberikan otorisasi ke aplikasi Anda.

  4. Hubungi URL otorisasi dan berikan ID aplikasi dan cakupan resmi saat Anda ingin meminta pengguna mengotorisasi aplikasi Anda untuk mengakses organisasi mereka. Panggil URL token akses saat Anda ingin mendapatkan token akses untuk memanggil REST API Azure DevOps Services.

Pengaturan untuk setiap aplikasi yang Anda daftarkan tersedia dari profil https://app.vssps.visualstudio.com/profile/viewAnda .

2. Otorisasi aplikasi Anda

  1. Jika pengguna Anda tidak mengotorisasi aplikasi Anda untuk mengakses organisasi mereka, panggil URL otorisasi. Ini memanggil Anda kembali dengan kode otorisasi, jika pengguna menyetujui otorisasi.
https://app.vssps.visualstudio.com/oauth2/authorize
        ?client_id={app ID}
        &response_type={Assertion}
        &state={state}
        &scope={scope}
        &redirect_uri={callback URL}
Pengaturan Tipe Catatan
ID klien - GUID ID yang ditetapkan ke aplikasi Anda saat terdaftar.
jenis_respons benang Assertion
negara benang Dapat berupa nilai apa pun. Biasanya nilai string yang dihasilkan yang menghubungkan panggilan balik dengan permintaan otorisasi terkait.
jangkauan benang Cakupan yang terdaftar di aplikasi. Dipisahkan dengan spasi Lihat cakupan tersedia.
URI pengalihan URL URL panggilan balik untuk aplikasi Anda. Harus sama persis dengan URL yang terdaftar di aplikasi.
  1. Tambahkan tautan atau tombol ke situs Anda yang membawa pengguna ke titik akhir otorisasi 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

Layanan Azure DevOps meminta pengguna untuk mengotorisasi aplikasi Anda.

Dengan asumsi pengguna menerima, Azure DevOps Services mengalihkan browser pengguna ke URL panggilan balik Anda, termasuk kode otorisasi berumur pendek dan nilai status yang disediakan dalam URL otorisasi:

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

3. Dapatkan akses dan refresh token untuk pengguna

Gunakan kode otorisasi untuk meminta token akses (dan token refresh) untuk pengguna. Layanan Anda harus membuat permintaan HTTP antar layanan ke Azure DevOps Services.

URL - mengotorisasi aplikasi

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

Header permintaan HTTP - mengotorisasi aplikasi

Kepala Halaman Nilai
Jenis-Konten application/x-www-form-urlencoded 
Content-Type: application/x-www-form-urlencoded

Isi permintaan HTTP - mengotorisasi aplikasi

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}

Ganti nilai placeholder di badan permintaan sampel sebelumnya.

  • {0}: Rahasia klien yang dikodekan dalam URL diperoleh saat pendaftaran aplikasi
  • {1}: "Kode" yang terenkripsi URL yang disediakan melalui parameter kueri code ke URL panggilan balik Anda
  • {2}: URL panggilan balik yang terdaftar di aplikasi

Contoh C# untuk membentuk isi permintaan - mengotorisasi aplikasi

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
        );
}

Respons - mengotorisasi aplikasi

{
    "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 }
}

Catatan

Pertahankan refresh_token dengan aman sehingga aplikasi Anda tidak perlu meminta pengguna untuk mengotorisasi lagi. Token akses kedaluwarsa dengan cepat dan tidak boleh dipertahankan.

4. Gunakan token akses

Untuk menggunakan token akses, sertakan sebagai token pembawa di header Otorisasi permintaan HTTP Anda:

Authorization: Bearer {access_token}

Misalnya, permintaan HTTP untuk mendapatkan build terbaru untuk proyek:

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

5. Refresh token akses yang kedaluwarsa

Jika token akses pengguna kedaluwarsa, Anda dapat menggunakan token refresh yang mereka peroleh dalam alur otorisasi untuk mendapatkan token akses baru. Ini mirip dengan proses awal untuk menukar kode otorisasi dengan token akses dan refresh.

URL - token penyegaran

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

Header permintaan HTTP - refresh token

Kepala Halaman Nilai
Jenis-konten application/x-www-form-urlencoded
Panjang konten Panjang string terhitung dari isi permintaan (lihat contoh berikut) 
Content-Type: application/x-www-form-urlencoded
Content-Length: 1654

Isi permintaan HTTP - refresh token

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

Ganti nilai placeholder di badan permintaan sampel sebelumnya.

  • {0}: Rahasia klien yang dikodekan dalam URL diperoleh saat pendaftaran aplikasi
  • {1}: Token refresh yang dikodekan URL untuk pengguna
  • {2}: URL panggilan balik yang terdaftar di aplikasi

Respons - token penyegaran

{
    "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 }
}

Catatan

Token refresh baru dikeluarkan untuk pengguna. Pertahankan token baru ini dan gunakan saat berikutnya Anda perlu memperoleh token akses baru untuk pengguna.

Sampel

Anda dapat menemukan sampel C# yang mengimplementasikan OAuth untuk memanggil REST API Azure DevOps Services di Sampel GitHub C# OAuth kami.

Regenerasi kunci rahasia klien

Rahasia aplikasi secara teratur kedaluwarsa setiap 60 hari (per Maret 2025). Anda mungkin memiliki dua rahasia kapan saja. Terus buat dan gunakan token akses dan refresh token dengan memperbarui rahasia aplikasi Anda yang akan segera kedaluwarsa dengan rahasia aplikasi baru. Ini dapat dilakukan di halaman pendaftaran aplikasi di profil Visual Studio atau melalui API Rahasia Pendaftaran. Untuk menggunakan API, Anda harus menggunakan token akses Entra dengan vso.tokensruang lingkup.

  1. Buat rahasia sekunder dengan memilih "Hasilkan Rahasia" untuk "Rahasia 2". (Gunakan API Buat Rahasia Pendaftaran.)

Cuplikan layar halaman aplikasi dengan rahasia sekunder yang sudah dibuat.

  1. Selanjutnya, konfirmasikan di kotak dialog bahwa Anda ingin menyelesaikan tindakan tersebut.

Cuplikan layar mengonfirmasi regenerasi rahasia.

  1. Perbarui aplikasi Anda untuk menggunakan Rahasia baru #2 sebelum Rahasia #1 kedaluwarsa. Dengan mengelola dua rahasia sekaligus, tidak ada waktu henti bagi pengguna Anda sebagai akibat dari rahasia yang kedaluwarsa.

  2. Rahasia #1 secara alami kedaluwarsa dan semua token sebelumnya berhenti berfungsi.

  3. Ketika saatnya untuk memutar Rahasia #2 yang akan segera kedaluwarsa, Anda dapat mengulangi proses ini dengan meregenerasi Rahasia #1 dan menggunakan Rahasia yang diregenerasi #1 sebagai pengganti Rahasia #2. (Gunakan API Rahasia Pendaftaran Putar.)

Jika rahasia bocor, Anda dapat dengan cepat mencabut rahasia dengan mengklik "Regenerasi Rahasia". Setelah Anda mengonfirmasi bahwa Anda ingin meregenerasi, rahasia aplikasi sebelumnya tidak lagi berfungsi dan semua token sebelumnya yang ditambang dengan rahasia ini juga berhenti berfungsi. Gunakan metode rotasi rahasia ganda untuk meminimalkan waktu henti saat mencabut rahasia yang bocor melalui regenerasi.

Menghapus aplikasi Anda

Jika Anda tidak lagi memerlukan aplikasi, hapus dari profil Anda.

  1. Buka profil Anda di: https://app.vssps.visualstudio.com/profile/view.

  2. Pastikan Anda berada di halaman penyewa yang benar dengan memilih dari menu dropdown di bawah nama Anda di bilah samping.

  3. Temukan aplikasi di bawah header Aplikasi dan layanan di bilah sisi kiri.

  4. pilih "Hapus" pada halaman pendaftaran aplikasi. Sebuah modal muncul untuk mengonfirmasi penghapusan Anda.

    Cuplikan layar halaman metadata aplikasi dengan tombol hapus disorot

  5. Setelah Anda menghapus pendaftaran aplikasi, aplikasi berhenti, dan kami berhenti menambang token baru atau menerima token yang ditambang untuk aplikasi ini.

Pertanyaan Umum

T: Dapatkah saya menggunakan OAuth dengan aplikasi ponsel saya?

J: Tidak. Azure DevOps Services hanya mendukung alur server web, sehingga tidak ada cara untuk menerapkan OAuth, karena Anda tidak dapat menyimpan rahasia aplikasi dengan aman.

T: Kesalahan atau kondisi khusus apa yang perlu saya tangani dalam kode saya?

A: Pastikan Anda menangani kondisi berikut:

  • Jika pengguna Anda menolak akses aplikasi Anda, tidak ada kode otorisasi yang dikembalikan. Jangan gunakan kode otorisasi tanpa memeriksa penolakan.
  • Jika pengguna Anda mencabut otorisasi aplikasi Anda, token akses tidak lagi valid. Saat aplikasi Anda menggunakan token untuk mengakses data, kesalahan 401 akan kembali. Minta otorisasi lagi.

T: Saya ingin men-debug aplikasi web saya secara lokal. Dapatkah saya menggunakan localhost untuk URL panggilan balik saat mendaftarkan aplikasi saya?

J: Ya. Layanan Azure DevOps sekarang mengizinkan penggunaan localhost pada URL panggilan balik Anda. Pastikan Anda menggunakan https://localhost sebagai awal URL panggilan balik saat mendaftarkan aplikasi.

T: Saya mendapatkan kesalahan HTTP 400 ketika saya mencoba mendapatkan token akses. Apa yang mungkin salah?

A: Periksa apakah Anda mengatur jenis konten ke application/x-www-form-urlencoded di header permintaan Anda.

T: Saya mendapatkan kesalahan HTTP 401 saat menggunakan token akses berbasis OAuth, tetapi PAT dengan cakupan yang sama berfungsi dengan baik. Mengapa?

A: Verifikasi bahwa admin organisasi Anda tidak menonaktifkan akses aplikasi pihak ketiga melalui OAuth di https://dev.azure.com/{your-org-name}/_settings/organizationPolicy. Dalam skenario ini, alur untuk mengotorisasi aplikasi dan menghasilkan token akses berfungsi, tetapi semua REST API hanya mengembalikan kesalahan, seperti TF400813: The user "<GUID>" is not authorized to access this resource.