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

Artykuł
05/15/2024

Azure DevOps Services

Jeśli masz do czynienia z dużym zestawem osobistych tokenów dostępu (PATs), może to stać się skomplikowane w celu zarządzania konserwacją tych tokenów przy użyciu samego 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 bogaty zestaw interfejsów API umożliwia zarządzanie punktami dostępu użytkowników, co umożliwia tworzenie nowych osobistych tokenów dostępu i odnawianie lub wygasanie istniejących osobistych tokenów dostępu.

W tym artykule wyjaśniono, jak skonfigurować aplikację korzystającą z tokenu usługi Microsoft Entra do uwierzytelniania i wykonującą wywołania za pomocą interfejsu API cyklu życia tokenów PAT. Jeśli chcesz zapoznać się z pełną listą dostępnych punktów końcowych, zobacz dokumentację interfejsu API tutaj.

Wymagania wstępne

Aby korzystać z interfejsu API, musisz uwierzytelnić się przy użyciu tokenu entra firmy Microsoft, który można wykonać za pośrednictwem protokołu OAuth identyfikatora Entra firmy Microsoft. Aby uzyskać więcej informacji, zobacz sekcję uwierzytelniania.

Musisz mieć dzierżawę firmy Microsoft Entra z aktywną subskrypcją platformy Azure.
W zależności od zasad zabezpieczeń dzierżawy aplikacja może potrzebować uprawnień 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ć.

Uwaga

Nie można używać jednostek usługi ani tożsamości zarządzanych do tworzenia ani odwoływanie paT.

Uwierzytelnianie przy użyciu tokenów firmy Microsoft Entra

W przeciwieństwie do innych interfejsów API usługi Azure DevOps Services użytkownicy muszą podać token dostępu firmy Microsoft w celu korzystania z tego interfejsu API zamiast tokenu PAT. Tokeny entra firmy Microsoft są bezpieczniejszym mechanizmem uwierzytelniania niż korzystanie z paT. 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.

Aby uzyskać i odświeżyć tokeny dostępu firmy Microsoft Entra, musisz:

Ważne

Rozwiązania "W imieniu aplikacji" (takie jak przepływ "poświadczeń klienta") i wszelkie przepływy uwierzytelniania, które nie wystawiają tokenu dostępu firmy Microsoft Entra, są nieprawidłowe do użycia z tym interfejsem API. Jeśli w dzierżawie firmy Microsoft Entra włączono uwierzytelnianie wieloskładnikowe, zdecydowanie należy użyć przepływu "kod autoryzacji".

Uwaga

Posiadanie dzierżawy firmy Microsoft Entra z aktywną subskrypcją platformy Azure jest wymaganiem wstępnym dla korzystania z tego interfejsu API.

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, należy podać token dostępu firmy Microsoft Entra jako Bearer token w Authorization nagłówku żądania. Aby zapoznać się z przykładami i pełną listą dostępnych żądań, zapoznaj się z 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 przy użyciu biblioteki MSAL i wywołuje interfejs API zarządzania cyklem życia pat.

Biblioteka Microsoft Authentication Library (MSAL) zawiera wiele zgodnych przepływów uwierzytelniania, których można użyć w aplikacji do uzyskiwania i odświeżania tokenów usługi Microsoft Entra. Pełną listę przepływów biblioteki MSAL można znaleźć w dokumentacji przepływów uwierzytelniania biblioteki uwierzytelniania firmy Microsoft. Przewodnik po wybraniu odpowiedniej metody uwierzytelniania dla aplikacji można znaleźć w obszarze Wybieranie odpowiedniej metody uwierzytelniania dla usługi Azure DevOps.

Wykonaj jeden z dwóch przykładów, aby rozpocząć pracę:

Sklonuj naszą przykładową aplikację Platformy Python Flask i skonfiguruj ją z twoją dzierżawą i organizacją ADO
Wygeneruj przykładową aplikację w witrynie Azure Portal dla wybranego języka i skonfiguruj ją dla interfejsu API 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 uwierzytelniania MSAL do uzyskania tokenu dostępu firmy Microsoft Entra.

Ważne

Zalecamy rozpoczęcie pracy z przykładową aplikacją internetową platformy Python Flask w usłudze GitHub, ale jeśli wolisz używać innego języka lub typu aplikacji, użyj opcji Szybki start, aby ponownie utworzyć równoważną aplikację testową.

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.

Przykład: rozpoczynanie pracy z aplikacją Szybki start platformy Python Flask

