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

Azure DevOps Services

Sahip olduğunuz büyük bir kişisel erişim belirteçleri (PATs) ile ilgilenirken, bu belirteçlerin yalnızca Kullanıcı arabirimini kullanarak bakımının yönetilmesi karmaşık hale gelebilir.

PAT yaşam döngüsü yönetim API 'SI ile otomatikleştirilmiş süreçler kullanarak kuruluşlarınız ile ilişkili patları kolayca yönetebilirsiniz. Bu zengin API kümesi, size ait olan PATs 'Leri yönetmenize olanak tanıyarak, yeni kişisel erişim belirteçleri oluşturmanıza ve mevcut kişisel erişim belirteçlerini yenilemenize veya bu belirteçleri sona Ermenize olanak tanır.

bu makalede, Azure Active Directory (Azure AD) belirteciyle kimlik doğrulaması yapan bir uygulamayı nasıl yapılandıracağınızı ve PAT yaşam döngüsü apı 'si ile çağrı yapmayı göstereceğiz. Yalnızca kullanılabilir uç noktaların tam listesini görmek isterseniz, API başvurusunu buradan görüntüleyin.

Önkoşullar

API 'yi kullanmak için bir Azure AD belirteciyle kimlik doğrulaması yapmanız gerekir. Aşağıdaki kimlik doğrulama bölümündebunun nasıl yapılacağı hakkında daha fazla bilgi edinin.

Bunu yapmak için birkaç önkoşulların karşılanması gerekir:

• Etkin bir Azure aboneliğine sahip bir Azure AD kiracısına sahip olmanız gerekir.
• Kiracınızın güvenlik ilkelerine bağlı olarak, uygulamanıza kuruluştaki kaynaklara erişmek için izin verilmesi gerekebilir. Bu anda bu uygulamada bu uygulamayı kullanmaya devam etmenin tek yolu, bir yöneticiden kullanabilmeniz için uygulamaya izin vermesini ister.

Azure Active Directory (Azure AD) belirteçleriyle kimlik doğrulama

diğer Azure DevOps Services apı 'lerinin aksine, kullanıcıların bir PAT belirteci yerine bu apı 'yi kullanmak için bir Azure AD erişim belirteci sağlaması gerekir. Azure AD belirteçleri, PATs kullanmaktan daha güvenli bir kimlik doğrulama mekanizmasıdır. Bu API 'nin PATs oluşturma ve iptal etme özelliği verildiğinde, bu tür güçlü işlevlerin yalnızca izin verilen kullanıcılara verildiğinden emin olmak istiyoruz.

Microsoft kimlik doğrulama kitaplığı (MSAL), uygulamanız dahilinde Azure AD belirteçlerini almak ve yenilemek için kullanabileceğiniz birden fazla uyumlu kimlik doğrulama akışı içerir. "Kimlik doğrulama akışları" belgelerinde, Microsoft kimlik doğrulama kitaplığı "altında bulunan tüm msal akışlarının listesini bulabilirsiniz. Uygulamanız için doğru kimlik doğrulama yöntemini seçmeye yönelik bir kılavuz, Azure DevOps için doğru kimlik doğrulama yöntemi seçme altında bulunabilir.

Azure AD erişim belirteçlerini otomatik olarak almak ve yenilemek üzere MSAL kitaplığını kullanmak için şunları yapmanız gerekir:

• Etkin bir Azure aboneliğine sahip bir Azure AD kiracısına sahip olmanız
• Bir uygulamayı Azure AD kiracısına kaydetme
• uygulamaya Azure DevOps izinleri ekleme

Azure AD belirteçlerini işlemek için çalışan bir kimlik doğrulama akışına sahip bir uygulamanız olduğunda, bu belirteçleri kullanarak PAT yaşam döngüsü yönetim API 'sine çağrılar yapabilirsiniz. Aşağıdaki bölümde, MSAL kitaplığını kullanarak bir Azure AD erişim belirtecine sahip bir kullanıcının kimliğini doğrulayan ve PAT yaşam döngüsü yönetim API 'imizi çağıran bir uygulama oluşturmayı göstereceğiz.

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

• Örnek Python Flask uygulamanızı kopyalayın ve KIRACı ve ADO kuruluşunuzla yapılandırın
• Seçtiğiniz diliniz için Azure Portal örnek bir uygulama oluşturun ve bunu Pat yaşam döngüsü yönetim API 'si için yapılandırın

Python Flask Web uygulamanızı kopyalayın

bu apı için GitHub indirebileceğiniz ve Azure AD kiracınızla ve Azure DevOps kuruluşunuzla kullanılmak üzere yapılandırılabileceğiniz örnek bir Python flask web uygulaması sunuyoruz. Örnek uygulama, bir Azure AD erişim belirteci almak için MSAL kimlik doğrulaması kod akışını kullanır.

