Příručka pro vývojáře k vyžádání oprávnění a souhlasu na platformě Microsoft Identity Platform

Aplikace na platformě Microsoft Identity Platform spoléhají na souhlas, aby získaly přístup k potřebným prostředkům nebo rozhraním API. Různé typy souhlasu jsou lepší pro různé scénáře aplikace. Volba nejlepšího přístupu k vyjádření souhlasu s vaší aplikací umožňuje, aby byla u uživatelů a organizací úspěšnější.

V tomto článku se dozvíte o různých typech souhlasu a o tom, jak požádat o oprávnění pro vaši aplikaci prostřednictvím souhlasu.

Poznámka:

U aplikací v externích tenantech nemohou zákazníci sami udělit souhlas k oprávněním. Správce bude muset udělit souhlas aplikaci k přístupu k prostředkům svým jménem. Další informace najdete v tématu Udělení souhlasu správce.

Ve scénáři souhlasu statického uživatele musíte zadat všechna oprávnění, která potřebuje, v konfiguraci aplikace v Centru pro správu Microsoft Entra. Pokud uživatel (nebo správce podle potřeby) neudělí souhlas pro tuto aplikaci, služba Microsoft Identity Platform vyzve uživatele, aby v tuto chvíli udělil souhlas.

Statická oprávnění také umožňují správcům souhlas jménem všech uživatelů v organizaci.

Při závislosti na statickém souhlasu a jediném seznamu oprávnění je kód pěkný a jednoduchý, znamená to také, že vaše aplikace požádá o všechna oprávnění, která může někdy potřebovat předem. Toto nastavení může uživatelům a správcům bránit ve schvalování žádosti o přístup vaší aplikace.

Pomocí koncového bodu Microsoft Identity Platform můžete ignorovat statická oprávnění definovaná v informacích o registraci aplikace v Centru pro správu Microsoft Entra. Místo toho můžete dynamicky požadovat oprávnění z kódu aplikace. Můžete začít tím, že požádáte o minimální minimální sadu oprávnění předem a požádáte ostatní v průběhu času, protože zákazník používá více funkcí aplikace. K tomu můžete kdykoli zadat obory, které vaše aplikace potřebuje, zahrnutím oborů do parametru scope při vyžádání přístupového tokenu bez nutnosti jejich předdefinování v informacích o registraci aplikace.

Pokud uživatel nesdělil souhlas s žádným z oborů v žádosti, zobrazí se mu výzva k vyjádření souhlasu se všemi oprávněními v této žádosti. Tyto oprávnění budou udělena kromě všech dalších oprávnění, která už byla pro danou aplikaci udělena (tj. přírůstková). Přírůstkový souhlas se vztahuje pouze na delegovaná oprávnění a ne na oprávnění aplikace.

Když aplikaci umožníte dynamicky vyžadovat oprávnění prostřednictvím parametru scope , získáte vývojářům plnou kontrolu nad prostředím uživatele. Přednastavíte udělení souhlasu a požádáte o všechna potřebná oprávnění v jedné úvodní žádosti o autorizaci. Pokud vaše aplikace vyžaduje velký počet oprávnění, můžete tato oprávnění shromáždit od uživatele postupně při pokusu o používání určitých funkcí aplikace v průběhu času.

Důležité

Dynamický souhlas může být pohodlný, ale představuje významnou výzvu pro oprávnění, která vyžadují souhlas správce. Prostředí pro vyjádření souhlasu správce v přehlídce registrací aplikací a podnikových aplikací na portálu nereflektuje tato dynamická oprávnění v době souhlasu. Doporučujeme, aby vývojář vypisoval všechna privilegovaná oprávnění správce, která aplikace potřebuje na portálu.

Správci tenantů tak můžou souhlasit jménem všech uživatelů na portálu jednou. Uživatelé nemusí projít prostředím souhlasu pro tato oprávnění při přihlášení. Alternativou je použití dynamického souhlasu pro tato oprávnění. Pokud chcete udělit souhlas správce, jednotlivý správce se přihlásí k aplikaci, aktivuje výzvu k vyjádření souhlasu pro příslušná oprávnění a vybere souhlas pro celou organizaci v dialogu souhlasu.

V žádosti o autorizaci OpenID Connect nebo OAuth 2.0 může aplikace požádat o oprávnění, která potřebuje, pomocí parametru scope dotazu. Když se například uživatel přihlásí k aplikaci, odešle aplikace požadavek podobný následujícímu příkladu. (Konce řádků jsou přidány pro čitelnost).

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=
https%3A%2F%2Fgraph.microsoft.com%2Fcalendars.read%20
https%3A%2F%2Fgraph.microsoft.com%2Fmail.send
&state=12345

