Sdílet prostřednictvím

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

  • Článek

Služby Azure DevOps

Pokud pracujete s velkou sadou tokenů PAT (Personal Access Tokens), 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 bohatou sadu rozhraní API umožňuje spravovat pracovní stanice s privilegovanými oprávněními, 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 provádí volání pomocí rozhraní PAT Lifecycle API.

Důležité

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

Požadavky

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. Vzhledem k tomu, že toto rozhraní API umožňuje vytvářet a odvolávat osobní přístupové tokeny, chceme zajistit, aby tyto silné funkce byly k dispozici pouze pro bezpečnější tokeny Microsoft Entra.

Pokud chcete získat a aktualizovat přístupové tokeny Microsoft Entra, musíte udělat toto:

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á Microsoft Authentication Library (MSAL) a volá naše 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 autorizační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.

  1. Jakmile zaregistrujete aplikaci v tenantovi Microsoft Entra s aktivním předplatným Azure, přejděte na svou registrovanou aplikaci v části Microsoft Entra ID –>Registrace aplikací na webu Azure Portal.

    Snímek obrazovky znázorňující otevřené ID Microsoft Entra, Registrace aplikací

  2. Vyberte aplikaci a přejděte na Oprávnění rozhraní API.

    Snímek obrazovky znázorňující výběr aplikace a přechod na oprávnění rozhraní API

  3. Vyberte Přidat oprávnění a vyberte Azure DevOps –> vyberte požadované obory. V tomto případě rozhraní API pro správu životního cyklu PAT podporují pouze user_impersonation, ale jiná rozhraní API mohou požadovat různé podrobnější rozsahy, které najdete na jednotlivých referenčních stránkách rozhraní API. Po výběru všech oborů klikněte na Přidat oprávnění.

    Snímek obrazovky znázorňující přidání oprávnění Azure DevOps user_impersonation

  4. Vyberte Rychlý start.

  5. Vyberte typ aplikace: pro Python Flask vyberte webovou aplikaci.

  6. Vyberte svou aplikační platformu. Pro účely tohoto kurzu vyberte Python.

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

    Snímek obrazovky znázorňující povolení, aby azure Portal mohl provést potřebné změny pro konfiguraci aplikace

  8. Stáhněte si aplikaci Rychlý start a extrahujte soubory.

    Snímek obrazovky ukazuje stažení aplikace Pro rychlý start a extrahování souborů.

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

    Snímek obrazovky znázorňující instalaci požadavků aplikace a spuštění aplikace

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:

  1. 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
  2. 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.

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

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

  3. 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'

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

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

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

  7. 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 'app.py' adresář upravit 'ms-identity-python-webapp-master\templates' 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.

Nejčastější dotazy

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

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ů?

Toto rozhraní API tokenu a rozhraní API pro správu tokenů , ačkoliv jsou si 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.

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:

  1. Vysvětlení metadat PAT pomocí volání GET
  2. Pomocí volání POST vytvořte novou pat s metadaty starého PAT.
  3. 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?

Zdá se, že váš tenant má zásady zabezpečení, které vyžadují, aby vaší aplikaci 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.