Vytvoření webové aplikace pomocí Azure DevOps OAuth 2.0

Služby Azure DevOps

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

1. Přejděte k https://app.vsaex.visualstudio.com/app/register registraci aplikace.

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

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

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

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

2. 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=00001111-aaaa-2222-bbbb-3333cccc4444
        &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

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 code volá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 }
}

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

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 }
}

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 pět let vyprší platnost tajného kódu aplikace. Znovu vygenerujte tajný kód aplikace, abyste mohli dál vytvářet a používat přístupové tokeny a obnovovací tokeny. Uděláte to tak, že vyberete Znovu vygenerovat tajný klíč, který pak potvrdí, že chcete tuto akci dokončit.

Když potvrdíte, že chcete znovu vygenerovat, předchozí tajný kód aplikace už nefunguje a všechny předchozí tokeny vytěsněné tímto tajným kódem také přestanou fungovat. Nezapomeňte zajistit, aby se obměně tajných kódů klienta dobře minimalizovala výpadky zákazníků.

Odstranění aplikace

Pokud už aplikaci nepotřebujete, odstraňte ji ze svého profilu.

1. Přejděte na svůj profil na adrese: https://app.vssps.visualstudio.com/profile/view.

2. Ujistěte se, že jste na správné stránce tenanta, a to tak, že na bočním panelu vyberete z rozevírací nabídky pod vaším jménem.

3. Na levém bočním panelu najděte aplikaci v záhlaví Aplikace a služby .

4. Na stránce registrace aplikace vyberte Odstranit. Zobrazí se modální potvrzení odstranění.

   

5. Jakmile odstraníte registraci aplikace, aplikace se přeruší a přestaneme generovat nové tokeny nebo přijímat tokeny vytěsněné pro tuto aplikaci.

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 vaší organizace nezakazoval přístup k aplikacím třetích stran prostřednictvím OAuth na adrese https://dev.azure.com/{your-org-name}/_settings/organizationPolicy. 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.

Související články

• Výběr správné metody ověřování
• Použití OAuth v Microsoft Entra ID
• Výchozí oprávnění a přístup pro Azure DevOps
• Správa autorizací