Sdílet prostřednictvím

Obory a oprávnění na platformě Microsoft Identity Platform

  • Článek

Platforma Microsoft Identity Platform implementuje autorizační protokol OAuth 2.0 . OAuth 2.0 je metoda, prostřednictvím které může aplikace třetí strany přistupovat k prostředkům hostovaným na webu jménem uživatele. Každý webový hostovaný prostředek, který se integruje s platformou Microsoft Identity Platform, má identifikátor prostředku nebo identifikátor URI ID aplikace.

V tomto článku se dozvíte o oborech a oprávněních na platformě Identity Platform.

Následující seznam ukazuje některé příklady prostředků hostovaných na webu Microsoftu:

  • Microsoft Graph: https://graph.microsoft.com
  • Rozhraní API pošty Microsoftu 365: https://outlook.office.com
  • Azure Key Vault: https://vault.azure.net

Totéž platí pro všechny prostředky třetích stran, které se integrují s platformou Microsoft Identity Platform. Kterýkoli z těchto prostředků může také definovat sadu oprávnění, která rozdělují funkce tohoto prostředku na menší bloky dat. Například Microsoft Graph definuje oprávnění k provedení následujících úkolů, mimo jiné:

  • Čtení kalendáře uživatele
  • Zápis do kalendáře uživatele
  • Odeslání pošty jako uživatele

Vzhledem k těmto typům definic oprávnění má prostředek jemně odstupňovanou kontrolu nad svými daty a tím, jak se funkce rozhraní API zveřejňují. Aplikace třetí strany může požádat o tato oprávnění od uživatelů a správců, kteří musí žádost schválit, aby aplikace mohl získat přístup k datům nebo jednat jménem uživatele.

Když se funkce prostředku rozdělí do malých sad oprávnění, dají se aplikace třetích stran vytvořit tak, aby požadovaly jenom oprávnění, která potřebují k provedení své funkce. Uživatelé a správci můžou vědět, k jakým datům má aplikace přístup. A můžou mít větší jistotu, že se aplikace nechová se zlými úmysly. Vývojáři by se měli vždy řídit principem nejnižších oprávnění a požádat pouze o oprávnění, která potřebují pro fungování svých aplikací.

V OAuth 2.0 se těmto typům sad oprávnění říká obory. Často se také označují jako oprávnění. Na platformě Microsoft Identity Platform je oprávnění reprezentováno jako řetězcová hodnota. Aplikace požádá o potřebná oprávnění zadáním oprávnění v parametru scope dotazu. Platforma Identity Platform podporuje několik dobře definovaných oborů OpenID Connect a oprávnění založená na prostředcích (každé oprávnění je indikováno připojením hodnoty oprávnění k identifikátoru prostředku nebo identifikátoru URI ID aplikace). Řetězec https://graph.microsoft.com/Calendars.Read oprávnění se například používá k vyžádání oprávnění ke čtení kalendářů uživatelů v Microsoft Graphu.

V požadavcích na autorizační server pro platformu Microsoft Identity Platform, pokud je identifikátor prostředku vynechán v parametru oboru, předpokládá se, že zdrojem je Microsoft Graph. Například scope=User.Read je ekvivalentní s https://graph.microsoft.com/User.Read.

Oprávnění omezená správcem

Oprávnění na platformě Microsoft Identity Platform je možné nastavit na omezení správce. Například mnoho oprávnění Microsoft Graphu s vyššími oprávněními vyžaduje schválení správcem. Pokud vaše aplikace vyžaduje oprávnění omezená správcem, musí správce organizace udělit souhlas s těmito obory jménem uživatelů organizace. Následující část obsahuje příklady těchto typů oprávnění:

  • User.Read.All: Čtení úplných profilů všech uživatelů
  • Directory.ReadWrite.All: Zápis dat do adresáře organizace
  • Groups.Read.All: Přečíst všechny skupiny v adresáři organizace

Poznámka:

V žádostech o autorizaci, token nebo koncové body souhlasu pro platformu Microsoft identity platform platí, že pokud je identifikátor prostředku vynechán v parametru oboru, předpokládá se, že prostředkem je Microsoft Graph. Například scope=User.Read je ekvivalentní s https://graph.microsoft.com/User.Read.

I když uživatel příjemce může aplikaci udělit přístup k tomuto druhu dat, uživatelé organizace nemůžou udělit přístup ke stejné sadě citlivých firemních dat. Pokud vaše aplikace požádá o přístup k některému z těchto oprávnění od uživatele organizace, uživateli se zobrazí chybová zpráva s informací, že nemá oprávnění k vyjádření souhlasu s oprávněními vaší aplikace.

