Behörigheter och medgivande i Microsofts identitetsplattform

Program som integreras med Microsofts identitetsplattform följer en auktoriseringsmodell som ger användare och administratörer kontroll över hur data kan nås. Implementeringen av auktoriseringsmodellen har uppdaterats på Microsofts identitetsplattform. Det ändrar hur en app måste interagera med Microsofts identitetsplattform. Den här artikeln beskriver de grundläggande begreppen i den här auktoriseringsmodellen, inklusive omfång, behörigheter och medgivande.

Omfång och behörigheter

Den Microsofts identitetsplattform implementerar OAuth 2.0-auktoriseringsprotokollet. OAuth 2.0 är en metod genom vilken en tredjepartsapp kan komma åt webbaserade resurser för en användares räkning. Alla webbvärdbaserade resurser som integreras med Microsofts identitetsplattform har en resursidentifierare eller program-ID-URI.

Här följer några exempel på Microsofts webbaserade resurser:

  • Microsoft Graph:https://graph.microsoft.com
  • Microsoft 365 Mail API:https://outlook.office.com
  • Azure Key Vault: https://vault.azure.net

Samma sak gäller för alla resurser från tredje part som har integrerats med Microsofts identitetsplattform. Alla dessa resurser kan också definiera en uppsättning behörigheter som kan användas för att dela upp funktionerna i resursen i mindre segment. Till exempel har Microsoft Graph definierat behörigheter för att utföra följande uppgifter, bland annat:

  • Läsa en användares kalender
  • Skriva till en användares kalender
  • Skicka e-post som en användare

På grund av dessa typer av behörighetsdefinitioner har resursen en finkornig kontroll över sina data och hur API-funktioner exponeras. En tredjepartsapp kan begära dessa behörigheter från användare och administratörer, som måste godkänna begäran innan appen kan komma åt data eller agera för en användares räkning.

När en resurs funktioner är indelade i små behörighetsuppsättningar kan appar från tredje part byggas för att endast begära de behörigheter som de behöver för att utföra sin funktion. Användare och administratörer kan veta vilka data som appen kan komma åt. Och de kan vara mer säkra på att appen inte beter sig med skadlig avsikt. Utvecklare bör alltid följa principen om minsta behörighet och endast be om de behörigheter de behöver för att deras program ska fungera.

I OAuth 2.0 kallas dessa typer av behörighetsuppsättningar för omfång. De kallas också för behörigheter. I Microsofts identitetsplattform representeras en behörighet som ett strängvärde. En app begär de behörigheter den behöver genom att ange behörigheten i scope frågeparametern. Identitetsplattformen stöder flera väldefinierade OpenID Anslut-omfång samt resursbaserade behörigheter (varje behörighet anges genom att behörighetsvärdet till resursens identifierare eller program-ID-URI har angetts). Behörighetssträngen används https://graph.microsoft.com/Calendars.Read till exempel för att begära behörighet att läsa användarnas kalendrar i Microsoft Graph.

En app begär oftast dessa behörigheter genom att ange omfången i begäranden till Microsofts identitetsplattform auktorisera slutpunkten. Vissa behörigheter med hög behörighet kan dock endast beviljas via administratörsmedgivande. De kan begäras eller beviljas med hjälp av slutpunkten för administratörsmedgivande. Läs vidare om du vill veta mer.

I begäranden till auktoriserings-, token- eller medgivandeslutpunkter för Microsoft Identity-plattformen antas resursen vara Microsoft Graph om resursidentifieraren utelämnas i omfångsparametern. scope=User.Read motsvarar till exempel https://graph.microsoft.com/User.Read.

Behörighetstyper

Den Microsofts identitetsplattform två typer av behörigheter: delegerade behörigheter och programbehörigheter.

  • Delegerade behörigheter används av appar som har en inloggad användare. För dessa appar godkänner antingen användaren eller en administratör de behörigheter som appen begär. Appen delegeras med behörighet att agera som en inloggad användare vid anrop till målresursen.

    Vissa delegerade behörigheter kan godkännas av icke-administratörer. Men vissa högbehörigheter kräver administratörsmedgivande. Information om vilka administratörsroller som kan godkänna delegerade behörigheter finns i Behörigheter för administratörsroll i Azure Active Directory (Azure AD).

  • Programbehörigheter används av appar som körs utan en inloggad användare, till exempel appar som körs som bakgrundstjänster eller daemons. Endast en administratör kan godkänna programbehörigheter.

