Správa osobních přístupových tokenů (PAT) pomocí rozhraní REST API

Článek
10/24/2024

Služby Azure DevOps

Když pracujete s velkou sadou tokenů patového přístupu, které vlastníte, může být složité spravovat údržbu těchto tokenů pomocí samotného uživatelského rozhraní.

Pomocí rozhraní API pro správu životního cyklu PAT můžete snadno spravovat tokeny PAT přidružené k vaší organizaci pomocí automatizovaných procesů. Tato bohatá sada rozhraní API umožňuje spravovat vaše paty, což vám umožní vytvářet nové paty a obnovovat nebo vypršet stávající paty.

V tomto článku vám ukážeme, jak nakonfigurovat aplikaci, která se ověřuje pomocí tokenu Microsoft Entra a volá pomocí rozhraní API pro správu životního cyklu PAT. Pokud chcete jenom zobrazit úplný seznam dostupných koncových bodů, projděte si referenční informace k rozhraní API.

Požadavky

Oprávnění: V závislosti na zásadách zabezpečení vašeho tenanta může vaše aplikace potřebovat oprávnění pro přístup k prostředkům v organizaci. V tuto chvíli je jediným způsobem, jak pokračovat v používání této aplikace v tomto tenantovi, požádat správce, aby aplikaci udělil oprávnění, než ji budete moct použít.

Authentication (Ověřování):
- Pokud chcete rozhraní API používat, ověřte se pomocí tokenu Microsoft Entra prostřednictvím OAuth ID Microsoft Entra. Další informace najdete v části ověřování.
- Mít tenanta Microsoft Entra s aktivním předplatným Azure.

Poznámka:

K vytvoření nebo odvolání patů nemůžete použít instanční objekty ani spravované identity.

Ověřování pomocí tokenů Microsoft Entra

Na rozdíl od jiných rozhraní API služby Azure DevOps Services musí uživatelé poskytnout přístupový token Microsoft Entra pro použití tohoto rozhraní API místo tokenu PAT. Tokeny Microsoft Entra představují bezpečnější mechanismus ověřování než používání patů. Vzhledem k tomu, že toto rozhraní API umožňuje vytvářet a odvolávat paty, chceme zajistit, aby tyto výkonné funkce byly uděleny pouze uživatelům.

Pokud chcete získat a aktualizovat přístupové tokeny Microsoft Entra, proveďte následující úlohy:

Důležité

Řešení "On-behalf-of application" (například tok "přihlašovacích údajů klienta") a jakýkoli tok ověřování, který nevydá přístupový token Microsoft Entra, není platný pro použití s tímto rozhraním API. Pokud je ve vašem tenantovi Microsoft Entra povolené vícefaktorové ověřování, musíte určitě použít tok "autorizačního kódu".

Jakmile máte aplikaci s pracovním ověřovacím tokem pro zpracování tokenů Microsoft Entra, můžete pomocí těchto tokenů volat rozhraní API pro správu životního cyklu PAT.

Pokud chcete rozhraní API volat přímo, zadejte přístupový token Microsoft Entra jako Bearer token v Authorization hlavičce vaší žádosti. Další informace a úplný seznam dostupných požadavků najdete v referenčních informacích k rozhraní API PAT.

V následující části si ukážeme, jak vytvořit aplikaci, která ověřuje uživatele pomocí přístupového tokenu Microsoft Entra. Aplikace používá knihovnu MSAL (Microsoft Authentication Library) a volá naše rozhraní API pro správu životního cyklu PAT.

Knihovna MSAL obsahuje více toků ověřování, které můžete použít v rámci aplikace pro získání a aktualizaci tokenů Microsoft Entra. Úplný seznam toků MSAL najdete v dokumentaci k ověřovacím tokům knihovny Microsoft Authentication Library. Průvodce výběrem správné metody ověřování pro vaši aplikaci najdete v části Výběr správné metody ověřování pro Azure DevOps.

Pokud chcete začít, podívejte se na některý z následujících příkladů:

Naklonujte naši ukázkovou aplikaci Python Flask a nakonfigurujte ji s vaším tenantem a organizací ADO.
Vygenerování ukázkové aplikace na webu Azure Portal pro zvolený jazyk a jeho konfigurace pro rozhraní API pro správu životního cyklu PAT