Pokud aplikace požádá o oprávnění aplikace a správce udělí tato oprávnění, nebude toto udělení provedeno jménem žádného konkrétního uživatele. Místo toho má klientská aplikace udělená oprávnění přímo. Tyto typy oprávnění by měly používat jenom služby démona a jiné neinteraktivní aplikace, které běží na pozadí. Další informace o scénáři přímého přístupu najdete v tématu Scénáře přístupu na platformě Microsoft Identity Platform.

Podrobný průvodce zveřejněním oborů ve webovém rozhraní API najdete v tématu Konfigurace aplikace pro zveřejnění webového rozhraní API.

Rozsahy OpenID Connect

Implementace platformy Microsoft Identity Platform openID Connect má několik dobře definovaných oborů, které jsou také hostované v Microsoft Graphu: openid, email, profilea offline_access. Rozsahy address a phone OpenID Connect nejsou podporovány. Tyto obory jsou někdy volitelné a považují se za obohacení tokenu ID. Tyto obory se nebudou vždy zobrazovat v samostatných řádcích v výzvě k vyjádření souhlasu uživateli.

Pokud požadujete scopy OpenID Connect a nějaký token, obdržíte token pro volání koncového bodu UserInfo.

Obor openid

Pokud se aplikace přihlásí pomocí OpenID Connect, musí požádat o openid obor. Obor openid se zobrazí na stránce souhlasu pracovního účtu jako oprávnění Přihlásit se.

Aplikace používá toto oprávnění k získání jedinečného identifikátoru uživatele ve formě deklarace identity sub. Oprávnění také aplikaci poskytuje přístup ke koncovému bodu UserInfo. Obor openid se dá použít na koncovém bodu tokenu Microsoft Identity Platform k získání tokenů ID. Aplikace může tyto tokeny použít k ověřování.

Obor email

Obor email lze použít s oborem openid a všemi dalšími obory. Aplikace umožňuje přístup k primární e-mailové adrese uživatele ve formě nároku email.

Deklarace email identity je součástí tokenu pouze v případě, že je e-mailová adresa přidružená k uživatelskému účtu, což není vždy případ. Pokud vaše aplikace používá obor email, musí být schopná zpracovat případ, kdy v tokenu neexistuje žádný nárok email.

Obor profile

Rozsah profile lze použít s rozsahem openid a jakýmkoli jiným rozsahem. Poskytuje aplikaci přístup k velkému množství informací o uživateli. Informace, ke kterým má přístup, zahrnují, ale nejsou omezeny pouze na křestní jméno uživatele, příjmení, preferované uživatelské jméno a ID objektu.

Úplný seznam profile nároků dostupných v parametru id_tokens pro konkrétního uživatele vizte referenci id_tokens.

Obor offline_access

offline_access Rozsah poskytuje vaší aplikaci přístup k prostředkům jménem uživatele po delší dobu. Na stránce souhlasu se tento rozsah zobrazuje jako oprávnění Udržovat přístup k datům, ke kterým jste mu udělili přístup.

Pokud je udělena některá z požadovaných delegovaných oprávnění z parametru scope (s výjimkou openid, profile, email), stačí, aby aplikace požádala o obnovovací token pomocí offline_access. Pokud je například udělena User.Read pro Microsoft, aplikace obdrží přístupový token. To znamená, že pokud by aplikace následně požádala o obnovovací token, skutečnost, že bylo uděleno User.Read, postačuje k poskytnutí obnovovacího tokenu. Obnovovací tokeny jsou určeny pro dlouhodobé použití. Vaše aplikace může získat nové přístupové tokeny, protože vyprší platnost starších přístupových tokenů.

Poznámka:

Toto oprávnění se aktuálně zobrazuje na všech stránkách souhlasu, i pro toky, které neposkytují obnovovací token (například implicitní tok). Toto nastavení řeší scénáře, kdy klient může začít v rámci implicitního toku, a pak přejde do toku kódu, kde se očekává obnovovací token.

Na platformě Microsoft Identity Platform (požadavky na koncový bod v2.0) musí vaše aplikace explicitně požádat o offline_access rozsah, aby přijímala obnovovací tokeny. Když tedy uplatníte autorizační kód v rámci toku autorizačního kódu OAuth 2.0 , obdržíte přístupový token z koncového bodu /token.

Přístupový token je platný přibližně jednu hodinu. V tomto okamžiku musí vaše aplikace přesměrovat uživatele zpět na /authorize koncový bod a požádat o nový autorizační kód. Během tohoto přesměrování a v závislosti na typu aplikace může uživatel muset znovu zadat své přihlašovací údaje nebo znovu udělit souhlas s oprávněními.

