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

Cikk
05/15/2024

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.

A PAT életciklus-felügyeleti API-jával, automatizált folyamatok használatával egyszerűen kezelheti a szervezetekkel társított PAT-ket. Ez a gazdag API-készlet lehetővé teszi a 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 kell beállítani egy olyan alkalmazást, amely Microsoft Entra tokennel hitelesíti magát, és hívásokat kezdeményez a PAT Lifecycle API-val. Ha csak az elérhető végpontok teljes listáját szeretné látni, tekintse meg itt az API-referenciát.

Előfeltételek

Az API használatához hitelesítenie kell egy Microsoft Entra-jogkivonattal, amelyet a Microsoft Entra ID OAuth használatával tehet meg. További információkért lásd a hitelesítési szakaszt.

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élyre van szüksége 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á.

Feljegyzés

Szolgáltatásnevek vagy felügyelt identitások nem használhatók PAT-k létrehozására vagy visszavonására.

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.

Figyelemfelhívá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ájá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 folyamatainak 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 GitHubról 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 önnek 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.

A mintaalkalmazás klónozása után 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. Az alábbi példát egy Python Flask gyorsútmutató-alkalmazással mutatjuk be.

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.
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 Pythont.
Győződjön meg arról, hogy megfelel a szükséges előfeltételeknek, majd engedélyezze az Azure Portal számára 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, 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 gyorsútmutató alkalmazást, úgy van konfigurálva, hogy egy teszt API-végpontot használjon a Microsoft Graphból. 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.

Végezze el a következő feladatokat:

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 ajánlott, ha az alkalmazás éles környezetben lesz használatban. 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.

Figyelemfelhívá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 kedvéért 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 változó alternatív értékét AUTHORITY , és adja hozzá az adott bérlő nevét 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-et áthelyezték egy környezeti változóba, az Azure KeyVaultba, vagy felcserélték a regisztrált alkalmazás tanúsítványával:

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. Az ellenőrzés után módosíthatja 'app.py' a könyvtár tartalmát és 'ms-identity-python-webapp-master\templates' tartalmát, 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 gyorsú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

Ha az alkalmazás megfelelően van konfigurálva, és a felhasználó beszerzett egy hozzáférési jogkivonatot, a jogkivonat akár egy óráig is használható. A két előző 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-kezelési API-k felfedezése

A fenti GitHub-mintaalkalmazásban és gyorsútmutató-alkalmazásokban az alkalmazás előre konfigurálva van, hogy kéréseket küldjön a beszerzett Microsoft Entra-jogkivonatokkal. További információkért tekintse meg az API-referencia dokumentumokat.

Gyakori kérdések (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 a rosszindulatú szereplők ezzel az API-val több belépési pontot hozhatnak létre a szervezet Azure DevOps-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ő "Regenerate" 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 hajtsa végre a következő lépéseket:

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ő biztonsági szabályzatokkal rendelkezik, 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: Miért jelenik meg olyan hibaüzenet, mint a "Szolgáltatásnevek nem hajthatják végre ezt a műveletet", amikor megpróbálok meghívni a PAT Életciklus Felügyeleti API-t szolgáltatásnévvel vagy felügyelt identitással?

Válasz: A szolgáltatásnevek és a felügyelt identitások nem engedélyezettek. 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.

Következő lépések

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

Share via