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é jsou integrované s platformou Microsoft Identity Platform. Kterýkoli z těchto prostředků může také definovat sadu oprávnění, která lze použít k rozdělení funkčnosti tohoto prostředku na menší bloky dat. Například Microsoft Graph má definovaná 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: Čtení všech skupin v adresáři organizace

Poznámka:

V žádostech o autorizaci, token nebo koncové body souhlasu pro platformu Microsoft Identity Platform, pokud je identifikátor prostředku vynechán v parametru oboru, předpokládá se, že prostředek 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.

Obory 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. Obory address OpenID Connect a phone OpenID Connect se nepodporují.

Pokud si vyžádáte obory OpenID Connect a token, získá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.

Pomocí tohoto oprávnění může aplikace obdržet jedinečný identifikátor uživatele ve formě sub deklarace identity. 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 získá přístup k primární e-mailové adrese uživatele ve formě email deklarace identity.

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á email obor, musí být aplikace schopná zpracovat případ, ve kterém v tokenu neexistuje žádná email deklarace identity.

Obor profile

Obor profile lze použít s oborem a jakýmkoli jiným oborem openid . Poskytuje aplikaci přístup k velkému množství informací o uživateli. Informace, ke které má přístup, patří, ale nikoli pouze na jméno uživatele, příjmení, upřednostňované uživatelské jméno a ID objektu.

Úplný seznam profile deklarací identity dostupných v parametru id_tokens pro konkrétního uživatele najdete v referenčních informacíchid_tokens.

Obor offline_access

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

Když uživatel rozsah schválí offline_access , může vaše aplikace přijímat obnovovací tokeny z koncového bodu tokenu platformy Microsoft Identity Platform. Obnovovací tokeny jsou dlouhodobé. 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 toku autorizačního kódu OAuth 2.0, obdržíte z koncového /token bodu pouze přístupový token.

Přístupový token je obvykle 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 je platná po dobu jednoho dne. 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 obor: Ujistěte se, že požadujete offline_access obory spolu s dalšími nezbytnými obory.
  • Typ udělení autorizace: Obnovovací token se obvykle 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í. V případě potřeby je nutné použít signály, .default které by měly být vyzvány k zadání všech požadovaných oprávnění uvedených v registraci aplikace (pro všechna rozhraní API v seznamu).

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

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 zahájit souhlas správce. 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. Výsledkem je scope=https://graph.microsoft.com/.default Mail.Read chyba, protože kombinuje typy oborů.

Parametr .default oboru aktivuje výzvu k vyjádření souhlasu pouze v případě, že nebyl udělen souhlas s delegovaným oprávněním 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 není pro požadovaný prostředek uděleno žádné oprávnění (nebo pokud prompt=consent byl parametr poskytnut), 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 pro Microsoft Graph byl udělen alespoň jedno delegované oprávnění jménem přihlášeného uživatele, bude přihlášení pokračovat a všechna delegovaná oprávnění Microsoft Graphu udělená pro tohoto uživatele 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 Mail.Read klientovi oprávnění a User.Read oprávnění Microsoft Graphu.

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 zaregistroval oprávnění User.Read a Contacts.Read. Zaregistrovala se také pro obor https://vault.azure.net/user_impersonationslužby Azure Key Vault.

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 Mail.Read s klientem. Klient je zaregistrovaný Contacts.Read pro obor.

Klient nejprve provede přihlášení pomocí scope=https://graph.microsoft.com/.default. Na scopes základě parametru odpovědi kód 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 formulář žádosti o souhlas správce.) Mail.Read V příkazovém řádku k vyjádření souhlasu se zobrazí obojíContacts.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.

.default Použití oboru 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 .

Toto nastavení by neměli používat noví klienti, kteří cílí na platformu Microsoft Identity Platform. Nezapomeňte migrovat do knihovny Microsoft Authentication Library (MSAL) ze služby Azure AD Authentication Library (ADAL).

Tok 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, {resource} pro které vaše aplikace hodlá volat, a chce získat přístupový token pro. 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, https://contoso.com/ například 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 identifikátoru URI prostředku znamená, že lomítko musí být k dispozici při vyžádání tokenu. Takže když požádáte o token pro https://management.azure.com/ použití .default, musíte požádat https://management.azure.com//.default (všimněte si dvojité lomítko!).

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é