Webalkalmazás létrehozása az Azure DevOps OAuth 2.0 használatával

Cikk
02/06/2024

Azure DevOps Services

Fontos

Ez az információ csak a meglévő Azure DevOps OAuth-alkalmazásokra vonatkozik. Az új alkalmazásfejlesztőknek a Microsoft Entra ID OAuth használatával kell integrálniuk az Azure DevOpsszal.

Az Azure DevOps az OAuth 2.0-alkalmazások identitásszolgáltatója. Az OAuth 2.0 implementációjával a fejlesztők engedélyezhetik az alkalmazásukat a felhasználók számára, és hozzáférési jogkivonatokat szerezhetnek be az Azure DevOps-erőforrásokhoz.

Az Azure DevOps OAuth használatának első lépései

1. Az alkalmazás regisztrálása

Nyissa meg az https://app.vsaex.visualstudio.com/app/register alkalmazás regisztrálását.
Válassza ki az alkalmazás által igényelt hatóköröket , majd használja ugyanazokat a hatóköröket az alkalmazás engedélyezésekor. Ha az alkalmazást az előzetes verziójú API-k használatával regisztrálta, regisztráljon újra, mert a használt hatókörök elavultak.
Válassza az Alkalmazás létrehozása lehetőséget.

Megjelenik az alkalmazásbeállítások lap.
- Amikor az Azure DevOps Services bemutatja az engedélyezési jóváhagyási oldalt a felhasználónak, az az Ön cégnevét, alkalmazásnevét és leírását használja. Emellett a céges webhely, alkalmazáswebhely, szolgáltatási feltételek és adatvédelmi nyilatkozatok URL-címeit is használja.
- Amikor az Azure DevOps Services egy felhasználó engedélyét kéri, és a felhasználó megadja, a rendszer átirányítja a felhasználó böngészőjét az engedélyezési visszahívási URL-címre az engedélyezési kóddal. A visszahívási URL-címnek biztonságos kapcsolatnak (https) kell lennie ahhoz, hogy a kódot visszavihesse az alkalmazásba, és pontosan egyezzen az alkalmazásban regisztrált URL-címével. Ha nem, akkor egy 400-ás hibalap jelenik meg ahelyett, hogy a felhasználó engedélyt kérne az alkalmazáshoz.
Hívja meg az engedélyezési URL-címet, és adja át az alkalmazásazonosítót és az engedélyezett hatóköröket, ha azt szeretné, hogy egy felhasználó engedélyezze az alkalmazás számára a szervezethez való hozzáférést. Hívja meg a hozzáférési jogkivonat URL-címét, ha hozzáférési jogkivonatot szeretne lekérni egy Azure DevOps Services REST API meghívásához.

Az egyes regisztrált alkalmazások beállításai elérhetők a profilból https://app.vssps.visualstudio.com/profile/view.

2. Az alkalmazás engedélyezése

Ha a felhasználó nem engedélyezte az alkalmazás számára a szervezet elérését, hívja meg az engedélyezési URL-címet. Ha a felhasználó jóváhagyja az engedélyezést, visszahívja Önt egy engedélyezési kóddal.

https://app.vssps.visualstudio.com/oauth2/authorize
        ?client_id={app ID}
        &response_type={Assertion}
        &state={state}
        &scope={scope}
        &redirect_uri={callback URL}

Paraméter	Típus szerint	Jegyzetek
ügyfél azonosítója	GUID azonosító	Az alkalmazáshoz rendelt azonosító a regisztrációkor.
response_type	húr	`Assertion`
állapot	húr	Bármilyen érték lehet. Általában egy generált sztringérték, amely korrelálja a visszahívást a hozzá tartozó engedélyezési kéréssel.
hatálya	húr	Az alkalmazással regisztrált hatókörök. Szóköz elválasztva. Tekintse meg az elérhető hatóköröket.
redirect_uri	URL-cím	Az alkalmazás visszahívási URL-címe. Pontosan meg kell egyeznie az alkalmazással regisztrált URL-címmel.

Adjon hozzá egy hivatkozást vagy gombot a webhelyhez, amely a felhasználót az Azure DevOps Services engedélyezési végpontjához irányítja:

https://app.vssps.visualstudio.com/oauth2/authorize
        ?client_id=88e2dd5f-4e34-45c6-a75d-524eb2a0399e
        &response_type=Assertion
        &state=User1
        &scope=vso.work%20vso.code_write
        &redirect_uri=https://fabrikam.azurewebsites.net/myapp/oauth-callback