Gällande behörigheter är de behörigheter som din app har när den gör begäranden till målresursen. Det är viktigt att förstå skillnaden mellan de delegerade behörigheterna och programbehörigheterna som din app beviljas och de gällande behörigheter som din app beviljas när den gör anrop till målresursen.

  • För delegerade behörigheter är de gällande behörigheterna för din app den minst privilegierade skärningspunkten för de delegerade behörigheter som appen har beviljats (genom medgivande) och behörigheterna för den inloggade användaren. Din app kan aldrig ha fler behörigheter än den inloggade användaren.

    Inom organisationer kan den inloggade användarens behörigheter fastställas av en princip eller genom medlemskap i en eller flera administratörsroller. Information om vilka administratörsroller som kan godkänna delegerade behörigheter finns i Behörigheter för administratörsroll i Azure AD.

    Anta till exempel att din app har beviljats behörigheten User.ReadWrite.All delegerad. Den här behörigheten ger i princip din app behörighet att läsa och uppdatera profilen för alla användare i en organisation. Om den inloggade användaren är en global administratör kan din app uppdatera profilen för alla användare i organisationen. Men om den inloggade användaren inte har någon administratörsroll kan din app bara uppdatera profilen för den inloggade användaren. Den kan inte uppdatera profiler för andra användare i organisationen eftersom den användare som den har behörighet att agera för inte har dessa behörigheter.

  • För programbehörigheter är de gällande behörigheterna för din app den fullständiga behörighetsnivån som behörigheten medför. Till exempel kan en app som har behörigheten User.ReadWrite.All uppdatera profilen för varje användare i organisationen.

OpenID Anslut omfång

Implementeringen Microsofts identitetsplattform OpenID-Anslut har några väldefinierade omfång som också finns på Microsoft Graph: openidemail , , och profileoffline_access . addressphone OpenID-Anslut stöds inte.

Om du begär OpenID Anslut omfång och en token får du en token för att anropa UserInfo-slutpunkten.

Openid

Om en app loggar in med hjälp av OpenID Anslutmåste den begära omfånget. openidOmfånget visas på medgivandesidan för arbetskontot som openid På sidan för Microsoft-konto personliga behörigheter visas den som Visa din profil och ansluter till appar och tjänster med din Microsoft-konto behörighet.

Med den här behörigheten kan en app ta emot en unik identifierare för användaren i form av sub anspråket. Behörigheten ger även appen åtkomst till UserInfo-slutpunkten. openidOmfånget kan användas vid den Microsofts identitetsplattform tokenslutpunkten för att hämta ID-token. Appen kan använda dessa token för autentisering.

e-post

emailOmfånget kan användas med openid omfånget och andra omfång. Det ger appen åtkomst till användarens primära e-postadress i form av email anspråket.

Anspråket ingår endast i en token om en e-postadress är associerad med email användarkontot, vilket inte alltid är fallet. Om appen använder omfånget måste appen kunna hantera email ett fall där det inte finns något anspråk i email token.

profil

profileOmfånget kan användas med openid omfånget och andra omfång. Det ger appen åtkomst till en stor mängd information om användaren. Den information som den kan komma åt omfattar, men är inte begränsad till, användarens förnamn, efternamn, föredraget användarnamn och objekt-ID.

En fullständig lista över anspråk profile som är tillgängliga i id_tokens parametern för en specifik användare finns i profile.

offline_access

Omfånget ger din app åtkomst till resurser för användarens räkning under en längre tid. På sidan för medgivande visas det här omfånget som Den behåller åtkomsten till data som du har gett åtkomst till behörighet.

När en användare godkänner offline_access omfånget kan appen ta emot uppdateringstoken från Microsofts identitetsplattform tokenslutpunkt. Uppdateringstoken är långlivade. Din app kan få nya åtkomsttoken när äldre upphör att gälla.

Anteckning

Den här behörigheten visas för närvarande på alla medgivandesidor, även för flöden som inte tillhandahåller en uppdateringstoken (till exempel det implicita flödet). Den här installationen åtgärdar scenarier där en klient kan börja i det implicita flödet och sedan flytta till kodflödet där en uppdateringstoken förväntas.

