Sdílet prostřednictvím

Microsoft Identity Platform 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. Grant specifikovaný v RFC 6749, někdy označovaný jako dvounohý OAuth, lze použít pro přístup 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žby .

V toku přihlašovacích údajů klienta jsou oprávnění udělena přímo samotné aplikaci správcem. Když aplikace předloží token prostředku, prostředek vynutí, aby aplikace měla sama autorizaci k provedení akce, protože do ověřování není zapojen žádný uživatel. Tento článek popisuje oba kroky potřebné k:

Tento článek popisuje, jak programovat přímo proti protokolu ve vaší aplikaci. Pokud je to možné, doporučujeme místo toho použít podporované knihovny MSAL (Microsoft Authentication Library) k získání tokenů a volání zabezpečených webových rozhraní API. Můžete se také podívat na ukázkové aplikace , které používají MSAL. Upozorňujeme, že obnovovací tokeny nebudou nikdy v rámci tohoto postupu uděleny, protože client_id a client_secret (které by byly nutné k získání obnovovacího tokenu) mohou být použity k získání přístupové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 nepublikuj tento přihlašovací údaj ve zdrojovém kódu, nevlož jej na webové stránky nebo nepoužívej 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.

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

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ů:

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. Zdroj 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, může token dekódovat a extrahovat ID aplikace klienta z tvrzení appid a iss. Potom porovná aplikaci se seznamem řízení přístupu (ACL), který udržuje. Členitost a metoda ACL se může podstatně lišit mezi zdroji.

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 ACL pro ID aplikace testovacího klienta, aby zajistilo plný přístup k veškeré funkčnosti rozhraní API. Pokud používáte tento typ ACL, nezapomeňte ověřit nejen hodnotu volajícího appid, ale také, že je důvěryhodná hodnota iss tokenu.

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 nároku roles

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 deklarace identity roles. 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 ve získávání přístupových tokenů pouze pro aplikaci bez přiřazené role, ujistěte se, že jsou pro vaši aplikaci povoleny podmínky přiřazení. Tím nebude možné, aby uživatelé a aplikace, které nemají přiřazené role, získali 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 . Oprávnění jsou udělena aplikaci správcem organizace a lze je použít jen 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 z 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 pro API v Centru pro správu Microsoft Entra. Potom nakonfigurovat požadované role aplikace výběrem těchto oprávnění v registraci aplikace klienta. 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žít delegovaná oprávnění, protože není k dispozici žádný uživatel, kterého by aplikace mohla zastupovat. 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.

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í přihlašovacího procesu aplikace, části nastavení aplikace nebo určeného připojovacího procesu. Pro aplikaci č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 přihlásit uživatele, postupujte podle kurzů protokolu Microsoft Identity Platform.

Žádost o oprávnění od správce adresáře

Až budete připraveni 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é Tenant adresáře, od kterého chcete požádat o oprávnění. Může to být ve formátu GUID nebo přátelské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 Povinné ID aplikace (klienta), které vaše aplikace získala prostřednictvím prostředí centrum pro správu Microsoft Entra – Registrace aplikací.
redirect_uri Povinné Adresa URI pro přesměrování, kam chcete, aby byla odpověď odeslána a vaše aplikace ji mohla zpracovat. 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 zahrnuta v požadavku a je také vrácena 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ávci bude zaslána žádost o schválení všech oprávnění aplikace, která jste požadovali pro svou aplikaci v 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 True.
Chybová 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 provisioning aplikace získala vaše aplikace požadovaná přímá aplikační oprávnění. 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 /token platformě Microsoft Identity Platform. Existuje několik různých případů:

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é Tenant adresáře, na kterém má aplikace v plánu pracovat, ve formátu GUID nebo názvu domény.
client_id Povinné ID aplikace, které je přiřazené k vaší aplikaci. Tyto informace najdete na portálu, kde jste aplikaci zaregistrovali.
scope Povinné 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 s příponou .default. Všechny zahrnuté rozsahy musí být pro jeden zdroj. Zahrnutí rozsahů pro více prostředků způsobí chybu.
V příkladu Microsoft Graphu je hodnota https://graph.microsoft.com/.default. 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 rozsahu /.default najdete v dokumentaci k vyjádření souhlasu .
client_secret Povinné 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 Povinné Musí být nastavena na 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: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é Tenant adresáře, na kterém má aplikace v plánu pracovat, ve formátu GUID nebo názvu domény.
client_id Povinné ID aplikace (klienta), které je přiřazené k vaší aplikaci.
scope Povinné 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 s příponou .default. Všechny zahrnuté rozsahy musí být pro jeden zdroj. Zahrnutí rozsahů pro více prostředků způsobí chybu.
V příkladu Microsoft Graphu je hodnota https://graph.microsoft.com/.default. 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 rozsahu /.default najdete v dokumentaci k vyjádření souhlasu .
client_assertion_type Povinné Hodnota musí být nastavena na urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion Povinné 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 údajích certifikátu a zjistěte, jak zaregistrovat certifikát a formát prohlášení.
grant_type Povinné Musí být nastavena na client_credentials.

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: parametr client_secret se nahradí parametry client_assertion_type 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: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é Tvrzení (JWT, nebo JSON web token), které vaše aplikace získá od jiného poskytovatele identity mimo Microsoft Identity Platform, jako třeba Kubernetes. Specifika tohoto JWT musí být ve vaší aplikaci zaregistrována jako pověření federované identity. Přečtěte si o federaci identit pracovních úloh, abyste se naučili, jak nastavit a používat aserce 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 procesu vaše aplikace nevytvoří samotné JWT tvrzení. Místo toho vaše aplikace používá JWT vytvořené jiným zprostředkovatelem identity. Říká se tomu 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. Pro informace o požadovaném formátu JWT, které byly vytvořeny jinými poskytovateli identity, si přečtěte o formátu tvrzení.

Ú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ý typ, který platforma Microsoft Identity Platform podporuje, je bearer.
expires_in Doba platnosti přístupového tokenu (v sekundách).

Výstraha

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 Microsoftu můžou používat speciální formát, který se neověří jako JWT a může být také zašifrován pro uživatele s uživatelským účtem (účet 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.

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: 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 koncový bod /token 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.

Ukázka 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 Node.js konzola Aplikace Node.js, která zobrazuje uživatele tenanta dotazováním Microsoft Graphu pomocí identity aplikace