Az Azure DevOps Services megkéri a felhasználót, hogy engedélyezze az alkalmazást.

Ha a felhasználó elfogadja, az Azure DevOps Services átirányítja a felhasználó böngészőjét a visszahívási URL-címre, beleértve egy rövid élettartamú engedélyezési kódot és az engedélyezési URL-címben megadott állapotértéket:

https://fabrikam.azurewebsites.net/myapp/oauth-callback
        ?code={authorization code}
        &state=User1

3. Hozzáférési és frissítési jogkivonat beszerzése a felhasználó számára

Az engedélyezési kód használatával kérjen hozzáférési jogkivonatot (és frissítse a jogkivonatot) a felhasználó számára. A szolgáltatásnak szolgáltatásról szolgáltatásra irányuló HTTP-kérést kell küldenie az Azure DevOps Servicesnek.

URL - alkalmazás engedélyezése

POST https://app.vssps.visualstudio.com/oauth2/token

HTTP-kérelemfejlécek – alkalmazás engedélyezése

Fejléc	Érték
Content-Type	`application/x-www-form-urlencoded`

Content-Type: application/x-www-form-urlencoded

HTTP-kérelem törzse – alkalmazás engedélyezése

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}

Cserélje le a helyőrző értékeket az előző mintakérés törzsében:

{0}: Az alkalmazás regisztrálásakor beszerzett URL-kódolt ügyfélkód
{1}: A lekérdezési paraméteren keresztül a code visszahívási URL-címhez megadott URL-cím kódolt "kód".
{2}: az alkalmazással regisztrált visszahívási URL-cím

C# példa a kérelem törzsének létrehozásához – alkalmazás engedélyezése

public string GenerateRequestPostData(string appSecret, string authCode, string callbackUrl)
{
   return String.Format("client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}",
               HttpUtility.UrlEncode(appSecret),
               HttpUtility.UrlEncode(authCode),
               callbackUrl
        );
}

Válasz – alkalmazás engedélyezése

{
    "access_token": { access token for the user },
    "token_type": { type of token },
    "expires_in": { time in seconds that the token remains valid },
    "refresh_token": { refresh token to use to acquire a new access token }
}

Fontos

Biztonságosan őrizze meg a refresh_token , hogy az alkalmazásnak ne kelljen újra engedélyeznie a felhasználót. A hozzáférési jogkivonatok gyorsan lejárnak, és nem szabad megmaradni.

4. A hozzáférési jogkivonat használata

Hozzáférési jogkivonat használatához adja meg tulajdonosi jogkivonatként a HTTP-kérés engedélyezési fejlécében:

Authorization: Bearer {access_token}

Például egy projekt legutóbbi buildjeinek lekérésére vonatkozó HTTP-kérés:

GET https://dev.azure.com/myaccount/myproject/_apis/build-release/builds?api-version=3.0
Authorization: Bearer {access_token}

5. Lejárt hozzáférési jogkivonat frissítése

Ha egy felhasználó hozzáférési jogkivonata lejár, használhatja az engedélyezési folyamatban beszerzett frissítési jogkivonatot egy új hozzáférési jogkivonat beszerzéséhez. Ez olyan, mint a hozzáférési és frissítési jogkivonat engedélyezési kódjának cseréjének eredeti folyamata.

URL - frissítési jogkivonat

POST https://app.vssps.visualstudio.com/oauth2/token

HTTP-kérelemfejlécek – jogkivonat frissítése

Fejléc	Érték
Content-Type	`application/x-www-form-urlencoded`
Tartalomhossz	A kérelem törzsének számított sztringhossza (lásd a következő példát)

Content-Type: application/x-www-form-urlencoded
Content-Length: 1654

HTTP-kérelem törzse – frissítési jogkivonat

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=refresh_token&assertion={1}&redirect_uri={2}

Cserélje le a helyőrző értékeket az előző mintakérés törzsében:

{0}: Az alkalmazás regisztrálásakor beszerzett URL-kódolt ügyfélkód
{1}: URL-kódolt frissítési jogkivonat a felhasználó számára
{2}: az alkalmazással regisztrált visszahívási URL-cím

Válasz – frissítési jogkivonat

{
    "access_token": { access token for this user },
    "token_type": { type of token },
    "expires_in": { time in seconds that the token remains valid },
    "refresh_token": { new refresh token to use when the token has timed out }
}