Platnost obnovovacího tokenu je delší než přístupový token a obvykle platí 90 dnů. Další informace o získání a používání obnovovacích tokenů najdete v referenčních informacích k protokolu Microsoft Identity Platform.

Zahrnutí obnovovacího tokenu do odpovědi může záviset na několika faktorech, včetně konkrétní konfigurace vaší aplikace a oborů požadovaných během procesu autorizace. Pokud očekáváte, že v odpovědi obdržíte obnovovací token, ale nepodaří se vám, zvažte následující faktory:

  • požadavky na rozsah: Ujistěte se, že požadujete oprávnění offline_access spolu s jakýmikoli dalšími nezbytnými oprávněními.
  • typ udělení autorizace: Obnovovací token se poskytuje při použití typu udělení autorizačního kódu. Pokud se váš tok liší, může to mít vliv na odpověď.
  • Konfigurace klienta: Zkontrolujte nastavení vaší aplikace na platformě Identity Platform. Některé konfigurace můžou omezit vystavování refresh_tokens.

Obor .default

Obor .default se používá k obecnému odkazování na službu prostředků (API) v požadavku bez identifikace konkrétních oprávnění. Pokud je potřeba souhlas, použití .default signalizuje, že by měl být vyžádán souhlas pro všechna požadovaná oprávnění uvedená v registraci aplikace (pro všechna rozhraní API v seznamu).

Hodnota parametru oboru je vytvořena pomocí identifikátoru URI prostředku a .default, oddělená lomítkem (/). Pokud je například identifikátor URI https://contoso.comprostředku , rozsah požadavku je https://contoso.com/.default. Vizte část o koncových lomítkách pro případy, kdy je nutné zadat druhé lomítko pro správné vyžádání tokenu.

