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

K přístupu 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 označované jako 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 démony nebo účty služeb.

Tento článek popisuje, jak vaši aplikaci programovat přímo s použitím protokolu. Pokud je to možné, doporučujeme místo toho použít podporované knihovny Microsoft Authentication Library (MSAL) k získání tokenů a volání zabezpečených webových rozhraní API. Podívejte se také na ukázkové aplikace, které používají MSAL. Poznámka na okraj: Obnovovací tokeny se s tímto tokem nikdy neudělí, protože client_id k získání přístupového tokenu je možné místo toho použít a client_secret (což by bylo potřeba k získání obnovovacího tokenu).

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

V toku přihlašovacích údajů klienta uděluje oprávnění přímo k samotné aplikaci správce. Když aplikace předloží token prostředku, prostředek vynutí, aby sama aplikace získala oprávnění k provedení akce, protože ověřování neobsahuje žádného uživatele. Tento článek popisuje kroky potřebné k autorizaci aplikace pro volání rozhraní API a také to, jak získat tokeny potřebné k volání tohoto rozhraní API.

Tip

Zkuste spustit tento požadavek v Nástroji Postman.
Zkuste spustit tento a další požadavky v Nástroji Postman – 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 si popíšeme 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 nejběžnější v Azure AD a doporučujeme je 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ů si může zvolit metodu, která je pro jeho aplikaci nejvhodnější.

Seznamy řízení přístupu

Poskytovatel prostředků může vynutit kontrolu autorizace na základě seznamu ID aplikací (klientů), které zná a ke kterým udělí určitou úroveň přístupu. Když prostředek obdrží token z Microsoft identity platform, může ho dekódovat a extrahovat ID aplikace klienta z deklarací appid identity a iss . Potom porovná aplikaci se seznamem řízení přístupu (ACL), který udržuje. Členitost seznamu ACL a jeho metoda se můžou v jednotlivých prostředcích 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 webové rozhraní API. Webové rozhraní API může konkrétnímu klientovi udělit jenom podmnožinu úplných oprávnění. Pokud chcete v rozhraní API spouštět kompletní testy, vytvořte testovacího klienta, který získá tokeny z Microsoft identity platform a pak je odešle do rozhraní API. Rozhraní API pak v seznamu ACL zkontroluje ID aplikace testovacího klienta pro ú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 appid , ale také ověřit, jestli iss je hodnota tokenu důvěryhodná.

Tento typ autorizace je běžný pro démony a účty služeb, které potřebují přístup k datům vlastněným uživateli uživatelů s osobními Microsoft účty. U dat vlastněných 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é povolit tento model autorizace založený na seznamu ACL, Azure AD nevyžaduje, aby aplikace byly autorizované k získání tokenů pro jinou aplikaci. Tokeny jen pro aplikace je tedy možné vydávat bez roles deklarace identity. Aplikace, které zpřístupňují rozhraní API, musí implementovat kontroly oprávnění, aby mohly přijímat tokeny.

Pokud chcete aplikacím zabránit v získávání přístupových tokenů bez rolí pro vaši aplikaci, ujistěte se, že jsou pro vaši aplikaci povolené požadavky na přiřazení. 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í seznamů ACL můžete pomocí rozhraní API zveřejnit sadu oprávnění aplikace. Oprávnění aplikace uděluje aplikaci správce organizace a dá se použít jenom pro přístup k datům vlastněným danou organizací a jejími zaměstnanci. Například Microsoft Graph zpřístupňuje několik oprávnění aplikace k provedení následujících akcí:

  • Čtení pošty ve všech poštovních schránkách
  • Čtení a zápis pošty ve všech poštovních schránkách
  • Odeslat e-mail jako libovolný uživatel
  • Čtení dat z adresáře

Pokud chcete používat role aplikace (oprávnění aplikace) s vlastním rozhraním API (na rozdíl od Microsoft Graphu), musíte role aplikace nejprve zveřejnit v registraci aplikace rozhraní API v Azure Portal. Potom nakonfigurujte požadované role aplikace tak, že tato oprávnění vyberete v registraci aplikace klienta. Pokud jste v registraci aplikace rozhraní API nezpřístupnili žádné role aplikace, nebudete moct v registraci aplikace klientské aplikace v Azure Portal zadat oprávnění aplikace pro toto rozhraní API.

Při ověřování jako aplikace (na rozdíl od uživatele) nemůžete použít delegovaná oprávnění , protože neexistuje žádný uživatel, který by mohl vaše aplikace jednat jménem uživatele. Musíte použít oprávnění aplikace, označovaná také jako role aplikace, která jsou udělena správcem nebo vlastníkem rozhraní API.

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

Když vytváříte aplikaci, která používá oprávnění aplikace, obvykle aplikace 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í toku přihlašování aplikace, součástí nastavení aplikace nebo může být vyhrazený tok připojení. V mnoha případech má smysl, aby aplikace toto zobrazení "připojit" zobrazovala až poté, co se uživatel přihlásí pomocí pracovního nebo školního Microsoft účtu.

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

Žádost o 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.

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

Tip pro: Zkuste v prohlížeči vložit následující požadavek.

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, od kterého chcete požádat o oprávnění. Může to být ve formátu GUID nebo popisného názvu. Pokud nevíte, do kterého tenanta uživatel patří, a chcete mu umožnit přihlášení 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é vaší aplikaci.
redirect_uri Vyžadováno Identifikátor URI přesměrování, ve kterém chcete, aby vaše aplikace zpracovávala odpověď. Musí přesně odpovídat některému 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 obsahovat další segmenty cest.
state Doporučeno Hodnota, která je zahrnutá v požadavku, která je také vrácena v odpovědi na token. 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 provedením žádosti o ověření, jako je stránka nebo zobrazení, na které se uživatel nacházel.

V tomto okamžiku Azure AD vynucuje, aby se k dokončení žádosti mohl přihlásit jenom správce tenanta. Správce bude požádán, aby na portálu pro registraci aplikací schválil všechna přímá oprávnění aplikace, která jste pro aplikaci požadovali.

Úspěšná odpověď

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

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 zahrnuta v 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 provedením žádosti o ověření, jako je stránka nebo zobrazení, na které se uživatel nacházel.
admin_consent Nastavte na Hodnotu True.
Odpověď na chybu

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

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 pomoct identifikovat původní příčinu chyby.

Jakmile obdržíte úspěšnou odpověď z koncového bodu zřizování aplikace, vaše aplikace získala přímá oprávnění aplikace, která požadovala. Teď můžete požádat o token pro požadovaný prostředek.

Získání tokenu

Po získání potřebné autorizace pro vaši aplikaci pokračujte získáním 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 Microsoft identity platform /token :

První případ: Žádost o přístupový token se sdíleným tajným kódem

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, pro který aplikace plánuje pracovat, ve formátu GUID nebo názvu domény.
client_id Vyžadováno ID aplikace, které je přiřazené vaší aplikaci. Tyto informace najdete na portálu, na kterém jste aplikaci zaregistrovali.
scope Vyžadováno Hodnota předaná parametru scope v tomto požadavku by měla být identifikátorem prostředku (IDENTIFIKÁTOR URI aplikace) požadovaného prostředku s příponou .default . V příkladu Microsoft Graph je https://graph.microsoft.com/.defaulthodnota .
Tato hodnota sděluje Microsoft identity platform, že ze všech přímých oprávnění aplikace, která jste pro aplikaci nakonfigurovali, by koncový bod měl vystavit token pro ta, která jsou přidružená k prostředku, který chcete použít. Další informace o rozsahu /.default najdete v dokumentaci k vyjádření souhlasu.
client_secret Vyžadováno Tajný klíč klienta, který jste vygenerovali pro aplikaci na portálu pro registraci aplikací. Tajný klíč klienta musí být před odesláním zakódovaný do adresy URL. Podporuje se také základní způsob ověřování, který místo zadávání přihlašovacích údajů v autorizační hlavičce podle RFC 6749 .
grant_type Vyžadováno Musí být nastavená na client_credentialshodnotu .

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, pro který aplikace plánuje pracovat, ve formátu GUID nebo názvu domény.
client_id Vyžadováno ID aplikace (klienta), které je přiřazené vaší aplikaci.
scope Vyžadováno Hodnota předaná parametru scope v tomto požadavku by měla být identifikátorem prostředku (IDENTIFIKÁTOR URI aplikace) požadovaného prostředku s příponou .default . V příkladu Microsoft Graph je https://graph.microsoft.com/.defaulthodnota .
Tato hodnota informuje Microsoft identity platform, že ze všech přímých oprávnění aplikace, která jste pro aplikaci nakonfigurovali, by měla vydat token pro ta, která jsou přidružená k prostředku, který chcete použít. Další informace o rozsahu /.default najdete v dokumentaci k vyjádření souhlasu.
client_assertion_type Vyžadováno Hodnota musí být nastavená na urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion Vyžadováno Kontrolní výraz (webový token JSON), který potřebujete vytvořit a podepsat certifikátem, který jste zaregistrovali jako přihlašovací údaje pro vaši aplikaci. Přečtěte si informace o přihlašovacích údaji certifikátu a zjistěte, jak zaregistrovat certifikát a jaký je formát kontrolního výrazu.
grant_type Vyžadováno Musí být nastavená na client_credentialshodnotu .