Fontos

A rendszer új frissítési jogkivonatot bocsát ki a felhasználó számára. Őrizze meg ezt az új jogkivonatot, és használja azt a következő alkalommal, amikor új hozzáférési jogkivonatot kell beszereznie a felhasználó számára.

Példák

A C# OAuth GitHub-mintánkban talál egy C#-mintát, amely az OAuthot implementálja az Azure DevOps Services REST API-k meghívásához.

Ügyfélkulcs újragenerálása

Az alkalmazás titkos kódja 5 évente lejár. Az alkalmazás titkos kódját várhatóan újra kell létrehoznia, hogy továbbra is létre tudja hozni és használni tudja a hozzáférési jogkivonatokat, és frissítse a jogkivonatokat. Ehhez kattintson a "Titkos kód újragenerálása" gombra, amely megjelenik egy párbeszédpanelen, amely megerősíti, hogy végre szeretné hajtani ezt a műveletet.

Screenshot confirming secret regeneration.

Amikor megerősíti, hogy újra létre szeretné hozni az alkalmazást, az előző alkalmazáskulcs már nem fog működni, és az ezzel a titkos kóddal kivert összes korábbi jogkivonat is leáll. Győződjön meg arról, hogy az ügyfél titkos kulcsának rotációja megfelelően időzít, hogy minimálisra csökkentse az ügyfelek állásidejét.

Gyakori kérdések (GYIK)

K: Használhatom az OAuth-ot a mobiltelefonos alkalmazásommal?

V.: Nem. Az Azure DevOps Services csak a webkiszolgálói folyamatot támogatja, ezért nem lehet implementálni az OAuthot, mivel nem tárolhatja biztonságosan az alkalmazás titkos kódját.

K: Milyen hibákat vagy speciális feltételeket kell kezelnem a kódban?

Válasz: Győződjön meg arról, hogy a következő feltételeket kezeli:

Ha a felhasználó tagadja az alkalmazáshoz való hozzáférést, a rendszer nem ad vissza engedélyezési kódot. Ne használja az engedélyezési kódot a megtagadás ellenőrzése nélkül.
Ha a felhasználó visszavonja az alkalmazás engedélyét, a hozzáférési jogkivonat már nem érvényes. Amikor az alkalmazás a jogkivonatot használja az adatok eléréséhez, 401-hiba jelenik meg. Kérje újra az engedélyezést.

K: Szeretnék helyileg hibakeresést végezni a webalkalmazásomban. Használhatom a localhostot a visszahívási URL-címhez az alkalmazás regisztrálásakor?

V: Igen. Az Azure DevOps Services mostantól engedélyezi a localhost használatát a visszahívási URL-címében. Győződjön meg arról, hogy a visszahívási URL-cím elején használja https://localhost az alkalmazás regisztrálásakor.

K: HTTP 400-hiba jelenik meg, amikor megpróbálok hozzáférési jogkivonatot lekérni. Mi lehet a hiba?

Válasz: Ellenőrizze, hogy a tartalomtípust az application/x-www-form-urlencoded értékre állította-e a kérés fejlécében.

K: HTTP 401-es hibát kapok OAuth-alapú hozzáférési jogkivonat használatakor, de az azonos hatókörű PAT rendben működik. Miért?

Válasz: Ellenőrizze, hogy a szervezet rendszergazdája https://dev.azure.com/{your-org-name}/_settings/organizationPolicynem tiltotta-e le az OAuthon keresztüli külső alkalmazáshozzáférést. Ebben a forgatókönyvben az alkalmazás engedélyezésére és hozzáférési jogkivonat létrehozására szolgáló folyamat működik, de minden REST API csak egy hibát ad vissza, például TF400813: The user "<GUID>" is not authorized to access this resource.

K: Használhatom az OAuthot a SOAP-végpontokkal és REST API-kkal?

V.: Nem. Az OAuth jelenleg csak a REST API-kban támogatott.

K: Hogyan kérhetem le a munkahelyi elemem mellékleteinek részleteit az Azure DevOps REST API-k használatával?

Válasz: Először a munkaelem részleteinek lekérése a Munkaelemekkel – Munkaelem REST API-jának lekérése :

GET https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}

A mellékletek részleteinek lekéréséhez a következő paramétert kell hozzáadnia az URL-címhez:

$expand=all

