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:

• Autorizace aplikace pro volání rozhraní API
• Jak získat tokeny potřebné k volání rozhraní API.

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

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

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

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'

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

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

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

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

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.