Parametry požadavku založeného na certifikátu se od požadavku založeného na sdíleném tajném kódu liší pouze jedním způsobem: client_secret parametr je nahrazen client_assertion_type parametry a client_assertion .

Třetí případ: Žádost o přístupový token s federovanými přihlašovacími údaji

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
client_assertion Povinné Kontrolní výraz (JWT nebo webový token JSON), který vaše aplikace získá od jiného zprostředkovatele identity mimo Microsoft identity platform, jako je Kubernetes. Specifika tohoto JWT musí být ve vaší aplikaci zaregistrovaná jako přihlašovací údaje federované identity. Přečtěte si o federaci identit úloh a zjistěte, jak nastavit a používat kontrolní výrazy vygenerované od jiných zprostředkovatelů identity.

Vše v požadavku je stejné jako výše uvedený tok založený na certifikátech, s jednou zásadní výjimkou – zdrojem client_assertion. V tomto toku vaše aplikace nevytvoří samotný kontrolní výraz JWT. Místo toho vaše aplikace používá JWT vytvořený jiným zprostředkovatelem identity. Tomu se říká federace identit úloh, kde se identita aplikací na jiné platformě identit používá k získání tokenů v rámci Microsoft identity platform. To je nejvhodnější pro scénáře napříč cloudy, jako je hostování výpočetních prostředků mimo Azure, ale přístup k rozhraním API chráněným Microsoft identity platform. Informace o požadovaném formátu uzlů JWT vytvořených jinými zprostředkovateli identity najdete v článku o formátu kontrolního výrazu.

Úspěšná odpověď

Úspěšná odpověď z jakékoli metody 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í vůči zabezpečenému prostředku, například k webovému rozhraní API.
token_type Označuje hodnotu typu tokenu. Jediný typ, který Microsoft identity platform podporuje, je bearer.
expires_in Doba platnosti přístupového tokenu (v sekundách)

Upozornění

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

Chybová odpověď

Odpověď na chybu (400 Chybný požadavek) 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 pomoct identifikovat původní příčinu chyby ověřování.
error_codes Seznam kódů chyb specifických pro službu STS, které můžou pomoct s diagnostikou.
timestamp Čas, kdy došlo k chybě.
trace_id Jedinečný identifikátor požadavku, který pomáhá s diagnostikou.
correlation_id Jedinečný identifikátor požadavku, který pomáhá s diagnostikou napříč komponentami.

Použití tokenu

Teď, když jste získali token, ho použijte k vytváření požadavků na prostředek. Po vypršení platnosti tokenu opakujte žádost koncovému /token bodu o 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 s přehledem přihlašovacích údajů klienta z knihovny Microsoft Authentication Library.

Ukázka Platforma Description
active-directory-dotnetcore-daemon-v2 Konzola .NET Core 2.1 Jednoduchá aplikace .NET Core, která zobrazuje uživatele tenanta dotazující se na Microsoft Graph pomocí identity aplikace místo jménem uživatele. Ukázka také ilustruje variantu použití certifikátů k ověřování.
active-directory-dotnet-daemon-v2 ASP.NET MVC Webová aplikace, která synchronizuje data z Microsoft Graph pomocí identity aplikace místo jménem uživatele.
ms-identity-javascript-nodejs-console konzola Node.js Jednoduchá aplikace Node.js, která zobrazuje uživatele tenanta dotazováním Microsoft Graphu pomocí identity aplikace