Naklonování webové aplikace Python Flask

Poskytli jsme vám ukázkovou webovou aplikaci Python Flask pro toto rozhraní API, kterou si můžete stáhnout na GitHubu a nakonfigurovat pro použití s vaším tenantem Microsoft Entra a organizací Azure DevOps. Ukázková aplikace používá tok ověřovacího kódu MSAL k získání přístupového tokenu Microsoft Entra.

Důležité

Doporučujeme začít s ukázkovou webovou aplikací Python Flask na GitHubu, ale pokud dáváte přednost použití jiného jazyka nebo typu aplikace, použijte možnost Rychlý start k opětovnému vytvoření ekvivalentní testovací aplikace.

Po naklonování ukázkové aplikace postupujte podle pokynů v souboru README úložiště. Soubor README vysvětluje, jak zaregistrovat aplikaci v tenantovi Microsoft Entra, nakonfigurovat ukázku pro použití tenanta Microsoft Entra a spustit klonovanou aplikaci.

Vygenerování aplikace webu Azure Portal pro rychlý start

Místo toho můžete vygenerovat ukázkovou aplikaci s vygenerovaným kódem MSAL pomocí možnosti Rychlý start na stránce aplikace na webu Azure Portal. Testovací aplikace Pro rychlý start se řídí tokem autorizačního kódu, ale provádí to s koncovým bodem rozhraní Microsoft Graph API. Uživatelé musí aktualizovat konfiguraci aplikace tak, aby odkazovat na koncový bod pro rozhraní API správy životního cyklu PAT.

Pokud chcete postupovat podle tohoto přístupu, postupujte podle pokynů pro rychlý start pro typ aplikace podle vašeho výběru na domovské stránce Microsoft Entra ID Develop docs. Projdeme si následující příklad s aplikací Rychlý start pro Python Flask.

Příklad: Začínáme s aplikací Python Flask Pro rychlý start

Jakmile zaregistrujete aplikaci v tenantovi Microsoft Entra, který má aktivní předplatné Azure, přejděte na svou zaregistrovanou aplikaci v části Registrace aplikace Microsoft Entra ID ->App na webu Azure Portal.
Vyberte aplikaci a přejděte na Oprávnění rozhraní API.
Vyberte Přidat oprávnění a vyberte Azure DevOps –> zkontrolujte user_impersonation –> vyberte Přidat oprávnění.
Vyberte Rychlý start.
Vyberte typ aplikace: pro Python Flask vyberte webovou aplikaci.
Vyberte svou aplikační platformu. Pro účely tohoto kurzu vyberte Python.
Ujistěte se, že splňujete nezbytné požadavky, a pak povolte webu Azure Portal provádět potřebné změny pro konfiguraci aplikace. Adresa URL odpovědi je adresa URL pro přesměrování nastavená při vytváření aplikace + "/getAToken".
Stáhněte si aplikaci Rychlý start a extrahujte soubory.
Nainstalujte požadavky aplikace a spusťte aplikaci, abyste měli jistotu, že máte všechny potřebné závislosti. Aplikace je původně nakonfigurovaná tak, aby v rozhraní Microsoft Graph API dosáhla koncového bodu. Podle pokynů ke konfiguraci v následující části se dozvíte, jak tento koncový bod změnit na základní koncový bod rozhraní API služby PAT Lifecycle Management.

Konfigurace aplikace Pro rychlý start

Jakmile uživatel stáhne a nainstaluje aplikaci Pro rychlý start, nakonfiguruje se tak, aby používal koncový bod testovacího rozhraní API z Microsoft Graphu. Upravte vygenerovaný konfigurační soubor tak, aby místo toho volal rozhraní API pro správu životního cyklu PAT.

Tip

Kolekce a organizace se v těchto dokumentech používá zaměnitelně. Pokud konfigurační proměnná potřebuje název kolekce, nahraďte ji názvem vaší organizace.

Proveďte následující úlohy:

Aktualizace konfigurační proměnné koncového bodu pro https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview rozhraní API správy životního cyklu PAT
Aktualizujte konfigurační proměnnou SCOPE na 499b84ac-1321-427f-aa17-267ca6975798/.default, aby odkazovala na prostředek Azure DevOps a všechny jeho obory.

