REST API kullanarak kişisel erişim belirteçlerini (PAT) yönetme

Makale
05/15/2024

Azure DevOps Services

Sahip olduğunuz çok sayıda kişisel erişim belirteci (PAT) ile ilgilenirken, bu belirteçlerin bakımını yalnızca kullanıcı arabirimini kullanarak yönetmek karmaşık hale gelebilir.

PAT Lifecycle Management API'si sayesinde, otomatik işlemleri kullanarak kurumunuzla ilişkili PAT’leri kolayca yönetebilirsiniz. Bu zengin API kümesi, YENI kişisel erişim belirteçleri oluşturmanıza ve mevcut kişisel erişim belirteçlerini yenilemenize veya süresinin dolmasına olanak tanıyarak, PAT'lerinizi yönetmenize olanak tanır.

Bu makalede, Microsoft Entra belirteci ile kimlik doğrulaması yapan ve PAT Lifecycle API’siyle çağrı yapan bir uygulamayı yapılandırmayı göstereceğiz. Kullanılabilir uç noktaların tam listesini görmek isterseniz API başvurusunu burada görüntüleyin.

Önkoşullar

API'yi kullanmak için, Microsoft Entra Id OAuth aracılığıyla yapabileceğiniz bir Microsoft Entra belirteci ile kimlik doğrulaması yapmanız gerekir. Daha fazla bilgi için kimlik doğrulama bölümüne bakın.

Etkin bir Azure aboneliğine sahip bir Microsoft Entra kiracınız olmalıdır .
Kiracınızın güvenlik ilkelerine bağlı olarak, uygulamanızın kuruluştaki kaynaklara erişmek için izinlere ihtiyacı olabilir. Şu anda, bu uygulamayı bu kiracıda kullanmaya devam etmenin tek yolu, kullanmadan önce yöneticiden uygulamaya izin vermesini istemektir.

Not

HIZMET sorumlularını veya yönetilen kimlikleri, PAT'leri oluşturmak veya iptal etmek için kullanamazsınız.

Microsoft Entra belirteçleriyle kimlik doğrulaması

Diğer Azure DevOps Services API'lerinden farklı olarak, kullanıcıların PAT belirteci yerine bu API'yi kullanmak için bir Microsoft Entra erişim belirteci sağlaması gerekir. Microsoft Entra belirteçleri, PAT kullanmaktan daha güvenli bir kimlik doğrulama mekanizmasıdır. Bu API'nin PAT oluşturma ve iptal etme özelliği göz önünde bulundurulduğunda, bu tür güçlü işlevlerin yalnızca izin verilen kullanıcılara verildiğinden emin olmak istiyoruz.

Microsoft Entra erişim belirteçlerini almak ve yenilemek için şunları gerçekleştirmelisiniz:

Önemli

"Uygulama adına" çözümleri ("istemci kimlik bilgileri" akışı gibi) ve Microsoft Entra erişim belirteci vermeyen herhangi bir kimlik doğrulama akışı bu API ile kullanım için geçerli değildir. Microsoft Entra kiracınızda çok faktörlü kimlik doğrulaması etkinleştirildiyse kesinlikle "yetkilendirme kodu" akışını kullanmanız gerekir.

Dikkat

Etkin bir Azure aboneliğine sahip bir Microsoft Entra kiracısı olması, bu API'yi kullanmak için bir önkoşuldur.

Microsoft Entra belirteçlerini işlemek için çalışan bir kimlik doğrulama akışına sahip bir uygulamanız olduğunda, PAT Yaşam Döngüsü Yönetimi API'sine çağrı yapmak için bu belirteçleri kullanabilirsiniz.

API'yi doğrudan çağırmak için, isteğinizin üst bilgisinde Authorization belirteç olarak bir Bearer Microsoft Entra erişim belirteci sağlamanız gerekir. Örnekleri ve kullanılabilir isteklerin tam listesini görmek için PAT API başvurusuna bakın.