Použití scope={resource-identifier}/.default je funkčně stejné jako resource={resource-identifier} v koncovém bodu verze 1.0 (kde {resource-identifier} je identifikátor URI pro rozhraní API, například https://graph.microsoft.com pro Microsoft Graph).

Obor .default je možné použít v jakémkoli toku OAuth 2.0 a k zahájení souhlasu administrátora. Jeho použití se vyžaduje v toku On-Behalf-Of a toku přihlašovacích údajů klienta.

Klienti nemůžou v jediné žádosti kombinovat statický.default souhlas () a dynamický souhlas. Takže scope=https://graph.microsoft.com/.default Mail.Read výsledkem je chyba, protože kombinuje různé typy rozsahů.

Parametr oboru .default aktivuje výzvu k vyjádření souhlasu pouze v případě, že nebyl udělen souhlas pro žádné delegované oprávnění mezi klientem a prostředkem jménem přihlášeného uživatele.

Pokud existuje souhlas, vrácený token obsahuje všechny obory udělené pro tento prostředek pro přihlášeného uživatele. Pokud však pro požadovaný prostředek nebyla udělena žádná oprávnění (nebo pokud je zadaný parametr prompt=consent), zobrazí se výzva k vyjádření souhlasu pro všechna požadovaná oprávnění nakonfigurovaná pro registraci klientské aplikace pro všechna rozhraní API v seznamu.

Pokud je například požadován obor https://graph.microsoft.com/.default , vaše aplikace požaduje přístupový token pro rozhraní Microsoft Graph API. Pokud byla pro Microsoft Graph udělena alespoň jedno delegované oprávnění jménem přihlášeného uživatele, přihlášení bude pokračovat. Všechna delegovaná oprávnění Microsoft Graphu udělená danému uživateli budou zahrnuta do přístupového tokenu. Pokud pro požadovaný prostředek (v tomto příkladu microsoft Graphu) nebyla udělena žádná oprávnění, zobrazí se výzva k vyjádření souhlasu pro všechna požadovaná oprávnění nakonfigurovaná v aplikaci pro všechna rozhraní API v seznamu.

Příklad 1: Uživatel nebo správce tenanta udělil oprávnění

V tomto příkladu uživatel nebo správce tenanta udělil klientovi oprávnění Mail.Read a User.Read Microsoft Graph.

Pokud klient požádá scope=https://graph.microsoft.com/.default, nezobrazí se žádná výzva k vyjádření souhlasu bez ohledu na obsah registrovaných oprávnění klientské aplikace pro Microsoft Graph. Vrácený token obsahuje obory Mail.Read a User.Read.

Příklad 2: Uživatel nemá udělená oprávnění mezi klientem a prostředkem

V tomto příkladu uživatel neudělil souhlas mezi klientem a Microsoft Graphem ani nemá správce. Klient je zaregistrovaný pro oprávnění User.Read a Contacts.Read a zaregistrovaný pro obor služby Azure Key Vault https://vault.azure.net/user_impersonation.

Když klient požádá o token scope=https://graph.microsoft.com/.default, zobrazí se uživateli stránka se souhlasem pro Microsoft Graph User.Read a Contacts.Read obory a obor služby Azure Key Vault user_impersonation . Vrácený token obsahuje pouze obory User.Read a Contacts.Read dá se použít pouze pro Microsoft Graph.

Příklad 3: Uživatel souhlasil a klient požaduje více oborů.

V tomto příkladu už uživatel souhlasil s Mail.Read pro klienta. Klient je zaregistrovaný Contacts.Read pro obor.

Klient nejprve provede přihlášení pomocí scope=https://graph.microsoft.com/.default. Na základě parametru scopes odpovědi aplikace zjistí, že byl udělen pouze Mail.Read. Klient pak zahájí druhé přihlášení pomocí scope=https://graph.microsoft.com/.default, a tentokrát vynutí souhlas pomocí prompt=consent. Pokud má uživatel povoleno souhlas se všemi oprávněními, která aplikace zaregistrovala, zobrazí se výzva k vyjádření souhlasu. (Pokud ne, zobrazí se jim chybová zpráva nebo žádost o souhlas správce formulář.) Ve výzvě k vyjádření souhlasu jsou Contacts.Read i Mail.Read. Pokud je udělen souhlas a přihlášení pokračuje, vrátí se token pro Microsoft Graph a obsahuje Mail.Read a Contacts.Read.

Použití oblasti .default s klientem

V některých případech si klient může vyžádat vlastní .default obor. Následující příklad ukazuje tento scénář.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
    ?response_type=token            //Code or a hybrid flow is also possible here
    &client_id=00001111-aaaa-2222-bbbb-3333cccc4444
    &scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
    &redirect_uri=https%3A%2F%2Flocalhost
    &state=1234

Tento příklad kódu vytvoří stránku souhlasu pro všechna registrovaná oprávnění, pokud předchozí popis souhlasu a .default použije se pro tento scénář. Pak kód vrátí id_tokenmísto přístupového tokenu .

Noví klienti, kteří cílí na platformu Microsoft Identity Platform, by neměli toto nastavení používat. Nezapomeňte přejít na knihovnu Microsoft Authentication Library (MSAL) z knihovny Azure AD Authentication Library (ADAL).

Proces udělení přihlašovacích údajů klienta a .default

Dalším použitím .default je vyžádání rolí aplikací (označovaných také jako oprávnění aplikace) v neinteraktivní aplikaci, jako je aplikace démona, která používá tok udělení přihlašovacích údajů klienta k volání webového rozhraní API.

Pokud chcete definovat role aplikací (oprávnění aplikace) pro webové rozhraní API, přečtěte si téma Přidání rolí aplikace do aplikace.

Požadavky na přihlašovací údaje klienta ve vaší klientské službě musí obsahovat scope={resource}/.default. Tady je webové rozhraní API, na které vaše aplikace hodlá volat a pro které chce získat přístupový token. Vydání žádosti o přihlašovací údaje klienta pomocí jednotlivých oprávnění aplikace (rolí) se nepodporuje . Všechny role aplikace (oprávnění aplikace), které byly uděleny pro toto webové rozhraní API, jsou zahrnuty do vráceného přístupového tokenu.

Pokud chcete udělit přístup k rolím aplikace, které definujete, včetně udělení souhlasu správce pro aplikaci, přečtěte si téma Konfigurace klientské aplikace pro přístup k webovému rozhraní API.

Koncové lomítko a .default

Některé identifikátory URI prostředků mají koncové lomítko, například https://contoso.com/, na rozdíl od https://contoso.com. Koncové lomítko může způsobit problémy s ověřením tokenu. K problémům dochází především v případě, že se vyžaduje token pro Azure Resource Manager (https://management.azure.com/).

V tomto případě koncové lomítko na konci identifikátoru URI prostředku znamená, že lomítko musí být přítomno při vyžádání tokenu. Takže když požádáte o token pro https://management.azure.com/ a použijete .default, je nutné požádat o https://management.azure.com//.default (všimněte si dvojitého lomítka!).

Obecně platí, že pokud ověříte, že se token vydává, a pokud je token odmítnut rozhraním API, které by ho mělo přijmout, zvažte přidání druhého lomítka a akci opakujte.

Viz také