Microsoft identity platform a tok přihlašovacích údajů klienta OAuth 2.0

Pro přístup k prostředkům hostovaným na webu pomocí identity aplikace můžete použít udělení přihlašovacích údajů klienta OAuth 2.0 zadané v dokumentu RFC 6749, někdy nazývané dvounohé OAuth. Tento typ udělení se běžně používá pro interakce mezi servery, které musí běžet na pozadí bez okamžité interakce s uživatelem. Tyto typy aplikací se často označují jako procesy démon nebo účty služeb.

Tento článek popisuje, jak programovat přímo pomocí protokolu ve vaší aplikaci. Pokud je to možné, doporučujeme k získání tokenů a volání zabezpečených webových rozhraní API použít podporované knihovny msal (Microsoft Authentication Libraries). Podívejte se také na ukázkové aplikace, které používají MSAL.

Tok udělení přihlašovacích údajů klienta OAuth 2.0 umožňuje webové službě (důvěrnému klientovi) používat vlastní přihlašovací údaje místo zosobnění uživatele k ověření při volání jiné webové služby. Pro zajištění vyšší úrovně záruky umožňuje Microsoft identity platform volající službě používat certifikát (místo sdíleného tajného klíče) jako přihlašovací údaje. Vzhledem k tomu, že se používají vlastní přihlašovací údaje aplikací, musí být tyto přihlašovací údaje v bezpečí – nikdy tyto přihlašovací údaje ne publikujte ve zdrojovém kódu, vložte je na webové stránky nebo je používejte v široce distribuované nativní aplikaci.

V toku přihlašovacích údajů klienta uděluje oprávnění přímo aplikaci samotné správcem. Když aplikace prostředku prezentuje token, prostředek vynutí, že aplikace má autorizaci k provedení akce, protože ověřování nemá žádný uživatel. Tento článek popisuje jak kroky potřebné k autorizaci aplikace pro volání rozhraní API,tak postup získání tokenů potřebných k volání tohoto rozhraní API.

Tip

Zkuste tento požadavek v postmanu spuštěný.
Zkuste tento požadavek a další informace odeslat v Postmanu – nezapomeňte nahradit tokeny a ID.

Diagram protokolu

Celý tok přihlašovacích údajů klienta vypadá podobně jako v následujícím diagramu. Jednotlivé kroky popisujeme dále v tomto článku.

Diagram znázorňující tok přihlašovacích údajů klienta

Získání přímé autorizace

Aplikace obvykle obdrží přímou autorizaci pro přístup k prostředku jedním ze dvou způsobů:

Tyto dvě metody jsou v Azure AD nejběžnější a doporučujeme je použít pro klienty a prostředky, které provádějí tok přihlašovacích údajů klienta. Prostředek se také může rozhodnout autorizovat své klienty jinými způsoby. Každý server prostředků může zvolit metodu, která pro svou aplikaci dává největší smysl.

Seznamy řízení přístupu

Poskytovatel prostředků může vynucovat kontrolu autorizace na základě seznamu ID aplikací (klientů), která zná a udělí konkrétní úroveň přístupu. Když prostředek obdrží token z Microsoft identity platform, může tento token dekódovat a extrahovat ID aplikace klienta z deklarací identity a appid iss . Pak porovná aplikaci se seznamem řízení přístupu (ACL), který udržuje. Členitost a metoda seznamu ACL se můžou mezi prostředky výrazně lišit.

Běžným případem použití je použití seznamu ACL ke spouštění testů pro webovou aplikaci nebo pro webové rozhraní API. Webové rozhraní API může konkrétnímu klientovi udělit pouze podmnožinu úplných oprávnění. Pokud chcete na rozhraní API spouštět testy od konce, vytvořte testovacího klienta, který získá tokeny z Microsoft identity platform a pak je odešle do rozhraní API. Rozhraní API pak zkontroluje seznam ACL pro ID aplikace testovacího klienta, aby byl k dispozici úplný přístup k celé funkci rozhraní API. Pokud používáte tento druh seznamu ACL, nezapomeňte ověřit nejen hodnotu volajícího, ale také ověřit, že hodnota tokenu je appid iss důvěryhodná.

Tento typ autorizace je běžný pro procesy démon a účty služeb, které potřebují přístup k datům vlastněných uživateli, kteří mají osobní účty Microsoft. Pro data vlastněná organizacemi doporučujeme získat potřebnou autorizaci prostřednictvím oprávnění aplikace.

