Vytvoření webové aplikace pomocí Azure DevOps OAuth 2.0
Služby Azure DevOps
Důležité
Tyto informace platí jenom pro stávající aplikace OAuth Azure DevOps. Noví vývojáři aplikací by měli k integraci s Azure DevOps použít OAuth Microsoft Entra ID.
Azure DevOps je zprostředkovatel identity pro aplikace OAuth 2.0. Naše implementace OAuth 2.0 umožňuje vývojářům autorizovat aplikaci pro uživatele a získat přístupové tokeny pro prostředky Azure DevOps.
Začínáme s Azure DevOps OAuth
1. Registrace aplikace
Přejděte k
https://app.vsaex.visualstudio.com/app/registerregistraci aplikace.Vyberte obory, které vaše aplikace potřebuje, a pak při autorizaci aplikace použijte stejné obory. Pokud jste aplikaci zaregistrovali pomocí rozhraní API ve verzi Preview, znovu se zaregistrujte, protože použité obory jsou teď zastaralé.
Vyberte Vytvořit aplikaci.
Zobrazí se stránka nastavení aplikace.
Když Azure DevOps Services uživateli zobrazí stránku schválení autorizace, použije název vaší společnosti, název aplikace a popisy. Používá také adresy URL pro web vaší společnosti, web aplikace a podmínky poskytování služeb a prohlášení o zásadách ochrany osobních údajů.
Když Služba Azure DevOps Services požádá o autorizaci uživatele a uživatel ji udělí, prohlížeč uživatele se přesměruje na adresu URL zpětného volání autorizace pomocí autorizačního kódu. Adresa URL zpětného volání musí být zabezpečené připojení (https), aby se kód přenesl zpět do aplikace a přesně odpovídal adrese URL zaregistrované ve vaší aplikaci. Pokud ne, zobrazí se místo stránky 400 chybová stránka s žádostí uživatele, aby udělil autorizaci vaší aplikaci.
Zavolejte adresu URL autorizace a předejte ID aplikace a autorizované obory, pokud chcete, aby uživatel autorizoval vaši aplikaci pro přístup ke své organizaci. Pokud chcete získat přístupový token pro volání rozhraní REST API služby Azure DevOps Services, zavolejte adresu URL přístupového tokenu.
Nastavení pro každou aplikaci, kterou zaregistrujete, jsou k dispozici ve vašem profilu https://app.vssps.visualstudio.com/profile/view.
2. Autorizace aplikace
- Pokud uživatel aplikaci neověřil pro přístup ke své organizaci, zavolejte autorizační adresu URL. Zavolá vás zpět s autorizačním kódem, pokud uživatel autorizaci schválí.
https://app.vssps.visualstudio.com/oauth2/authorize
?client_id={app ID}
&response_type={Assertion}
&state={state}
&scope={scope}
&redirect_uri={callback URL}
| Parametr | Typ | Notes |
|---|---|---|
| client_id | Identifikátor GUID | ID přiřazené k aplikaci při registraci |
| response_type | string | Assertion |
| state | string | Může to být libovolná hodnota. Obvykle vygenerovaná řetězcová hodnota, která koreluje zpětné volání s přidruženým požadavkem na autorizaci. |
| rozsah | string | Obory zaregistrované v aplikaci Mezera oddělená. Podívejte se na dostupné obory. |
| redirect_uri | Adresa URL | Adresa URL zpětného volání pro vaši aplikaci Musí přesně odpovídat adrese URL zaregistrované v aplikaci. |
- Přidejte odkaz nebo tlačítko na web, který uživatele přesměruje do koncového bodu autorizace azure DevOps Services:
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
Azure DevOps Services požádá uživatele o autorizaci vaší aplikace.
Za předpokladu, že uživatel přijme, Azure DevOps Services přesměruje prohlížeč uživatele na adresu URL zpětného volání, včetně krátkodobého autorizačního kódu a hodnoty stavu zadané v autorizační adrese URL:
https://fabrikam.azurewebsites.net/myapp/oauth-callback
?code={authorization code}
&state=User1
3. Získání přístupového a obnovovacího tokenu pro uživatele
Autorizační kód použijte k vyžádání přístupového tokenu (a obnovovacího tokenu) pro uživatele. Vaše služba musí provést požadavek HTTP mezi službami do Azure DevOps Services.
Adresa URL – autorizace aplikace
POST https://app.vssps.visualstudio.com/oauth2/token
Hlavičky požadavku HTTP – autorizace aplikace
| Hlavička | Hodnota |
|---|---|
| Typ obsahu | application/x-www-form-urlencoded |
Content-Type: application/x-www-form-urlencoded
Text požadavku HTTP – autorizace aplikace
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}
Nahraďte zástupné hodnoty v textu předchozího ukázkového požadavku:
- {0}: Tajný kód klienta kódovaný adresou URL získaný při registraci aplikace
- {1}: Adresa URL kód kódovaná prostřednictvím parametru dotazu do adresy URL zpětného
codevolání - {2}: Adresa URL zpětného volání zaregistrovaná v aplikaci
Příklad jazyka C# pro vytvoření textu požadavku – autorizace aplikace
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
);
}
Odpověď – autorizace aplikace
{
"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 }
}
Důležité
Bezpečně zachovejte refresh_token , aby aplikace nemusela uživatele vyzvat k opětovné autorizaci. Platnost přístupových tokenů vyprší rychle a neměla by se uchovávat.
4. Použití přístupového tokenu
Pokud chcete použít přístupový token, zahrňte ho jako nosný token do autorizační hlavičky požadavku HTTP:
Authorization: Bearer {access_token}
Například požadavek HTTP na získání nedávných buildů pro projekt:
GET https://dev.azure.com/myaccount/myproject/_apis/build-release/builds?api-version=3.0
Authorization: Bearer {access_token}
5. Aktualizace přístupového tokenu s vypršenou platností
Pokud vyprší platnost přístupového tokenu uživatele, můžete k získání nového přístupového tokenu použít obnovovací token, který získal v autorizačním toku. Je to jako původní proces výměny autorizačního kódu pro přístupový a obnovovací token.
Adresa URL – obnovovací token
POST https://app.vssps.visualstudio.com/oauth2/token
Hlavičky požadavku HTTP – obnovovací token
| Hlavička | Hodnota |
|---|---|
| Typ obsahu | application/x-www-form-urlencoded |
| Délka obsahu | Délka počítaného řetězce textu požadavku (viz následující příklad) |
Content-Type: application/x-www-form-urlencoded
Content-Length: 1654
Text požadavku HTTP – obnovovací token
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=refresh_token&assertion={1}&redirect_uri={2}
Nahraďte zástupné hodnoty v textu předchozího ukázkového požadavku:
- {0}: Tajný kód klienta kódovaný adresou URL získaný při registraci aplikace
- {1}: Obnovovací token zakódovaný adresou URL pro uživatele
- {2}: Adresa URL zpětného volání zaregistrovaná v aplikaci
Odpověď – obnovovací token
{
"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 }
}
Důležité
Uživateli se vydá nový obnovovací token. Tento nový token zachovej a použijte ho při příštím získání nového přístupového tokenu pro uživatele.
Ukázky
Ukázku jazyka C#, která implementuje OAuth pro volání rozhraní REST API služby Azure DevOps Services, najdete v naší ukázce GitHubu C# OAuth.
Opětovné vygenerujte tajný klíč klienta.
Každých 5 let vyprší platnost tajného kódu aplikace. Očekává se, že tajný kód aplikace znovu vygenerujete, abyste mohli dál vytvářet a používat přístupové tokeny a obnovovací tokeny. Uděláte to tak, že kliknete na tlačítko Znovu vygenerovat tajný kód, které zobrazí dialogové okno pro potvrzení, že chcete tuto akci dokončit.
Když potvrdíte, že chcete znovu vygenerovat, předchozí tajný kód aplikace už nebude fungovat a všechny předchozí tokeny s tímto tajným kódem přestanou fungovat. Nezapomeňte zajistit, aby se obměně tajných kódů klienta dobře minimalizovala výpadky zákazníků.
Nejčastější dotazy
Otázka: Můžu v mobilní aplikaci používat OAuth?
Odpověď: Ne. Azure DevOps Services podporuje jenom tok webového serveru, takže neexistuje způsob, jak implementovat OAuth, protože tajný klíč aplikace nejde bezpečně uložit.
Otázka: Jaké chyby nebo zvláštní podmínky musím v kódu zpracovat?
A: Ujistěte se, že zpracováváte následující podmínky:
- Pokud uživatel přístup k aplikaci odepře, nevrátí se žádný autorizační kód. Nepoužívejte autorizační kód bez kontroly odepření.
- Pokud uživatel odvolá autorizaci vaší aplikace, přístupový token už není platný. Když aplikace používá token pro přístup k datům, vrátí se chyba 401. Znovu požádejte o autorizaci.
Otázka: Chci ladit svou webovou aplikaci místně. Můžu při registraci aplikace použít adresu LOCALHOST pro adresu URL zpětného volání?
Odpověď: Ano. Azure DevOps Services teď umožňuje v adrese URL zpětného volání místní hostitele. Při registraci aplikace se ujistěte, že používáte https://localhost jako začátek adresy URL zpětného volání.
Otázka: Při pokusu o získání přístupového tokenu se zobrazí chyba HTTP 400. Co se může pokazit?
A: Zkontrolujte, jestli jste v hlavičce požadavku nastavili typ obsahu na application/x-www-form-urlencoded.
Otázka: Při použití přístupového tokenu založeného na OAuth se zobrazuje chyba HTTP 401, ale pat se stejným oborem funguje správně. Proč?
A: Ověřte, že správce https://dev.azure.com/{your-org-name}/_settings/organizationPolicyvaší organizace na adrese neaktivuje přístup k aplikacím třetích stran prostřednictvím OAuth.
V tomto scénáři tok pro autorizaci aplikace a vygenerování přístupového tokenu funguje, ale všechna rozhraní REST API vrací pouze chybu, například TF400813: The user "<GUID>" is not authorized to access this resource.
Otázka: Můžu použít OAuth s koncovými body SOAP a rozhraními REST API?
Odpověď: Ne. OAuth se v tomto okamžiku podporuje jenom v rozhraních REST API.
Otázka: Jak můžu získat podrobnosti příloh pro pracovní položku pomocí rozhraní REST API Azure DevOps?
A: Nejprve získejte podrobnosti o pracovní položce pomocí pracovních položek – Získání rozhraní REST API pracovní položky :
GET https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}
Pokud chcete získat podrobnosti o přílohách, musíte do adresy URL přidat následující parametr:
$expand=all
S výsledky získáte vlastnost vztahů. Tam najdete adresu URL příloh a v adrese URL najdete ID. Příklad:
$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
Související články
Váš názor
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu: https://aka.ms/ContentUserFeedback.
Odeslat a zobrazit názory pro