Aşağıdaki bölümde, MSAL kitaplığını kullanarak Microsoft Entra erişim belirteciyle kullanıcının kimliğini doğrulayan ve PAT Yaşam Döngüsü Yönetimi API'mizi çağıran bir uygulamanın nasıl oluşturulacağını göstereceğiz.

Microsoft Kimlik Doğrulama Kitaplığı (MSAL), Microsoft Entra belirteçlerini almak ve yenilemek için uygulamanızda kullanabileceğiniz birden çok uyumlu kimlik doğrulama akışı içerir. MSAL akışlarının tam listesi Microsoft Authentication Library kimlik doğrulama akışları belgeleri altında bulunabilir. Uygulamanız için doğru kimlik doğrulama yöntemini seçme kılavuzu, Azure DevOps için doğru kimlik doğrulama yöntemini seçme bölümünde bulunabilir.

Başlamak için iki örnekten birini izleyin:

Örnek Python Flask uygulamamızı kopyalayın ve kiracınız ve ADO kuruluşunuzla yapılandırın
Azure portalında tercih ettiğiniz dil için örnek bir uygulama oluşturun ve PAT Yaşam Döngüsü Yönetimi API'si için yapılandırın

Python Flask web uygulamamızı kopyalama

Bu API için GitHub'dan indirebileceğiniz ve Microsoft Entra kiracınız ve Azure DevOps kuruluşunuzla kullanmak üzere yapılandırabileceğiniz örnek bir Python Flask web uygulaması sağladık. Örnek uygulama, Bir Microsoft Entra erişim belirteci almak için MSAL kimlik doğrulama kodu akışını kullanır.

Önemli

GitHub'da örnek Python Flask web uygulamasını kullanmaya başlamanızı öneririz, ancak farklı bir dil veya uygulama türü kullanmayı tercih ediyorsanız, eşdeğer bir test uygulamasını yeniden oluşturmak için Hızlı Başlangıç seçeneğini kullanın.

Örnek uygulamayı kopyaladıktan sonra deponun BENİOKU başlığındaki yönergeleri izleyin. README, bir uygulamayı Microsoft Entra kiracınıza kaydetmeyi, örneği Microsoft Entra kiracınızı kullanacak şekilde yapılandırmayı ve kopyalanan uygulamanızı çalıştırmayı açıklar.

Hızlı Başlangıç Azure portalı uygulaması oluşturma

Bunun yerine, Azure portalındaki uygulamanın sayfasındaki Hızlı Başlangıç seçeneğini kullanarak oluşturulan MSAL koduyla örnek bir uygulama oluşturabilirsiniz. Hızlı Başlangıç test uygulaması yetkilendirme kodu akışını izler, ancak bunu bir Microsoft Graph API uç noktasıyla yapar. Kullanıcıların PAT Yaşam Döngüsü Yönetimi API'sinin uç noktasına işaret etmek için uygulamanın yapılandırmasını güncelleştirmeleri gerekir.

Bu yaklaşımı izlemek için Microsoft Entra ID Develop docs giriş sayfasında seçtiğiniz uygulama türüne yönelik Hızlı Başlangıç yönergelerini izleyin. Python Flask Hızlı Başlangıç uygulamasıyla aşağıdaki örneği inceleyeceğiz.

Örnek: Python Flask Hızlı Başlangıç uygulamasını kullanmaya başlama