Řízení tokenů bez roles deklarace identity

Aby bylo možné tento model autorizace na základě seznamu ACL povolit, Azure AD nevyžaduje, aby aplikace měly oprávnění k získání tokenů pro jinou aplikaci. Proto je možné tokeny jen pro aplikace vystavovat bez roles deklarace identity. Aplikace, které vystavují rozhraní API, musí implementovat kontroly oprávnění, aby přijímaly tokeny.

Pokud chcete aplikacím zabránit v získání přístupových tokenů aplikace bez rolí, ujistěte se, že jsou pro vaši aplikaci povolené požadavky na přiřazení uživatelů. Tím se uživatelům a aplikacím bez přiřazených rolí zablokuje možnost získat token pro tuto aplikaci.

Oprávnění aplikace

Místo použití seznamu ACL můžete pomocí rozhraní API zveřejnit sadu aplikačních oprávnění. Oprávnění aplikace je aplikaci uděleno správcem organizace a lze ho použít pouze pro přístup k datům vlastněných organizací a jejími zaměstnanci. Microsoft Graph například zveřejňuje několik oprávnění aplikace k následujícím akcím:

  • Čtení pošty ve všech poštovních schránkách
  • Čtení a zápis e-mailů ve všech poštovních schránkách
  • Odeslání e-mailu jako jakýkoli uživatel
  • Čtení dat z adresáře

Pokud chcete oprávnění aplikace používat s vlastním rozhraním API (na rozdíl od Microsoft Graph), musíte rozhraní API nejprve zveřejnit definováním oborů v registraci aplikace rozhraní API v Azure Portal. Pak nakonfigurujte přístup k rozhraní API tak, že tato oprávnění vyberete v registraci aplikace vaší klientské aplikace. Pokud jste v registraci aplikace vašeho rozhraní API nez vystavení žádných oborů, nebudete moct zadat oprávnění aplikace k rozhraní API v registraci aplikace klientské aplikace v Azure Portal.

Při ověřování jako aplikace (na rozdíl od uživatele) nemůžete použít delegovaná oprávnění obory, které jsou udělené uživatelem – protože aplikace nemá žádného uživatele, který by jednal jménem. Musíte použít oprávnění aplikace, označované také jako role, které správce udělil pro aplikaci nebo prostřednictvím předběžné autorizace webovým rozhraním API.

Další informace o oprávněních aplikací najdete v tématu Oprávnění a souhlas.

Když sestavíte aplikaci, která používá oprávnění aplikace, aplikace obvykle vyžaduje stránku nebo zobrazení, na kterém správce schválí oprávnění aplikace. Tato stránka může být součástí přihlašovacího toku aplikace, součástí nastavení aplikace nebo vyhrazeným tokem připojení. V mnoha případech dává smysl, aby aplikace toto zobrazení "připojení" předala až poté, co se uživatel přihlásil pomocí pracovního nebo školního účet Microsoft.

Pokud uživatele přihlásíte k aplikaci, můžete určit organizaci, do které uživatel patří, než uživatele požádáte o schválení oprávnění aplikace. I když to není nezbytně nutné, může vám to pomoct vytvořit intuitivnější prostředí pro vaše uživatele. Pokud se chcete přihlásit k uživateli, postupujte podle Microsoft identity platform protokolu.

Vyžádání oprávnění od správce adresáře

Až budete připraveni požádat správce organizace o oprávnění, můžete uživatele přesměrovat na koncový bod souhlasu správce Microsoft identity platform správce.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=http://localhost/myapp/permissions

Pro tip: Zkuste do prohlížeče vložením následujícího požadavku.

https://login.microsoftonline.com/common/adminconsent?client_id=6731de76-14a6-49ae-97bc-6eba6914391e&state=12345&redirect_uri=http://localhost/myapp/permissions
Parametr Podmínka Popis
tenant Povinné Tenant adresáře, ze kterého chcete požádat o oprávnění. Může být ve formátu GUID nebo popisný název. Pokud nevíte, do kterého tenanta uživatel patří, a chcete, aby se přihlašoval pomocí libovolného tenanta, použijte common .
client_id Vyžadováno ID aplikace (klienta), které Azure Portal – Registrace aplikací prostředí přiřazené k vaší aplikaci.
redirect_uri Vyžadováno Identifikátor URI přesměrování, do kterého se má odpověď odeslat, aby vaše aplikace zvládla. Musí přesně odpovídat jedné z identifikátorů URI přesměrování, které jste zaregistrovali na portálu, s tím rozdílem, že musí být zakódovaná adresa URL a může mít další segmenty cesty.
state Doporučeno Hodnota, která je součástí požadavku, která je také vrácena v odpovědi tokenu. Může to být řetězec libovolného obsahu, který chcete. Stav se používá ke kódování informací o stavu uživatele v aplikaci před tím, než došlo k žádosti o ověření, jako je například stránka nebo zobrazení, na které byl uživatel.

