Személyes hozzáférési jogkivonatok (PAT-k) kezelése REST API használatával

Cikk
10/23/2023

Azure DevOps Services

Ha nagy számú személyes hozzáférési jogkivonattal (PAT-jal) dolgozik, összetettsé válhat ezeknek a jogkivonatoknak a karbantartása a felhasználói felületen keresztül.

With the PAT Lifecycle Management API, you can easily manage the PATs associated with your organizations using automated processes. Ez a gazdag API-készlet lehetővé teszi a saját paT-k kezelését, lehetővé téve új személyes hozzáférési jogkivonatok létrehozását, valamint a meglévő személyes hozzáférési jogkivonatok megújítását vagy lejáratát.

Ebben a cikkben bemutatjuk, hogyan konfigurálhat egy Microsoft Entra-jogkivonattal hitelesítő alkalmazást, és hogyan indíthat hívásokat a PAT Életciklus API-val. If you'd like to just see the full list of available endpoints, view the API reference here.

Előfeltételek

Az API használatához hitelesítenie kell egy Microsoft Entra-jogkivonattal, amely a Microsoft Entra ID OAuth használatával végezhető el. Erről az alábbi hitelesítési szakaszban olvashat bővebben.

Ennek érdekében néhány előfeltételnek teljesülnie kell:

Aktív Azure-előfizetéssel rendelkező Microsoft Entra-bérlővel kell rendelkeznie.
A bérlő biztonsági szabályzataitól függően előfordulhat, hogy az alkalmazásnak engedélyeket kell adnia a szervezet erőforrásainak eléréséhez. Jelenleg csak úgy folytathatja az alkalmazás használatát ebben a bérlőben, ha megkér egy rendszergazdát, hogy adjon engedélyt az alkalmazásnak, mielőtt használhatná.

Hitelesítés Microsoft Entra-jogkivonatokkal

Más Azure DevOps Services API-któl eltérően a felhasználóknak egy Microsoft Entra hozzáférési jogkivonatot kell biztosítaniuk ahhoz, hogy PAT-jogkivonat helyett használják ezt az API-t. A Microsoft Entra-jogkivonatok biztonságosabb hitelesítési mechanizmust jelentenek, mint a PAT-k használata. Mivel az API képes paT-k létrehozására és visszavonására, biztosítani szeretnénk, hogy az ilyen hatékony funkciók csak az engedélyezett felhasználók számára legyenek elérhetők.

A Microsoft Entra hozzáférési jogkivonatok beszerzéséhez és frissítéséhez a következőkkel kell rendelkeznie:

Fontos

Az "alkalmazás nevében" megoldások (például az "ügyfél hitelesítő adatai" folyamat) és a Microsoft Entra hozzáférési jogkivonatot nem tartalmazó hitelesítési folyamatok nem érvényesek az API-val való használatra. Ha a Többtényezős hitelesítés engedélyezve van a Microsoft Entra-bérlőben, mindenképpen az "engedélyezési kód" folyamatot kell használnia.

Figyelmeztetés

Az API használatának előfeltétele, hogy a Microsoft Entra-bérlő aktív Azure-előfizetéssel rendelkezzen.

Ha már rendelkezik a Microsoft Entra-jogkivonatok kezelésére szolgáló működő hitelesítési folyamattal rendelkező alkalmazással, ezekkel a jogkivonatokkal hívásokat kezdeményezhet a PAT Életciklus Felügyeleti API-hoz.

Ahhoz, hogy közvetlenül meghívhassa az API-t, meg kell adnia egy Microsoft Entra hozzáférési jogkivonatot jogkivonatként Bearer a kérés fejlécében Authorization . A példák és az elérhető kérések teljes listájának megtekintéséhez tekintse meg a PAT API-referenciát

A következő szakaszban bemutatjuk, hogyan hozhat létre olyan alkalmazást, amely microsoft Entra hozzáférési jogkivonattal hitelesít egy felhasználót az MSAL-kódtár használatával, és meghívja a PAT Életciklus Felügyeleti API-t.

A Microsoft Authentication Library (MSAL) több megfelelő hitelesítési folyamatot is tartalmaz, amelyek a Microsoft Entra-jogkivonatok beszerzéséhez és frissítéséhez használhatók az alkalmazásban. Az MSAL-folyamatok teljes listája a Microsoft Authentication Library "hitelesítési folyamatok" dokumentációjában található. Az alkalmazáshoz megfelelő hitelesítési módszer kiválasztásáról az Azure DevOps megfelelő hitelesítési módszerének kiválasztása című témakörben talál útmutatást.

Az első lépésekhez kövesse a két példa valamelyikét:

Python Flask-mintaalkalmazás klónozása és konfigurálása a bérlővel és az ADO-szervezettel
Hozzon létre egy mintaalkalmazást az Azure Portalon a választott nyelvhez, és konfigurálja a PAT Életciklus Felügyeleti API-hoz

Python Flask-webalkalmazás klónozása

A GitHubon letölthető és a Microsoft Entra-bérlővel és az Azure DevOps-szervezettel való használatra konfigurálható Python Flask-mintaalkalmazást biztosítottunk ehhez az API-hoz. A mintaalkalmazás az MSAL hitelesítési kódfolyamat használatával szerez be egy Microsoft Entra hozzáférési jogkivonatot.

Fontos

Javasoljuk, hogy kezdje el használni a Python Flask-mintaalkalmazást a GitHubon, de ha más nyelvet vagy alkalmazástípust szeretne használni, használja a Rövid útmutató lehetőséget egy egyenértékű tesztalkalmazás újbóli létrehozásához.

Miután klónozta a mintaalkalmazást, kövesse az adattár README-jében található utasításokat. A README bemutatja, hogyan regisztrálhat egy alkalmazást a Microsoft Entra-bérlőben, hogyan konfigurálhatja a mintát a Microsoft Entra-bérlő használatára, és hogyan futtathatja a klónozott alkalmazást.

Gyorsútmutató Azure Portal-alkalmazás létrehozása

Ehelyett létrehozhat egy mintaalkalmazást a létrehozott MSAL-kóddal az alkalmazás oldalán, az Azure Portal gyorsútmutató lehetőségével. A gyorsútmutató-tesztalkalmazás követi az engedélyezési kód folyamatát, de ezt egy Microsoft Graph API-végponttal teszi. A felhasználóknak frissítenie kell az alkalmazás konfigurációját, hogy a PAT Életciklus Felügyeleti API végpontjára mutasson.

Ennek a megközelítésnek a követéséhez kövesse a Microsoft Entra ID Develop dokumentációjának kezdőlapján a választott alkalmazástípusra vonatkozó rövid útmutatókat. Bemutatunk egy példát, ahol ezt egy Python Flask gyorsútmutató-alkalmazáshoz készítettük.

Példa: Python Flask rövid útmutató alkalmazás használatának első lépései

Miután regisztrálta az alkalmazást egy aktív Azure-előfizetéssel rendelkező Microsoft Entra-bérlőben, lépjen a regisztrált alkalmazáshoz a Microsoft Entra ID ->App Registrations (Alkalmazásregisztrációk) területen az Azure Portalon.
Válassza ki az alkalmazást, és keresse meg az API-engedélyeket.
Válassza az Engedély hozzáadása lehetőséget, majd az Azure DevOps lehetőséget –> ellenőrizze user_impersonation –> válassza az Engedélyek hozzáadása lehetőséget.
A bal oldali navigációs panelen válassza a Rövid útmutató lehetőséget.
Válassza ki az alkalmazás típusát: a Python Flask esetében válassza a webalkalmazást.
Válassza ki az alkalmazásplatformot. Ebben az oktatóanyagban válassza a "Python" lehetőséget.
Győződjön meg arról, hogy megfelelt a szükséges előfeltételeknek, majd engedélyezze az Azure Portal számára, hogy elvégezhesse az alkalmazás konfigurálásához szükséges módosításokat. A válasz URL-cím az átirányítási URL-cím lesz, amelyet az alkalmazás létrehozása + "/getAToken" beállításnál állítottak be.
Töltse le a rövid útmutató alkalmazást, és bontsa ki a fájlokat.
Telepítse az alkalmazás követelményeit, és futtassa az alkalmazást, hogy meggyőződjön arról, hogy rendelkezik az összes szükséges függőségtel. Az alkalmazás kezdetben úgy van konfigurálva, hogy elérjen egy végpontot a Microsoft Graph API-ban. Ebből a cikkből megtudhatja, hogyan módosíthatja ezt a végpontot a PAT Életciklus Management API alapvégpontra a következő szakaszban található konfigurációs utasítások követésével.

Gyorsútmutató-alkalmazás konfigurálása

Miután a felhasználó letöltötte és telepítette a Rövid útmutató alkalmazást, a rendszer úgy lesz konfigurálva, hogy a Microsoft Graph teszt API-végpontjait használja. Módosítani kell a létrehozott konfigurációs fájlt, hogy inkább a PAT Életciklus Management API-t hívja meg.

Tipp.

Ezekben a dokumentumokban felcserélhetően használjuk a gyűjteményt és a szervezést. Ha egy konfigurációs változónak gyűjteménynévre van szüksége, cserélje le a szervezet nevére.

Ehhez meg kell tennünk néhány dolgot:

Az ENDPOINT konfigurációs változójának https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview frissítése a PAT Életciklus Felügyeleti API-khoz
Frissítse a SCOPE konfigurációs változót a "499b84ac-1321-427f-aa17-267ca6975798/.default" értékre, hogy az Azure DevOps-erőforrásra és annak összes hatókörére hivatkozzon.

Az alábbi példa bemutatja, hogyan hajtottuk végre ezt a konfigurációt az Előző szakaszban az Azure Portalon létrehozott Python Flask-alkalmazáshoz.

Ügyeljen arra, hogy kövesse az ügyfél titkos kódjának védelmét, amely eredetileg egyszerű szövegbe van beszúrva az alkalmazáskonfigurációs fájlba. Ajánlott eljárásként távolítsa el az egyszerű szöveges változót a konfigurációs fájlból, és használjon környezeti változót vagy Azure KeyVaultot az alkalmazás titkos kódjának védelméhez.

Ehelyett dönthet úgy, hogy az ügyfélkulcs helyett tanúsítványt használ. A tanúsítványok használata akkor ajánlott, ha az alkalmazást végül éles környezetben fogják használni. A tanúsítvány használatára vonatkozó utasítások a rövid útmutató alkalmazásbeállításának utolsó lépésében találhatók.

Figyelmeztetés

Soha ne hagyjon egyszerű szöveges ügyfélkulcsot az éles alkalmazás kódjában.

Példa: Python Flask gyorsútmutató-alkalmazás konfigurálása a PAT életciklus-kezelési API-hoz

Miután letöltötte a gyorsútmutató-alkalmazást, telepítette annak függőségeit, és tesztelte, hogy fut-e a környezetben, nyissa meg a fájlt a app_config.py választott szerkesztőben. A fájlnak a következő kódrészlethez kell hasonlítania; az egyértelműség érdekében az alapértelmezett Microsoft Graph API-konfigurációra hivatkozó megjegyzések el lettek távolítva:

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

Frissítse az ügyfél-azonosítót vagy az ügyfélkulcsot az alkalmazásregisztráció ügyfélazonosítójával és titkos ügyfélkódjával. Éles környezetben győződjön meg arról, hogy az ügyfél titkos kulcsát egy környezeti változó, az Azure KeyVault vagy egy tanúsítványra váltás használatával védi.
```
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.
```

Módosítsa a változót ENDPOINT az Azure DevOps-gyűjtemény URL-címére és API-végpontra. Például egy "testCollection" nevű gyűjtemény esetében az érték a következő:

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

A "testCollection" nevű gyűjtemény esetében ez a végpont a következő:

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

Módosítsa a változót SCOPE az Azure DevOps API-erőforrásra való hivatkozáshoz; a karaktersztring az Azure DevOps API erőforrás-azonosítója, az ".default" hatókör pedig az adott erőforrás-azonosító összes hatókörére vonatkozik.
```
SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
```
Ha az alkalmazás egy adott bérlőhöz van konfigurálva (a több-bérlős konfiguráció helyett), használja a AUTHORITY változó alternatív értékét, és adja hozzá az adott bérlőnevet a "Enter_the_Tenant_Name_Here" kifejezéshez.
```
# 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"
```

Ellenőrizze, hogy az utolsó app_config.py fájl megegyezik-e a következővel, a CLIENT_ID, a bérlőazonosítóval és a gyűjtemény URL-címével. Biztonsági okokból győződjön meg arról, hogy a CLIENT_Standard kiadás CRET-t áthelyezték egy környezeti változóba, az Azure KeyVaultba, vagy felcserélték a regisztrált alkalmazáshoz tartozó tanúsítvánnyal:

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

Futtassa újra az alkalmazást annak teszteléséhez, hogy lekérheti-e a kérést kérő felhasználó összes PAT-jogkivonatát. Miután ellenőrizte, hogy rendelkezik-e, nyugodtan módosítsa a tartalom és a 'ms-identity-python-webapp-master\templates' könyvtár tartalmát'app.py', hogy támogassa a kérések küldését a PAT életciklus-kezelési API-végpontok többi részére. Az összes PAT életciklus-kezelési API-végpontra irányuló kérések támogatásához módosított Python Flask rövid útmutatóalkalmazásra példaként tekintse meg ezt a gitHubon található mintaadattárat.

Microsoft Entra hozzáférési jogkivonat automatikus frissítése

Miután az alkalmazás megfelelően konfigurálva lett, és a felhasználó beszerzett egy hozzáférési jogkivonatot, a jogkivonat akár egy óráig is használható. A fenti két példában megadott MSAL-kód automatikusan frissíti a jogkivonatot a lejárat után. A jogkivonat frissítése megakadályozza, hogy a felhasználónak újra be kell jelentkeznie, és be kell szereznie egy új engedélyezési kódot. Előfordulhat azonban, hogy a felhasználóknak 90 nap elteltével újra be kell jelentkezniük a frissítési jogkivonat lejárata után.

A PAT Életciklus Felügyeleti API bemutatása

A fenti GitHub-mintaalkalmazásban és gyorsútmutató-alkalmazásokban az alkalmazás előre konfigurálva lett, hogy kéréseket küldjön a beszerzett Microsoft Entra-jogkivonatokkal. A végpontokról, az általuk elfogadott paraméterekről és a válaszokban visszaadott adatokról az API referencia-dokumentációjában olvashat bővebben.

GYIK

K: Miért van szükségem a Microsoft Entra-jogkivonattal való hitelesítésre? Miért nem elég a PAT?

V: Ezzel a PAT Életciklus Felügyeleti API-val megnyitottuk az új PAT-k létrehozását és a meglévő PAT-k visszavonását. Rossz kezekben ezt az API-t rosszindulatú szereplők használhatják több belépési pont létrehozásához a szervezet ADO-erőforrásaiba. A Microsoft Entra-hitelesítés kényszerítésével reméljük, hogy ez a hatékony API biztonságosabb lesz ezzel a jogosulatlan használattal szemben.

K: Rendelkezni kell egy Aktív Azure-előfizetéssel rendelkező Microsoft Entra-bérlővel ennek az API-nak a használatához?

Válasz: Ez az API sajnos csak az aktív Azure-előfizetéssel rendelkező Microsoft Entra-bérlőhöz tartozó felhasználók számára érhető el.

K: Kaphatok egy példát erre a mintaalkalmazásra egy másik nyelvhez/keretrendszerhez/alkalmazástípushoz?

Válasz: Szeretjük, hogy az API-t a választott nyelven szeretné használni! Ha van egy példakérése, lépjen a fejlesztői közösséghez, és ellenőrizze, hogy van-e másnak egy példa, amelyet meg szeretne osztani. Ha van egy mintaalkalmazása, amelyet meg szeretne osztani a nagyobb Azure DevOps-közönségnek, tudassa velünk, és részletesebben is megvizsgálhatjuk a dokumentációkban való terjesztését!

K: Mi a különbség a token API és a jogkivonat-rendszergazdai API között?

Válasz: Ez a token API és a jogkivonat-rendszergazdai API hasonló módon különböző használati eseteket és célközönségeket szolgál ki:

Ez a jogkivonat API nagyrészt azon felhasználók számára készült, akik egy automatizált folyamatban szeretnék kezelni a tulajdonukba tartozó paT-okat. Ez az API lehetővé teszi. Lehetővé teszi új jogkivonatok létrehozását és a meglévők frissítését.
A jogkivonat-rendszergazdai API szervezeti rendszergazdáknak készült. Rendszergazda az API használatával lekérhetik és visszavonhatják a szervezetük felhasználóinak OAuth-engedélyeit, beleértve a személyes hozzáférési jogkivonatokat (PAT-okat) és az önleíró munkamenet-jogkivonatokat.

K: Hogyan lehet újragenerálni/elforgatni a PAT-okat az API-n keresztül? Láttam ezt a lehetőséget a felhasználói felületen, de nem látok hasonló metódust az API-ban.

Válasz: Nagy kérdés! A felhasználói felületen elérhető "Újragenerálás" funkció ténylegesen végrehajt néhány műveletet, amelyek teljes mértékben replikálhatóak az API-val.

A PAT elforgatásához a következőkre van szükség:

A PAT metaadatainak megismerése GET-hívással,
Hozzon létre egy új PAT-t a régi PAT metaadataival POST-hívással,
A régi PAT visszavonása DELETE-hívással

K: Megjelenik egy "Rendszergazdai jóváhagyásra van szükség" előugró ablak, amikor megpróbálok továbblépni az alkalmazás használatára. Hogyan használhatom ezt az alkalmazást rendszergazdai jóváhagyás nélkül?

Válasz: Úgy tűnik, hogy a bérlő olyan biztonsági szabályzatokat állított be, amelyek megkövetelik, hogy az alkalmazás engedélyt kapjon a szervezet erőforrásainak eléréséhez. Jelenleg csak úgy folytathatja az alkalmazás használatát ebben a bérlőben, ha megkér egy rendszergazdát, hogy adjon engedélyt az alkalmazásnak, mielőtt használhatná.

Következő lépések

Tudnivalók a PAT életciklus-kezelési API-végpontokról