Dela via

Omfång och behörigheter i Microsofts identitetsplattform

The Microsoft identity platform implements the OAuth 2.0 authorization protocol. 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 i identitetsplattformen.

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

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

Detsamma gäller för alla resurser från tredje part som integreras med Microsofts identitetsplattform. Någon av dessa resurser kan också definiera en uppsättning behörigheter som delar upp funktionen för resursen i mindre segment. As an example, Microsoft Graph defines permissions to do the following tasks, among others:

  • 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.

In OAuth 2.0, these types of permission sets are called scopes. They're also often referred to as permissions. 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.

Admin-restricted permissions

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

Note

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. Instead, the client application is granted permissions directly. 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-implementering av OpenID Connect har några väldefinierade omfång som också finns i Microsoft Graph: openid, email, profile och offline_access. Omfången address och phone OpenID Connect stöds inte. Dessa omfång kan vara valfria och kan övervägas för berikning av ID-token. Dessa omfång visas inte alltid i separata rader i en medgivandeprompt till en användare.

If you request the OpenID Connect scopes and a token, you get a token to call the UserInfo endpoint.

Omfånget openid

If an app signs in by using OpenID Connect, it must request the openid scope. Omfånget openid visas på medgivandesidan för arbetskontot som behörigheten Logga in.

En app använder den här behörigheten för att ta emot en unik identifierare för användaren i form av sub-anspråket. 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 alla andra omfång. Det ger appen åtkomst till användarens primära e-postadress i form av påståendet 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 typer av 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 behörigheten Underhåll åtkomst till data som du har gett den åtkomst till.

Om någon delegerad behörighet beviljas, ges offline_access implicit. Du kan anta att programmet har offline_access om det finns delegerade behörigheter. Uppdateringstoken är långvariga. Din app kan hämta nya åtkomsttoken när äldre går ut.

Note

This permission currently appears on all consent pages, even for flows that don't provide a refresh token (such as the implicit flow). 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ödefår du en åtkomsttoken från /token slutpunkten.

Åtkomsttoken är 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 i 90 dagar. För ytterligare information om hur du hämtar och använder uppfräschnings-token, se 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:

  • Scope requirements: Ensure that you're requesting the offline_access scopes along with any other necessary scopes.
  • Beviljandetyp av auktorisering: En uppdateringstoken tillhandahålls när du använder beviljandetypen för auktoriseringskod. Om flödet skiljer sig åt kan svaret påverkas.
  • Client configuration: Check your application's settings in the identity platform. 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 samtycke är nödvändigt, bör du använda .default för att signalera att ett samtycke ska begäras för alla nödvändiga behörigheter som anges i applikationsregistreringen (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 identifier-URI till exempel är https://contoso.com, är omfånget för begäran https://contoso.com/.default. Om du behöver lägga till ett andra snedstreck för att begära token på rätt sätt 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).

The .default scope can be used in any OAuth 2.0 flow and to initiate admin consent. Its use is required in the On-Behalf-Of flow and client credentials flow.

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.

Parametern .default-omfång utlöser endast en medgivandeprompt 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 det finns medgivande 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 medgivandeprompt 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. 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 hyresgästadministratör beviljat Microsoft Graph-behörigheterna till klienten Mail.Read och User.Read.

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 registrerades för behörigheterna User.Read och Contacts.Read och registrerades 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. Kunden har registrerat sig för Contacts.Read-omfånget.

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 medgivandeprompten. (Om inte, visas ett felmeddelande eller formuläret för begäran om administratörsmedgivande .) Både Contacts.Read och Mail.Read finns i samtyckesprompten. Om medgivande beviljas och inloggningen fortsätter är den token som returneras för Microsoft Graph och innehåller Mail.Read och Contacts.Read.

Att använda .default-omfånget 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.

Nya klienter som riktar sig till Microsofts identitetsplattform bör inte använda den här konfigurationen. Se till att du migrerar till Microsoft Authentication Library (MSAL) från Azure AD Authentication Library (ADAL).

Flöde för klientautentiseringsuppgifter och .default

Another use of .default is to request app roles (also known as application permissions) in a non-interactive application like a daemon app that uses the client credentials grant flow to call a web API.

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

Client credentials requests in your client service must include scope={resource}/.default. {resource} Här är webb-API:et som appen tänker anropa och vill hämta en åtkomsttoken för. Issuing a client credentials request by using individual application permissions (roles) is not supported. 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!).

Generellt, om du säkerställer att token utfärdas och om token avvisas av API:et som borde acceptera den, överväg att lägga till ett extra snedstreck och försök igen.

See also