Menggunakan Azure DevOps OAuth 2.0 untuk membuat aplikasi web
Azure DevOps
Penting
Informasi ini hanya untuk aplikasi Azure DevOps OAuth yang ada. Pengembang aplikasi baru harus menggunakan Microsoft Entra ID OAuth untuk berintegrasi dengan Azure DevOps.
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
https://app.vsaex.visualstudio.com/app/registerBuka untuk mendaftarkan aplikasi Anda.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.
Pilih Buat aplikasi.
Halaman pengaturan aplikasi ditampilkan.
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.
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.
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
- 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}
| Parameter | Tipe | Catatan |
|---|---|---|
| client_id | GUID | ID yang ditetapkan ke aplikasi Anda saat terdaftar. |
| response_type | string | Assertion |
| state | string | Dapat berupa nilai apa pun. Biasanya nilai string yang dihasilkan yang menghubungkan panggilan balik dengan permintaan otorisasi terkait. |
| cakupan | string | Cakupan yang terdaftar di aplikasi. Spasi dipisahkan. Lihat cakupan yang tersedia. |
| redirect_uri | URL | URL panggilan balik untuk aplikasi Anda. Harus sama persis dengan URL yang terdaftar di aplikasi. |
- 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=88e2dd5f-4e34-45c6-a75d-524eb2a0399e
&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 layanan ke layanan ke Layanan Azure DevOps.
URL - mengotorisasi aplikasi
POST https://app.vssps.visualstudio.com/oauth2/token
Header permintaan HTTP - mengotorisasi aplikasi
| Header | Value |
|---|---|
| Content-Type | 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 tempat penampung di isi permintaan sampel sebelumnya:
- {0}: Rahasia klien yang dikodekan URL diperoleh ketika aplikasi terdaftar
- {1}: URL yang dikodekan "kode" yang disediakan melalui
codeparameter kueri 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 }
}
Penting
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 seperti proses asli untuk bertukar kode otorisasi untuk akses dan token refresh.
URL - refresh token
POST https://app.vssps.visualstudio.com/oauth2/token
Header permintaan HTTP - refresh token
| Header | Value |
|---|---|
| Content-Type | 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 tempat penampung di isi permintaan sampel sebelumnya:
- {0}: Rahasia klien yang dikodekan URL diperoleh ketika aplikasi terdaftar
- {1}: Token refresh yang dikodekan URL untuk pengguna
- {2}: URL panggilan balik yang terdaftar di aplikasi
Respons - refresh token
{
"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 }
}
Penting
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.
Meregenerasi rahasia klien
Setiap 5 tahun, rahasia aplikasi Anda akan kedaluwarsa. Anda diharapkan untuk meregenerasi rahasia aplikasi Anda untuk terus dapat membuat dan menggunakan token akses dan token refresh. Untuk melakukannya, Anda dapat mengklik tombol "Regenerasi rahasia", yang akan memunculkan dialog untuk mengonfirmasi bahwa Anda ingin menyelesaikan tindakan ini.
Ketika Anda mengonfirmasi bahwa Anda ingin meregenerasi, rahasia aplikasi sebelumnya tidak akan lagi berfungsi dan semua token sebelumnya yang ditambang dengan rahasia ini juga akan berhenti berfungsi. Pastikan untuk meluangkan waktu rotasi rahasia klien ini dengan baik untuk meminimalkan waktu henti pelanggan.
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 localhost di 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 akses aplikasi pihak ketiga melalui OAuth tidak dinonaktifkan oleh admin organisasi Anda 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.
T: Dapatkah saya menggunakan OAuth dengan titik akhir SOAP dan REST API?
J: Tidak. OAuth hanya didukung di REST API pada saat ini.
T: Bagaimana cara mendapatkan detail lampiran untuk item kerja saya menggunakan REST API Azure DevOps?
A: Pertama, dapatkan detail item kerja dengan Item kerja - Dapatkan REST API item kerja:
GET https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}
Untuk mendapatkan detail lampiran, Anda perlu menambahkan parameter berikut ke URL:
$expand=all
Dengan hasilnya, Anda mendapatkan properti relasi. Di sana Anda dapat menemukan URL lampiran, dan di dalam URL Anda dapat menemukan ID. Misalnya:
$url = https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/434?$expand=all&api-version=5.0
$workItem = Invoke-RestMethod -Uri $url -Method Get -ContentType application/json
$split = ($workitem.relations.url).Split('/')
$attachmentId = $split[$split.count - 1]
# Result: 1244nhsfs-ff3f-25gg-j64t-fahs23vfs
Artikel terkait
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk