Bagikan melalui

Mengelola token akses pribadi (PATs) menggunakan REST API

  • Artikel

Azure DevOps

Ketika Anda berhadapan dengan sekumpulan besar token akses pribadi (PATs) yang Anda miliki, mungkin menjadi kompleks untuk mengelola pemeliharaan token ini menggunakan UI saja.

Dengan PAT Lifecycle Management API, Anda dapat mengelola PAT yang terkait dengan organisasi Anda menggunakan proses otomatis dengan mudah. Set API yang kaya ini memungkinkan Anda mengelola PAT, memungkinkan Anda membuat PAT baru dan memperbarui atau kedaluwarsa PATs yang ada.

Artikel ini memuat cara mengonfigurasi aplikasi yang mengautentikasi dengan token Microsoft Entra dan melakukan panggilan dengan API Siklus Hidup PAT. Jika Anda hanya ingin melihat daftar lengkap titik akhir yang tersedia, harap lihat referensi API di sini.

Prasyarat

  • Izin: Bergantung pada kebijakan keamanan penyewa Anda, aplikasi Anda mungkin memerlukan izin untuk mengakses sumber daya di organisasi. Saat ini, satu-satunya cara untuk melanjutkan menggunakan aplikasi ini di penyewa ini adalah dengan meminta administrator untuk memberikan izin ke aplikasi sebelum Anda dapat menggunakannya.

Catatan

Anda tidak dapat menggunakan perwakilan layanan atau identitas terkelola untuk membuat atau mencabut PAT.

Mengautentikasi dengan token Microsoft Entra

Tidak seperti API Azure DevOps Services lainnya, pengguna harus menyediakan token akses Microsoft Entra untuk menggunakan API ini alih-alih PAT. Token Microsoft Entra adalah mekanisme autentikasi yang lebih aman daripada menggunakan PATs. Mengingat kemampuan API ini untuk membuat dan mencabut PATs, kami ingin memastikan bahwa fungsionalitas canggih tersebut diberikan hanya kepada pengguna yang diizinkan.

Untuk memperoleh dan merefresh token akses Microsoft Entra, lakukan tugas berikut:

Penting

Solusi "Atas nama aplikasi" (seperti alur "kredensial klien"), dan alur autentikasi apa pun yang tidak mengeluarkan token akses Microsoft Entra tidak valid untuk digunakan dengan API ini. Jika autentikasi multifaktor diaktifkan di penyewa Microsoft Entra, Anda pasti harus menggunakan alur "kode otorisasi".

Setelah Anda memiliki aplikasi dengan alur autentikasi yang berfungsi untuk menangani token Microsoft Entra, Anda dapat menggunakan token ini untuk melakukan panggilan ke PAT Lifecycle Management API.

Untuk memanggil API secara langsung, berikan token akses Microsoft Entra sebagai Bearer token di Authorization header permintaan Anda. Untuk informasi selengkapnya dan daftar lengkap permintaan yang tersedia, lihat referensi PAT API.

Di bagian berikut, kami menunjukkan cara membuat aplikasi yang mengautentikasi pengguna dengan token akses Microsoft Entra. Aplikasi ini menggunakan pustaka Microsoft Authentication Library (MSAL) dan memanggil PAT Lifecycle Management API kami.

MSAL menyertakan beberapa alur autentikasi yang sesuai yang dapat Anda gunakan dalam aplikasi Anda untuk memperoleh dan menyegarkan token Microsoft Entra. Daftar lengkap alur MSAL dapat ditemukan di bawah dokumentasi alur autentikasi Pustaka Autentikasi Microsoft. Panduan untuk memilih metode autentikasi yang tepat untuk aplikasi Anda dapat ditemukan di bawah Memilih metode autentikasi yang tepat untuk Azure DevOps.

Untuk memulai, lihat salah satu contoh berikut:

Mengkloning aplikasi web Python Flask kami

