Używanie osobistych tokenów dostępu

Usługi Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022

Osobisty token dostępu (PAT) to alternatywne hasło do uwierzytelniania Azure DevOps. PAT identyfikuje użytkownika i określa zasoby oraz operacje dostępne dla niego. Traktuj PAT z taką samą ostrożnością jak hasło.

Ostrzeżenie

Unikaj PAT, gdy dostępna jest bezpieczniejsza metoda uwierzytelniania. W przypadku aplikacji i automatyzacji należy w miarę możliwości używać tokenów Microsoft Entra, tożsamości zarządzanych lub nazw głównych usług.

Jeśli narzędzie nie obsługuje uwierzytelniania Microsoft Entra, użyj tokenu PAT o zakresie obejmującym całą organizację, z minimalnym zakresem uprawnień i możliwie najkrótszym okresem ważności.

Ważna

Azure DevOps wycofuje globalne tokeny PAT. Wszystkie istniejące globalne tokeny PAT przestaną działać 1 grudnia 2026 r. Zmigruj je teraz do tokenów PAT o zakresie organizacji lub do uwierzytelniania Microsoft Entra. Aby uzyskać więcej informacji, zobacz Wycofywanie globalnych osobistych tokenów dostępu w Azure DevOps.

Wymagania wstępne

• Dostęp do organizacji Azure DevOps lub kolekcji Azure DevOps Server.
• Uprawnienia wymagane dla zasobów i operacji, do których uzyskuje dostęp pat. PAT nie może nadać więcej uprawnień niż jego właściciel.

• Uprawnienie do tworzenia tokenów PAT zgodnie z zasadami obowiązującymi w organizacji. Administrator może ograniczyć tworzenie tokenów PAT, ich zakresy i okres ważności. Aby uzyskać więcej informacji, zobacz Manage PATs with policies (Zarządzanie sieciami uprzywilejowanymi przy użyciu zasad).

Tworzenie tokenu dostępu