På Microsofts identitetsplattform (begäranden som görs till v2.0-slutpunkten) måste din app uttryckligen begära offline_access omfånget för att ta emot uppdateringstoken. Så när du löser in en auktoriseringskod i OAuth 2.0-auktoriseringskodflödetfår du bara en åtkomsttoken från slutpunkten.

Åtkomsttoken är giltig under en kort tid. Den upphör vanligtvis att gälla om en timme. Då måste appen omdirigera användaren tillbaka till slutpunkten för att /authorize få en ny auktoriseringskod. Under den här omdirigeringen kan användaren, beroende på typ av app, behöva ange sina autentiseringsuppgifter igen eller godkänna behörigheterna igen.

Mer information om hur du hämtar och använder uppdateringstoken finns i Microsofts identitetsplattform protokollreferens .

Program i Microsofts identitetsplattform förlitar sig på medgivande för att få åtkomst till nödvändiga resurser eller API:er. Det finns ett antal typer av godkännanden som din app kan behöva ha för att fungera. Om du definierar behörigheter behöver du också känna till hur användarna får tillgång till din app eller API.

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

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

Även om statiska behörigheter för appen som definierats i Azure Portal ser till att koden är bra och enkel så medför den några möjliga problem för utvecklare:

  • Appen måste begära alla behörigheter som behövs vid användarens första inloggning. Detta kan leda till en lång lista över behörigheter som avråder slutanvändare från att godkänna appens åtkomst vid den första inloggningen.

  • Appen måste känna till alla resurser som den någonsin skulle ha åtkomst till i förväg. Det är svårt att skapa appar som kan komma åt ett godtyckligt antal resurser.

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

Genom att tillåta en app att begära behörigheter dynamiskt via scope parametern får utvecklarna fullständig kontroll över användarens upplevelse. Du kan också läsa in din medgivandeupplevelse och be om alla behörigheter i en inledande auktoriseringsbegäran. Om din app kräver ett stort antal behörigheter kan du samla in dessa behörigheter från användaren inkrementellt när de försöker använda vissa funktioner i appen över tid.

Viktigt

Ett dynamiskt godkännande kan vara praktiskt, men det är en utmaning för behörigheter som kräver administratörsmedgivande eftersom man inte känner till dessa behörigheter vid godkännandet. Om du behöver privilegierade administratörsbehörigheter eller om din app använder dynamiskt medgivande måste du registrera alla behörigheter i Azure Portal (inte bara den delmängd av behörigheter som kräver administratörsmedgivande). Detta gör det möjligt för klientorganisationsadministratörer att godkänna för alla deras användares räkning.

Administratörsmedgivande krävs när din app behöver åtkomst till vissa behörigheter med hög behörighet. Administratörsmedgivande säkerställer att administratörer har vissa ytterligare kontroller innan de godkänner appar, eller att användare får åtkomst till högprivilegierade data från organisationen.

Administratörsmedgivande som görs för en organisations räkning kräver fortfarande de statiska behörigheter som registrerats för appen. Ange dessa behörigheter för appar i appregistreringsportalen om du behöver en administratör för att ge medgivande åt hela organisationen. Detta minskar de cykler som krävs av organisationsadministratören för att konfigurera programmet.

I en OpenID Anslut- eller OAuth 2.0-auktoriseringsbegäran kan en app begära de behörigheter den behöver med hjälp av frågeparametern. När en användare till exempel loggar in på en app skickar appen en begäran som i följande exempel. (Radbrytningar läggs till för att göra det lätt att göra det.)

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&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 appen begär. Varje behörighet anges genom att lägga till behörighetsvärdet till resursens identifierare (program-ID:ts URI). I exemplet med begäran behöver appen behörighet att läsa användarens kalender och skicka e-post som användaren.

När användaren anger sina autentiseringsuppgifter söker Microsofts identitetsplattform efter en matchande post med användarens medgivande. 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.

Just nu ingår behörigheten ("Behåll åtkomst till data som du har gett åtkomst till") och ("Logga in och läsa din profil") automatiskt i det första medgivandet till offline_accessUser.Read ett program. Dessa behörigheter krävs vanligtvis för rätt appfunktioner. Behörigheten offline_access ger appen åtkomst till uppdateringstoken som är viktiga för interna appar och webbappar. Behörigheten User.Read ger åtkomst till sub anspråket. Det gör att klienten eller appen kan identifiera användaren över tid och få åtkomst till enkel användarinformation.