Örnek uygulamayı klonladıktan sonra, deponun BENIOKU dosyasındaki yönergeleri izleyin. BENIOKU dosyasında, Azure AD kiracınızda bir uygulamanın nasıl kaydedileceği, Azure AD kiracınızı kullanmak için örnek yapılandırmanın nasıl yapılandırılacağı ve klonlanmış uygulamanızı nasıl çalıştırılacağı açıklanmaktadır.

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

Bunun yerine, Azure Portal' deki uygulama sayfasındaki hızlı başlangıç seçeneğini kullanarak oluşturulan msal kodu ile örnek bir uygulama oluşturabilirsiniz. hızlı başlangıç test uygulaması yetkilendirme kodu akışını izler, ancak bunu bir Microsoft Graph apı uç noktası ile yapar. Kullanıcıların, PAT yaşam döngüsü yönetim API 'SI için uç noktayı işaret edecek şekilde uygulamanın yapılandırmasını güncelleştirmesi gerekir.

Bu yaklaşımı izlemek için, Azure AD geliştirme belgeleri girişsayfasında seçtiğiniz uygulama türüne yönelik hızlı başlangıç yönergelerini izleyin. Bunu bir Python Flask hızlı başlangıç uygulaması için yaptığımız bir örnek adım adım göstereceğiz.

Örnek: Python Flask hızlı başlangıç uygulaması ile çalışmaya başlama

1. uygulamanızı etkin bir azure aboneliğine sahip bir azure AD kiracısında kaydettikten sonra, Azure portal Azure Active Directory - uygulama kayıtları altında kayıtlı uygulamanıza gidin.

   

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

   

3. izin ekle ' yi seçin ve Azure DevOps -user_impersonation seç ' i seçin .

   

4. Sol Gezinti panelinden hızlı başlangıç ' ı seçin.

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

6. Uygulama platformunuzu seçin. Bu öğretici için "Python" öğesini seçin.

7. Gerekli önkoşulları karşıladığınızdan emin olun ve Azure portal 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 'si olacaktır.

   

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

   

9. Gerekli tüm bağımlılıklara sahip olduğunuzdan emin olmak için uygulama gereksinimlerini yükleyip uygulamayı çalıştırın. Uygulama başlangıçta Microsoft Graph API 'sindeki bir uç noktaya isabet etmek üzere yapılandırılmıştır. Aşağıdaki bölümdeki yapılandırma yönergelerini izleyerek bu uç noktayı PAT yaşam döngüsü yönetim API 'SI temel uç noktasına nasıl değiştireceğinizi öğrenin.

   

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

Kullanıcı hızlı başlangıç uygulamasını indirdikten ve yükledikten sonra, Microsoft Graph 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önetim API 'sini çağırmak üzere değiştirmemiz gerekir.

Bunu yapmak için birkaç şey yapmanız gerekir:

1. Pat yaşam döngüsü yönetimi API 'Leri için uç nokta yapılandırma değişkenini güncelleştirme
2. kapsam yapılandırma değişkenini, Azure DevOps kaynağına ve tüm kapsamlarına başvuracak şekilde "499b84ac-1321-427f-aa17-267ca6975798/. default" olarak güncelleştirin.

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.

Başlangıçta uygulama yapılandırma dosyasına düz metin olarak yerleştirilen istemci gizli dizisini güvenli hale getirmek için yönergeleri izlediğinizden emin olun. En iyi uygulama olarak, düz metin değişkenini yapılandırma dosyasından kaldırın ve uygulamanın gizli anahtarını korumak için bir ortam değişkeni veya Azure Anahtar Kasası kullanın.

Bunun yerine, bir istemci parolası yerine bir sertifika kullanmayı seçebilirsiniz. Uygulama üretimde kullanılacaksa, sertifikaların kullanılması önerilen seçenektir. Bir sertifika kullanmaya yönelik yönergeler hızlı başlangıç uygulaması kurulumunun son adımında bulunabilir.

Örnek: PAT yaşam döngüsü yönetim API 'SI için bir Python Flask hızlı başlangıç uygulaması yapılandırma

1. Hızlı başlangıç uygulamanızı indirdikten, bağımlılıklarını yükledikten ve ortamınızda çalıştığı test edildikten sonra app_config.py dosyayı istediğiniz Düzenleyicinizde açın. Dosya aşağıdaki kod parçacığına benzer olmalıdır; açıklık için, varsayılan Microsoft Graph apı yapılandırmasına başvuran açıklamalar kaldırılmıştır:

   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 istemci parolasını güncelleştirin. Üretimde, bir ortam değişkeni veya Azure Keykasasını kullanarak veya bir sertifikaya geçerek, istemci gizliliğini güvenli hale getirmeye dikkat edin.

   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. ENDPOINTdeğişkeni Azure DevOps koleksiyon URL 'si ve apı uç noktası olarak 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. SCOPEdeğişkeni Azure DevOps apı kaynağına başvuracak şekilde değiştirin; karakter dizesi Azure DevOps apı 'sinin kaynak kimliğidir ve ". default" kapsamı, bu kaynak kimliği için tüm kapsamlara başvurur.

   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 alternatif değeri kullanın AUTHORITY , "Enter_the_Tenant_Name_Here" içine 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. app_config.pyCLIENT_ID, KIRACı kimliğiniz ve koleksıyon URL 'niz ile, son dosyanın aşağıdaki ile eşleştiğini doğrulayın. Güvenlik nedenleriyle, CLIENT_SECRET bir ortam değişkenine, Azure Keykasasından taşındığından veya kayıtlı uygulamanız için bir sertifikayla birlikte yer aldığından 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 ALABILMENIZ için uygulamayı yeniden çalıştırın. Sahip olduğunuz doğrulandıktan sonra, ve ' nin içeriğini 'app.py' ve 'ms-identity-python-webapp-master\templates' DIZININI, Pat yaşam döngüsü yönetim API uç noktalarının geri kalanına istek göndermeyi destekleyecek şekilde 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ş Python Flask hızlı başlangıç uygulamasının bir örneği için, GitHub Bu örnek depoyu inceleyin.

