Zarządzanie osobistymi tokenami dostępu (PAT) przy użyciu interfejsu API REST

Azure DevOps Services

W przypadku posiadania dużego zestawu osobistych tokenów dostępu (PATs)może stać się skomplikowane zarządzanie tymi tokenami używając wyłącznie interfejsu użytkownika.

Interfejs API zarządzania cyklem życia tokenów PAT umożliwia łatwe zarządzanie tokenami PAT skojarzonymi z organizacjami przy użyciu zautomatyzowanych procesów. Ten rozbudowany zestaw interfejsów API umożliwia zarządzanie punktami dostępu uprzywilejowanego, co pozwala na tworzenie nowych punktów dostępu oraz odnawianie lub wycofywanie istniejących punktów dostępu uprzywilejowanego.

W tym artykule pokazano, jak skonfigurować aplikację, która uwierzytelnia się przy użyciu tokenu Microsoft Entra i wykonuje wywołania za pomocą interfejsu API cyklu życia PAT.

Wymagania wstępne

W przeciwieństwie do innych interfejsów API usługi Azure DevOps Services użytkownicy muszą udostępnić token dostępu firmy Microsoft Entra do korzystania z tego interfejsu API. Biorąc pod uwagę możliwość tworzenia i odwoływania paT tego interfejsu API, chcemy upewnić się, że takie zaawansowane funkcje są dostępne tylko w celu bezpieczniejsze tokeny firmy Microsoft Entra.

Aby uzyskać i odświeżyć tokeny dostępu firmy Microsoft, należy wykonać następujące czynności:

• Posiadanie dzierżawy firmy Microsoft Entra z aktywną subskrypcją platformy Azure
• Rejestrowanie aplikacji w dzierżawie firmy Microsoft Entra
• Dodawanie uprawnień usługi Azure DevOps do aplikacji
• Uzyskaj zgodę od administratora dzierżawy: w zależności od zasad zabezpieczeń dzierżawy aplikacja może potrzebować uprawnień dostępu do zasobów w organizacji. Poproś administratora dzierżawy o udzielenie aplikacji uprawnień do korzystania z niej w dzierżawie.

Gdy masz aplikację z działającym przepływem uwierzytelniania do obsługi tokenów firmy Microsoft Entra, możesz użyć tych tokenów, aby wykonać wywołania interfejsu API zarządzania cyklem życia pat.

Aby wywołać interfejs API bezpośrednio, podaj token dostępu firmy Microsoft Entra jako Bearer token w Authorization nagłówku żądania. Aby uzyskać więcej informacji i pełną listę dostępnych żądań, zobacz dokumentację interfejsu API pat.

W poniższej sekcji pokazano, jak utworzyć aplikację, która uwierzytelnia użytkownika przy użyciu tokenu dostępu firmy Microsoft Entra. Aplikacja używa biblioteki Microsoft Authentication Library (MSAL) i wywołuje interfejs API do zarządzania cyklem życia PAT.

Klonowanie naszej aplikacji internetowej platformy Python Flask

Udostępniliśmy przykładową aplikację internetową platformy Python Flask dla tego interfejsu API, którą można pobrać w witrynie GitHub, i skonfigurować do użycia z dzierżawą usługi Microsoft Entra i organizacją usługi Azure DevOps. Przykładowa aplikacja używa przepływu kodu autoryzacji MSAL w celu uzyskania tokenu dostępu Microsoft Entra.

Po sklonowania przykładowej aplikacji postępuj zgodnie z instrukcjami w pliku README repozytorium. W artykule README wyjaśniono, jak zarejestrować aplikację w dzierżawie firmy Microsoft Entra, skonfigurować przykład do korzystania z dzierżawy firmy Microsoft Entra i uruchomić sklonowaną aplikację.

Generowanie aplikacji Szybki start w witrynie Azure Portal

Zamiast tego możesz wygenerować przykładową aplikację z wygenerowanym kodem BIBLIOTEKI MSAL przy użyciu opcji Szybki start na stronie aplikacji w witrynie Azure Portal. Aplikacja testowa Szybkiego startu jest zgodna z przepływem kodu autoryzacji, ale robi to z punktem końcowym interfejsu API programu Microsoft Graph. Użytkownicy muszą zaktualizować konfigurację aplikacji, aby wskazać punkt końcowy dla interfejsu API zarządzania cyklem życia pat.

Aby wykonać to podejście, postępuj zgodnie z instrukcjami Szybki start dotyczącymi wybranego typu aplikacji na stronie głównej witryny Microsoft Entra ID Develop docs. W poniższym przykładzie przedstawiono aplikację Szybki start platformy Python Flask.

1. Po zarejestrowaniu aplikacji w dzierżawie Microsoft Entra z aktywną subskrypcją Azure, przejdź do zarejestrowanej aplikacji w obszarze Microsoft Entra ID —>Rejestracje aplikacji w portalu Azure.

   

2. Wybierz aplikację i przejdź do pozycji Uprawnienia interfejsu API.

   