Následující příklad ukazuje, jak jsme tuto konfiguraci provedli pro aplikaci Python Flask pro rychlý start, kterou jsme vygenerovali prostřednictvím webu Azure Portal v předchozí části.

Ujistěte se, že postupujete podle pokynů k zabezpečení tajného klíče klienta, který je původně vložen do konfiguračního souboru aplikace ve formátu prostého textu. Osvědčeným postupem je odebrat proměnnou prostého textu z konfiguračního souboru a použít proměnnou prostředí nebo Azure KeyVault k zabezpečení tajného kódu aplikace.

Místo tajného klíče klienta můžete použít certifikát. Použití certifikátů je doporučená možnost, pokud se aplikace použije v produkčním prostředí. Pokyny k použití certifikátu najdete v posledním kroku instalace aplikace Pro rychlý start.

Upozornění

Nikdy neochovejte tajný kód klienta ve formátu prostého textu v kódu produkční aplikace.

Příklad: Konfigurace aplikace Rychlého startu Python Flask pro rozhraní API pro správu životního cyklu PAT

Jakmile si stáhnete aplikaci Pro rychlý start, nainstalujte její závislosti a otestujte, že běží ve vašem prostředí, otevřete app_config.py soubor v libovolném editoru. Soubor by měl vypadat podobně jako následující fragment kódu; pro přehlednost byly odebrány komentáře odkazující na výchozí konfiguraci rozhraní Microsoft Graph API:

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

Aktualizujte ID klienta nebo tajný klíč klienta do vaší aplikace pomocí ID klienta a tajného klíče klienta vaší aplikace. V produkčním prostředí nezapomeňte tajný klíč klienta zabezpečit pomocí proměnné prostředí, služby Azure KeyVault nebo přepnutím na certifikát.
```
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.
```

Změňte proměnnou ENDPOINT na adresu URL kolekce Azure DevOps a koncový bod rozhraní API. Například pro kolekci s názvem "testCollection" by hodnota byla:

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

Pro kolekci s názvem testCollection by tento koncový bod byl:

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

