Begära behörigheter via medgivande

  • Artikel

Program i Microsofts identitetsplattform förlitar sig på medgivande för att få åtkomst till nödvändiga resurser eller API:er. Olika typer av medgivande är bättre för olika programscenarier. Om du väljer den bästa metoden för medgivande för din app blir det enklare för användare och organisationer att lyckas.

I den här artikeln får du lära dig om de olika typerna av medgivande och hur du begär behörigheter för ditt program via medgivande.

I scenariot med statiskt användarmedgivande måste du ange alla behörigheter som krävs i appens konfiguration i administrationscentret för Microsoft Entra. Om användaren (eller administratören efter behov) inte har beviljat medgivande för den här appen uppmanar Microsofts identitetsplattform användaren att ge sitt medgivande just nu.

Statiska behörigheter gör det också möjligt för administratörer att samtycka åt alla användare i organisationen.

Om du förlitar dig på statiskt medgivande och en enda behörighetslista är koden enkel och enkel, men det innebär också att din app begär alla behörigheter som den kan behöva i förväg. Detta kan avskräcka användare och administratörer från att godkänna appens åtkomstbegäran.

Med Microsofts identitetsplattform slutpunkten kan du ignorera de statiska behörigheter som definierats i programregistreringsinformationen i administrationscentret för Microsoft Entra. I stället kan du begära behörigheter stegvis. Du kan be om en minimal uppsättning behörigheter i förväg och begära mer över tid eftersom kunden använder ytterligare programfunktioner. För att göra det kan du ange de omfång som programmet behöver när som helst genom att inkludera de nya omfången i parametern scope när du begär en åtkomsttoken – utan att behöva fördefiniera dem i programregistreringsinformationen. Om användaren ännu inte har samtyckt till nya omfång som lagts till i begäran uppmanas de endast att godkänna de nya behörigheterna. Inkrementellt eller dynamiskt medgivande gäller endast delegerade behörigheter och inte programbehörigheter.

Om du tillåter att ett program begär behörigheter dynamiskt via parametern scope får utvecklarna fullständig kontroll över användarens upplevelse. Du kan också läsa in ditt medgivande i förväg och be om alla behörigheter i en första auktoriseringsbegäran. Om programmet kräver ett stort antal behörigheter kan du samla in dessa behörigheter från användaren stegvis när de försöker använda vissa funktioner i programmet över tid.

Viktigt!

Dynamiskt medgivande kan vara praktiskt, men utgör en stor utmaning för behörigheter som kräver administratörsmedgivande. Administratörens medgivande på bladet Appregistreringar- och Enterprise-program i portalen känner inte till dessa dynamiska behörigheter vid medgivandetillfället. Vi rekommenderar att en utvecklare listar alla administratörsprivilegerade behörigheter som krävs av programmet i portalen. Detta gör det möjligt för klientadministratörer att godkänna för alla sina användare i portalen, en gång. Användarna behöver inte gå igenom medgivandeupplevelsen för dessa behörigheter vid inloggning. Alternativet är att använda dynamiskt medgivande för dessa behörigheter. För att bevilja administratörsmedgivande loggar en enskild administratör in i appen, utlöser en medgivandeprompt för lämpliga behörigheter och väljer medgivande för hela min organisation i medgivandedialogen.

I en OpenID-Anslut- eller OAuth 2.0-auktoriseringsbegäran kan ett program begära de behörigheter som krävs med hjälp scope av frågeparametern. När en användare till exempel loggar in på en app skickar programmet en begäran som i följande exempel. (Radbrytningar läggs till för läsbarhet).

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

Parametern scope är en blankstegsavgränsad lista över delegerade behörigheter som programmet begär. Varje behörighet anges genom att behörighetsvärdet läggs till i resursens identifierare (program-ID-URI). I begärandeexemplet behöver programmet behörighet att läsa användarens kalender och skicka e-post som användare.

När användaren har angett sina autentiseringsuppgifter söker Microsofts identitetsplattform efter en matchande post med användarmedgivande. Om användaren inte har samtyckt till någon av de begärda behörigheterna tidigare, och om administratören inte har samtyckt till dessa behörigheter för hela organisationens räkning, ber Microsofts identitetsplattform användaren att bevilja de begärda behörigheterna.

I följande exempel inkluderas behörigheten offline_access ("Underhåll åtkomst till data som du har gett den åtkomst till") och User.Read ("Logga in och läs din profil") automatiskt i det första medgivandet till ett program. Dessa behörigheter krävs för rätt programfunktioner. Behörigheten offline_access ger programmet åtkomst till uppdateringstoken som är viktiga för interna appar och webbappar. Behörigheten User.Read ger åtkomst till anspråket sub . Det gör att klienten eller programmet kan identifiera användaren korrekt över tid och få åtkomst till rudimentär användarinformation.

Exempelbild som visar medgivande för arbetskontot.

När användaren godkänner behörighetsbegäran registreras medgivande. Användaren behöver inte godkänna det igen när de senare loggar in på programmet.

Begäran om medgivande för en hel klientorganisation kräver administratörsmedgivande. Administratörsmedgivande som görs för en organisations räkning kräver de statiska behörigheter som registrerats för appen. Ange dessa behörigheter i appregistreringsportalen om du behöver en administratör för att ge medgivande åt hela organisationen.

När ditt program begär delegerade behörigheter som kräver administratörsmedgivande får användaren ett felmeddelande om att de inte har behörighet att samtycka till appens behörigheter. Användaren måste be administratören om åtkomst till appen. Om administratören beviljar medgivande för hela klientorganisationen ser organisationens användare inte en medgivandesida för programmet om inte tidigare beviljade behörigheter återkallas eller programbegäranden om en ny behörighet stegvis.

Administratörer som använder samma program ser uppmaningen om administratörsmedgivande. Uppmaningen om administratörsmedgivande ger en kryssruta som gör att de kan ge programmet åtkomst till begärda data för användarnas räkning för hela klientorganisationen. Mer information om användar- och administratörsmedgivande finns i Programmedgivande.

Exempel på delegerade behörigheter för Microsoft Graph som kräver administratörsmedgivande är:

  • Läs alla användares fullständiga profiler med hjälp av User.Read.All
  • Skriva data till en organisations katalog med hjälp av Directory.ReadWrite.All
  • Läs alla grupper i en organisations katalog med hjälp av Groups.Read.All

Om du vill visa den fullständiga listan över Microsoft Graph-behörigheter kan du läsa Referens för Microsoft Graph-behörigheter.

Du kan också konfigurera behörigheter för dina egna resurser för att kräva administratörsmedgivande. Mer information om hur du lägger till omfång som kräver administratörsmedgivande finns i Lägga till ett omfång som kräver administratörsmedgivande.

Vissa organisationer kan ändra standardprincipen för användarmedgivande för klientorganisationen. När ditt program begär åtkomst till behörigheter utvärderas de mot dessa principer. Användaren kan behöva begära administratörsmedgivande även om det inte krävs som standard. Mer information om hur administratörer hanterar medgivandeprinciper för program finns i Hantera principer för appmedgivande.

Kommentar

Om resursidentifieraren utelämnas i omfångsparametern antas resursen vara Microsoft Graph i begäranden till auktoriserings-, token- eller medgivandeslutpunkterna för Microsofts identitetsplattform. Till exempel är scope=User.Read likvärdigt med https://graph.microsoft.com/User.Read.

Programbehörigheter kräver alltid administratörsmedgivande. Programbehörigheter har ingen användarkontext och beviljandet av medgivande görs inte för någon specifik användares räkning. I stället beviljas klientprogrammet behörigheter direkt. Dessa typer av behörigheter används endast av daemontjänster och andra icke-interaktiva program som körs i bakgrunden. Administratörer måste konfigurera behörigheterna i förväg och bevilja administratörsmedgivande via administrationscentret för Microsoft Entra.

Om programmet som begär behörigheten är ett program med flera klientorganisationer finns dess programregistrering bara i klientorganisationen där det skapades, därför kan behörigheter inte konfigureras i den lokala klientorganisationen. Om programmet begär behörigheter som kräver administratörsmedgivande måste administratören godkänna för användarnas räkning. För att godkänna dessa behörigheter måste administratörerna själva logga in på programmet, så inloggningsupplevelsen för administratörsmedgivande utlöses. Information om hur du konfigurerar administratörsmedgivande för program med flera klientorganisationer finns i Aktivera inloggningar för flera klientorganisationer

En administratör kan bevilja medgivande för ett program med följande alternativ.

När du skapar ett program som kräver administratörsmedgivande behöver programmet vanligtvis en sida eller vy där administratören kan godkänna appens behörigheter. Den här sidan kan vara:

  • En del av appens registreringsflöde.
  • En del av appens inställningar.
  • Ett dedikerat "anslut"-flöde.

I många fall är det klokt att programmet visar "anslut"-vyn först efter att en användare har loggat in med ett Microsoft-arbetskonto eller ett Microsoft-skolkonto.

När du loggar in användaren i din app kan du identifiera den organisation som administratören tillhör innan du ber dem godkänna nödvändiga behörigheter. Även om det här steget inte är absolut nödvändigt kan det hjälpa dig att skapa en mer intuitiv upplevelse för organisationens användare.

Om du vill logga in användaren följer du självstudierna för Microsofts identitetsplattform protokoll.

Begär behörigheterna i appregistreringsportalen

I appregistreringsportalen kan program visa de behörigheter de behöver, inklusive både delegerade behörigheter och programbehörigheter. Den här konfigurationen tillåter användning av omfånget .default och microsoft Entra-administrationscentrets alternativet Bevilja administratörsmedgivande.

I allmänhet bör behörigheterna definieras statiskt för ett visst program. De bör vara en superuppsättning av de behörigheter som programmet begär dynamiskt eller inkrementellt.

Kommentar

Programbehörigheter kan endast begäras med hjälp av .default. Om ditt program behöver programbehörigheter kontrollerar du därför att de finns med i appregistreringsportalen.

Så här konfigurerar du listan över statiskt begärda behörigheter för ett program:

  1. Logga in på administrationscentret för Microsoft Entra som minst molnprogramadministratör.
  2. Bläddra till Identitetsprogram>> Appregistreringar> Alla program.
  3. Välj ett program eller skapa en app om du inte redan har gjort det.
  4. På programmets översiktssida går du till Hantera och väljer API-behörigheter>Lägg till en behörighet.
  5. Välj Microsoft Graph i listan över tillgängliga API:er. Lägg sedan till de behörigheter som programmet kräver.
  6. Välj Lägg till behörigheter.

Lyckat svar

Om administratören godkänner behörigheterna för din app ser det lyckade svaret ut så här:

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
Parameter Description
tenant Katalogklientorganisationen som gav ditt program de behörigheter som begärdes, i GUID-format.
state Ett värde som ingår i begäran som också returneras i tokensvaret. Det kan vara en sträng med valfritt innehåll. Tillståndet används för att koda information om användarens tillstånd i programmet innan autentiseringsbegäran inträffade, till exempel sidan eller vyn de var på.
admin_consent Kommer att anges till True.

När du har fått ett lyckat svar från slutpunkten för administratörsmedgivande har programmet fått de behörigheter som begärdes. Därefter kan du begära en token för den resurs du vill ha.

Felsvar

Om administratören inte godkänner behörigheterna för din app ser det misslyckade svaret ut så här:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Parameter Description
error En felkodssträng som kan användas för att klassificera typer av fel som inträffar. Den kan också användas för att reagera på fel.
error_description Ett specifikt felmeddelande som kan hjälpa en utvecklare att identifiera rotorsaken till ett fel.

När användaren har samtyckt till behörigheter för din app kan programmet hämta åtkomsttoken som representerar appens behörighet att komma åt en resurs i viss kapacitet. En åtkomsttoken kan endast användas för en enskild resurs. Men kodad i åtkomsttoken är alla behörigheter som programmet har beviljats för den resursen. Om du vill hämta en åtkomsttoken kan ditt program göra en begäran till Microsofts identitetsplattform tokenslutpunkt, så här:

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
}

Du kan använda den resulterande åtkomsttoken i HTTP-begäranden till resursen. Det anger på ett tillförlitligt sätt för resursen att programmet har rätt behörighet att utföra en viss uppgift.

Mer information om OAuth 2.0-protokollet och hur du hämtar åtkomsttoken finns i referensen för Microsofts identitetsplattform slutpunktsprotokoll.

Se även