Parametr scope je seznam delegovaných oprávnění oddělených mezerami, která aplikace požaduje. Každé oprávnění je označeno připojením hodnoty oprávnění k identifikátoru prostředku (identifikátor URI ID aplikace). V příkladu požadavku potřebuje aplikace oprávnění ke čtení kalendáře uživatele a odesílání pošty jako uživatele.

Po přihlášení zkontroluje platforma Microsoft Identity Platform stávající souhlas uživatele. Pokud uživatel požadovaná oprávnění neschválí a správce je neschválí, platforma vyzve uživatele k udělení souhlasu.

V následujícím příkladu jsou oprávnění offline_access ("Udržovat přístup k datům, ke kterým udělíte přístup") a User.Read ("Přihlásit se a přečíst svůj profil") automaticky zahrnuta do počátečního souhlasu s aplikací. Tato oprávnění jsou vyžadována pro správné funkce aplikace.

Oprávnění offline_access dává aplikaci přístup k obnovovacím tokenům, které jsou důležité pro nativní aplikace a webové aplikace. Oprávnění User.Read uděluje přístup k sub nároku. Umožňuje klientovi nebo aplikaci správně identifikovat uživatele v průběhu času a přistupovat k rudimentárním uživatelským informacím.

Příklad snímku obrazovky znázorňující souhlas pracovního účtu

Když uživatel žádost o oprávnění schválí, zaznamená se souhlas. Uživatel nemusí znovu souhlasit, když se později přihlásí k aplikaci.

Žádost o souhlas pro celého tenanta vyžaduje souhlas správce. Souhlas správce provedený jménem organizace vyžaduje statická oprávnění zaregistrovaná pro aplikaci. Pokud potřebujete, aby správce udělil souhlas jménem celé organizace, nastavte tato oprávnění na portálu registrace aplikace Microsoft Entra.

Když vaše aplikace požádá o delegovaná oprávnění, která vyžadují souhlas správce, zobrazí se uživatelům chyba "Neautorizováno k vyjádření souhlasu" a potřebují požádat správce o přístup. Jakmile správce udělí souhlas pro celého tenanta, nebudou uživatelé znovu vyzváni, pokud se neodvolají souhlas nebo se nepřidají nová oprávnění.

Správci, kteří používají stejnou aplikaci, se zobrazí výzva k vyjádření souhlasu správce. Výzva k vyjádření souhlasu správce obsahuje zaškrtávací políčko, které mu umožní udělit aplikaci přístup k požadovaným datům jménem uživatelů pro celého tenanta. Další informace o prostředí souhlasu uživatele a správce najdete v tématu Prostředí souhlasu aplikace.

Příklady delegovaných oprávnění pro Microsoft Graph, která vyžadují souhlas správce, jsou:

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

Pokud chcete zobrazit úplný seznam oprávnění Microsoft Graphu, přečtěte si referenční informace o oprávněních Microsoft Graphu.

Můžete také nakonfigurovat oprávnění pro vlastní prostředky tak, aby vyžadovala souhlas správce. Další informace o tom, jak přidat obory, které vyžadují souhlas správce, najdete v tématu Přidání oboru, který vyžaduje souhlas správce.

Některé organizace můžou změnit výchozí zásady souhlasu uživatele pro tenanta. Když vaše aplikace požádá o přístup k oprávněním, která se vyhodnocují proti těmto zásadám. Uživatel může potřebovat požádat o souhlas správce, i když to ve výchozím nastavení nevyžaduje. Informace o tom, jak správci spravují zásady souhlasu pro aplikace, najdete v tématu Správa zásad souhlasu aplikací.

Poznámka:

V žádostech o autorizaci, token nebo souhlas v platformě Microsoft identity, pokud vynecháte identifikátor prostředku v parametru scope, použije se ve výchozím nastavení Microsoft Graph. Například scope=User.Read se považuje za https://graph.microsoft.com/User.Read.

Oprávnění aplikace vždy vyžadují souhlas správce. Oprávnění aplikace nemají kontext uživatele a udělení souhlasu není 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í používají jenom služby démona a jiné neinteraktivní aplikace, které běží na pozadí. Správci musí předem nakonfigurovat oprávnění a udělit souhlas správce prostřednictvím Centra pro správu Microsoft Entra.