Změňte proměnnou SCOPE tak, aby odkazovat na prostředek rozhraní AZURE DevOps API; řetězec znaků je ID prostředku pro rozhraní Azure DevOps API a .default obor odkazuje na všechny obory pro toto ID prostředku.
```
SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
```
Pokud je vaše aplikace nakonfigurovaná pro konkrétního tenanta (místo konfigurace s více tenanty), použijte alternativní hodnotu proměnné AUTHORITY a přidejte název konkrétního tenanta do pole "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"
```

Ověřte, že konečný app_config.py soubor odpovídá následujícímu souboru s vaší CLIENT_ID, ID tenanta a adresou URL kolekce. Z bezpečnostních důvodů se ujistěte, že se CLIENT_SECRET přesunula do proměnné prostředí, Služby Azure KeyVault nebo aby se prohodila s certifikátem pro vaši zaregistrovanou aplikaci:

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

Spusťte aplikaci znovu a otestujte, že můžete získat všechny tokeny PAT pro žádajícího uživatele. Po ověření můžete obsah a 'ms-identity-python-webapp-master\templates' adresář upravit 'app.py' tak, aby podporoval odesílání požadavků do zbývajících koncových bodů rozhraní API správy životního cyklu PAT. Příklad aplikace Pro rychlý start pro Python Flask, která byla upravena tak, aby podporovala požadavky na všechny koncové body rozhraní API pro správu životního cyklu PAT, najdete v tomto ukázkovém úložišti na GitHubu.

Automatická aktualizace přístupového tokenu Microsoft Entra

Jakmile je aplikace správně nakonfigurovaná a uživatel získal přístupový token, můžete ho použít až na hodinu. Kód MSAL uvedený v obou předchozích příkladech token po vypršení platnosti automaticky aktualizuje. Aktualizace tokenu zabrání uživateli v opětovném přihlášení a získání nového autorizačního kódu. Uživatelé se ale můžou po 90 dnech po vypršení platnosti obnovovacího tokenu muset znovu přihlásit.

Seznámení s rozhraními API pro správu životního cyklu PAT

V předchozí ukázkové aplikaci GitHubu a aplikacích Pro rychlý start je aplikace předem nakonfigurovaná tak, aby řídila požadavky pomocí tokenů Microsoft Entra, které jste získali. Další informace najdete v dokumentaci k referenčním informacím k rozhraní API.

Nejčastější dotazy

Otázka: Proč je potřeba provést ověření pomocí tokenu Microsoft Entra? Proč pat nestačí?

A: S tímto rozhraním API pro správu životního cyklu PAT jsme otevřeli možnost vytvářet nové paty a odvolat stávající paty. V nesprávných rukou můžou aktéři se zlými úmysly použít toto rozhraní API k vytvoření několika vstupních bodů do prostředků Azure DevOps vaší organizace. Vynucením ověřování Microsoft Entra doufáme, že toto výkonné rozhraní API bude bezpečnější proti tomuto neoprávněnému použití.

Otázka: Musím mít tenanta Microsoft Entra s aktivním předplatným Azure, aby bylo možné toto rozhraní API používat?

A: Toto rozhraní API je bohužel dostupné jenom uživatelům, kteří jsou součástí tenanta Microsoft Entra s aktivním předplatným Azure.

Otázka: Můžu získat příklad této ukázkové aplikace pro jiný jazyk, architekturu nebo typ aplikace?

Odpověď: Rádi byste chtěli používat rozhraní API ve vašem jazyce podle vašeho výběru. Pokud máte například žádost, přejděte do naší komunity vývojářů, abyste zjistili, jestli má někdo jiný příklad ke sdílení. Pokud máte ukázkovou aplikaci, kterou chcete sdílet s větší cílovou skupinou Azure DevOps, dejte nám vědět a můžeme se na ni podívat podrobněji v těchto dokumentech.

Otázka: Jaký je rozdíl mezi tímto rozhraním API tokenu a rozhraním API pro správu tokenů?

A: Toto rozhraní API tokenu a rozhraní API pro správu tokenů, zatímco podobné, slouží různým případům použití a cílovým skupinám:

Toto rozhraní API tokenu je z velké části určené pro uživatele, kteří chtějí spravovat paty, které vlastní v automatizovaném kanálu. Toto rozhraní API umožňuje. Umožňuje vytvářet nové tokeny a aktualizovat stávající tokeny.
Rozhraní API pro správu tokenů je určené pro správce organizace. Správci můžou toto rozhraní API použít k načítání a odvolávání autorizací OAuth, včetně tokenů PAT (Personal Access Tokens) a samoobslužných popisů tokenů relací uživatelů ve svých organizacích.

Otázka: Jak můžu znovu vygenerovat nebo otočit paty prostřednictvím rozhraní API? Viděl jsem tuhle možnost v uživatelském rozhraní, ale v rozhraní API nevidím podobnou metodu.

Odpověď: Skvělá otázka! Funkce Opětovné generování dostupné v uživatelském rozhraní ve skutečnosti provádí několik akcí, které jsou plně replikovatelné prostřednictvím rozhraní API.

Pokud chcete pat otočit, postupujte takto:

Vysvětlení metadat PAT pomocí volání GET
Pomocí volání POST vytvořte novou pat s metadaty starého PAT.
Odvolání starého patu pomocí volání DELETE

Otázka: Při pokusu o pokračování v používání této aplikace se zobrazí automaticky otevírané okno "Potřebuji schválení správcem". Jak můžu tuto aplikaci používat bez schválení správcem?

A: Zdá se, že váš tenant má zásady zabezpečení, které vyžadují, aby vaše aplikace byla udělena oprávnění pro přístup k prostředkům v organizaci. V tuto chvíli je jediným způsobem, jak pokračovat v používání této aplikace v tomto tenantovi, požádat správce, aby aplikaci udělil oprávnění, než ji budete moct použít.

Otázka: Proč se mi při pokusu o volání rozhraní API pro správu životního cyklu PAT pomocí instančního objektu nebo spravované identity zobrazuje chyba typu Instanční objekty nejsou povolené provádět tuto akci?

A: Instanční objekty a spravované identity nejsou povolené. Vzhledem k tomu, že toto rozhraní API umožňuje vytvářet a odvolávat paty, chceme zajistit, aby tyto výkonné funkce byly uděleny pouze uživatelům.

Další kroky

Informace o koncových bodech rozhraní API pro správu životního cyklu PAT

Sdílet prostřednictvím