Uygulamanızı etkin bir Azure aboneliği olan bir Microsoft Entra kiracısına kaydettikten sonra, Azure portalında Microsoft Entra Id ->App Registrations altında kayıtlı uygulamanıza gidin.
Uygulamanızı seçin ve API İzinleri'ne gidin.
İzin ekle'yi seçin ve Azure DevOps -> user_impersonation denetle -> İzin ekle'yi seçin.
Hızlı Başlangıç'ı seçin.
Uygulama türünüzü seçin: Python Flask için Web uygulaması'yı seçin.
Uygulama platformunuzu seçin. Bu öğretici için Python'ı seçin.
Gerekli önkoşulları karşıladığınızdan emin olun, ardından Azure portalının uygulamanızı yapılandırmak için gerekli değişiklikleri yapmasına izin verin. Yanıt URL'si, uygulama oluşturma + "/getAToken" sırasında ayarlanan yeniden yönlendirme URL'sidir.
Hızlı Başlangıç uygulamasını indirin ve dosyaları ayıklayın.
Tüm gerekli bağımlılıklara sahip olduğunuzdan emin olmak için uygulama gereksinimlerini yükleyin ve uygulamayı çalıştırın. Uygulama başlangıçta Microsoft Graph API'sindeki bir uç noktaya isabet etmek üzere yapılandırılır. Aşağıdaki bölümde yer alan yapılandırma yönergelerini izleyerek bu uç noktayı PAT Yaşam Döngüsü Yönetimi API'sinin temel uç noktası olarak değiştirmeyi öğrenin.

Hızlı Başlangıç uygulaması yapılandırma

Kullanıcı Hızlı Başlangıç uygulamasını indirip yükledikten sonra, Microsoft Graph'tan bir test API uç noktası kullanacak şekilde yapılandırılır. Bunun yerine pat Yaşam Döngüsü Yönetimi API'sini çağırması için oluşturulan yapılandırma dosyasını değiştirmemiz gerekir.

İpucu

Koleksiyonu ve kuruluşu bu belgelerde birbirinin yerine kullanırız. Bir yapılandırma değişkeninin koleksiyon adına ihtiyacı varsa, lütfen bunu kuruluşunuzun adıyla değiştirin.

Aşağıdaki görevleri gerçekleştirin:

PAT Yaşam Döngüsü Yönetimi API'leri https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview için ENDPOINT yapılandırma değişkenini olarak güncelleştirin
KAPSAM yapılandırma değişkenini "499b84ac-1321-427f-aa17-267ca6975798/.default" olarak güncelleştirerek Azure DevOps kaynağına ve tüm kapsamlarına başvurun.

Aşağıdaki örnekte, önceki bölümde Azure portalı aracılığıyla oluşturduğumuz Hızlı Başlangıç Python Flask uygulaması için bu yapılandırmayı nasıl yaptığımız gösterilmektedir.

İlk olarak uygulama yapılandırma dosyasına düz metin olarak eklenen istemci gizli dizinizin güvenliğini sağlamak için yönergeleri izlediğinizden emin olun. En iyi yöntem olarak, yapılandırma dosyasından düz metin değişkenini kaldırın ve bir ortam değişkeni veya Azure KeyVault kullanarak uygulamanın gizli dizisini koruyun.

Bunun yerine, istemci gizli dizisi yerine sertifika kullanmayı seçebilirsiniz. Uygulama üretimde kullanılacaksa, önerilen seçenek sertifikaları kullanmaktır. Sertifika kullanma yönergeleri, Hızlı Başlangıç uygulaması kurulumunun son adımında bulunabilir.

Dikkat

Üretim uygulama kodunda hiçbir zaman düz metin istemci gizli dizisi bırakmayın.

Örnek: PAT yaşam döngüsü yönetimi API'si için Python Flask Hızlı Başlangıç uygulaması yapılandırma

Hızlı Başlangıç uygulamanızı indirdikten, bağımlılıklarını yükledikten ve ortamınızda çalıştığını test ettikten sonra dosyayı istediğiniz düzenleyicide açın app_config.py . Dosya aşağıdaki kod parçacığına benzemelidir; Netlik sağlamak için, varsayılan Microsoft Graph API yapılandırmasına başvuran açıklamalar kaldırıldı:

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

Uygulama kaydınızın istemci kimliği ve istemci gizli anahtarı ile uygulamanıza istemci kimliğini veya gizli dizisini güncelleştirin. Üretim sırasında, bir ortam değişkeni olan Azure KeyVault'ı kullanarak veya bir sertifikaya geçerek istemci gizli dizisinin güvenliğini sağladığından emin olun.
```
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.
```