Example screenshot that shows work account consent.

När användaren godkänner behörighetsbegäran registreras medgivande. Användaren behöver inte ge sitt medgivande igen när de senare loggar in i programmet.

När en organisation köper en licens eller prenumeration för ett program vill organisationen ofta proaktivt konfigurera programmet för användning av alla medlemmar i organisationen. Som en del av den här processen kan en administratör bevilja medgivande för programmet att agera för alla användare i klientorganisationen. Om administratören beviljar medgivande för hela klientorganisationen ser inte organisationens användare en medgivandesida för programmet.

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 för appar i appregistreringsportalen om du behöver en administratör för att ge medgivande åt hela organisationen.

Om du vill begära medgivande för delegerade behörigheter för alla användare i en klientorganisation kan din app använda slutpunkten för administratörsmedgivande.

Dessutom måste program använda slutpunkten för administratörsmedgivande för att begära programbehörigheter.

Administratörsbegränsade behörigheter

Vissa behörigheter med hög behörighet i Microsoft-resurser kan anges till administratörsbegränsade. Här följer några exempel på dessa typer av behörigheter:

  • Läsa 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äsa alla grupper i en organisations katalog med hjälp av Groups.Read.All

Anteckning

I begäranden till auktoriserings-, token- eller medgivandeslutpunkter för Microsoft Identity-plattformen antas resursen vara Microsoft Graph om resursidentifieraren utelämnas i omfångsparametern. scope=User.Read motsvarar till exempel https://graph.microsoft.com/User.Read.

Även om en konsumentanvändare kan ge ett program åtkomst till den här typen av data, kan organisationsanvändare inte bevilja åtkomst till samma uppsättning känsliga företagsdata. Om ditt program begär åtkomst till någon av dessa behörigheter från en organisationsanvändare får användaren ett felmeddelande som säger att de inte har behörighet att godkänna appens behörigheter.

Om din app kräver omfång för administratörsbegränsade behörigheter måste en organisations administratör godkänna dessa omfång för organisationens användares räkning. Appen kan använda slutpunkten för administratörsmedgivande för att undvika att visa frågor för användare som begär medgivande för behörigheter som de inte kan bevilja. Slutpunkten för administratörsmedgivande tas upp i nästa avsnitt.

Om programmet begär delegerade behörigheter med hög behörighet och en administratör beviljar dessa behörigheter via slutpunkten för administratörsmedgivande, beviljas medgivande för alla användare i klientorganisationen.

Om programmet begär programbehörigheter och en administratör beviljar dessa behörigheter via slutpunkten för administratörsmedgivande görs detta beviljande 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 daemon-tjänster och andra icke-interaktiva program som körs i bakgrunden.

När du använder slutpunkten för administratörsmedgivande för att bevilja administratörsmedgivande är du klar. Användarna behöver inte vidta några ytterligare åtgärder. När administratörsmedgivande har beviljats kan användarna få en åtkomsttoken via ett vanligt auth-flöde. Den resulterande åtkomsttoken har de behörigheter som krävs.

När en global administratör använder ditt program och dirigeras till auktorisera slutpunkten Microsofts identitetsplattform identifierar användarens roll. Den frågar om den globala administratören vill godkänna för hela klientorganisationens räkning för de behörigheter som du har begärt. Du kan i stället använda en dedikerad slutpunkt för administratörsmedgivande för att proaktivt begära att en administratör beviljar behörighet åt hela klientorganisationen. Den här slutpunkten är också nödvändig för att begära programbehörigheter. Programbehörigheter kan inte begäras med hjälp av auktorisera slutpunkten.

Om du följer dessa steg kan din app begära behörigheter för alla användare i en klientorganisation, inklusive administratörsbegränsade omfång. Den här åtgärden har hög behörighet. Använd bara åtgärden om det behövs för ditt scenario.

Ett kodexempel som implementerar stegen finns i exemplet med administratörsbegränsade omfång i GitHub.

Begära behörigheterna i appregistreringsportalen