Kami memberi Anda sampel aplikasi web Python Flask untuk API ini yang dapat Anda unduh di GitHub dan mengonfigurasi untuk digunakan dengan penyewa Microsoft Entra dan organisasi Azure DevOps Anda. Aplikasi sampel menggunakan alur kode autentikasi MSAL untuk memperoleh token akses Microsoft Entra.

Penting

Sebaiknya mulai menggunakan contoh aplikasi web Python Flask di GitHub, tetapi jika Anda lebih suka menggunakan bahasa atau jenis aplikasi yang berbeda, gunakan opsi Mulai Cepat untuk membuat ulang aplikasi pengujian yang setara.

Setelah Anda mengkloning aplikasi sampel, ikuti instruksi di README repositori. README menjelaskan cara mendaftarkan aplikasi di penyewa Microsoft Entra Anda, mengonfigurasi sampel untuk menggunakan penyewa Microsoft Entra Anda, dan menjalankan aplikasi kloning Anda.

Membuat aplikasi portal Azure Mulai Cepat

Sebagai gantinya, Anda dapat membuat aplikasi sampel dengan kode MSAL yang dihasilkan menggunakan opsi Mulai Cepat di halaman aplikasi di portal Azure. Aplikasi pengujian Mulai Cepat mengikuti alur kode otorisasi, tetapi melakukannya dengan titik akhir Microsoft Graph API. Pengguna perlu memperbarui konfigurasi aplikasi untuk menunjuk ke titik akhir untuk PAT Lifecycle Management API.

Untuk mengikuti pendekatan ini, ikuti instruksi Mulai Cepat untuk jenis aplikasi pilihan Anda di beranda dokumen Microsoft Entra ID Develop. Kami menelusuri contoh berikut dengan aplikasi Mulai Cepat Python Flask.

Contoh: Mulai menggunakan aplikasi Mulai Cepat Python Flask

  1. Setelah Anda mendaftarkan aplikasi Anda di penyewa Microsoft Entra yang memiliki langganan Azure aktif, navigasikan ke aplikasi terdaftar Anda di bawah Microsoft Entra ID ->Pendaftaran Aplikasi di portal Azure.

    Cuplikan layar memperlihatkan ID Microsoft Entra yang dibuka, Pendaftaran Aplikasi.

  2. Pilih aplikasi Anda dan navigasikan ke Izin API.

    Cuplikan layar memperlihatkan memilih aplikasi dan menavigasi ke Izin API.

  3. Pilih Tambahkan izin dan pilih Azure DevOps -> periksa user_impersonation -> pilih Tambahkan izin.

    Cuplikan layar memperlihatkan tambahkan izin Azure DevOps, user_impersonation.

  4. Pilih Mulai Cepat.

  5. Pilih jenis aplikasi Anda: untuk Python Flask, pilih Aplikasi web.

  6. Pilih platform aplikasi Anda. Untuk tutorial ini, pilih Python.

  7. Pastikan Anda memenuhi prasyarat yang diperlukan, lalu izinkan portal Azure untuk membuat perubahan yang diperlukan untuk mengonfigurasi aplikasi Anda. URL balasan adalah URL pengalihan yang diatur pada pembuatan aplikasi + "/getAToken".

    Cuplikan layar memperlihatkan mengizinkan portal Azure membuat perubahan yang diperlukan untuk mengonfigurasi aplikasi Anda.

  8. Unduh aplikasi Mulai Cepat dan ekstrak file.

    Cuplikan layar memperlihatkan pengunduhan aplikasi Mulai Cepat dan mengekstrak file.

  9. Instal persyaratan aplikasi dan jalankan aplikasi untuk memastikan Anda memiliki semua dependensi yang diperlukan. Aplikasi ini awalnya dikonfigurasi untuk mencapai titik akhir di Microsoft Graph API. Pelajari cara mengubah titik akhir ini ke titik akhir dasar API Lifecycle Management PAT dengan mengikuti instruksi konfigurasi di bagian berikut.

    Cuplikan layar memperlihatkan penginstalan persyaratan aplikasi dan menjalankan aplikasi.