V tomto okamžiku Azure AD vynucuje, aby se k dokončení žádosti mohl přihlásit pouze správce tenanta. Správce bude požádán o schválení všech přímých oprávnění aplikace, která jste pro svou aplikaci vyžádali na portálu pro registraci aplikací.

Úspěšná odpověď

Pokud správce schválí oprávnění pro vaši aplikaci, úspěšná odpověď bude vypadat takhle:

GET http://localhost/myapp/permissions?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&state=state=12345&admin_consent=True
Parametr Popis
tenant Tenant adresáře, který vaší aplikaci udělil požadovaná oprávnění ve formátu GUID.
state Hodnota, která je součástí požadavku, která je také vrácena v odpovědi tokenu. Může to být řetězec libovolného obsahu, který chcete. Stav se používá ke kódování informací o stavu uživatele v aplikaci před tím, než došlo k žádosti o ověření, jako je například stránka nebo zobrazení, na které byl uživatel.
admin_consent Nastavte na Hodnotu True.
Chybová odpověď

Pokud správce neschválí oprávnění pro vaši aplikaci, odpověď, která selhala, vypadá takhle:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Parametr Popis
error Řetězec kódu chyby, který můžete použít ke klasifikaci typů chyb a který můžete použít k reakci na chyby.
error_description Konkrétní chybová zpráva, která vám může pomáhat identifikovat hlavní příčinu chyby.

Po přijetí úspěšné odpovědi z koncového bodu zřizování aplikace získala aplikace přímo požadovaná oprávnění aplikace. Nyní můžete požádat o token pro prostředek, který chcete.

Získání tokenu

Po získání potřebné autorizace pro vaši aplikaci pokračujte v získání přístupových tokenů pro rozhraní API. pokud chcete získat token pomocí udělení přihlašovacích údajů klienta, odešlete požadavek POST do /token Microsoft identity platform:

První případ: žádost přístupového tokenu se sdíleným tajným klíčem

POST /{tenant}/oauth2/v2.0/token HTTP/1.1           //Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=sampleCredentia1s
&grant_type=client_credentials
# Replace {tenant} with your tenant!
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'client_id=535fb089-9ff3-47b6-9bfb-4f1264799865&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=qWgdYAmab0YSkuL1qKv5bPX&grant_type=client_credentials' 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token'
Parametr Podmínka Popis
tenant Povinné Tenant adresáře, na který aplikace plánuje pracovat, v identifikátoru GUID nebo ve formátu názvu domény.
client_id Vyžadováno ID aplikace přiřazené vaší aplikaci. Tyto informace najdete na portálu, kde jste zaregistrovali vaši aplikaci.
scope Vyžadováno Hodnota předaná pro scope parametr v této žádosti by měla být identifikátorem prostředku (identifikátor URI ID aplikace) prostředku, který chcete připojit, a to s .default příponou. v příkladu Microsoft Graph je hodnota https://graph.microsoft.com/.default .
tato hodnota oznamuje Microsoft identity platform, že všechna oprávnění k přímé aplikaci, která jste nakonfigurovali pro vaši aplikaci, koncový bod by měl vydat token pro ty, které jsou přidružené k prostředku, který chcete použít. Další informace o tomto /.default oboru najdete v dokumentaci k vyjádření souhlasu.
client_secret Vyžadováno Tajný kód klienta, který jste vygenerovali pro vaši aplikaci na portálu pro registraci aplikací. Tajný klíč klienta musí být před odesláním zakódovaný na adrese URL. Základní vzor ověřování místo toho, aby poskytoval přihlašovací údaje v autorizační hlavičce, je také podporován na základě RFC 6749 .
grant_type Vyžadováno Musí být nastaven na hodnotu client_credentials .