Po zarejestrowaniu aplikacji w dzierżawie firmy Microsoft Entra, która ma aktywną subskrypcję platformy Azure, przejdź do zarejestrowanej aplikacji w obszarze Microsoft Entra ID —> Rejestracje aplikacji w witrynie Azure Portal.
Wybierz aplikację i przejdź do pozycji Uprawnienia interfejsu API.
Wybierz pozycję Dodaj uprawnienie i wybierz pozycję Azure DevOps —> sprawdź user_impersonation —> wybierz pozycję Dodaj uprawnienia.
Wybierz pozycję Szybki start.
Wybierz typ aplikacji: w polu Python Flask wybierz pozycję Aplikacja internetowa.
Wybierz platformę aplikacji. Na potrzeby tego samouczka wybierz pozycję Python.
Upewnij się, że spełnisz 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".
Pobierz aplikację Szybki start i wyodrębnij pliki.
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 jest skonfigurowany do używania testowego punktu końcowego interfejsu API z poziomu programu Microsoft Graph. Musimy zmodyfikować wygenerowany plik konfiguracji, aby zamiast tego wywołał interfejs API zarządzania cyklem życia pat.

Napiwek

Używamy kolekcji i organizacji zamiennie w tych dokumentach. Jeśli zmienna konfiguracji wymaga nazwy kolekcji, zastąp ją nazwą organizacji.

Wykonaj następujące zadania:

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
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 będzie używana w środowisku produkcyjnym. Instrukcje dotyczące używania certyfikatu można znaleźć w ostatnim kroku konfiguracji aplikacji Szybki start.

Uwaga

Nigdy nie pozostaw wpisu tajnego klienta w postaci zwykłego tekstu w kodzie aplikacji produkcyjnej.

Przykład: Konfigurowanie aplikacji Szybki start platformy Python Flask dla interfejsu API zarządzania cyklem życia pat

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

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

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'

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 zakres ".default" odnosi się do wszystkich zakresów dla tego identyfikatora zasobu.
```
SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
```
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"
```

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

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.

Eksplorowanie interfejsów API zarządzania cyklem życia pat

W powyższych przykładowych aplikacjach GitHub i aplikacjach Szybki start jest wstępnie skonfigurowana do tworzenia żądań przy użyciu uzyskanych tokenów firmy Microsoft Entra. Aby uzyskać więcej informacji, zobacz dokumentację referencyjną interfejsu API.

Często zadawane pytania (FAQ)

Pyt.: Dlaczego muszę uwierzytelnić się przy użyciu tokenu firmy Microsoft Entra? Dlaczego pat nie wystarczy?

1: Przy użyciu tego interfejsu API zarządzania cyklem życia pat otworzyliśmy możliwość tworzenia nowych punktów dostępu i odwoływania istniejących punktów dostępu. W niewłaściwych rękach złośliwi aktorzy mogą użyć tego interfejsu API do utworzenia wielu punktów wejścia do zasobów usługi Azure DevOps organizacji. Wymuszając uwierzytelnianie firmy Microsoft Entra, mamy nadzieję, że ten zaawansowany interfejs API będzie bardziej bezpieczny przed tym nieautoryzowanym użyciem.

Pyt.: Czy muszę mieć dzierżawę firmy Microsoft Entra z aktywną subskrypcją platformy Azure, aby korzystać z tego interfejsu API?

1: Niestety ten interfejs API jest dostępny tylko dla użytkowników będących częścią dzierżawy firmy Microsoft Entra z aktywną subskrypcją platformy Azure.

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

Odpowiedź: Uwielbiamy używać interfejsu API w wybranym języku! 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.

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

1: Ten interfejs API tokenu i interfejs API administratora tokenu, podobnie jak w przypadku różnych przypadków 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. Administracja mogą używać tego interfejsu API do pobierania i odwoływania autoryzacji OAuth, w tym osobistych tokenów dostępu (PAT) i samodzielnego opisywania tokenów sesji użytkowników w swoich organizacjach.

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

Odpowiedź: Wielkie pytanie! 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:

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

Pyt.: 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?

1: Wygląda na to, że dzierżawa ma zasady zabezpieczeń, które wymagają udzielenia aplikacji uprawnień 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ć.

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

Następne kroki

Dowiedz się więcej o punktach końcowych interfejsu API zarządzania cyklem życia pat

Udostępnij za pośrednictwem

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

Wymagania wstępne

Uwierzytelnianie przy użyciu tokenów firmy Microsoft Entra

Klonowanie naszej aplikacji internetowej platformy Python Flask

Generowanie aplikacji Szybki start w witrynie Azure Portal

Przykład: rozpoczynanie pracy z aplikacją Szybki start platformy Python Flask

Konfigurowanie aplikacji Szybki start

Przykład: Konfigurowanie aplikacji Szybki start platformy Python Flask dla interfejsu API zarządzania cyklem życia pat

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

Eksplorowanie interfejsów API zarządzania cyklem życia pat

Często zadawane pytania (FAQ)

Pyt.: Dlaczego muszę uwierzytelnić się przy użyciu tokenu firmy Microsoft Entra? Dlaczego pat nie wystarczy?

Pyt.: Czy muszę mieć dzierżawę firmy Microsoft Entra z aktywną subskrypcją platformy Azure, aby korzystać z tego interfejsu API?

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

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

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

Pyt.: 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?

Pyt.: 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?

Następne kroki

Opinia

Opinia

Dodatkowe zasoby