Dela via

Hämta och cachelagrar token med hjälp av Microsoft Authentication Library (MSAL)

  • Artikel

Med åtkomsttoken kan klienter anropa webb-API:er som skyddas av Azure på ett säkert sätt. Det finns flera sätt att hämta en token med hjälp av Microsoft Authentication Library (MSAL). Vissa kräver användarinteraktion via en webbläsare, medan andra inte kräver användarinteraktion. Den metod som används för att hämta en token beror vanligtvis på om programmet är ett offentligt klientprogram (skrivbord eller mobilt) eller ett konfidentiellt klientprogram (webbapp, webb-API eller daemonapp).

MSAL cachelagrar en token när den har hämtats. Programkoden bör först försöka hämta en token tyst från cachen innan du försöker hämta en token på annat sätt.

Du kan också rensa tokencacheminnet genom att ta bort kontona från cacheminnet. Detta tar dock inte bort sessionscookien som finns i webbläsaren.

Omfattningar vid anskaffning av token

Omfång är de behörigheter som ett webb-API exponerar som klientprogram kan begära åtkomst till. Klientprogram begär användarens medgivande för dessa omfång när de gör autentiseringsbegäranden för att få token för att komma åt webb-API:erna. MED MSAL kan du hämta token för att komma åt Microsofts identitetsplattform API:er. V2.0-protokollet använder omfång i stället för resurser i begäranden. Baserat på webb-API:ets konfiguration av den tokenversion som accepteras returnerar v2.0-slutpunkten åtkomsttoken till MSAL.

Flera av MSAL:s metoder för tokenförvärv kräver en scopes parameter. Parametern scopes är en lista över strängar som deklarerar önskade behörigheter och begärda resurser. Välkända omfång är Microsoft Graph-behörigheter.

Begära omfång för ett webb-API

När ditt program behöver begära en åtkomsttoken med specifika behörigheter för ett resurs-API skickar du de omfång som innehåller api:ets app-ID-URI i formatet <app ID URI>/<scope>.

Några exempel på omfångsvärden för olika resurser:

  • Microsoft Graph API: https://graph.microsoft.com/User.Read
  • Anpassat webb-API: api://00001111-aaaa-2222-bbbb-3333cccc4444/api.read

Omfångsvärdets format varierar beroende på vilken resurs (API) som tar emot åtkomsttoken och de anspråksvärden som aud den accepterar.

Endast för Microsoft Graph mappar omfånget user.read till https://graph.microsoft.com/User.Read, och båda omfångsformaten kan användas omväxlande.