Druhý případ: žádost o přístupový token s certifikátem

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=97e0a5b7-d745-40b6-94fe-5f77d35c6e05
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials
Parametr Podmínka Popis
tenant Povinné Tenant adresáře, na který aplikace plánuje pracovat, v identifikátoru GUID nebo ve formátu názvu domény.
client_id Vyžadováno ID aplikace (klienta), které je přiřazeno vaší aplikaci.
scope Vyžadováno Hodnota předaná pro scope parametr v této žádosti by měla být identifikátorem prostředku (identifikátor URI ID aplikace) prostředku, který chcete připojit, a to s .default příponou. v příkladu Microsoft Graph je hodnota https://graph.microsoft.com/.default .
tato hodnota informuje Microsoft identity platform, že všechna oprávnění k přímé aplikaci, která jste nakonfigurovali pro vaši aplikaci, by měla vydávat token pro ty, které jsou přidružené k prostředku, který chcete použít. Další informace o tomto /.default oboru najdete v dokumentaci k vyjádření souhlasu.
client_assertion_type Vyžadováno Hodnota musí být nastavena na urn:ietf:params:oauth:client-assertion-type:jwt-bearer .
client_assertion Vyžadováno Kontrolní výraz (webový token JSON), který potřebujete k vytvoření a podepsání certifikátu, který jste zaregistrovali jako přihlašovací údaje pro vaši aplikaci. Přečtěte si informace o přihlašovacích údajích k certifikátu , kde se dozvíte, jak zaregistrovat certifikát a formát kontrolního výrazu.
grant_type Vyžadováno Musí být nastaven na hodnotu client_credentials .

Parametry žádosti založené na certifikátech se liší pouze jediným způsobem ze sdíleného tajného klíče: client_secret parametr je nahrazen client_assertion_type client_assertion parametry a.

Úspěšná odpověď

Úspěšná odpověď z obou metod vypadá takto:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
Parametr Popis
access_token Požadovaný přístupový token Aplikace může tento token použít k ověření zabezpečeného prostředku, například k webovému rozhraní API.
token_type Určuje hodnotu typu tokenu. jediný typ, který Microsoft identity platform podporuje, je bearer .
expires_in Doba, po kterou je přístupový token platný (v sekundách).

Upozornění

Nepokoušejte se ve svém kódu ověřovat ani číst tokeny pro žádné rozhraní API, které vlastníte, včetně tokenů v tomto příkladu. Tokeny pro služby Microsoft mohou používat speciální formát, který se neověřuje jako JWT a může být také šifrován pro uživatele příjemce (účet Microsoft). Čtení tokenů je užitečný nástroj pro ladění a učení, ale nezá závislostí na tomto tokenu v kódu ani předpokládejte konkrétní informace o tokenech, které nejsou pro rozhraní API, které řídíte.

Chybová odezva

Reakce na chybu vypadá takto:

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/.default is not valid.\r\nTrace ID: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
Parametr Popis
error Řetězec kódu chyby, který můžete použít ke klasifikaci typů chyb, ke kterým dochází, a k reakci na chyby.
error_description Konkrétní chybová zpráva, která vám může pomáhat identifikovat hlavní příčinu chyby ověřování.
error_codes Seznam chybových kódů specifických pro službu STS, které mohou pomáhat s diagnostikou.
timestamp Čas, kdy došlo k chybě.
trace_id Jedinečný identifikátor pro požadavek, který vám může pomáhat s diagnostikou.
correlation_id Jedinečný identifikátor požadavku, který bude pomáhat s diagnostikou napříč komponentami.

Použití tokenu

Teď, když jste získali token, použijte token k vytvoření požadavků na prostředek. Po vypršení platnosti tokenu opakujte požadavek na /token koncový bod pro získání nového přístupového tokenu.

GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
# Pro tip: Try the following command! (Replace the token with your own.)

curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...." 'https://graph.microsoft.com/v1.0/me/messages'

Ukázky kódu a další dokumentace

Přečtěte si dokumentaci přehled přihlašovacích údajů klienta z knihovny Microsoft Authentication Library.

Ukázka Platforma Description
Active-Directory-dotnetcore-démon-v2 Konzola .NET Core 2,1 jednoduchá aplikace .net Core, která zobrazuje uživatele tenanta, který dotazuje Microsoft Graph pomocí identity aplikace, a ne jménem uživatele. Ukázka také znázorňuje variaci pomocí certifikátů pro ověřování.
Active-Directory-dotnet-démon-v2 ASP.NET MVC webová aplikace, která synchronizuje data z Microsoft Graph pomocí identity aplikace, nikoli jménem uživatele.