Değişkenini ENDPOINT Azure DevOps koleksiyon URL'niz ve API uç noktanızla değiştirin. Örneğin, "testCollection" adlı bir koleksiyon için değer şöyle olacaktır:

# 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'

"testCollection" adlı bir koleksiyon için bu uç nokta şöyle olacaktır:

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

Değişkenini SCOPE Azure DevOps API kaynağına başvurmak üzere değiştirin; karakter dizesi Azure DevOps API'sinin kaynak kimliğidir ve ".default" kapsamı bu kaynak kimliğinin tüm kapsamlarını ifade eder.
```
SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
```
Uygulamanız belirli bir kiracı için yapılandırılmışsa (çok kiracılı yapılandırma yerine), değişken için AUTHORITY alternatif değeri kullanın ve "Enter_the_Tenant_Name_Here" alanına belirli kiracı adını ekleyin.
```
# 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"
```

Son app_config.py dosyanın aşağıdakiyle eşleşip eşleşmediğini CLIENT_ID, kiracı kimliğiniz ve koleksiyon URL'nizle doğrulayın. Güvenlik nedeniyle, CLIENT_SECRET bir ortam değişkenine (Azure KeyVault) taşındığından veya kayıtlı uygulamanız için bir sertifikayla değiştirildiğinden emin olun:

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

İstekte bulunan kullanıcının tüm PAT belirteçlerini alabildiğinizi test etmek için uygulamayı yeniden çalıştırın. Doğrulandıktan sonra, PAT yaşam döngüsü yönetimi API uç noktalarının geri kalanına istek göndermeyi desteklemek için ve 'ms-identity-python-webapp-master\templates' dizinin içeriğini 'app.py' değiştirebilirsiniz. Tüm PAT yaşam döngüsü yönetimi API uç noktalarına yönelik istekleri destekleyecek şekilde değiştirilmiş bir Python Flask Hızlı Başlangıç uygulaması örneği için GitHub'da bu örnek depoya bakın.

Microsoft Entra erişim belirtecini otomatik olarak yenileme

Uygulama doğru yapılandırıldıktan ve kullanıcı bir erişim belirteci aldıktan sonra belirteç bir saate kadar kullanılabilir. Önceki her iki örnekte de sağlanan MSAL kodu, süresi dolduğunda belirteci otomatik olarak yeniler. Belirtecin yenilenmesi, kullanıcının yeniden oturum açması ve yeni bir yetkilendirme kodu almasına gerek duymasını önler. Ancak, yenileme belirtecinin süresi dolduktan sonra kullanıcıların 90 gün sonra yeniden oturum açması gerekebilir.

PAT Yaşam Döngüsü Yönetimi API'lerini keşfetme

Yukarıdaki GitHub örnek uygulamasında ve Hızlı Başlangıç uygulamalarında uygulama, edindiğiniz Microsoft Entra belirteçleriyle istekte bulunmak için önceden yapılandırılmıştır. Daha fazla bilgi için bkz . API Başvurusu belgeleri.

Sık sorulan sorular (SSS)

S: Neden Bir Microsoft Entra belirteci ile kimlik doğrulaması yapmam gerekiyor? PAT neden yeterli değildir?

Y: Bu PAT Yaşam Döngüsü Yönetimi API'siyle yeni PTS oluşturma ve mevcut PAT'ları iptal etme özelliğini açtık. Kötü amaçlı aktörler, kuruluşunuzun Azure DevOps kaynaklarına birden çok giriş noktası oluşturmak için bu API'yi yanlış ellerde kullanabilir. Microsoft Entra kimlik doğrulamasını zorunlu kılarak, bu güçlü API'nin bu yetkisiz kullanıma karşı daha güvenli olmasını umuyoruz.

S: Bu API'yi kullanmak için etkin bir Azure aboneliğine sahip bir Microsoft Entra kiracım olması gerekir mi?

Y: Ne yazık ki, bu API yalnızca etkin bir Azure aboneliğine sahip bir Microsoft Entra kiracısının parçası olan kullanıcılar tarafından kullanılabilir.

S: Başka bir dil/çerçeve/uygulama türü için bu örnek uygulamanın bir örneğini alabilir miyim?

Y: API'yi istediğiniz dilde kullanmak istemenizi çok isteriz! Bir örnek için bir isteğiniz varsa, başka birinin paylaşacak bir örneği olup olmadığını görmek için Geliştirme Topluluğumuza gidin. Daha büyük Azure DevOps hedef kitlesiyle paylaşmak istediğiniz örnek bir uygulamanız varsa bize bildirin ve bu belgelerde daha geniş bir şekilde dolaşıma sokabiliriz!

S: Bu belirteç API'si ile belirteç yöneticisi API'si arasındaki fark nedir?

Y: Bu belirteç API'si ve belirteç yöneticisi API'si benzer olsa da farklı kullanım örneklerine ve hedef kitlelere hizmet eder:

Bu belirteç API'leri büyük ölçüde otomatik işlem hattında sahip oldukları PAT'leri yönetmek isteyen kullanıcılar içindir. Bu API izin verir. Yeni belirteçler oluşturma ve mevcut belirteçleri güncelleştirme olanağı sağlar.
Belirteç yöneticisi API'sinin amacı kuruluş yöneticileridir. Yönetici, kuruluşlarındaki kullanıcıların kişisel erişim belirteçleri (PAT) ve kendi kendini açıklayan oturum belirteçleri dahil olmak üzere OAuth yetkilendirmelerini almak ve iptal etmek için bu API'yi kullanabilir.

S: API aracılığıyla PAT'leri nasıl yeniden oluşturabilir/döndürebilirim? Kullanıcı arabiriminde bu seçeneği gördüm, ancak API'de benzer bir yöntem görmüyorum.

Y: Harika bir soru! Kullanıcı arabiriminde bulunan 'Yeniden Oluştur' işlevi aslında API aracılığıyla tamamen çoğaltılabilir birkaç eylem gerçekleştirir.

PAT'nizi döndürmek için aşağıdaki adımları uygulayın:

GET çağrısı kullanarak PAT'nin meta verilerini anlayın,
POST çağrısı kullanarak eski PAT'nin meta verileriyle yeni bir PAT oluşturun,
DELETE çağrısı kullanarak eski PAT'yi iptal etme

S: Bu uygulamayı kullanmaya devam etmeye çalıştığımda "Yönetici onayı gerekiyor" açılır penceresi görüyorum. Bu uygulamayı yönetici onayı olmadan nasıl kullanabilirim?

Y: Kiracınızın, uygulamanıza kuruluştaki kaynaklara erişim izinleri verilmesini gerektiren güvenlik ilkeleri var gibi görünüyor. Şu anda, bu uygulamayı bu kiracıda kullanmaya devam etmenin tek yolu, kullanmadan önce yöneticiden uygulamaya izin vermesini istemektir.

S: Hizmet Sorumlusu veya Yönetilen Kimlik kullanarak PAT Yaşam Döngüsü Yönetimi API'sini çağırmaya çalıştığımda neden "Hizmet sorumlularının bu eylemi gerçekleştirmesine izin verilmiyor" gibi bir hata görüyorum?

Y: Hizmet Sorumlularına ve Yönetilen Kimliklere izin verilmez. Bu API'nin PAT oluşturma ve iptal etme özelliği göz önünde bulundurulduğunda, bu tür güçlü işlevlerin yalnızca izin verilen kullanıcılara verildiğinden emin olmak istiyoruz.

Sonraki adımlar

PAT yaşam döngüsü yönetimi API uç noktaları hakkında bilgi edinin

Aracılığıyla paylaş