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

Článek
10/23/2023

Služby Azure DevOps

Pokud 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 vlastní paty, které vlastníte, a umožňuje vytvářet nové tokeny pat a obnovovat nebo vypršet stávající tokeny pat.

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

Předpoklady

Pokud chcete rozhraní API používat, musíte se ověřit pomocí tokenu Microsoft Entra, který je možné provést prostřednictvím OAuth id Microsoft Entra. Další informace o tom, jak to udělat, najdete v následující části ověřování.

Aby to bylo možné provést, musí být splněno několik požadavků:

Musíte mít tenanta Microsoft Entra s aktivním předplatným Azure.
V závislosti nazásadách 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.

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, který místo tokenu PAT použije toto rozhraní API. 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, musíte:

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

Upozornění

Pokud máte tenanta Microsoft Entra s aktivním předplatným Azure, je předpokladem pro použití tohoto rozhraní API.

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.

Abyste mohli rozhraní API volat přímo, musíte jako token v Authorization hlavičce požadavku zadat přístupový token Bearer Microsoft Entra. Pokud chcete zobrazit příklady a úplný seznam dostupných požadavků, projděte si referenční informace k rozhraní API PAT.

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

Knihovna MICROSOFT Authentication Library (MSAL) obsahuje několik toků ověřování, které můžete použít v rámci aplikace k získání a aktualizaci tokenů Microsoft Entra. Úplný seznam toků MSAL najdete v dokumentaci k ověřovací knihovně 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.

Začněte jedním z těchto dvou 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 můžete ji nakonfigurovat tak, aby se používala 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é budou muset 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 příklad, ve kterém jsme to udělali pro aplikaci Python Flask Pro rychlý start.

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 registrovanou aplikaci v části Registrace aplikace Microsoft Entra ID -> App Registrations 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í.
V levém navigačním panelu 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 jste splnili nezbytné požadavky, a pak povolte webu Azure Portal provádět potřebné změny pro konfiguraci aplikace. Adresa URL odpovědi bude 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 si 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. Budeme muset upravit 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.

Abychom to mohli udělat, musíme udělat několik věcí:

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 vám ukáže, 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 nakonec 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 otestujete, ž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 obor .default 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 (nikoli pro konfiguraci 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í, Azure KeyVault nebo že se prohodila 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. Jakmile ověříte, že máte, 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 pro správu ž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 správy ž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říkladech výše automaticky aktualizuje token, jakmile vyprší jeho platnost. 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ím API pro správu životního cyklu PAT

Ve výše uvedené ukázkové aplikaci GitHubu a aplikacích Pro rychlý start byla aplikace předem nakonfigurovaná tak, aby řídila požadavky pomocí tokenů Microsoft Entra, které jste získali. Další informace o koncových bodech, o parametrech, které přijímají, a o tom, co se vrátí v odpovědích, najdete v referenční dokumentaci k rozhraní API.

Často kladené 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ůže toto rozhraní API použít aktéři se zlými úmysly k vytvoření několika vstupních bodů do prostředků ADO 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áva můžou pomocí tohoto rozhraní API načítat a odvolávat autorizaci OAuth, včetně tokenů PAT (Personal Access Tokens) a samoobslužných 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 "Znovu vygenerovat" 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, musíte:

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

Další kroky

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