Omfång och behörigheter i Microsofts identitetsplattform

  • Artikel

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å Microsofts webbaserade resurser:

  • Microsoft Graph: https://graph.microsoft.com
  • Microsoft 365 Mail API: https://outlook.office.com
  • Azure Key Vault: 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. Microsoft Graph har till exempel 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 dessa typer av behörighetsdefinitioner har resursen detaljerad kontroll över sina data och hur API-funktioner exponeras. En app från tredje part 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 in 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 minsta behörighet och bara 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 program-ID URI). Till exempel används behörighetssträngen https://graph.microsoft.com/Calendars.Read för att begära behörighet att läsa användarnas kalendrar i Microsoft Graph.

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

Administratörsbegränsade behörigheter

Behörigheter i Microsofts identitetsplattform kan anges till administratörsbegränsade. Många Microsoft Graph-behörigheter med högre behörighet 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:

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

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. 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 scenariot för direktåtkomst 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. Omfången address och phone OpenID Connect stöds inte.

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

Omfånget 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.

Omfånget email

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

Anspråket email ingår endast 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.

Omfånget profile

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. Informationen som den kan komma åt omfattar, men inte begränsat till, användarens förnamn, efternamn, föredragna användarnamn och objekt-ID.

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

Omfånget offline_access

Omfånget offline_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 Underhåll å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 tokenslutpunkten. Uppdateringstoken är långlivade. Din app kan hämta nya åtkomsttoken när äldre går ut.

Kommentar

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 kodflödet där en uppdateringstoken förväntas.

På Microsofts identitetsplattform (begäranden som görs till v2.0-slutpunkten) måste appen 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 vanligtvis giltig i ungefär en timme. Då måste appen omdirigera användaren tillbaka till /authorize slutpunkten för att begära en ny auktoriseringskod. Under den här omdirigeringen och beroende på apptyp kan användaren behöva ange sina autentiseringsuppgifter igen eller samtycka till behörigheter igen.

Uppdateringstoken har ett längre utgångsdatum än åtkomsttoken och är vanligtvis giltig för en dag. Mer information om hur du hämtar och använder uppdateringstoken finns i referensen för Microsofts identitetsplattform protokoll.

Inkluderingen av uppdateringstoken i svaret kan bero på flera faktorer, inklusive den specifika konfigurationen av ditt program och de omfång som begärdes under auktoriseringsprocessen. Tänk på följande faktorer om du förväntar dig att få en uppdateringstoken i svaret men inte gör det:

  • Omfångskrav: Se till att du begär omfången offline_access tillsammans med andra nödvändiga omfång.
  • Typ av auktoriseringsbidrag: Uppdateringstoken tillhandahålls vanligtvis när du använder auktoriseringskodens beviljandetyp. Om flödet skiljer sig åt kan det påverka svaret.
  • Klientkonfiguration: Kontrollera programmets inställningar på identitetsplattformen. Vissa konfigurationer kan begränsa utfärdandet av refresh_tokens.

Omfånget .default

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 bör uppmanas att ange 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 identifierarens 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 endast en medgivandefråga om medgivande inte har beviljats för någon 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 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 uppmaning om medgivande för alla nödvändiga behörigheter som konfigurerats för registrering av klientprogram 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:et. 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 klienten och User.Read Microsoft Graph-behörigheterna.

Om klienten begär scope=https://graph.microsoft.com/.defaultvisas ingen medgivandeprompt, 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 registrerat sig för behörigheterna User.Read och Contacts.Read. Det har också registrerats för Azure Key Vault-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 och för Azure Key Vault-omfånget user_impersonation . 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 omfånget .default med klienten

I vissa fall kan en klient begära ett eget .default omfång. I följande exempel visas 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=00001111-aaaa-2222-bbbb-3333cccc4444
    &scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
    &redirect_uri=https%3A%2F%2Flocalhost
    &state=1234

Det här kodexemplet skapar en medgivandesida 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.

Den här konfigurationen ska inte användas av nya klienter som riktar in sig på Microsofts identitetsplattform. Se till att migrera till Microsoft Authentication Library (MSAL) från Azure AD Authentication Library (ADAL).

Bevilja flö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 som en daemonapp som använder flödet för beviljande av 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 webb-API:et som appen tänker anropa och vill hämta en åtkomsttoken för. Det går inte 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 tokenverifiering. 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 kan du överväga att lägga till ett andra snedstreck och försöka igen.

Se även