V případě, že aplikace požadující oprávnění je víceklientická aplikace, její registrace aplikace existuje pouze v tenantovi, ve kterém byla vytvořena, a proto v místním tenantovi není možné nakonfigurovat oprávnění. Pokud aplikace požaduje oprávnění, která vyžadují souhlas správce, musí správce souhlasit jménem uživatelů. K vyjádření souhlasu s těmito oprávněními se správci musí přihlásit k samotné aplikaci, takže se aktivuje přihlašovací prostředí souhlasu správce. Informace o nastavení prostředí souhlasu správce pro víceklientské aplikace najdete v tématu Povolení víceklientských přihlášení.

Správce může udělit souhlas pro aplikaci s následujícími možnostmi.

Při vytváření aplikace, která vyžaduje souhlas správce, aplikace obvykle potřebuje stránku nebo zobrazení, ve kterém může správce schválit oprávnění aplikace. Tato stránka může být následující:

  • Část procesu registrace aplikace
  • Část nastavení aplikace
  • Vyhrazený proces „connect“.

V mnoha případech je vhodné, aby aplikace zobrazila pohled Připojení až po přihlášení pomocí pracovního nebo školního účtu Microsoft.

Když uživatele přihlásíte do aplikace, můžete určit organizaci, do které správce patří, a teprve potom požádat o schválení potřebných oprávnění. I když tento krok není nezbytně nutný, může vám pomoct vytvořit intuitivnější prostředí pro uživatele organizace.

Pokud chcete uživatele přihlásit, postupujte podle kurzů protokolu Microsoft Identity Platform.

Vyžádání oprávnění na portálu registrace aplikace Microsoft Entra

Na portálu pro registraci aplikací Microsoft Entra můžou aplikace zobrazit seznam oprávnění, která vyžadují, včetně delegovaných oprávnění i oprávnění aplikace. Toto nastavení umožňuje použití .default oboru a možnosti Udělit souhlas správce v Centru pro správu Microsoft Entra.

Obecně platí, že oprávnění by měla být staticky definovaná pro danou aplikaci. Měly by se jednat o nadmnožinu oprávnění, která aplikace dynamicky nebo přírůstkově požaduje.

Poznámka:

Oprávnění aplikace lze požadovat pouze pomocí .default. Pokud tedy vaše aplikace potřebuje oprávnění aplikace, ujistěte se, že jsou uvedená na portálu pro registraci aplikací Microsoft Entra.

Konfigurace seznamu staticky požadovaných oprávnění pro aplikaci:

  1. Přihlaste se do Centra pro správu Microsoft Entra jako alespoň správce cloudových aplikací.
  2. Přejděte na Entra ID>Registrace aplikací>Všechny aplikace.
  3. Vyberte aplikaci nebo vytvořte aplikaci , pokud jste ji ještě neudělali.
  4. Na stránce Přehled aplikace v části Spravovat vyberte Oprávnění> rozhraní APIPřidat oprávnění.
  5. V seznamu dostupných rozhraní API vyberte Microsoft Graph . Potom přidejte oprávnění, která vaše aplikace vyžaduje.
  6. Vyberte Přidat oprávnění.

Ú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á do požadavku vráceného 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 Je nastavena na True.

Jakmile obdržíte úspěšnou odpověď z koncového bodu souhlasu správce, vaší aplikaci se udělí požadovaná oprávnění. Dále můžete požádat o token pro požadovaný prostředek.

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ý lze použít ke klasifikaci typů chyb, ke kterým dochází. Dá se také použít k reakci na chyby.
error_description Konkrétní chybová zpráva, která může vývojáři pomoct identifikovat původní příčinu chyby.

Jakmile uživatel souhlasí s oprávněními pro vaši aplikaci, může vaše aplikace získat přístupové tokeny, které představují oprávnění aplikace pro přístup k prostředku v určité kapacitě. Přístupový token lze použít pouze pro jeden prostředek. Uvnitř přístupového tokenu jsou ale zakódována všechna oprávnění, která byla vaší aplikaci udělena pro daný prostředek. K získání přístupového tokenu může vaše aplikace vytvořit požadavek na koncový bod tokenu platformy Microsoft Identity Platform, například takto:

POST common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "scope": "https://microsoft.graph.com/Mail.Read https://microsoft.graph.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "A1bC2dE3f..."  // NOTE: Only required for web apps
}

Výsledný přístupový token můžete použít v požadavcích HTTP na prostředek. Spolehlivě naznačuje prostředku, že vaše aplikace má správné oprávnění k provedení konkrétní úlohy.

Další informace o protokolu OAuth 2.0 a o tom, jak získat přístupové tokeny, najdete v referenčních informacích k protokolu koncového bodu platformy Microsoft Identity Platform.

Související obsah

  • Last updated on