I appregistreringsportalen kan program lista de behörigheter som de behöver, inklusive både delegerade behörigheter och programbehörigheter. Med den här konfigurationen kan .default omfånget och Azure Portal alternativet .default

I allmänhet ska behörigheterna statiskt definieras för ett visst program. De bör vara en supermängd av de behörigheter som appen begär dynamiskt eller inkrementellt.

Anteckning

Programbehörigheter kan endast begäras med hjälp av .default . Om din app behöver programbehörigheter kontrollerar du att den finns med i appregistreringsportalen.

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

  1. Gå till ditt program i Azure Portal – Appregistreringar snabbstart.
  2. Välj ett program eller skapa en app om du inte redan har gjort det.
  3. På programmets översiktssida går du till Hantera och väljerAPI-behörigheter Läggtill en behörighet.
  4. Välj Microsoft Graph i listan över tillgängliga API:er. Lägg sedan till de behörigheter som din app kräver.
  5. Välj Lägg till behörigheter.

När du skapar ett program som använder slutpunkten för administratörsmedgivande behöver appen 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 inloggningsflöde.
  • En del av appens inställningar.
  • Ett dedikerat "anslut"-flöde.

I många fall är det klokt att appen endast visar den här anslutningsvyn när en användare har loggat in med ett arbets- Microsoft-konto eller Microsoft-konto.

När du loggar in användaren i din app kan du identifiera organisationen som administratören tillhör innan du ber dem att godkänna de behörigheter som krävs. Ä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 Microsofts identitetsplattform protokollet.

Begära behörigheter från en katalogadministratör

När du är redo att begära behörigheter från din organisations administratör kan du omdirigera användaren till slutpunkten för Microsofts identitetsplattform administratörsmedgivande.

// Line breaks are for legibility only.
GET https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=http://localhost/myapp/permissions
&scope=
https://graph.microsoft.com/calendars.read
https://graph.microsoft.com/mail.send
Parameter Villkor Beskrivning
tenant Krävs Den katalogklient som du vill begära behörighet från. Det kan anges i ett GUID eller eget namnformat. Eller så kan den refereras allmänt till organisationer, som du ser i exemplet. Använd inte "vanliga", eftersom personliga konton inte kan ge administratörsmedgivande förutom i kontexten för en klientorganisation. Använd klientorganisations-ID:t när det är möjligt för att säkerställa bästa kompatibilitet med personliga konton som hanterar klienter.
client_id Obligatorisk Det program-ID (klient) som Azure Portal – Appregistreringar till din app.
redirect_uri Obligatorisk Omdirigerings-URI:en där du vill att svaret ska skickas för din app att hantera. Den måste exakt matcha en av de omdirigerings-URI:er som du registrerade i appregistreringsportalen.
state Rekommenderas Ett värde som ingår i begäran som också returneras i tokensvaret. Det kan vara en sträng med val annat innehåll. Använd tillståndet för att koda information om användarens tillstånd i appen innan autentiseringsbegäran gjordes, till exempel den sida eller vy som användaren var på.
scope Obligatorisk Definierar den uppsättning behörigheter som begärs av programmet. Omfång kan vara antingen statiska (med .default ) eller dynamiska. Den här uppsättningen kan innehålla OpenID Anslut omfattningar ( openid , profile , email ). Om du behöver programbehörigheter måste du använda .default för att begära den statiskt konfigurerade listan över behörigheter.

I det här läget kräver Azure AD att en innehavaradministratör loggar in för att slutföra begäran. Administratören uppmanas att godkänna alla behörigheter som du har begärt i scope parametern . Om du använde ett statiskt ( ) värde fungerar det som v1.0-slutpunkten för administratörsmedgivande och begär medgivande för alla omfång som finns i de behörigheter som krävs .default för appen.

Lyckat svar

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

GET http://localhost/myapp/permissions?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&state=state=12345&admin_consent=True
Parameter Beskrivning
tenant Katalogklientorganisationen som beviljat programmet 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 val annat innehåll. Tillståndet används för att koda information om användarens tillstånd i appen innan autentiseringsbegäran gjordes, till exempel den sida eller vy som användaren var på.
admin_consent Anges till True .

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 Beskrivning
error En felkodssträng som kan användas för att klassificera typer av fel som inträffar. Det 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 du har fått ett lyckat svar från slutpunkten för administratörsmedgivande har appen fått de behörigheter som begärdes. Därefter kan du begära en token för den resurs som du vill använda.

Använda behörigheter

När användaren har gett sitt medgivande till behörigheter för din app kan din app hämta åtkomsttoken som representerar appens behörighet att komma åt en resurs i viss kapacitet. En åtkomsttoken kan bara användas för en enskild resurs. Men kodad i åtkomsttoken är alla behörigheter som din app har beviljats för den resursen. Om du vill hämta en åtkomsttoken kan din app 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": "6731de76-14a6-49ae-97bc-6eba6914391e",
    "scope": "https://outlook.office.com/Mail.Read https://outlook.office.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "zc53fwe80980293klaj9823"  // NOTE: Only required for web apps
}

Du kan använda den resulterande åtkomsttoken i HTTP-begäranden till resursen. Den anger på ett tillförlitligt sätt för resursen att din app 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 Microsofts identitetsplattform slutpunktsprotokollreferensen.

Standardomfånget

.defaultOmfånget används för att referera allmänt till en resurstjänst (API) i en begäran utan att identifiera specifika behörigheter. Om medgivande krävs ska du använda signaler om att medgivande ska uppmanas att ange alla nödvändiga behörigheter som anges i programregistreringen (för alla .default API:er i listan).

Omfångsparametervärdet konstrueras med hjälp av identifierar-URI:n för resursen och .default , avgränsade med ett snedstreck ( / ). Om resursens identifierar-URI till exempel är https://contoso.com är omfånget för begäran https://contoso.com/.default . Om du måste inkludera ett andra snedstreck för att begära token korrekt kan du läsa avsnittet om avslutande snedstreck.