Azure AD 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. Yukarıdaki örneklerde belirtilen MSAL kodu, süresi dolduktan sonra belirteci otomatik olarak yeniler. Belirtecin yenilenmesi, kullanıcının yeniden oturum açmasını ve yeni bir yetkilendirme kodu almasını engeller. 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 'leri 'ni keşfet

yukarıdaki GitHub örnek uygulama ve hızlı başlangıç uygulamalarında uygulama, aldığınız Azure AD belirteçleriyle istek yapmak üzere önceden yapılandırılmıştır. Uç noktalar hakkında daha fazla bilgi edinmek için kabul ettikleri parametreleri ve yanıt olarak döndürülen API başvurusu belgelerinebakın.

SSS

S: neden Azure AD belirteciyle kimlik doğrulaması yapmam gerekir? Bir PAT neden yeterince değil?

Y : Bu PAT yaşam döngüsü yönetim API 'SI ile yeni PATs oluşturma ve var olan PATs 'leri iptal etme özelliğini açtık. Yanlış ellerde Bu API, kötü amaçlı aktörler tarafından kuruluşunuzun ADO kaynaklarına birden çok giriş noktası oluşturmak için kullanılabilir. Azure AD kimlik doğrulamasını zorunlu tutarak, bu güçlü API 'nin bu yetkisiz kullanıma karşı daha güvenli olmasını istediğinizi umuyoruz.

S: Bu API 'YI kullanmak için etkin bir Azure aboneliğine sahip bir Azure AD kiracının olması gerekir mi?

Y : Ne yazık ki bu API yalnızca etkin bir Azure aboneliğine sahip bir Azure AD 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 : Tercih ettiğiniz dilde API kullanmak istediğinizi sevtik! bir örneğin isteğiniz varsa, başka birinin paylaşmak üzere bir örnek olup olmadığını görmek için Dev Community üzerine gidin. daha büyük Azure DevOps kitle paylaşmak istediğiniz bir örnek uygulamanız varsa, bize bu docs üzerinde daha fazla bilgi sahibi olarak bakabiliriz!

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

Y : Bu belirteç API 'si ve token yönetici API 'si, benzer bir şekilde farklı kullanım örnekleri ve izleyiciler sunar:

• Bu belirteç API 'SI, bir otomatik işlem hattında sahip oldukları PATs 'leri yönetmek isteyen kullanıcılar için oldukça önemlidir. Bu API izin verir. Yeni belirteçler oluşturma ve var olanları güncelleştirme olanakları sağlar.
• Belirteç Yöneticisi API 'SI, kuruluş yöneticileri için tasarlanmıştır. Yöneticiler, kuruluşlardaki kullanıcıların kişisel erişim belirteçleri (PATs) 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 PATs 'YI yeniden oluşturma/döndürme hakkında ne yapabilirim? Kullanıcı arabiriminde bu seçeneği gördüm, ancak API 'de benzer bir yöntem görmüyorum.

Y : Harika soru! Kullanıcı arabiriminde kullanılabilen "yeniden üret" işlevselliği, API aracılığıyla tamamen yinelenebilir olan birkaç eylemi gerçekleştirir.

PAT 'nizi döndürmek için şunları yapmanız gerekir:

1. Get ÇAĞRıSıNı kullanarak Pat 'in meta verilerini anlayın,
2. Bir Post çağrısı kullanarak eski Pat 'in meta verileriyle yenı bir pat oluşturun,
3. Delete çağrısını kullanarak eski Pat iptal etme

S: Bu uygulamayı kullanmaya devam etmek için "yönetici onayı gerekiyor" açılır penceresi görüyorum. Yönetici onayı olmadan bu uygulamayı nasıl kullanabilirim?

Y : Kiracınızda, uygulamanızın kuruluştaki kaynaklara erişmek için izin verilmesini gerektiren güvenlik ilkelerini ayarlamış olduğu görülüyor. Bu anda bu uygulamada bu uygulamayı kullanmaya devam etmenin tek yolu, bir yöneticiden kullanabilmeniz için uygulamaya izin vermesini ister.

Sonraki adımlar