3. Wybierz Dodaj uprawnienie i wybierz Azure DevOps -> wybierz odpowiednie zakresy, które są potrzebne. W tym przypadku interfejsy API zarządzania cyklem życia pat obsługują tylko user_impersonation, ale inne interfejsy API mogą zażądać innych bardziej szczegółowych zakresów, które można znaleźć na indywidualnej stronie referencyjnej każdego interfejsu API. Po wybraniu wszystkich zakresów kliknij Dodaj uprawnienia.

   

4. Wybierz pozycję Szybki start.

5. Wybierz typ aplikacji: w polu Python Flask wybierz pozycję Aplikacja internetowa.

6. Wybierz platformę aplikacji. Na potrzeby tego samouczka wybierz pozycję Python.

7. Upewnij się, że spełniasz niezbędne wymagania wstępne, a następnie zezwól witrynie Azure Portal na wprowadzenie niezbędnych zmian w celu skonfigurowania aplikacji. Adres URL odpowiedzi to adres URL przekierowania ustawiony podczas tworzenia aplikacji + "/getAToken".

   

8. Pobierz aplikację Szybki start i wyodrębnij pliki.

   

9. Zainstaluj wymagania aplikacji i uruchom aplikację, aby upewnić się, że masz wszystkie niezbędne zależności. Aplikacja jest początkowo skonfigurowana do trafienia do punktu końcowego w interfejsie API programu Microsoft Graph. Dowiedz się, jak zmienić ten punkt końcowy na podstawowy punkt końcowy interfejsu API zarządzania cyklem życia pat, postępując zgodnie z instrukcjami konfiguracji w poniższej sekcji.

   

Konfigurowanie aplikacji Szybki start

Po pobraniu i zainstalowaniu aplikacji Szybki start użytkownik zostanie skonfigurowany do korzystania z testowego punktu końcowego interfejsu API z programu Microsoft Graph. Zmodyfikuj wygenerowany plik konfiguracji, aby wywołać interfejs API zarządzania cyklem życia pat.

Wykonaj następujące zadania:

1. Aktualizowanie zmiennej konfiguracji punktu końcowego dla https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview interfejsów API zarządzania cyklem życia pat
2. Zaktualizuj zmienną konfiguracji SCOPE na "499b84ac-1321-427f-aa17-267ca6975798/.default" , aby odwołać się do zasobu usługi Azure DevOps i wszystkich jego zakresów.

W poniższym przykładzie pokazano, jak wykonaliśmy tę konfigurację dla aplikacji Szybki start python Flask wygenerowanej za pośrednictwem witryny Azure Portal w poprzedniej sekcji.

Upewnij się, że wykonano instrukcje, aby zabezpieczyć klucz tajny klienta, który jest początkowo wstawiany w postaci zwykłego tekstu do pliku konfiguracji aplikacji. Najlepszym rozwiązaniem jest usunięcie zmiennej zwykłego tekstu z pliku konfiguracji i użycie zmiennej środowiskowej lub usługi Azure KeyVault w celu zabezpieczenia wpisu tajnego aplikacji.

Zamiast tego można użyć certyfikatu zamiast klucza tajnego klienta. Używanie certyfikatów jest zalecaną opcją, jeśli aplikacja zostanie użyta w środowisku produkcyjnym. Instrukcje dotyczące używania certyfikatu można znaleźć w ostatnim kroku konfiguracji aplikacji Szybki start.

1. Po pobraniu aplikacji Szybki start zainstaluj jej zależności i przetestuj ją w środowisku, otwórz app_config.py plik w wybranym edytorze. Plik powinien przypominać następujący fragment kodu; aby uzyskać jasność, komentarze odwołujące się do domyślnej konfiguracji interfejsu API programu Microsoft Graph zostały usunięte:

   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. Zaktualizuj identyfikator klienta lub klucz tajny klienta do aplikacji przy użyciu identyfikatora klienta i klucza tajnego klienta rejestracji aplikacji. W środowisku produkcyjnym upewnij się, że klucz tajny klienta został zabezpieczony przy użyciu zmiennej środowiskowej, usługi Azure KeyVault lub przez przełączenie do certyfikatu.

   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. Zmień zmienną ENDPOINT na adres URL kolekcji usługi Azure DevOps i punkt końcowy interfejsu API. Na przykład w przypadku kolekcji o nazwie "testCollection" wartość będzie następująca:

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

   W przypadku kolekcji o nazwie "testCollection" ten punkt końcowy będzie następujący:

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

4. Zmień zmienną SCOPE , aby odwoływać się do zasobu interfejsu API usługi Azure DevOps. Ciąg znaków jest identyfikatorem zasobu interfejsu API usługi Azure DevOps, a .default zakres odnosi się do wszystkich zakresów dla tego identyfikatora zasobu.

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