Mengonfigurasi aplikasi Mulai Cepat

Setelah pengguna mengunduh dan menginstal aplikasi Mulai Cepat, aplikasi tersebut akan dikonfigurasi untuk menggunakan titik akhir API pengujian dari Microsoft Graph. Ubah file konfigurasi yang dihasilkan agar disebut PAT Lifecycle Management API sebagai gantinya.

Tip

Kami menggunakan koleksi dan organisasi secara bergantian dalam dokumen ini. Jika variabel konfigurasi memerlukan nama koleksi, ganti dengan nama organisasi Anda.

Lakukan tugas-tugas berikut:

  1. Memperbarui variabel konfigurasi TITIK AKHIR ke https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview untuk API Manajemen Siklus Hidup PAT
  2. Perbarui variabel konfigurasi CAKUPAN ke "499b84ac-1321-427f-aa17-267ca6975798/.default" untuk merujuk ke sumber daya Azure DevOps dan semua cakupannya.

Contoh berikut menunjukkan kepada Anda bagaimana kami melakukan konfigurasi ini untuk aplikasi Quickstart Python Flask yang kami buat melalui portal Azure di bagian sebelumnya.

Pastikan Anda mengikuti instruksi untuk mengamankan rahasia klien Anda, yang awalnya dimasukkan dalam teks biasa ke dalam file konfigurasi aplikasi. Sebagai praktik terbaik, hapus variabel teks biasa dari file konfigurasi dan gunakan variabel lingkungan atau Azure KeyVault untuk mengamankan rahasia aplikasi mereka.

Sebagai gantinya, Anda dapat memilih untuk menggunakan sertifikat alih-alih rahasia klien. Menggunakan sertifikat adalah opsi yang direkomendasikan jika aplikasi digunakan dalam produksi. Instruksi untuk menggunakan sertifikat dapat ditemukan di langkah terakhir penyiapan aplikasi Mulai Cepat.

Perhatian

Jangan pernah meninggalkan rahasia klien teks biasa dalam kode aplikasi produksi.

Contoh: Mengonfigurasi aplikasi Mulai Cepat Python Flask untuk API manajemen siklus hidup PAT

  1. Setelah Anda mengunduh aplikasi Mulai Cepat, instal dependensinya, dan uji bahwa aplikasi tersebut berjalan di lingkungan Anda, buka app_config.py file di editor pilihan Anda. File harus menyerupai cuplikan kode berikut; untuk kejelasan, komentar yang mereferensikan konfigurasi Microsoft Graph API default dihapus:

    import os

CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

CLIENT_SECRET = "YOUR_CLIENT_SECRET_HERE" 
# Placeholder - for use ONLY during testing.
# In a production app, we recommend you use a more secure method of storing your secret,
# like Azure Key Vault. Or, use an environment variable as described in Flask's documentation:
# https://flask.palletsprojects.com/en/1.1.x/config/#configuring-from-environment-variables
# CLIENT_SECRET = os.getenv("CLIENT_SECRET")
# if not CLIENT_SECRET:
#     raise ValueError("Need to define CLIENT_SECRET environment variable")

AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"  # For multi-tenant app
# AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"

REDIRECT_PATH = "/getAToken"  
# Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set
# in the app's registration in the Azure portal.

ENDPOINT = 'https://graph.microsoft.com/v1.0/users'  

SCOPE = ["User.ReadBasic.All"]

SESSION_TYPE = "filesystem"  
# Specifies the token cache should be stored in server-side session

  2. Perbarui ID klien atau rahasia klien ke aplikasi Anda dengan ID klien pendaftaran aplikasi dan rahasia klien Anda. Saat dalam produksi, pastikan untuk mengamankan rahasia klien dengan menggunakan variabel lingkungan, Azure KeyVault, atau dengan beralih ke sertifikat.

    CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