Att använda fungerar på samma sätt som på scope={resource-identifier}/.defaultresource={resource-identifier} v1.0-slutpunkten (där är {resource-identifier} IDENTIFIERAR-URI för API:et, till exempel https://graph.microsoft.com för Microsoft Graph).

.defaultOmfånget kan användas i ett OAuth 2.0-flöde och för att initiera .default Den används krävs i flödet On-Behalf-Of ochklientautentiseringsuppgifter.

Klienter kan inte kombinera statiskt ( .default ) medgivande och dynamiskt medgivande i en enda begäran. Därför scope=https://graph.microsoft.com/.default Mail.Read resulterar det i ett fel eftersom den kombinerar omfångstyper.

.defaultOmfånget är funktionellt identiskt med beteendet för den resource -centric v1.0-slutpunkten. Den har även medgivandebeteendet för v1.0-slutpunkten. Det vill säga utlöser endast en fråga om medgivande inte har beviljats för delegerad behörighet mellan klienten och resursen, för den .default inloggade användarens räkning.

Om medgivande finns innehåller den returnerade token alla omfång som beviljats för den resursen för den inloggade användaren. Men om ingen behörighet har beviljats för den begärda resursen (eller om parametern har angetts) visas en fråga om medgivande för alla behörigheter som krävs för registrering av klientprogram för alla API:er i prompt=consent listan.

Om omfånget till exempel https://graph.microsoft.com/.default begärs begär programmet en åtkomsttoken för Microsoft Graph API. Om minst en delegerad behörighet har beviljats för Microsoft Graph för den inloggade användarens räkning fortsätter inloggningen och alla Microsoft Graph-delegerade behörigheter som har beviljats för den användaren inkluderas i åtkomsttoken. Om inga behörigheter har beviljats för den begärda resursen (Microsoft Graph, i det här exemplet), visas en fråga om medgivande för alla behörigheter som krävs för programmet för alla API:er i listan.

Exempel 1: Användaren, eller klientadministratören, har beviljats behörigheter

I det här exemplet har användaren eller en innehavaradministratör Mail.Read beviljat User.Read och Microsoft Graph behörighet till klienten.

Om klienten begär visas ingen fråga om medgivande, oavsett innehållet i klientprogrammets registrerade behörigheter scope=https://graph.microsoft.com/.default för Microsoft Graph. Den returnerade token innehåller omfången Mail.Read och User.Read .

Exempel 2: Användaren har inte beviljats behörighet mellan klienten och resursen

I det här exemplet har användaren inte beviljat medgivande mellan klienten och Microsoft Graph och har inte heller någon administratör. Klienten har registrerats för behörigheterna User.Read och Contacts.Read . Den har också registrerats för Azure Key Vault https://vault.azure.net/user_impersonation omfånget .

När klienten begär en token för ser användaren en medgivandesida för Microsoft-Graph och omfång och för scope=https://graph.microsoft.com/.defaultUser.ReadContacts.Readuser_impersonation Azure Key Vault omfånget. Den returnerade token innehåller endast User.ReadContacts.Read omfången och och kan endast användas mot Microsoft Graph.

Exempel 3: Användaren har samtyckt till och klienten begär fler omfång

I det här exemplet har användaren redan samtyckt Mail.Read till för klienten. Klienten har registrerats för Contacts.Read omfånget.

Klienten utför först en inloggning med scope=https://graph.microsoft.com/.default . Baserat på scopes parametern i svaret identifierar programmets kod att endast Mail.Read har beviljats. Klienten initierar sedan en andra inloggning med hjälp av scope=https://graph.microsoft.com/.default , och den här gången tvingar fram medgivande med hjälp av prompt=consent . Om användaren tillåts godkänna alla behörigheter som programmet har registrerat visas användarens fråga om medgivande. (Annars visas ett felmeddelande eller formuläret för begäran om administratörsmedgivande.) Både Contacts.Read och kommer att finnas i fråga om Mail.Read medgivande. Om medgivande beviljas och inloggningen fortsätter är den token som returneras för Microsoft Graph innehåller Mail.Read och Contacts.Read .

Använda .default-omfånget med klienten

I vissa fall kan en klient begära ett eget .default omfång. Följande exempel visar det här scenariot.

// 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=9ada6f8a-6d83-41bc-b169-a306c21527a5
    &scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
    &redirect_uri=https%3A%2F%2Flocalhost
    &state=1234

Det här kodexe exemplet skapar en medgivandesida för alla registrerade behörigheter om föregående beskrivningar av medgivande och .default gäller för scenariot. Koden returnerar sedan en id_token , i stället för en åtkomsttoken.

Det här beteendet kan hantera vissa äldre klienter som flyttar från Azure AD Authentication Library (ADAL) till Microsoft Authentication Library (MSAL). Den här konfigurationen ska inte användas av nya klienter som riktar sig mot Microsofts identitetsplattform.

Klientautentiseringsuppgifter beviljar flöde och .default

Ett annat sätt att använda är att begära approller (även kallade programbehörigheter) i ett icke-interaktivt program, till exempel en daemonapp som använder flödet för att bevilja klientautentiseringsuppgifter för att anropa ett .default webb-API. .default

Information om hur du definierar approller (programbehörigheter) för ett webb-API finns i Lägga till approller i ditt program.

Begäranden om klientautentiseringsuppgifter i klienttjänsten måste innehålla . Här är {resource} webb-API:et som appen har för avsikt att anropa och vill hämta en åtkomsttoken för. Att utfärda en begäran om klientautentiseringsuppgifter med hjälp av enskilda programbehörigheter (roller) stöds inte. Alla approller (programbehörigheter) som har beviljats för webb-API:et ingår i den returnerade åtkomsttoken.

Information om hur du beviljar åtkomst till de approller som du definierar, inklusive att bevilja administratörsmedgivande för programmet, finns i Konfigurera ett klientprogram för åtkomst till ett webb-API.

Avslutande snedstreck och .default

Vissa resurs-URI:er har ett avslutande snedstreck, https://contoso.com/ till exempel i stället för https://contoso.com . Det avslutande snedstrecket kan orsaka problem med tokenvalidering. Problem uppstår främst när en token begärs för Azure Resource Manager ( https://management.azure.com/ ). I det här fallet innebär ett avslutande snedstreck på resurs-URI:en att snedstrecket måste finnas när token begärs. Så när du begär en token för och använder måste du begära (observera det https://management.azure.com/ dubbla .defaulthttps://management.azure.com//.default snedstrecket!). Om du i allmänhet kontrollerar att token utfärdas, och om token avvisas av API:et som ska godkänna den, bör du överväga att lägga till ett andra snedstreck och försöka igen.

Felsökningssteg finns i Oväntat fel när du utför medgivande till ett program.

Nästa steg