5. Jeśli aplikacja jest skonfigurowana dla określonej dzierżawy (zamiast konfiguracji wielodostępnej), użyj alternatywnej wartości dla AUTHORITY zmiennej, dodając konkretną nazwę dzierżawy w ciągu "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. Sprawdź, czy app_config.py ostateczny plik jest zgodny z następującymi elementami, przy użyciu adresu URL CLIENT_ID, identyfikatora dzierżawy i kolekcji. Ze względów bezpieczeństwa upewnij się, że CLIENT_SECRET została przeniesiona do zmiennej środowiskowej, usługi Azure KeyVault lub zamieniono na certyfikat zarejestrowanej aplikacji:

   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. Uruchom ponownie aplikację, aby przetestować, że możesz pobrać wszystkie tokeny pat dla żądanego użytkownika. Po zweryfikowaniu możesz zmodyfikować zawartość 'app.py' i 'ms-identity-python-webapp-master\templates' katalog, aby obsługiwać wysyłanie żądań do pozostałych punktów końcowych interfejsu API zarządzania cyklem życia pat. Aby zapoznać się z przykładem aplikacji Szybki start platformy Python Flask, która została zmodyfikowana w celu obsługi żądań obsługi wszystkich punktów końcowych interfejsu API zarządzania cyklem życia pat, zobacz to przykładowe repozytorium w witrynie GitHub.

Automatyczne odświeżanie tokenu dostępu firmy Microsoft Entra

Po poprawnym skonfigurowaniu aplikacji i uzyskaniu tokenu dostępu przez użytkownika token może być używany przez maksymalnie godzinę. Kod BIBLIOTEKi MSAL podany w obu poprzednich przykładach automatycznie odświeża token po wygaśnięciu. Odświeżanie tokenu uniemożliwia użytkownikowi ponowne zalogowanie się i uzyskanie nowego kodu autoryzacji. Jednak użytkownicy mogą wymagać ponownego zalogowania się po upływie 90 dni po wygaśnięciu tokenu odświeżania.

Często zadawane pytania (FAQ)

.: Czy mogę uzyskać przykład tej przykładowej aplikacji dla innego języka/struktury/typu aplikacji?

Jeśli masz na przykład żądanie, przejdź do naszej społeczności deweloperów , aby sprawdzić, czy ktoś inny ma przykład do udostępnienia. Jeśli masz przykładową aplikację, którą chcesz udostępnić większej odbiorcom usługi Azure DevOps, daj nam znać i możemy szerzej przyjrzeć się jej rozpowszechnianiu w tych dokumentach.

.: Jaka jest różnica między tym interfejsem API tokenu a interfejsem API administratora tokenu?

Ten interfejs API tokenu i interfejs API administratora tokenu , chociaż są podobne, obsługują różne przypadki użycia i odbiorców.

• Ten interfejs API tokenu jest w dużej mierze przeznaczony dla użytkowników, którzy chcą zarządzać dostawcami dostępu współwłasnego w zautomatyzowanym potoku. Ten interfejs API umożliwia. Umożliwia tworzenie nowych tokenów i aktualizowanie istniejących.
• Interfejs API administratora tokenu jest przeznaczony dla administratorów organizacji. Administratorzy mogą używać tego interfejsu API do pobierania i odwoływania autoryzacji protokołu OAuth, w tym osobistych tokenów dostępu (PAT) i samodzielnego opisywania tokenów sesji użytkowników w swoich organizacjach.

.: Jak mogę ponownie wygenerować/obrócić karty PAT za pośrednictwem interfejsu API? Widziałem tę opcję w interfejsie użytkownika, ale nie widzę podobnej metody w interfejsie API.

Funkcja "Regeneruj ponownie" dostępna w interfejsie użytkownika rzeczywiście wykonuje kilka akcji, które są w pełni replikowane za pośrednictwem interfejsu API.

Aby obrócić swój token dostępu, wykonaj następujące czynności:

1. Omówienie metadanych tokenu pat przy użyciu wywołania GET
2. Utwórz nowy identyfikator pat z metadanymi starego tokenu dostępu przy użyciu wywołania POST ,
3. Odwoływanie starego identyfikatora PAT przy użyciu wywołania DELETE

.: Podczas próby kontynuowania korzystania z tej aplikacji widzę wyskakujące okienko "Potrzebuję zatwierdzenia przez administratora". Jak mogę używać tej aplikacji bez zatwierdzania przez administratora?

Wygląda na to, że dzierżawca (np. w kontekście chmurowym) ma polityki bezpieczeństwa, które wymagają nadania aplikacji uprawnień do dostępu do zasobów w organizacji. W tej chwili jedynym sposobem na kontynuowanie korzystania z tej aplikacji w tej dzierżawie jest prośba administratora o udzielenie uprawnień do aplikacji, zanim będzie można jej używać.

.: Dlaczego występuje błąd, taki jak "Jednostki usługi nie mogą wykonać tej akcji", gdy próbuję wywołać interfejs API zarządzania cyklem życia pat przy użyciu jednostki usługi lub tożsamości zarządzanej?

1: Jednostki usługi i tożsamości zarządzane nie są dozwolone. Biorąc pod uwagę możliwość tworzenia i odwoływania paT tego interfejsu API, chcemy mieć pewność, że takie zaawansowane funkcje będą dostępne tylko dla użytkowników.