CLIENT_SECRET = "YOUR_CLIENT_SECRET_HERE" 
# Placeholder - for use ONLY during testing.
# In a production app, we recommend you use a more secure method of storing your secret.

  3. Ubah variabel ke ENDPOINT URL koleksi Azure DevOps dan titik akhir API Anda. Misalnya, untuk koleksi bernama "testCollection," nilainya adalah:

    # Fill in the url to the user's ADO collection + the PAT lifecycle management API endpoint here

ENDPOINT = 'https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview'

    Untuk koleksi bernama "testCollection," titik akhir ini adalah:

    ENDPOINT = 'https://vssps.dev.azure.com/testCollection/_apis/Tokens/Pats?api-version=6.1-preview'

  4. SCOPE Ubah variabel untuk mereferensikan sumber daya AZURE DevOps API; string karakter adalah ID sumber daya untuk AZURE DevOps API, dan cakupan mengacu pada semua cakupan untuk ID sumber daya tersebut.default.

    SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]

  5. Jika aplikasi Anda dikonfigurasi untuk penyewa tertentu (bukan konfigurasi multipenyewa), gunakan nilai alternatif untuk AUTHORITY variabel , menambahkan nama penyewa tertentu di "Enter_the_Tenant_Name_Here."

    # For single-tenant app:
AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"

# For multi-tenant app:
AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"

  6. Verifikasi bahwa file akhir app_config.py cocok dengan yang berikut ini, dengan CLIENT_ID, ID penyewa, dan URL koleksi Anda. Untuk alasan keamanan, pastikan bahwa CLIENT_SECRET dipindahkan ke variabel lingkungan, Azure KeyVault, atau ditukar dengan sertifikat untuk aplikasi terdaftar Anda:

    import os

CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

# Note that the CLIENT_SECRET has been removed and moved to an environment variable or Azure KeyVault

AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"  # For multi-tenant app
# AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"

REDIRECT_PATH = "/getAToken"  
# Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set in the app's registration in the Azure portal.

ENDPOINT = 'https://vssps.dev.azure.com/testCollection/_apis/Tokens/Pats?api-version=6.1-preview' 
# Used to configure user's collection URL and the desired API endpoint

SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
# Means "All scopes for the Azure DevOps API resource"

SESSION_TYPE = "filesystem"  
# Specifies the token cache should be stored in server-side session

  7. Jalankan ulang aplikasi untuk menguji bahwa Anda dapat MENDAPATKAN semua token PAT untuk pengguna yang meminta. Setelah diverifikasi, Anda dapat memodifikasi konten 'app.py' dan 'ms-identity-python-webapp-master\templates' direktori untuk mendukung pengiriman permintaan ke titik akhir API manajemen siklus hidup PAT lainnya. Untuk contoh aplikasi Mulai Cepat Python Flask yang dimodifikasi untuk mendukung permintaan ke semua titik akhir API manajemen siklus hidup PAT, lihat repositori sampel ini di GitHub.

Merefresh token akses Microsoft Entra secara otomatis

Setelah aplikasi dikonfigurasi dengan benar dan pengguna memperoleh token akses, token dapat digunakan hingga satu jam. Kode MSAL yang disediakan dalam kedua contoh sebelumnya secara otomatis me-refresh token setelah kedaluwarsa. Merefresh token mencegah pengguna perlu masuk lagi dan memperoleh kode otorisasi baru. Namun, pengguna mungkin perlu masuk lagi setelah 90 hari setelah token refresh mereka kedaluwarsa.

Menjelajahi API Manajemen Siklus Hidup PAT

Dalam aplikasi sampel GitHub sebelumnya dan aplikasi Mulai Cepat, aplikasi telah dikonfigurasi sebelumnya untuk membuat permintaan dengan token Microsoft Entra yang Anda peroleh. Untuk informasi selengkapnya, lihat dokumen Referensi API.

Pertanyaan Umum

T: Mengapa saya perlu mengautentikasi dengan token Microsoft Entra? Mengapa PAT tidak cukup?