Az eredményekkel megkapja a kapcsolatok tulajdonságot. Itt megtalálhatja a mellékletek URL-címét, az URL-címen belül pedig az azonosítót. Példa:

$url = https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/434?$expand=all&api-version=5.0

$workItem = Invoke-RestMethod -Uri $url -Method Get -ContentType application/json

$split = ($workitem.relations.url).Split('/')

$attachmentId = $split[$split.count - 1]

# Result: 1244nhsfs-ff3f-25gg-j64t-fahs23vfs

Megosztás a következőn keresztül:

Webalkalmazás létrehozása az Azure DevOps OAuth 2.0 használatával

Az Azure DevOps OAuth használatának első lépései

1. Az alkalmazás regisztrálása

2. Az alkalmazás engedélyezése

3. Hozzáférési és frissítési jogkivonat beszerzése a felhasználó számára

URL - alkalmazás engedélyezése

HTTP-kérelemfejlécek – alkalmazás engedélyezése

HTTP-kérelem törzse – alkalmazás engedélyezése

C# példa a kérelem törzsének létrehozásához – alkalmazás engedélyezése

Válasz – alkalmazás engedélyezése

4. A hozzáférési jogkivonat használata

5. Lejárt hozzáférési jogkivonat frissítése

URL - frissítési jogkivonat

HTTP-kérelemfejlécek – jogkivonat frissítése

HTTP-kérelem törzse – frissítési jogkivonat

Válasz – frissítési jogkivonat

Példák

Ügyfélkulcs újragenerálása

Gyakori kérdések (GYIK)

K: Használhatom az OAuth-ot a mobiltelefonos alkalmazásommal?

K: Milyen hibákat vagy speciális feltételeket kell kezelnem a kódban?

K: Szeretnék helyileg hibakeresést végezni a webalkalmazásomban. Használhatom a localhostot a visszahívási URL-címhez az alkalmazás regisztrálásakor?

K: HTTP 400-hiba jelenik meg, amikor megpróbálok hozzáférési jogkivonatot lekérni. Mi lehet a hiba?

K: HTTP 401-es hibát kapok OAuth-alapú hozzáférési jogkivonat használatakor, de az azonos hatókörű PAT rendben működik. Miért?

K: Használhatom az OAuthot a SOAP-végpontokkal és REST API-kkal?

K: Hogyan kérhetem le a munkahelyi elemem mellékleteinek részleteit az Azure DevOps REST API-k használatával?

Visszajelzés

Visszajelzés

További források

Megosztás a következőn keresztül:

Webalkalmazás létrehozása az Azure DevOps OAuth 2.0 használatával

Az Azure DevOps OAuth használatának első lépései

1. Az alkalmazás regisztrálása

2. Az alkalmazás engedélyezése

3. Hozzáférési és frissítési jogkivonat beszerzése a felhasználó számára

URL - alkalmazás engedélyezése

HTTP-kérelemfejlécek – alkalmazás engedélyezése

HTTP-kérelem törzse – alkalmazás engedélyezése

C# példa a kérelem törzsének létrehozásához – alkalmazás engedélyezése

Válasz – alkalmazás engedélyezése

4. A hozzáférési jogkivonat használata

5. Lejárt hozzáférési jogkivonat frissítése

URL - frissítési jogkivonat

HTTP-kérelemfejlécek – jogkivonat frissítése

HTTP-kérelem törzse – frissítési jogkivonat

Válasz – frissítési jogkivonat

Példák

Ügyfélkulcs újragenerálása

Gyakori kérdések (GYIK)

K: Használhatom az OAuth-ot a mobiltelefonos alkalmazásommal?

K: Milyen hibákat vagy speciális feltételeket kell kezelnem a kódban?

K: Szeretnék helyileg hibakeresést végezni a webalkalmazásomban. Használhatom a localhostot a visszahívási URL-címhez az alkalmazás regisztrálásakor?

K: HTTP 400-hiba jelenik meg, amikor megpróbálok hozzáférési jogkivonatot lekérni. Mi lehet a hiba?

K: HTTP 401-es hibát kapok OAuth-alapú hozzáférési jogkivonat használatakor, de az azonos hatókörű PAT rendben működik. Miért?

K: Használhatom az OAuthot a SOAP-végpontokkal és REST API-kkal?

K: Hogyan kérhetem le a munkahelyi elemem mellékleteinek részleteit az Azure DevOps REST API-k használatával?

Kapcsolódó cikkek

Visszajelzés

Visszajelzés

További források