Omfång och behörigheter i Microsofts identitetsplattform

Microsofts identitetsplattform implementerar OAuth 2.0-auktoriseringsprotokollet. OAuth 2.0 är en metod genom vilken en app från tredje part kan komma åt webbaserade resurser för en användares räkning. Alla webbaserade resurser som integreras med Microsofts identitetsplattform har en resursidentifierare eller program-ID-URI.

I den här artikeln får du lära dig mer om omfång och behörigheter på identitetsplattformen.

I följande lista visas några exempel på Microsoft webbaserade resurser:

  • Microsoft Graph:https://graph.microsoft.com
  • Microsoft 365 Mail API:https://outlook.office.com
  • Azure 密钥保管库:https://vault.azure.net

Detsamma 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 resursens funktioner 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 användare

På grund av de här typerna av behörighetsdefinitioner har resursen detaljerad 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 resurss funktioner delas upp i små behörighetsuppsättningar kan appar från tredje part skapas 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 lägsta 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å ofta 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 frågeparametern scope . Identitetsplattformen stöder flera väldefinierade OpenID Connect-omfång och resursbaserade behörigheter (varje behörighet anges genom att behörighetsvärdet läggs till i resursens identifierare eller URI för program-ID). Behörighetssträngen https://graph.microsoft.com/Calendars.Read används till exempel för att begära behörighet att läsa användarnas kalendrar i Microsoft Graph.

Om resursidentifieraren utelämnas i omfångsparametern för Microsoft identitetsplattformen i begäranden till auktoriseringsservern antas resursen vara Microsoft Graph. scope=User.Read motsvarar till exempel https://graph.microsoft.com/User.Read.

Admin begränsade behörigheter

Behörigheter i Microsofts identitetsplattform kan anges till administratörsbegränsade. Många behörigheter med högre behörighet Microsoft Graph kräver till exempel administratörsgodkännande. Om din app kräver administratörsbegränsade behörigheter måste en organisations administratör godkänna dessa omfång för organisationens användares räkning. Följande avsnitt innehåller exempel på den här typen 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 om att de inte har behörighet att godkänna appens behörigheter.

Om programmet begär programbehörigheter och en administratör beviljar dessa behörigheter görs inte det här beviljandet för någon specifik användares räkning. I stället beviljas klientprogrammet behörigheter direkt. Dessa typer av behörigheter bör endast användas av daemontjänster och andra icke-interaktiva program som körs i bakgrunden. Mer information om direktåtkomstscenariot finns i Åtkomstscenarier i Microsofts identitetsplattform.

En stegvis guide om hur du exponerar omfång i ett webb-API finns i Konfigurera ett program för att exponera ett webb-API.

OpenID Connect-omfång

Den Microsofts identitetsplattform implementeringen av OpenID Connect har några väldefinierade omfång som också finns i Microsoft Graph: openid, email, profileoch offline_access. OpenID Connect-omfången address och phone stöds inte.

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

Openid

Om en app loggar in med OpenID Connect måste den begära omfånget openid . Omfånget openid visas på arbetskontots medgivandesida som behörigheten Logga in dig .

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

e-post

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

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

profil

Omfånget profile kan användas med omfånget openid 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, önskat användarnamn och objekt-ID.

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

offline_access

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

När en användare godkänner omfånget offline_access kan appen ta emot uppdateringstoken från Microsofts identitetsplattform tokenslutpunkt. Uppdateringstoken är långlivade. Din app kan hämta 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 konfigurationen behandlar scenarier där en klient kan börja i det implicita flödet och sedan gå över till det kodflöde 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 omfånget offline_access för att ta emot uppdateringstoken. Så när du löser in en auktoriseringskod i OAuth 2.0-auktoriseringskodflödet får du bara en åtkomsttoken från /token slutpunkten.

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

Mer information om hur du hämtar och använder uppdateringstoken finns i referensen för Microsofts identitetsplattform protokoll.

.default-omfånget

Omfånget .default 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 är nödvändigt bör du använda .default signaler om att medgivande ska tillfrågas om alla nödvändiga behörigheter som anges i programregistreringen (för alla API:er i listan).

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

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

Omfånget .default kan användas i valfritt OAuth 2.0-flöde och för att initiera administratörsmedgivande. Dess användning krävs i flödet För räkning och autentiseringsuppgifter för klienten.

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

Omfångsparametern .default utlöser bara en fråga om medgivande om medgivande inte har beviljats för delegerad behörighet mellan klienten och resursen, för den 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 prompt=consent har angetts) visas en fråga om medgivande för alla nödvändiga behörigheter som konfigurerats för klientprogramregistreringen för alla API:er i listan.

Om omfånget https://graph.microsoft.com/.default till exempel begärs begär ditt program 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 medgivandeprompt för alla nödvändiga behörigheter som konfigurerats för programmet för alla API:er i listan.

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

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

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

Exempel 2: Användaren har inte beviljat behörigheter 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 密钥保管库-omfånget https://vault.azure.net/user_impersonation.

När klienten begär en token för scope=https://graph.microsoft.com/.defaultser användaren en medgivandesida för Microsoft Graph User.Read och Contacts.Read omfång samt för Azure-密钥保管库 user_impersonation omfång. Den returnerade token innehåller endast omfången User.Read och Contacts.Read och kan endast användas mot Microsoft Graph.

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

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

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

Använda .default-omfånget med klienten

I vissa fall kan en klient begära sitt eget .default omfång. I följande exempel visas det här scenariot.

Scenariot hanterar vissa äldre klienter som flyttar från Azure AD Authentication Library (ADAL) till Microsoft Authentication Library (MSAL). Den här konfigurationen bör inte användas av nya klienter som riktar in sig på Microsofts identitetsplattform.

// 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 kodexemplet skapar en sida för medgivande för alla registrerade behörigheter om föregående beskrivningar av medgivande och .default gäller för scenariot. Sedan returnerar koden en id_token, i stället för en åtkomsttoken.

Beviljandeflöde för klientautentiseringsuppgifter och .default

En annan användning av .default ä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 webb-API.

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 scope={resource}/.default. {resource} Här är det webb-API som din app avser att anropa och vill hämta en åtkomsttoken för. Det finns inte stöd för att utfärda en begäran om klientautentiseringsuppgifter med hjälp av enskilda programbehörigheter (roller). 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:n att snedstrecket måste finnas när token begärs. Så när du begär en token för https://management.azure.com/ och använder .defaultmåste du begära https://management.azure.com//.default (observera det dubbla snedstrecket!). Om du i allmänhet kontrollerar att token utfärdas och om token avvisas av API:et som ska acceptera den, bör du överväga att lägga till ett andra snedstreck och försöka igen.

Nästa steg