A: Dengan PAT Lifecycle Management API ini, kami membuka kemampuan untuk membuat PAT baru dan mencabut PAT yang ada. Di tangan yang salah, aktor jahat dapat menggunakan API ini untuk membuat beberapa titik masuk ke sumber daya Azure DevOps organisasi Anda. Dengan memberlakukan autentikasi Microsoft Entra, kami berharap API yang kuat ini lebih aman terhadap penggunaan yang tidak sah ini.

T: Apakah saya harus memiliki penyewa Microsoft Entra dengan langganan Azure aktif untuk menggunakan API ini?

A: Sayangnya, API ini hanya tersedia untuk pengguna yang merupakan bagian dari penyewa Microsoft Entra dengan langganan Azure aktif.

T: Bisakah saya mendapatkan contoh aplikasi sampel ini untuk bahasa/kerangka kerja/jenis aplikasi lain?

A: Kami senang Anda ingin menggunakan API dalam bahasa pilihan Anda! Jika Anda memiliki permintaan untuk contoh, buka Komunitas Dev kami untuk melihat apakah orang lain memiliki contoh untuk dibagikan. Jika Anda memiliki aplikasi sampel yang ingin Anda bagikan ke audiens Azure DevOps yang lebih besar, beri tahu kami dan kami dapat mengedarkannya di dokumen ini secara lebih luas!

T: Apa perbedaan antara API token ini dan API admin token?

A: API token ini dan API admin token, meskipun serupa, melayani kasus penggunaan dan audiens yang berbeda:

  • API token ini sebagian besar untuk pengguna yang ingin mengelola PAT yang mereka miliki dalam alur otomatis. API ini memungkinkan. Ini memberi Anda kemampuan untuk membuat token baru dan memperbarui yang sudah ada.
  • API admin token dimaksudkan untuk admin organisasi. Admin dapat menggunakan API ini untuk mengambil dan mencabut otorisasi OAuth, termasuk token akses pribadi (PATs) dan token sesi yang menjelaskan sendiri, pengguna di organisasi mereka.

T: Bagaimana cara meregenerasi/memutar PAT melalui API? Saya melihat opsi itu di UI, tetapi saya tidak melihat metode serupa di API.

A: Pertanyaan besar! Fungsionalitas 'Regenerasi' yang tersedia di UI benar-benar menyelesaikan beberapa tindakan, yang sepenuhnya dapat direplikasi melalui API.

Untuk memutar PAT Anda, lakukan langkah-langkah berikut:

  1. Memahami metadata PAT menggunakan panggilan GET ,
  2. Buat PAT baru dengan metadata PAT lama menggunakan panggilan POST ,
  3. Mencabut PAT lama menggunakan panggilan DELETE

T: Saya melihat pop-up "Perlu persetujuan admin" saat saya mencoba melanjutkan menggunakan aplikasi ini. Bagaimana cara menggunakan aplikasi ini tanpa persetujuan admin?

A: Tampaknya penyewa Anda memiliki kebijakan keamanan, yang mengharuskan aplikasi Anda diberikan izin untuk mengakses sumber daya di organisasi. Saat ini, satu-satunya cara untuk melanjutkan menggunakan aplikasi ini di penyewa ini adalah dengan meminta admin untuk memberikan izin ke aplikasi sebelum Anda dapat menggunakannya.

T: Mengapa saya melihat kesalahan seperti "Perwakilan layanan tidak diizinkan untuk melakukan tindakan ini" ketika saya mencoba memanggil PAT Lifecycle Management API menggunakan Perwakilan Layanan atau Identitas Terkelola?

A: Perwakilan Layanan dan Identitas Terkelola tidak diizinkan. Mengingat kemampuan API ini untuk membuat dan mencabut PATs, kami ingin memastikan bahwa fungsionalitas canggih tersebut diberikan hanya kepada pengguna yang diizinkan.

Langkah berikutnya

Pelajari tentang titik akhir API manajemen siklus hidup PAT