1. Zaloguj się do swojej organizacji (https://dev.azure.com/{organization}).

2. Na stronie głównej otwórz ustawienia użytkownika i wybierz pozycję Osobiste tokeny dostępu.

   

3. Wybierz pozycję + Nowy token.

   

4. Wprowadź nazwę, wybierz jedną organizację i ustaw datę wygaśnięcia.

   

5. Wybierz tylko zakresy wymagane dla zamierzonych zadań.

   Na przykład, aby zarejestrować agenta hostowanego samodzielnie, wybierz pozycję Pule agentów (Odczyt i zarządzanie). Twój administrator może ograniczyć tokeny PAT z pełnym zakresem uprawnień lub wymagać dodania określonych zakresów do listy dozwolonych.

   

6. Wybierz pozycję Utwórz, skopiuj token i zapisz go w bezpiecznej lokalizacji. Wartość tokenu nie jest ponownie wyświetlana.

   

W przypadku organizacji korzystających z Microsoft Entra ID zaloguj się przy użyciu nowego osobistego tokenu dostępu (PAT) w ciągu 90 dni, w przeciwnym razie stanie się on nieaktywny. Aby uzyskać więcej informacji, zobacz Częstotliwość logowania użytkownika dla dostępu warunkowego.

Powiadomienia

Azure DevOps wysyła powiadomienie po utworzeniu osobistego tokenu dostępu (PAT) oraz kolejne powiadomienie przed jego wygaśnięciem.

Jeśli zasady organizacji nie zezwalają już na ponowne generowanie tokenu dostępu, wiadomość e-mail o wygaśnięciu zidentyfikuje ograniczenie. Skontaktuj się z administratorem kolekcji projektów, jeśli potrzebujesz wpisu na listę dozwolonych.

Nieoczekiwane powiadomienie

Nieoczekiwane powiadomienie może oznaczać, że token PAT został utworzony dla Ciebie przez administratora lub narzędzie. Typowe nazwy tokenów obejmują:

• git: https://dev.azure.com/{organization} on {machine}, utworzony podczas nawiązywania połączenia usługi Git z repozytorium Azure Repos.
• Service Hooks: Azure App Service: Deploy web app, utworzony podczas konfigurowania wdrożenia Azure App Service.
• Microsoft Teams Integration, utworzony podczas konfigurowania integracji Microsoft Teams.

Jeśli nie rozpoznajesz tokenu PAT, unieważnij go i zmień hasło. Aby uzyskać konto Microsoft Entra, poproś administratora o przejrzenie nieznanego działania logowania.

Użyj PAT

Użyj osobistego tokenu dostępu (PAT) do jednorazowych żądań, lokalnych prototypów lub narzędzi, które nie obsługują uwierzytelniania Microsoft Entra. Nie używaj poświadczeń PAT jako długoterminowych poświadczeń dla aplikacji produkcyjnych lub usług.

Azure DevOps obsługuje uwierzytelnianie PAT za pośrednictwem nagłówka uwierzytelniania HTTP Basic. Nazwa użytkownika może być pusta. Zakoduj ciąg :{PAT} w formacie Base64 i użyj uzyskanej wartości w tym nagłówku:

Authorization: Basic BASE64_ENCODED_PAT

W poniższych przykładach zakłada się, że zmienna środowiskowa AZURE_DEVOPS_PAT jest wypełniana z bezpiecznego źródła sekretów.

Windows

$patBytes = [Text.Encoding]::ASCII.GetBytes(":$env:AZURE_DEVOPS_PAT")
$headers = @{ Authorization = "Basic $([Convert]::ToBase64String($patBytes))" }

Invoke-RestMethod `
  -Uri "https://dev.azure.com/{organization}/{project}/_apis/build/builds?api-version=7.1" `
  -Headers $headers

Linux/macOS

curl --user ":${AZURE_DEVOPS_PAT}" \
  "https://dev.azure.com/{organization}/{project}/_apis/build/builds?api-version=7.1"

Gdy prototyp już działa, przenieś go na Microsoft Entra OAuth na potrzeby delegowanego dostępu użytkownika lub nazwę główną usługi albo tożsamość zarządzaną na potrzeby dostępu aplikacji.

Modyfikacja PAT

Możesz zmienić nazwę tokenu PAT, datę wygaśnięcia lub zakresy. Ponowne wygenerowanie tokenu PAT powoduje utworzenie nowej wartości tokenu PAT i unieważnienie poprzedniej wartości. Nie można modyfikować ani ponownie wygenerować wygasłego lub odwołanego identyfikatora PAT; Zamiast tego utwórz nowy.

1. Na stronie głównej otwórz ustawienia użytkownika i wybierz pozycję Osobiste tokeny dostępu.

2. Wybierz PAT, a następnie wybierz pozycję Edytuj.

   

3. Zmień nazwę tokena, datę wygaśnięcia lub zakresy, a następnie wybierz Zapisz.

   

Odwołać PAT

Unieważnij osobisty token dostępu (PAT), gdy został naruszony, nie jest już potrzebny lub ma szerszy zakres uprawnień, niż jest to wymagane.

1. Na stronie głównej otwórz ustawienia użytkownika i wybierz pozycję Osobiste tokeny dostępu.

2. Wybierz token PAT, a następnie wybierz pozycję Unieważnij.

   

3. W oknie dialogowym potwierdzenia wybierz pozycję Odwołaj.

   

Zastępowanie wygasającego lub odwołanego tokenu dostępu

Po wygaśnięciu lub odwołaniu pat Azure DevOps odrzuca kolejne próby uwierzytelnienia, które go używają. Potok, skrypt, klient pakietu lub operacja usługi Git zwykle kończy się niepowodzeniem przy następnym uwierzytelnieniu. Azure DevOps nie gwarantuje, że odwołanie kończy każde połączenie, które zostało już ustanowione.

Obróć token PAT przed jego wygaśnięciem

Aby wymienić PAT bez możliwej do uniknięcia przerwy w działaniu usługi:

1. Utwórz token PAT na poziomie organizacji tylko z wymaganymi zakresami uprawnień i krótkim okresem ważności.

2. Zapisz nową wartość w magazynie sekretów. Nie osadzaj paTs w zdalnych adresach URL usługi Git, .git/configkodzie źródłowym, potoku YAML ani dziennikach.

3. Przetestuj nowy PAT w operacji nieprodukcyjnej lub w jednej integracji, zanim zaktualizujesz wszystkie zależności.

4. Zaktualizuj każdą usługę lub narzędzie, które przechowuje stary identyfikator PAT:

   Integration	Gdzie zaktualizować poświadczenia
   Git	Git Credential Manager lub inny bezpieczny menedżer poświadczeń
   Azure Pipelines	Zmienna tajna, grupa zmiennych lub połączenie usługi
   Azure Artifacts	Dostawca poświadczeń Azure Artifacts lub bezpieczna konfiguracja menedżera pakietów
   Skrypty i klienci REST	Magazyn sekretów lub chroniona zmienna środowiskowa
   Narzędzia innych firm	Bezpieczny magazyn poświadczeń narzędzia

5. Przetestuj każdą zaktualizowaną integrację. Uruchom potok, którego dotyczy problem, operację Git, operację na pakiecie, skrypt lub żądanie interfejsu API i sprawdź, czy występują niepowodzenia uwierzytelniania.

6. Odwoływanie starego identyfikatora PAT.

Prowadź ewidencję właściciela, przeznaczenia, zakresów uprawnień, daty wygaśnięcia i powiązanych integracji dla każdego PAT. Wymień PAT-y przed ich wygaśnięciem zgodnie z zasadami obowiązującymi w organizacji i poziomem ryzyka w danym scenariuszu.

Odzyskiwanie po wygaśnięciu lub odwołaniu

Jeśli pat przestanie działać nieoczekiwanie:

1. Na stronie Osobiste tokeny dostępu sprawdź stan i datę wygaśnięcia tokenu PAT.
2. Utwórz zastępczy identyfikator PAT tylko z zakresami wymaganymi przez objęte integracje.
3. Zaktualizuj integracje, które przechowywały niedostępny identyfikator PAT.
4. Przetestuj każdą integrację i monitoruj kolejną zaplanowaną operację pod kątem niepowodzeń uwierzytelniania.

Jeśli przyczyna niepowodzenia jest niejasna, przejrzyj zdarzenia audytu PAT, aby ustalić, czy PAT wygasł, został zaktualizowany lub unieważniony.

Zarządzanie punktami uprzywilejowanymi przy użyciu interfejsów API zarządzania cyklem życia

Użyj interfejsów API do zarządzania cyklem życia PAT-ów, aby programowo wyświetlać, tworzyć, aktualizować i unieważniać własne PAT-y.

Te interfejsy API wymagają tokenu dostępu Microsoft Entra z przepływu delegowanego przez użytkownika. Użyj zakresu vso.pats. Nazwy główne usług i tożsamości zarządzane nie mogą tworzyć tokenów dostępu osobistego (PAT) ani nimi zarządzać, ponieważ nie reprezentują użytkownika.

Operation	Żądanie
Wyświetl PAT-y	GET https://vssps.dev.azure.com/{organization}/_apis/tokens/pats?api-version=7.1
Tworzenie tokenu dostępu	POST https://vssps.dev.azure.com/{organization}/_apis/tokens/pats?api-version=7.1
Odwołać PAT	DELETE https://vssps.dev.azure.com/{organization}/_apis/tokens/pats?authorizationId={authorizationId}&api-version=7.1

Wyślij token Microsoft Entra jako token elementu nośnego. Żądanie utworzenia ma następującą strukturę treści:

{
  "displayName": "CI build access",
  "scope": "vso.build",
  "validTo": "{expiration-in-UTC}",
  "allOrgs": false
}

Odpowiedź listy zwraca tokeny w tablicy patTokens . Odpowiedź na żądanie utworzenia zwraca sekret tylko raz w patToken.token. Przechowuj ją bezpiecznie i nigdy nie zapisuj jej w dziennikach. Aby unieważnić stary token, przekaż jego authorizationId jako parametr zapytania podany w tabeli.

Aby uzyskać pełne schematy i przykłady, zobacz Wyświetlanie listy tokenów PAT, Tworzenie tokenu PAT i Unieważnianie tokenu PAT.

Przegląd zdarzeń inspekcji PAT

Azure DevOps Services rejestruje zdarzenia związane z cyklem życia PAT w dzienniku inspekcji organizacji. W obszarze Ustawienia organizacji wybierz pozycję Inspekcja, a następnie odfiltruj następujące akcje:

Action	Event
Tworzony jest PAT	Token.PatCreateEvent
PAT wygasa	Token.PatExpiredEvent
Token PAT znajduje się w publicznym repozytorium	Token.PatPublicDiscoveryEvent
Użytkownik unieważnia token PAT	Token.PatRevokeEvent
Azure DevOps unieważnia PAT	Token.PatSystemRevokeEvent
Token PAT jest modyfikowany lub wygenerowany ponownie	Token.PatUpdateEvent

Zdarzenia dostępu do tokenów nie są obecnie rejestrowane. Użyj dziennika audytu do badania zmian w cyklu życia, a nie do określania, kiedy lub czy użyto tokenu PAT.

Przechowywanie dziennika inspekcji

Zdarzenia inspekcji są zachowywane przez 90 dni, a następnie usuwane. Okres retencji nie jest konfigurowalny. Aby zachować zdarzenia dłużej, wyeksportuj je do formatu CSV lub JSON lub skonfiguruj strumień inspekcji w zewnętrznym systemie zarządzania informacjami i zdarzeniami zabezpieczeń (SIEM).

Aby uzyskać więcej informacji, zobacz Access, export, and filter audit logs and Azure DevOps auditing events (Uzyskiwanie dostępu, eksportowanie i filtrowanie dzienników inspekcji oraz Azure DevOps zdarzeń inspekcji).

Skonfiguruj zasady PAT

Administratorzy dzierżawcy mogą ograniczać globalne tokeny PAT i tokeny PAT o pełnym zakresie, ustawiać maksymalny okres ważności tokenu PAT oraz kontrolować automatyczne unieważnianie ujawnionych tokenów PAT. Skonfiguruj zasady PAT na poziomie dzierżawy w Ustawieniach organizacji>Microsoft Entra.

Właściciele organizacji mogą ograniczyć tworzenie osobistego tokenu dostępu (PAT) w danej organizacji w obszarze Ustawienia organizacji>Zasady. Aby zapoznać się z rolami, zachowaniem zasad i procedurami listy dozwolonych, zobacz Manage PATs with policies (Zarządzanie punktami dostępu użytkowników przy użyciu zasad).

Format PAT

Ciągi znaków PAT mają łatwo rozpoznawalny format, który usprawnia wykrywanie wpisów tajnych i zmniejsza liczbę wyników fałszywie dodatnich.

• PaTs mają długość 84 znaków, w tym 52 znaki losowe.
• Tokeny PAT usługi Azure DevOps zawierają stałą sygnaturę AZDO na pozycjach 76–80.

Jeśli integracja weryfikuje tokeny PAT, obsługuj format o długości 84 znaków. Informacje o zabezpieczeniach dotyczących wyciekłych tokenów można znaleźć w Automatyczne unieważnianie wyciekłych tokenów PAT.

Najlepsze praktyki dotyczące korzystania z PATs

Rozważ alternatywy

• Użyj tokenów Microsoft Entra dla aplikacji i automatyzacji.
• W przypadku jednorazowych poleceń uzyskaj token Microsoft Entra za pośrednictwem Azure CLI.
• W przypadku usługi Git użyj menedżera poświadczeń usługi Git. W przypadku Azure Artifacts użyj dostawcy poświadczeń Azure Artifacts.

Utwórz PATy

• Utwórz tylko sieci PAT z zakresem organizacji. Globalne tokeny dostępu osobistego przestaną działać 1 grudnia 2026 r.
• Użyj innego identyfikatora PAT dla każdego narzędzia lub przepływu pracy.
• Wybierz tylko zakresy wymagane dla zadania.
• Zachowaj okres istnienia tak krótko, jak to jest praktyczne.
• Nie dołączaj danych osobowych ani żadnej części wartości tokenu w nazwie wyświetlanej.

Zarządzanie tokenami dostępu osobistego

• Nie udostępniaj PAT.
• Przechowuj PAT w bezpiecznym magazynie wpisów tajnych, takim jak Azure Key Vault.
• Wymień PAT-y przed ich wygaśnięciem i unieważnij je, gdy nie są już potrzebne.
• Natychmiast unieważnij token PAT, jeśli został ujawniony lub zagrożony.

Dla administratorów

• Ogranicz tokeny PAT o pełnym zakresie uprawnień i ustaw maksymalny okres ważności zgodnie z wymaganiami dotyczącymi zabezpieczeń.
• Ogranicz tworzenie PAT w organizacjach, które tego nie wymagają.
• Użyj obsługiwanych interfejsów API administracji tokenami, aby unieważnić osobiste tokeny dostępu (PAT) użytkowników.
• Preferuj uwierzytelnianie Microsoft Entra dla usług i automatyzacji.

Przeglądanie ryzykownych paT i reagowanie na nie

W ramach przeglądu zabezpieczeń:

1. Zidentyfikuj tokeny PAT z pełnymi zakresami, długim okresem ważności, globalnym dostępem lub bez udokumentowanego właściciela i celu.
2. Przejrzyj w dzienniku audytu zdarzenia tworzenia, aktualizacji, publicznego wykrycia, wygaśnięcia i unieważnienia tokenów PAT. Ponieważ dostęp do tokenu nie jest rejestrowany, nie należy używać dziennika inspekcji do klasyfikowania tokenu dostępu jako aktywnego lub nieaktualnego.
3. Unieważnij ujawnione, przejęte lub niepotrzebne tokeny PAT. W ramach procesu offboardingu użyj obsługiwanych interfejsów API administracji tokenami, aby unieważnić tokeny PAT użytkownika i powiadomić właścicieli integracji, których to dotyczy.
4. Skonfiguruj zasady PAT dla dzierżawy i organizacji, aby ograniczyć tokeny PAT o zasięgu globalnym i pełnym zakresie, ustawić maksymalny okres ważności oraz kontrolować automatyczne unieważnianie ujawnionych tokenów PAT.
5. Wyeksportuj zdarzenia inspekcji lub skonfiguruj strumień inspekcji, gdy wymagania dotyczące przechowywania przekraczają 90 dni.

Często zadawane pytania

Dlaczego nie mogę edytować ani ponownie wygenerować tokenu PAT przypisanego do jednej organizacji?

Zaloguj się do organizacji, dla której obowiązuje PAT. Możesz wyświetlić listę tokenów PAT z dowolnej organizacji w tej samej dzierżawie Microsoft Entra, zmieniając filtr Zakres dostępu, ale token PAT o zakresie organizacji możesz edytować tylko w tej organizacji.

Co dzieje się z PAT-ami, gdy konto użytkownika zostanie wyłączone?

Gdy konto zostanie wyłączone lub usunięte z organizacji, jego tokeny dostępu osobistego (PAT) nie mogą już uzyskiwać dostępu do zasobów tej organizacji. Azure DevOps nie usuwa automatycznie tokenów PAT. Jeśli dostęp zostanie przywrócony, identyfikator PAT, który nie wygasł lub został odwołany, działa z bieżącymi uprawnieniami użytkownika.

Czy można używać PAT ze wszystkimi interfejsami API REST Azure DevOps?

Nie. PATs współpracują z większością interfejsów API REST usługi Azure DevOps. Niektóre interfejsy API, w tym Organizations, Profiles i PAT Lifecycle Management APIs, wymagają tokenów Microsoft Entra.

Co się stanie, jeśli umieszczę token PAT w publicznym repozytorium GitHub?

Azure DevOps skanuje publiczne repozytoria GitHub w poszukiwaniu ujawnionych tokenów PAT. Po wykryciu tokenu Azure DevOps powiadamia właściciela i rejestruje zdarzenie inspekcji. Jeśli zasada dzierżawcy nie wyłącza automatycznego unieważniania, Azure DevOps unieważnia ujawniony token PAT. Aby uzyskać więcej informacji, zobacz Automatyczne unieważnianie ujawnionych PAT.

Czy mogę użyć PAT jako klucza API do publikowania pakietów NuGet?

Nie. Azure Artifacts nie obsługuje przekazywania PAT jako klucza API. W lokalnym środowisku programistycznym zainstaluj dostawcę poświadczeń Azure Artifacts. W Azure Pipelines użyj zadania uwierzytelniania NuGet.

Aby zapoznać się z przykładami, zobacz Publikowanie za pomocą narzędzia dotnet, Publikowanie przy użyciu NuGet.exei Publikowanie pakietów NuGet przy użyciu Azure Pipelines.

Dlaczego mój pat przestał działać?

Sprawdź, czy pat wygasł, został odwołany, stał się nieaktywny, ma niewystarczające zakresy lub należy do użytkownika, którego uprawnienia uległy zmianie. W przypadku organizacji wspieranej przez Microsoft Entra ID zaloguj się do Azure DevOps i ukończ pełny monit uwierzytelniania, a następnie spróbuj ponownie. Konfiguracja dostępu warunkowego może wymagać częstszego logowania.

W przypadku Azure DevOps Server podstawowe uwierzytelnianie IIS uniemożliwia uwierzytelnianie PAT. Pozostaw uwierzytelnianie podstawowe w usługach IIS wyłączone.

Jak utworzyć token dostępu, który nie jest powiązany z użytkownikiem?

PaTs są zawsze skojarzone z użytkownikiem, który je utworzył. W przypadku tożsamości innej niż użytkownik użyj tokenu Microsoft Entra wystawionego dla jednostki usługi aplikacji lub tożsamości zarządzanej. W przypadku potoków użyj połączenia z usługą.

Jak mogę odnowić token PAT za pomocą interfejsu API?

Interfejsy API do zarządzania cyklem życia nie regenerują tokenu PAT w ramach jednej operacji. Wyświetl informacje o starym osobistym tokenie dostępu (PAT), aby uzyskać jego metadane, utwórz nowy osobisty token dostępu (PAT) z wymaganym zakresem i datą wygaśnięcia, zaktualizuj i przetestuj każdą zależną integrację, a następnie unieważnij stary token PAT za pomocą jego authorizationId. Aby uzyskać poprawne ścieżki, zobacz Zarządzanie tokenami PAT za pomocą interfejsów API zarządzania cyklem życia.

Dlaczego podczas wywoływania interfejsów API do zarządzania cyklem życia tokenów PAT jest wyświetlany komunikat o zatwierdzeniu przez administratora?

Zasady zabezpieczeń dzierżawy wymagają zgody administratora, zanim aplikacja Microsoft Entra będzie mogła uzyskać dostęp do zasobów organizacji. Skontaktuj się z administratorem dzierżawy.

Powiązane artykuły

• Wskazówki dotyczące uwierzytelniania
• Uwierzytelnij się za pomocą tokenów Microsoft Entra
• Używanie jednostek usługi i tożsamości zarządzanych
• Zarządzanie sieciami uprzywilejowanymi przy użyciu zasad
• Odwoływanie paT użytkowników