Vissa webb-API:er, till exempel Azure Resource Manager API (https://management.core.windows.net/) förväntar sig ett avslutande snedstreck (/) i målgruppsanspråket (aud) för åtkomsttoken. I det här fallet skickar du omfånget som https://management.core.windows.net//user_impersonation, inklusive det dubbla snedstrecket (//).

Andra API:er kan kräva att inget schema eller värd ingår i omfångsvärdet och endast förväntar sig app-ID :t (ett GUID) och omfångsnamnet, till exempel:

00001111-aaaa-2222-bbbb-3333cccc4444/api.read

Dricks

Om den underordnade resursen inte är under din kontroll kan du behöva prova olika omfångsvärdeformat (till exempel med/utan schema och värd) om du får 401 eller andra fel när du skickar åtkomsttoken till resursen.

När funktionerna som tillhandahålls av ditt program eller dess krav ändras kan du begära ytterligare behörigheter efter behov med hjälp av omfångsparametern. Med sådana dynamiska omfång kan användarna ge inkrementellt medgivande till omfång.

Du kan till exempel logga in på användaren men först neka dem åtkomst till alla resurser. Senare kan du ge dem möjlighet att visa sin kalender genom att begära kalenderomfånget i metoden hämta token och få användarens medgivande att göra det. Till exempel genom att begära omfången https://graph.microsoft.com/User.Read och https://graph.microsoft.com/Calendar.Read .

Hämta token tyst (från cacheminnet)

MSAL underhåller en tokencache (eller två cacheminnen för konfidentiella klientprogram) och cachelagrar en token efter att den har hämtats. I många fall hämtar försök att tyst hämta en token en annan token med fler omfång baserat på en token i cacheminnet. Den kan också uppdatera en token när den närmar sig förfallodatum (eftersom tokencacheminnet också innehåller en uppdateringstoken).

Programmets källkod bör först försöka hämta en token tyst från cacheminnet. Om metodanropet returnerar ett "användargränssnitt krävs"-fel eller undantag kan du prova att hämta en token på annat sätt.

Det finns två flöden där du inte bör försöka hämta en token tyst:

  • Flöde för klientautentiseringsuppgifter, som inte använder cacheminnet för användartoken utan ett cacheminne för programtoken. Den här metoden tar hand om att verifiera cacheminnet för programtoken innan du skickar en begäran till säkerhetstokentjänsten (STS).
  • Auktoriseringskodflöde i webbappar, eftersom det löser in en kod som programmet erhåller genom att logga in användaren och ge dem medgivande till fler omfång. Eftersom en kod och inte ett konto skickas som en parameter kan metoden inte titta i cacheminnet innan koden löses in, vilket anropar ett anrop till tjänsten.

För webbprogram som använder OpenID Connect-auktoriseringskodflödet är det rekommenderade mönstret i kontrollanterna att:

  • Instansiera ett konfidentiellt klientprogram med en tokencache med anpassad serialisering.
  • Hämta token med hjälp av auktoriseringskodflödet

Hämta token

Metoden för att hämta en token beror på om det är en offentlig klient eller ett konfidentiellt klientprogram.

Offentliga klientprogram

I offentliga klientprogram (skrivbord och mobil) kan du:

  • Hämta token interaktivt genom att låta användaren logga in via ett användargränssnitt eller popup-fönster.
  • Hämta en token tyst för den inloggade användaren med hjälp av integrerad Windows-autentisering (IWA/Kerberos) om skrivbordsprogrammet körs på en Windows-dator som är ansluten till en domän eller till Azure.
  • Hämta en token med ett användarnamn och lösenord i .NET Framework Desktop-klientprogram (rekommenderas inte). Använd inte användarnamn/lösenord i konfidentiella klientprogram.
  • Hämta en token via enhetskodflödet i program som körs på enheter som inte har någon webbläsare. Användaren får en URL och en kod, som sedan går till en webbläsare på en annan enhet och anger koden och loggar in. Microsoft Entra-ID skickar sedan tillbaka en token till den webbläsarlösa enheten.

Konfidentiella klientprogram

För konfidentiella klientprogram (webbapp, webb-API eller en daemonapp som en Windows-tjänst) kan du;

  • Hämta token för själva programmet och inte för en användare med hjälp av autentiseringsuppgifterna för klienten. Den här tekniken kan användas för synkronisering av verktyg eller verktyg som bearbetar användare i allmänhet och inte för en specifik användare.
  • Använd OBO-flödet (on-behalf-of) för ett webb-API för att anropa ett API åt användaren. Programmet identifieras med klientautentiseringsuppgifter för att hämta en token baserat på en användarkontroll (TILL exempel SAML eller en JWT-token). Det här flödet används av program som behöver åtkomst till resurser för en viss användare i tjänst-till-tjänst-anrop. Token ska cachelagras på sessionsbasis, inte på användarbasis.
  • Hämta token med hjälp av auktoriseringskodflödet i webbappar när användaren loggar in via URL:en för auktoriseringsbegäran. OpenID Connect-programmet använder vanligtvis den här mekanismen, vilket gör att användaren kan logga in med OpenID Connect och sedan komma åt webb-API:er för användarens räkning. Token kan cachelagras på en användare eller på sessionsbasis. Om cachelagringstoken används av användaren rekommenderar vi att du begränsar sessionslivslängden så att Microsoft Entra-ID:t kan kontrollera tillståndet för principerna för villkorsstyrd åtkomst ofta.

Autentiseringsresultat

När klienten begär en åtkomsttoken returnerar Microsoft Entra-ID också ett autentiseringsresultat som innehåller metadata om åtkomsttoken. Den här informationen omfattar förfallotiden för åtkomsttoken och de omfång som den är giltig för. Med dessa data kan din app utföra intelligent cachelagring av åtkomsttoken utan att behöva parsa själva åtkomsttoken. Autentiseringsresultatet visar:

  • Åtkomsttoken för webb-API:et för åtkomst till resurser. Den här strängen är vanligtvis en Base64-kodad JWT, men klienten bör aldrig titta inuti åtkomsttoken. Formatet är inte garanterat stabilt och kan krypteras för resursen. Personer som skriver kod beroende på åtkomsttokeninnehåll på klienten är en av de vanligaste felkällorna och klientlogikbrott.
  • ID-token för användaren (en JWT).
  • Tokens förfallodatum, som anger datum/tid när token upphör att gälla.
  • Klientorganisations-ID:t innehåller klientorganisationen där användaren hittades. För gästanvändare (Microsoft Entra B2B-scenarier) är klientorganisations-ID:t gästklientorganisationen, inte den unika klientorganisationen. När token levereras i en användares namn innehåller autentiseringsresultatet även information om den här användaren. För konfidentiella klientflöden där token begärs utan användare (för programmet) är den här användarinformationen null.
  • De omfång som token utfärdades för.
  • Det unika ID:t för användaren.

(Avancerat) Åtkomst till användarens cachelagrade token i bakgrundsappar och -tjänster

Du kan använda MSAL:s tokencacheimplementering för att tillåta att bakgrundsappar, API:er och tjänster använder cacheminnet för åtkomsttoken för att fortsätta att agera åt användare i deras frånvaro. Detta är särskilt användbart om bakgrundsappar och tjänster måste fortsätta att fungera för användarens räkning när användaren har avslutat klientwebbappen.

I dag använder de flesta bakgrundsprocesser programbehörigheter när de behöver arbeta med en användares data utan att de finns för att autentisera eller autentisera igen. Eftersom programbehörigheter ofta kräver administratörsmedgivande, vilket kräver utökade privilegier, uppstår onödig friktion eftersom utvecklaren inte hade för avsikt att få behörighet utöver det som användaren ursprungligen samtyckt till för sin app.

Det här kodexemplet på GitHub visar hur du undviker den här onödiga friktionen genom att komma åt MSAL:s tokencache från bakgrundsappar:

Komma åt den inloggade användarens tokencache från bakgrundsappar, API:er och tjänster

Se även

Flera av de plattformar som stöds av MSAL har ytterligare tokencacherelaterad information i dokumentationen för plattformens bibliotek. Till exempel: