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

Azure DevOps Services

büyük bir kişisel erişim belirteci (PAT) kümesine sahip olduğunuzda, yalnızca kullanıcı arabirimini kullanarak bu belirteçlerin bakımını 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, PAT'lerinizi yönetmenize olanak tanıyarak yeni PAT'ler oluşturmanıza ve mevcut PAT'leri yenilemenize veya süresinin dolmasına olanak tanır.

Bu makalede, bir Microsoft Entra belirteci ile kimlik doğrulaması yapan ve PAT Yaşam Döngüsü API'siyle çağrı yapan bir uygulamanın nasıl yapılandırıldığını göstereceğiz.

Önkoşullar

Diğer Azure DevOps Services API'lerinden farklı olarak, kullanıcıların bu API'yi kullanmak için bir Microsoft Entra erişim belirteci sağlaması gerekir. 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ızcadaha güvenli Microsoft Entra belirteçleri için kullanılabildiğinden emin olmak istiyoruz.

Microsoft Entra erişim belirteçlerini almak ve yenilemek için aşağıdakileri yapmanız gerekir:

• Etkin Azure aboneliğine sahip bir Microsoft Entra kiracısı olması
• Bir uygulamayı Microsoft Entra kiracısına kaydetme
• Uygulamaya Azure DevOps izinleri ekleme
• Kiracı yöneticisinden onay alma: Kiracınızın güvenlik ilkelerine bağlı olarak, uygulamanızın kuruluştaki kaynaklara erişmek için izinlere ihtiyacı olabilir. Bir kiracı yöneticisinden uygulamaya kiracınızda kullanma izni vermesini isteyin.

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 Bearer belirteç olarak bir Authorization Microsoft Entra erişim belirteci sağlayın. Daha fazla bilgi ve kullanılabilir isteklerin tam listesi için PAT API başvurusuna bakın.

Aşağıdaki bölümde, Microsoft Entra erişim belirteci ile kullanıcının kimliğini doğrulayan bir uygulamanın nasıl oluşturulacağını göstereceğiz. Uygulama, Microsoft Authentication Library (MSAL) kullanır ve PAT Yaşam Döngüsü Yönetimi API'mizi çağırır.

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, Microsoft Entra erişim belirtecini almak için MSAL yetkilendirme kodu akışı kullanır.

Ö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.

1. Uygulamanızı etkin bir Azure aboneliğine sahip bir Microsoft Entra kiracısına kaydettikten sonra, Azure portalında> -Uygulama Kayıtları altında tescilli uygulamanıza gidin.

   

2. Uygulamanızı seçin ve API İzinleri'ne gidin.

   

3. İzin ekle'yi seçin ve Azure DevOps'u seçin -> ihtiyacınız olan uygun kapsamları seçin. Bu durumda, PAT Yaşam Döngüsü Yönetimi API'leri yalnızca user_impersonationdestekler, ancak diğer API'ler her API'ninayrı başvuru sayfasında bulabileceğiniz farklı daha ayrıntılı kapsamlar isteyebilir. Tüm kapsamlar seçildikten sonra İzin ekle'yetıklayın.

   

4. Hızlı Başlangıç'ı seçin.

5. Uygulama türünüzü seçin: Python Flask için Web uygulaması'yı seçin.

6. Uygulama platformunuzu seçin. Bu öğretici için Python'ı seçin.

7. 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.

   

8. Hızlı Başlangıç uygulamasını indirin ve dosyaları ayıklayın.

   

9. 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. Oluşturulan yapılandırma dosyasını, bunun yerine PAT Yaşam Döngüsü Yönetimi API'sini çağıracak şekilde değiştirin.

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

1. yapılandırma değişkenini olarak güncelleştirin
2. 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ılıyorsa, sertifikaların kullanılması önerilen seçenektir. Sertifika kullanma yönergeleri, Hızlı Başlangıç uygulaması kurulumunun son adımında bulunabilir.

1. 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
   

2. 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.
   

3. 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'
   

4. Değişkenini SCOPE Azure DevOps API kaynağına başvuracak şekilde değiştirin; karakter dizesi Azure DevOps API'sinin kaynak kimliğidir ve kapsam bu kaynak kimliğinin .default tüm kapsamlarını ifade eder.

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

5. 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"
   

6. 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
   

7. İ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 'app.py' dizinin içeriğini 'ms-identity-python-webapp-master\templates' 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.

Sık sorulan sorular (SSS)

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

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?

Bu belirteç API'sini ve belirteç yöneticisi API'sini, benzer şekilde 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öneticiler, 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.

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:

1. GET çağrısı kullanarak PAT'nin meta verilerini anlayın,
2. POST çağrısı kullanarak eski PAT'nin meta verileriyle yeni bir PAT oluşturun,
3. 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?

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.