Microsoft Identity Platformy a tok přihlašovacích údajů klienta OAuth 2.0
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. Udělení zadané v DOKUMENTU RFC 6749, někdy označované jako OAuth s dvěma leggy, se dá použít k přístupu k prostředkům hostovaným na webu pomocí identity aplikace. Tento typ se běžně používá pro interakce mezi servery, které musí běžet na pozadí, bez okamžité interakce s uživatelem a často se označuje jako démony nebo účty služeb.
V toku přihlašovacích údajů klienta jsou oprávnění udělena přímo samotné aplikaci správcem. Když aplikace zobrazí token prostředku, prostředek vynucuje, aby aplikace sama má autorizaci k provedení akce, protože k ověřování není zapojen žádný uživatel. Tento článek popisuje oba kroky potřebné k:
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 získávání tokenů a volání zabezpečených webových rozhraní API raději používat podporované knihovny MSAL (Microsoft Authentication Libraries). Můžete se také podívat na ukázkové aplikace, které používají KNIHOVNU MSAL. Jako poznámka na straně se k získání přístupového tokenu nikdy neudělí tokeny aktualizace s tímto tokem jako client_id a client_secret (které by bylo nutné k získání obnovovacího tokenu).
Pro vyšší úroveň zajištění umožňuje platforma Microsoft Identity Platform také volající službě ověřovat pomocí certifikátu nebo federovaných přihlašovacích údajů místo sdíleného tajného kódu. 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, vložte je na webové stránky nebo je používejte v široce distribuované nativní aplikaci.
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.
Získání přímé autorizace
Aplikace obvykle přijímá přímou autorizaci pro přístup k prostředku jedním ze dvou způsobů:
- Prostřednictvím seznamu řízení přístupu (ACL) v prostředku
- Prostřednictvím přiřazení oprávnění aplikace v Microsoft Entra ID
Tyto dvě metody jsou nejběžnější v Microsoft Entra ID 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ů může zvolit metodu, která má pro svou aplikaci největší smysl.
Seznamy řízení přístupu
Poskytovatel prostředků může vynutit kontrolu autorizace na základě seznamu ID aplikací (klientů), která zná a uděluje konkrétní úroveň přístupu. Když prostředek obdrží token z platformy Microsoft Identity Platform, může dekódovat token a extrahovat ID aplikace klienta z appid identity a iss deklarací identity. Potom porovná aplikaci se seznamem řízení přístupu (ACL), který udržuje. Členitost a metoda seznamu ACL se může podstatně lišit mezi prostředky.
Běžným případem použití je použití seznamu ACL ke spouštění testů pro webovou aplikaci nebo webového rozhraní API. Webové rozhraní API může konkrétnímu klientovi udělit pouze podmnožinu úplných oprávnění. Pokud chcete spouštět kompletní testy rozhraní API, můžete vytvořit testovacího klienta, který získá tokeny z platformy 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 úplný přístup k celé funkci rozhraní API. Pokud používáte tento typ seznamu ACL, nezapomeňte ověřit nejen hodnotu volajícího appid , ale také ověřit, že iss hodnota tokenu je důvěryhodná.
Tento typ autorizace je běžný pro démony a účty služeb, které potřebují přistupovat k datům vlastněným uživatelskými 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é povolit tento autorizační model založený na seznamu ACL, microsoft Entra ID nevyžaduje, aby aplikace byly autorizované k získání tokenů pro jinou aplikaci. Tokeny jen pro aplikace je tedy možné vystavit 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ání přístupových tokenů jen pro aplikaci bez role, 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, kteří nemají přiřazené role, nebudou moct získat token pro tuto aplikaci.
Oprávnění aplikace
Místo použití seznamů ACL můžete pomocí rozhraní API vystavit sadu oprávnění aplikace. Aplikaci uděluje 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. Microsoft Graph například zveřejňuje několik oprávnění aplikace, aby mohla provádět následující akce:
- Č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
- Odeslání pošty jako libovolného uživatele
- Čtení dat adresáře
Pokud chcete používat role aplikací (oprávnění aplikace) s vlastním rozhraním API (na rozdíl od Microsoft Graphu), musíte nejprve zpřístupnit role aplikací v registraci aplikace rozhraní API v Centru pro správu Microsoft Entra. Potom nakonfigurujte požadované role aplikace tak, že v registraci aplikace klienta vyberete tato oprávnění. Pokud jste v registraci aplikace rozhraní API nezpřístupnili žádné role aplikací, nebudete moct v Centru pro správu Microsoft Entra 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žívat delegovaná oprávnění , protože aplikace nemůže jednat jménem uživatele. Musíte použít oprávnění aplikace, označovaná také jako role aplikací, které uděluje správce nebo vlastník rozhraní API.
Další informace o oprávněních aplikace naleznete v tématu Oprávnění a souhlas.
Doporučeno: Pokud chcete mít přiřazené role aplikací, přihlaste se správce do aplikace.
Při vytváření aplikace, 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í toku přihlašování aplikace, části nastavení aplikace nebo vyhrazeného toku připojení . Aplikace často dává smysl zobrazit toto zobrazení připojení až po přihlášení uživatele pomocí pracovního nebo školního účtu Microsoft.
Pokud uživatele přihlásíte do aplikace, můžete určit organizaci, do které uživatel patří, a teprve potom požádat uživatele, aby schválil 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 chcete uživatele přihlásit, postupujte podle kurzů protokolu Microsoft Identity Platform.
Žádost o oprávnění od správce adresáře
Až budete připravení požádat o oprávnění od správce organizace, 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=00001111-aaaa-2222-bbbb-3333cccc4444
&state=12345
&redirect_uri=http://localhost/myapp/permissions
Tip pro: Zkuste vložit následující požadavek v prohlížeči.
https://login.microsoftonline.com/common/adminconsent?client_id=00001111-aaaa-2222-bbbb-3333cccc4444&state=12345&redirect_uri=http://localhost/myapp/permissions
| Parametr | Podmínka | Popis |
|---|---|---|
tenant |
Povinní účastníci | 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, ke kterému tenantovi patří uživatel, a chcete, aby se přihlásil pomocí libovolného tenanta, použijte common. |
client_id |
Požaduje se | ID aplikace (klienta), které centrum pro správu Microsoft Entra – Registrace aplikací prostředí přiřazené k vaší aplikaci. |
redirect_uri |
Požaduje se | Identifikátor URI přesměrování, do kterého chcete odeslat odpověď, aby vaše aplikace zpracovávala. Musí přesně odpovídat jednomu z identifikátorů URI přesměrování, které jste zaregistrovali na portálu, s tím rozdílem, že musí být kódovaný adresou URL a může obsahovat další segmenty cest. |
state |
Doporučené | Hodnota, která je zahrnutá v požadavku, který se vrátí také v odpovědi tokenu. Může to být řetězec libovolného obsahu. 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 stránka nebo zobrazení, na které byli. |
V tuto chvíli Microsoft Entra ID vynucuje, aby se k dokončení požadavku mohl přihlásit jenom správce tenanta. Správce se zobrazí výzva ke schválení všech oprávnění přímé aplikace, která jste požádali o aplikaci na portálu pro registraci aplikací.
Úspěšná odpověď
Pokud správce schválí oprávnění pro vaši aplikaci, úspěšná odpověď vypadá takto:
GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
| Parametr | Popis |
|---|---|
tenant |
Tenant adresáře, který vaší aplikaci udělil oprávnění, která požadoval, ve formátu GUID. |
state |
Hodnota zahrnutá v požadavku, která se také vrátí v odpovědi tokenu. Může to být řetězec libovolného obsahu. 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 stránka nebo zobrazení, na které byli. |
admin_consent |
Nastavte na hodnotu True. |
Chybná odpověď
Pokud správce oprávnění pro vaši aplikaci neschválí, 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. |
Po přijetí úspěšné odpovědi z koncového bodu zřizování aplikace získala vaše aplikace oprávnění přímé 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 aplikaci pokračujte získáním přístupových tokenů pro rozhraní API. Pokud chcete token získat pomocí udělení přihlašovacích údajů klienta, odešlete požadavek POST na platformu /token Microsoft Identity Platform. Existuje několik různých případů:
- Žádost o přístupový token se sdíleným tajným kódem
- Žádost o přístupový token s certifikátem
- Žádost o přístupový token s federovanými přihlašovacími údaji
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:443
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials
# Replace {tenant} with your tenant!
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'client_id=00001111-aaaa-2222-bbbb-3333cccc4444&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=A1bC2dE3f...&grant_type=client_credentials' 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token'
| Parametr | Podmínka | Popis |
|---|---|---|
tenant |
Povinní účastníci | Tenant adresáře, na kterém má aplikace v plánu pracovat, ve formátu GUID nebo názvu domény. |
client_id |
Požaduje se | ID aplikace, které je přiřazené k vaší aplikaci. Tyto informace najdete na portálu, kde jste aplikaci zaregistrovali. |
scope |
Požaduje se | Hodnota předaná parametru scope v tomto požadavku by měla být identifikátorem prostředku (identifikátor URI ID aplikace) požadovaného prostředku, který je opatřen příponou .default . Všechny zahrnuté obory musí být pro jeden prostředek. Zahrnutí rozsahů pro více prostředků způsobí chybu. V příkladu Microsoft Graphu je https://graph.microsoft.com/.defaulthodnota . Tato hodnota říká platformě Microsoft Identity Platform, že ze všech přímých oprávnění aplikace, která jste pro aplikaci nakonfigurovali, by měl koncový bod vydat token pro ty, které jsou přidružené k prostředku, který chcete použít. Další informace o oboru najdete v dokumentaci k /.default vyjádření souhlasu. |
client_secret |
Požaduje se | 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 kódován adresou URL. Model základního ověřování, který místo toho poskytuje přihlašovací údaje v autorizační hlavičce, se podporuje také podle dokumentu RFC 6749 . |
grant_type |
Požaduje se | Musí být nastavena 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:443
Content-Type: application/x-www-form-urlencoded
scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&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í účastníci | Tenant adresáře, na kterém má aplikace v plánu pracovat, ve formátu GUID nebo názvu domény. |
client_id |
Požaduje se | ID aplikace (klienta), které je přiřazené k vaší aplikaci. |
scope |
Požaduje se | Hodnota předaná parametru scope v tomto požadavku by měla být identifikátorem prostředku (identifikátor URI ID aplikace) požadovaného prostředku, který je opatřen příponou .default . Všechny zahrnuté obory musí být pro jeden prostředek. Zahrnutí rozsahů pro více prostředků způsobí chybu. V příkladu Microsoft Graphu je https://graph.microsoft.com/.defaulthodnota . Tato hodnota říká platformě Microsoft Identity Platform, že ze všech přímých oprávnění aplikace, která jste pro aplikaci nakonfigurovali, by měl koncový bod vydat token pro ty, které jsou přidružené k prostředku, který chcete použít. Další informace o oboru najdete v dokumentaci k /.default vyjádření souhlasu. |
client_assertion_type |
Požaduje se | Hodnota musí být nastavena na urn:ietf:params:oauth:client-assertion-type:jwt-bearerhodnotu . |
client_assertion |
Požaduje se | Kontrolní výraz (webový token JSON), který potřebujete vytvořit a podepsat pomocí 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 údaji certifikátu a zjistěte, jak zaregistrovat certifikát a formát kontrolního výrazu. |
grant_type |
Požaduje se | Musí být nastavena na client_credentialshodnotu . |
Parametry požadavku založeného na certifikátu se liší pouze jedním způsobem od požadavku založeného na sdíleném tajném kódu: client_secret parametr se nahradí client_assertion_type parametry a client_assertion parametry.
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:443
Content-Type: application/x-www-form-urlencoded
scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555&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í účastníci | Kontrolní výraz (JWT nebo webový token JSON), který vaše aplikace získá od jiného zprostředkovatele identity mimo platformu 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é z jiných zprostředkovatelů identity. |
Vše v požadavku je stejné jako tok založený na certifikátech, s zásadní výjimkou zdroje 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. To se označuje jako federace identit úloh, kde se identita vašich aplikací v jiné platformě identity používá k získání tokenů v rámci platformy 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 platformou Microsoft Identity Platform. Informace o požadovaném formátu JWT vytvořených jinými zprostředkovateli identity najdete v tématu 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í zabezpečeného prostředku, jako je například webové rozhraní API. |
token_type |
Označuje hodnotu typu tokenu. Jediným typem, který platforma Microsoft Identity Platform podporuje, je bearer. |
expires_in |
Doba platnosti přístupového tokenu (v sekundách). |
Upozorňující
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 služby Microsoft můžou používat speciální formát, který se neověří jako JWT a může být také zašifrovaný pro uživatele s uživatelským účtem (účtem Microsoft). Přestože je čtení tokenů užitečným nástrojem pro ladění a učení, nepřebídejte závislosti na tomto kódu ani nepředpokládejte konkrétní údaje o tokenech, které nejsou určené pro rozhraní API, které řídíte.
Chybná 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "YYYY-MM-DD HH:MM:SSZ",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| 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 stS, které můžou pomoct s diagnostikou. |
timestamp |
Čas, kdy k chybě došlo. |
trace_id |
Jedinečný identifikátor požadavku, který vám pomůže 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, použijte token k provedení požadavků na prostředek. Po vypršení platnosti tokenu opakujte požadavek na /token koncový bod a získejte nový přístupový token.
GET /v1.0/users HTTP/1.1
Host: graph.microsoft.com:443
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...
Zkuste v terminálu použít následující příkaz, abyste token nahradili vlastními.
curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG..." 'https://graph.microsoft.com/v1.0/users'
Ukázky kódu a další dokumentace
Přečtěte si dokumentaci k přehledu přihlašovacích údajů klienta z knihovny Microsoft Authentication Library.
| Vzorek | Platforma | Popis |
|---|---|---|
| active-directory-dotnetcore-daemon-v2 | .NET 6.0+ | Aplikace ASP.NET Core, která zobrazuje uživatele tenanta dotazující se na Microsoft Graph pomocí identity aplikace, nikoli jménem uživatele. Ukázka také ilustruje variantu pomocí certifikátů pro ověřování. |
| active-directory-dotnet-daemon-v2 | ASP.NET MVC | Webová aplikace, která synchronizuje data z Microsoft Graphu pomocí identity aplikace místo jménem uživatele. |
| ms-identity-javascript-nodejs-console | konzola Node.js | Aplikace Node.js, která zobrazuje uživatele tenanta dotazováním Microsoft Graphu pomocí identity aplikace |