Åtkomsttoken för Microsoft identity Platform

Med åtkomsttoken kan klienter anropa skyddade webb-API:er på ett säkert sätt och används av webb-API:er för att utföra autentisering och auktorisering. Enligt OAuth-specifikationen är åtkomsttoken täckande strängar utan ett angivet format – vissa identitetsprovidrar (IDP:er) använder GUID,andra använder krypterade blobar. Microsofts identitetsplattform använder olika format för åtkomsttoken beroende på konfigurationen av API:et som accepterar token. Anpassade API:er som registrerats av utvecklare på Microsofts identitetsplattform kan välja mellan två olika format för JSON-webbtoken (JWT), som kallas "v1" och "v2", och Microsoft-utvecklade API:er som Microsoft Graph eller API:er i Azure har andra patentskyddade tokenformat. Dessa upphovsrättsskyddade format kan vara krypterade token, JWT eller särskilda JWT-liknande token som inte valideras.

Klienter måste behandla åtkomsttoken som täckande strängar eftersom innehållet i token endast är avsett för resursen (API:et). I verifierings- och felsökningssyfte kan utvecklare avkoda JWT:er med hjälp av en webbplats som jwt.ms. Tänk dock på att de token som du får för ett Microsoft API kanske inte alltid är en JWT och att du inte alltid kan avkoda dem.

För mer information om vad som finns i åtkomsttoken bör klienterna använda tokensvarsdata som returneras med åtkomsttoken till klienten. När klienten begär en åtkomsttoken returnerar Microsofts identitetsplattform även vissa metadata om åtkomsttoken för din apps användning. 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.

Se följande avsnitt för att lära dig hur ditt API kan verifiera och använda anspråken i en åtkomsttoken.

Anteckning

All dokumentation på den här sidan, förutom där detta anges, gäller endast för token som utfärdats för API:er som du har registrerat. Den gäller inte för token som utfärdats för API:er som ägs av Microsoft och dessa token kan inte heller användas för att verifiera hur Microsofts identitetsplattform kommer att utfärda token för ett API som du skapar.

Tokenformat och ägarskap

v1.0 och v2.0

Det finns två versioner av åtkomsttoken som är tillgängliga på Microsofts identitetsplattform: v1.0 och v2.0. Dessa versioner styr vilka anspråk som finns i token, vilket säkerställer att ett webb-API kan styra hur deras token ser ut. Webb-API:er har en av dessa valda som standard under registreringen – v1.0 för endast Azure AD-appar och v2.0 för appar som stöder konsumentkonton. Detta kan styras av program med hjälp accessTokenAcceptedVersion av inställningen i appmanifestet, där null och 1 resulterar i v1.0-token och 2 resulterar i v2.0-token.

Vilken app är en token "för"?

Det finns två parter som är inblandade i en begäran om åtkomsttoken: klienten, som begär token och resursen (API:et) som accepterar token när API:et anropas. Anspråket aud i en token anger den resurs som token är avsedd för (dess målgrupp). Klienter använder token men bör inte förstå eller försöka parsa den. Resurser accepterar token.

Microsofts identitetsplattform stöder utfärdande av valfri tokenversion från valfri versionsslutpunkt – de är inte relaterade. Därför innebär en resursinställning accessTokenAcceptedVersion att 2 en klient som anropar v1.0-slutpunkten för att hämta en token för det API:et får en v2.0-åtkomsttoken. Resurser äger alltid sina token (de med anspråk aud ) och är de enda program som kan ändra sin tokeninformation. Därför ändrar inte valfria anspråk för åtkomsttoken för klienten åtkomsttoken som tas emot när en token begärs för user.read, som ägs av Microsoft Graph-resursen.

Exempeltoken

v1.0- och v2.0-token ser liknande ut och innehåller många av samma anspråk. Ett exempel på var och en finns här. Dessa exempeltoken valideras dock inte eftersom nycklarna har roterats innan publiceringen och personlig information har tagits bort från dem.

V1.0

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd

Visa den här v1.0-token i JWT.ms.

v2.0

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt

Visa den här v2.0-token i JWT.ms.

Anspråk i åtkomsttoken

JWTs (JSON Web Tokens) är uppdelade i tre delar:

  • Rubrik – Innehåller information om hur du verifierar token , inklusive information om typen av token och hur den signerades.
  • Payload – innehåller alla viktiga data om den användare eller app som försöker anropa din tjänst.
  • Signatur – Används den råvara som används för att verifiera token.

Varje del avgränsas med en punkt (.) och base64-kodas separat.

Anspråk finns bara om det finns ett värde för att fylla det. Din app bör inte vara beroende av att ett anspråk finns. Exempel är pwd_exp (alla klientorganisationer kräver inte att lösenord upphör att gälla) och family_name (flöden för klientautentiseringsuppgifter är för program som inte har namn). Anspråk som används för validering av åtkomsttoken finns alltid.

Vissa anspråk används för att hjälpa Azure AD att skydda token vid återanvändning. Dessa markeras som att de inte är för offentlig förbrukning i beskrivningen som "ogenomskinliga". Dessa anspråk kanske eller kanske inte visas i en token, och nya kan läggas till utan föregående meddelande.

Rubrikanspråk

Begär Format Beskrivning
typ Sträng – alltid "JWT" Anger att token är en JWT.
alg Sträng Anger algoritmen som användes för att signera token, till exempel "RS256"
kid Sträng Anger tumavtrycket för den offentliga nyckeln som kan användas för att verifiera tokens signatur. Genereras i både v1.0- och v2.0-åtkomsttoken.
x5t Sträng Fungerar på samma sätt (används och är värde) som kid. x5t är ett äldre anspråk som endast genereras i v1.0-åtkomsttoken i kompatibilitetssyfte.

Nyttolastanspråk

Begär Format Beskrivning
aud Sträng, en app-ID-URI eller GUID Identifierar den avsedda mottagaren av token – dess målgrupp. Ditt API måste verifiera det här värdet och avvisa token om värdet inte matchar. I v2.0-token är detta alltid klient-ID för API:et, och i v1.0-token kan det vara klient-ID:t eller resurs-URI:n som används i begäran, beroende på hur klienten begärde token.
iss Sträng, en STS-URI Identifierar säkerhetstokentjänsten (STS) som konstruerar och returnerar token och den Azure AD-klientorganisation där användaren autentiserades. Om token som utfärdas är en v2.0-token (se anspråket ver ) slutar URI:n i /v2.0. DET GUID som anger att användaren är en konsumentanvändare från ett Microsoft-konto är 9188040d-6c67-4c5b-b112-36a304b66dad. Din app kan använda GUID-delen av anspråket för att begränsa den uppsättning klienter som kan logga in på appen, om tillämpligt.
idp Sträng, vanligtvis en STS-URI Registrerar den identitetsprovider som har autentiserat subjektet för token. Det här värdet är identiskt med värdet för utfärdaranspråket om inte användarkontot inte finns i samma klientorganisation som utfärdaren – gäster, till exempel. Om anspråket inte finns innebär det att värdet iss för kan användas i stället. För personliga konton som används i en organisationskontext (till exempel ett personligt konto som bjuds in till en Azure AD-klientorganisation) kan anspråket idp vara "live.com" eller en STS-URI som innehåller Microsoft-kontoklienten 9188040d-6c67-4c5b-b112-36a304b66dad.
iat int, en Unix-tidsstämpel "Utfärdat vid" anger när autentiseringen för denna token inträffade.
nbf int, en Unix-tidsstämpel Anspråket "nbf" (inte före) identifierar den tid innan JWT inte får godkännas för bearbetning.
exp int, en Unix-tidsstämpel Anspråket "exp" (förfallotid) identifierar förfallotiden på eller efter vilken JWT inte får accepteras för bearbetning. Det är viktigt att observera att en resurs också kan avvisa token före den här tiden, till exempel när en ändring i autentisering krävs eller ett tokenåterkallelse har identifierats.
aio Täckande sträng Ett internt anspråk som används av Azure AD för att registrera data för återanvändning av token. Resurser bör inte använda det här anspråket.
acr Sträng, "0" eller "1" Finns endast i v1.0-token. Anspråket "Autentiseringskontextklass". Värdet "0" anger att slutanvändarautentiseringen inte uppfyllde kraven i ISO/IEC 29115.
amr JSON-matris med strängar Finns endast i v1.0-token. Identifierar hur ämnet för token autentiserades. Mer information finns i avsnittet amr-anspråk .
appid Sträng, ett GUID Finns endast i v1.0-token. Program-ID:t för klienten med hjälp av token. Programmet kan fungera som sig självt eller för en användares räkning. Program-ID:t representerar vanligtvis ett programobjekt, men det kan också representera ett objekt för tjänstens huvudnamn i Azure AD.
azp Sträng, ett GUID Finns endast i v2.0-token, en ersättning för appid. Program-ID:t för klienten med hjälp av token. Programmet kan fungera som sig självt eller för en användares räkning. Program-ID:t representerar vanligtvis ett programobjekt, men det kan också representera ett objekt för tjänstens huvudnamn i Azure AD.
appidacr "0", "1" eller "2" Finns endast i v1.0-token. Anger hur klienten autentiserades. För en offentlig klient är värdet "0". Om klient-ID och klienthemlighet används är värdet "1". Om ett klientcertifikat användes för autentisering är värdet "2".
azpacr "0", "1" eller "2" Finns endast i v2.0-token, en ersättning för appidacr. Anger hur klienten autentiserades. För en offentlig klient är värdet "0". Om klient-ID och klienthemlighet används är värdet "1". Om ett klientcertifikat användes för autentisering är värdet "2".
preferred_username Sträng Det primära användarnamnet som representerar användaren. Det kan vara en e-postadress, ett telefonnummer eller ett allmänt användarnamn utan ett angivet format. Dess värde är föränderligt och kan ändras med tiden. Eftersom det är föränderligt får det här värdet inte användas för att fatta auktoriseringsbeslut. Den kan dock användas för användarnamnstips och i användargränssnittet som ett användarnamn. Omfånget profile krävs för att ta emot det här anspråket. Finns endast i v2.0-token.
name Sträng Ger ett läsbart värde för människor som identifierar tokens ämne. Värdet är inte garanterat unikt, det är föränderligt och är utformat för att endast användas i visningssyfte. Omfånget profile krävs för att ta emot det här anspråket.
scp Sträng, en blankstegsavgränsad lista över omfång Den uppsättning omfång som exponeras av ditt program som klientprogrammet har begärt (och tagit emot) medgivande för. Din app bör kontrollera att dessa omfång är giltiga som exponeras av din app och fatta auktoriseringsbeslut baserat på värdet för dessa omfång. Ingår endast för användartoken.
roles Matris med strängar, en lista med behörigheter Den uppsättning behörigheter som exponeras av ditt program som det begärande programmet eller användaren har fått behörighet att anropa. För programtoken används detta under flödet för klientautentiseringsuppgifter (v1.0, v2.0) i stället för användaromfång. För användartoken fylls detta i med de roller som användaren tilldelades i målprogrammet.
wids Matris med RoleTemplateID GUID Anger de innehavaromfattande roller som tilldelats den här användaren, från avsnittet med roller som finns i inbyggda Roller i Azure AD. Det här anspråket konfigureras per program via groupMembershipClaims egenskapen för programmanifestet. Du måste ange "Alla" eller "DirectoryRole". Kanske inte finns i token som hämtas via det implicita flödet på grund av problem med tokenlängd.
groups JSON-matris med GUID:ar Innehåller objekt-ID:t som representerar ämnets gruppmedlemskap. Dessa värden är unika (se Objekt-ID) och kan användas på ett säkert sätt för att hantera åtkomst, till exempel framtvinga auktorisering för åtkomst till en resurs. De grupper som ingår i gruppanspråket konfigureras per program, via groupMembershipClaims egenskapen för programmanifestet. Värdet null exkluderar alla grupper. Värdet "SecurityGroup" innehåller endast Medlemskap i Active Directory-säkerhetsgrupper och värdet "Alla" innehåller både säkerhetsgrupper och Microsoft 365-distributionslistor.

Mer information om hur du använder anspråket groups med implicit beviljande finns i anspråket hasgroups nedan.
För andra flöden, om antalet grupper som användaren är i överskrider en gräns (150 för SAML, 200 för JWT), läggs ett överförbrukningsanspråk till i anspråkskällorna som pekar på Microsoft Graph-slutpunkten som innehåller listan över grupper för användaren.
hasgroups Boolesk Om det finns finns alltid true, anges användaren i minst en grupp. Används i stället för anspråket groups för JWT i implicita beviljandeflöden om hela gruppanspråket skulle utöka URI-fragmentet utöver URL-längdgränserna (för närvarande sex eller flera grupper). Anger att klienten ska använda Microsoft Graph API för att fastställa användarens grupper (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects).
groups:src1 JSON-objekt För tokenbegäranden som inte är längdbegränsade (se hasgroups ovan) men fortfarande är för stora för token inkluderas en länk till listan över fullständiga grupper för användaren. För JWT som ett distribuerat anspråk, för SAML som ett nytt anspråk i stället för anspråket groups .

Exempel på JWT-värde:
"groups":"src1"
"_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }
sub Sträng Det huvudnamn som token anger information om, till exempel användaren av en app. Det här värdet är oföränderligt och kan inte omtilldelas eller återanvändas. Den kan användas för att utföra auktoriseringskontroller på ett säkert sätt, till exempel när token används för att komma åt en resurs och kan användas som en nyckel i databastabeller. Eftersom ämnet alltid finns i de token som Azure AD utfärdar rekommenderar vi att du använder det här värdet i ett auktoriseringssystem för generell användning. Ämnet är dock en parvis identifierare – det är unikt för ett visst program-ID. Om en enskild användare loggar in på två olika appar med två olika klient-ID:er får dessa appar därför två olika värden för ämnesanspråket. Detta kan vara önskvärt eller inte beroende på din arkitektur och sekretesskrav. Se även anspråket oid (som förblir detsamma för appar i en klientorganisation).
oid Sträng, ett GUID Den oföränderliga identifieraren för begärans "huvudnamn" – användaren eller tjänstens huvudnamn vars identitet har verifierats. I ID-token och app+användartoken är detta användarens objekt-ID. I endast apptoken är detta objekt-ID för anropande tjänstens huvudnamn. Den kan också användas för att utföra auktoriseringskontroller på ett säkert sätt och som en nyckel i databastabeller. Det här ID:t identifierar unikt huvudnamnet för program – två olika program som loggar in samma användare får samma värde i anspråket oid . oid Därför kan användas när du gör frågor till Microsofts onlinetjänster, till exempel Microsoft Graph. Microsoft Graph returnerar detta ID som id egenskap för ett visst användarkonto. oid Eftersom tillåter flera appar att korrelera huvudkonton krävs omfånget profile för att ta emot det här anspråket för användare. Om en enskild användare finns i flera klientorganisationer innehåller användaren ett annat objekt-ID i varje klientorganisation – de betraktas som olika konton, även om användaren loggar in på varje konto med samma autentiseringsuppgifter.
tid Sträng, ett GUID Representerar den klientorganisation som användaren loggar in på. För arbets- och skolkonton är GUID:t det oföränderliga klient-ID:t för organisationen som användaren loggar in på. För inloggningar till den personliga Microsoft-kontoklientorganisationen (tjänster som Xbox, Teams for Life eller Outlook) är 9188040d-6c67-4c5b-b112-36a304b66dadvärdet . Om du vill ta emot det här anspråket måste din app begära omfånget profile .
unique_name Sträng Finns endast i v1.0-token. Innehåller ett läsbart värde som identifierar subjektet för token. Det här värdet är inte garanterat unikt i en klientorganisation och bör endast användas i visningssyfte.
uti Sträng Tokenidentifieraranspråk, motsvarande jti I JWT-specifikationen. Unik identifierare per token som är skiftlägeskänslig.
rh Ogenomskinlig sträng Ett internt anspråk som används av Azure för att återanvända token. Resurser bör inte använda det här anspråket.
ver Sträng, antingen 1.0 eller 2.0 Anger versionen av åtkomsttoken.

Överförbrukningsanspråk för grupper

För att säkerställa att tokenstorleken inte överskrider storleksgränserna för HTTP-sidhuvud begränsar Azure AD antalet objekt-ID:t som den innehåller i gruppanspråket. Om en användare är medlem i fler grupper än överförbrukningsgränsen (150 för SAML-token, 200 för JWT-token och endast 6 om den utfärdas via det implicita flödet) genererar Inte Azure AD gruppanspråket i token. I stället innehåller den ett överförbrukningsanspråk i token som anger för programmet att fråga Microsoft Graph API för att hämta användarens gruppmedlemskap.

{
    ...
    "_claim_names": {
        "groups": "src1"
    },
    "_claim_sources": {
        "src1": {
            "endpoint": "[Url to get this user's group membership from]"
        }   
    }
    ...
}

Du kan använda den BulkCreateGroups.ps1 angivna i mappen Skript för appskapande för att testa överförbrukningsscenarier.

v1.0 grundläggande anspråk

Följande anspråk inkluderas i v1.0-token om det är tillämpligt, men ingår inte i v2.0-token som standard. Om du använder v2.0 och behöver något av dessa anspråk kan du begära dem med hjälp av valfria anspråk.

Begär Format Beskrivning
ipaddr Sträng IP-adressen som användaren autentiserades från.
onprem_sid Sträng i SID-format I de fall där användaren har en lokal autentisering tillhandahåller det här anspråket sitt SID. Du kan använda onprem_sid för auktorisering i äldre program.
pwd_exp int, en Unix-tidsstämpel Anger när användarens lösenord upphör att gälla.
pwd_url Sträng En URL där användare kan skickas för att återställa sitt lösenord.
in_corp boolean Signalerar om klienten loggar in från företagsnätverket. Om de inte är det ingår inte anspråket.
nickname Sträng Ytterligare ett namn för användaren, separat från för- eller efternamn.
family_name Sträng Anger efternamnet, efternamnet eller familjenamnet för användaren enligt definitionen i användarobjektet.
given_name Sträng Anger användarens för- eller förnamn, enligt inställningen för användarobjektet.
upn Sträng Användarens användarnamn. Kan vara ett telefonnummer, en e-postadress eller en oformaterad sträng. Bör endast användas i visningssyfte och tillhandahålla användarnamnstips i omautentiseringsscenarier.

Anspråket amr

Microsoft-identiteter kan autentiseras på olika sätt, vilket kan vara relevant för ditt program. Anspråket amr är en matris som kan innehålla flera objekt, till exempel ["mfa", "rsa", "pwd"], för en autentisering som använde både ett lösenord och Authenticator-appen.

Värde Beskrivning
pwd Lösenordsautentisering, antingen en användares Microsoft-lösenord eller en apps klienthemlighet.
rsa Autentiseringen baserades på beviset på en RSA-nyckel, till exempel med Microsoft Authenticator-appen. Detta inkluderar om autentisering utfördes av ett självsignerat JWT med ett tjänstägt X509-certifikat.
otp Engångslösenord med ett e-postmeddelande eller ett sms.
fed En federerad autentiseringskontroll (till exempel JWT eller SAML) användes.
wia Windows-integrerad autentisering
mfa Multifaktorautentisering användes. När detta finns kommer även de andra autentiseringsmetoderna att inkluderas.
ngcmfa mfaMotsvarar , används för etablering av vissa avancerade typer av autentiseringsuppgifter.
wiaormfa Användaren använde Windows eller en MFA-autentiseringsuppgift för att autentisera.
none Ingen autentisering har utförts.

Livslängd för åtkomsttoken

Standardlivslängden för en åtkomsttoken är variabel. När den utfärdas tilldelas en åtkomsttokens standardlivstid ett slumpmässigt värde mellan 60–90 minuter (i genomsnitt 75 minuter). Variationen förbättrar tjänstens motståndskraft genom att sprida efterfrågan på åtkomsttoken under en period av 60 till 90 minuter, vilket förhindrar timtoppar i trafiken till Azure AD.

Klienter som inte använder villkorsstyrd åtkomst har en standardtid på 2 timmar för klienter som Microsoft Teams och Microsoft 365.

Du kan justera livslängden för en åtkomsttoken för att styra hur ofta klientprogrammet förfaller programsessionen och hur ofta det kräver att användaren autentiserar igen (antingen tyst eller interaktivt). Kunder som vill åsidosätta standardvarianten för åtkomsttokens livslängd kan ange en livslängd för statisk standardåtkomsttoken med hjälp av konfigurerbar tokenlivslängd (CTL).

Standardvarianten för tokenlivslängd tillämpas på organisationer som har kontinuerlig åtkomstutvärdering (CAE) aktiverat, även om CTL-principer har konfigurerats. Standardtokens livslängd för livslängden för token med lång livslängd varierar från 20 till 28 timmar. När åtkomsttoken upphör att gälla måste klienten använda uppdateringstoken för att (vanligtvis tyst) hämta en ny uppdateringstoken och åtkomsttoken.

Organisationer som använder inloggningsfrekvens för villkorsstyrd åtkomst (SIF) för att framtvinga hur ofta inloggningar sker kan inte åsidosätta standardvarianten för åtkomsttokens livslängd. När du använder SIF är tiden mellan autentiseringsmeddelanden för en klient tokenlivslängden (mellan 60 och 90 minuter) plus inloggningsfrekvensintervallet.

Här är ett exempel på hur standardvarianten för tokenlivslängd fungerar med inloggningsfrekvens. Anta att en organisation ställer in inloggningsfrekvensen varje timme. Det faktiska inloggningsintervallet sker någonstans mellan 1 timme och 2,5 timmar eftersom token utfärdas med en livslängd på mellan 60 och 90 minuter (på grund av tokens livslängdsvariant).

Om en användare med en token med en timmes livslängd utför en interaktiv inloggning på 59 minuter (precis innan inloggningsfrekvensen överskrids) finns det ingen uppmaning om autentiseringsuppgifter eftersom inloggningen ligger under tröskelvärdet för SIF. Om en ny token utfärdas med en livslängd på 90 minuter ser användaren ingen uppmaning om autentiseringsuppgifter på ytterligare en och en halv timme. När ett tyst förnyelseförsök görs för den 90 minuter långa tokenlivslängden kräver Azure AD en uppmaning om autentiseringsuppgifter eftersom den totala sessionslängden har överskridit inställningen för inloggningsfrekvens på 1 timme. I det här exemplet är tidsskillnaden mellan frågor om autentiseringsuppgifter på grund av SIF-intervallet och tokenlivsvarianten 2,5 timmar.

Verifiera token

Alla appar bör inte verifiera token. Endast i specifika scenarier bör appar verifiera en token:

  • Webb-API:er måste verifiera åtkomsttoken som skickas till dem av en klient. De får bara acceptera token som innehåller deras aud anspråk.
  • Konfidentiella webbappar som ASP.NET Core måste verifiera ID-token som skickas till dem via användarens webbläsare i hybridflödet, innan du tillåter åtkomst till en användares data eller upprättar en session.

Om inget av ovanstående scenarier gäller kommer ditt program inte att ha nytta av att verifiera token och kan utgöra en säkerhets- och tillförlitlighetsrisk om beslut fattas baserat på tokens giltighet. Offentliga klienter som interna appar eller SPA:er drar inte nytta av validering av token – appen kommunicerar direkt med IDP, så SSL-skydd säkerställer att token är giltiga.

API:er och webbappar får bara verifiera token som har ett aud anspråk som matchar deras program. Andra resurser kan ha anpassade tokenverifieringsregler. Token för Microsoft Graph valideras till exempel inte enligt dessa regler på grund av deras egenutvecklade format. Validering och godkännande av token som är avsedda för en annan resurs är ett exempel på det förvirrade biträdande problemet.

Om ditt program behöver verifiera en id_token eller en access_token enligt ovanstående bör appen först verifiera tokens signatur och utfärdare mot värdena i OpenID-identifieringsdokumentet. Till exempel finns den klientoberoende versionen av dokumentet på https://login.microsoftonline.com/common/.well-known/openid-configuration.

Följande information tillhandahålls för dem som vill förstå den underliggande processen. Azure AD-mellanprogrammet har inbyggda funktioner för validering av åtkomsttoken, och du kan bläddra igenom våra exempel för att hitta ett på det språk du väljer. Det finns också flera bibliotek med öppen källkod från tredje part som är tillgängliga för JWT-validering – det finns minst ett alternativ för nästan alla plattformar och språk. Mer information om Azure AD-autentiseringsbibliotek och kodexempel finns i autentiseringsbiblioteken.

Verifiera signaturen

En JWT innehåller tre segment som avgränsas med . tecknet. Det första segmentet kallas för rubriken, det andra som brödtexten och det tredje som signaturen. Signatursegmentet kan användas för att verifiera tokens äkthet så att den kan lita på din app.

Token som utfärdas av Azure AD signeras med hjälp av asymmetriska krypteringsalgoritmer av branschstandard, till exempel RS256. Rubriken för JWT innehåller information om nyckeln och krypteringsmetoden som används för att signera token:

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk",
  "kid": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk"
}

Anspråket alg anger den algoritm som användes för att signera token, medan anspråket kid anger den offentliga nyckel som användes för att verifiera token.

Vid en viss tidpunkt kan Azure AD signera en id_token med någon av en viss uppsättning offentlig-privata nyckelpar. Azure AD roterar en möjlig uppsättning nycklar regelbundet, så din app bör skrivas för att hantera dessa nyckeländringar automatiskt. En rimlig frekvens för att söka efter uppdateringar av de offentliga nycklar som används av Azure AD är var 24:e timme.

Du kan hämta de signeringsnyckeldata som krävs för att verifiera signaturen med hjälp av openID Connect-metadatadokumentet som finns på:

https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

Tips

Prova den här URL: en i en webbläsare!

Det här metadatadokumentet:

  • Är ett JSON-objekt som innehåller flera användbara informationsdelar, till exempel platsen för de olika slutpunkter som krävs för att utföra OpenID Connect-autentisering.
  • Innehåller en jwks_uri, som ger platsen för den uppsättning offentliga nycklar som motsvarar de privata nycklar som används för att signera token. JSON-webbnyckeln (JWK) som finns i jwks_uri innehåller all offentlig nyckelinformation som används just då. JWK-formatet beskrivs i RFC 7517. Din app kan använda anspråket kid i JWT-huvudet för att välja den offentliga nyckeln från det här dokumentet, vilket motsvarar den privata nyckel som har använts för att signera en viss token. Den kan sedan utföra signaturvalidering med rätt offentlig nyckel och den angivna algoritmen.

Anteckning

Vi rekommenderar att du använder anspråket kid för att verifiera din token. Även om v1.0-token innehåller både anspråken x5t och kid innehåller v2.0-token endast anspråket kid .

Att utföra signaturvalidering ligger utanför omfånget för det här dokumentet – det finns många bibliotek med öppen källkod som hjälper dig att göra det om det behövs. Microsofts identitetsplattform har dock ett tokensigneringstillägg till standarderna – anpassade signeringsnycklar.

Om din app har anpassade signeringsnycklar till följd av att du använder funktionen för anspråksmappning måste du lägga till en appid frågeparameter som innehåller app-ID:t för att få en jwks_uri pekar på din apps signeringsnyckelinformation, som ska användas för validering. Till exempel: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e innehåller en jwks_uri av https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

Anspråksbaserad auktorisering

Programmets affärslogik avgör det här steget, några vanliga auktoriseringsmetoder beskrivs nedan.

Verifiera att token är avsedd för dig

  • Använd anspråket aud för att se till att användaren har för avsikt att anropa ditt program. Om resursens identifierare inte finns i anspråket aud avvisar du det.

Verifiera att användaren har behörighet att komma åt dessa data

  • Använd anspråken roles och wids för att verifiera att användaren själva har behörighet att anropa ditt API. En administratör kan till exempel ha behörighet att skriva till ditt API, men inte en normal användare.
  • Kontrollera att tid inuti token matchar klientorganisations-ID:t som används för att lagra data i ditt API.
    • När en användare lagrar data i ditt API från en klientorganisation måste de logga in på klientorganisationen igen för att få åtkomst till dessa data. Tillåt aldrig att data i en klientorganisation nås från en annan klientorganisation.
  • Använd anspråket amr för att kontrollera att användaren har utfört MFA. Detta bör framtvingas med villkorlig åtkomst.
  • Om du har begärt anspråken roles eller groups i åtkomsttoken kontrollerar du att användaren är i den grupp som tillåts utföra den här åtgärden.
    • För token som hämtas med det implicita flödet måste du förmodligen fråga Microsoft Graph efter dessa data, eftersom det ofta är för stort för att få plats i token.

Använd email aldrig eller upn anspråksvärden för att avgöra om användaren i en åtkomsttoken ska ha åtkomst till data! Föränderliga anspråksvärden som dessa kan ändras med tiden, vilket gör dem osäkra och otillförlitliga för auktorisering.

Använd oföränderliga anspråksvärden tid och sub eller oid som en kombinerad nyckel för att lagra för att unikt identifiera api:ets data och avgöra om en användare ska beviljas åtkomst till dessa data.

  • Bra: tid + sub
  • Bättre: tid + oidoid är konsekvent mellan program, så ett ekosystem med appar kan till exempel granska användaråtkomst till data.

Använd inte föränderliga, läsbara identifierare som email eller upn för unikt identifierande data.

  • Dålig: email
  • Dålig: upn

Kontrollera att programmet som loggade in användaren har behörighet att komma åt dessa data

  • Använd anspråket scp för att verifiera att användaren har beviljat den anropande appen behörighet att anropa ditt API.
  • Se till att den anropande klienten får anropa ditt API med hjälp av anspråket appid .

Användar- och programtoken

Ditt program kan ta emot token för användaren (flödet diskuteras vanligtvis) eller direkt från ett program (via flödet för klientautentiseringsuppgifter). Dessa apptoken anger att det här anropet kommer från ett program och inte har någon användare som stöder det. Dessa token hanteras i stort sett på samma sätt:

  • Använd roles för att se behörigheter som har beviljats till ämnet för token.
  • Använd oid eller sub för att verifiera att det anropande tjänstens huvudnamn är det förväntade.

Om din app behöver skilja mellan åtkomsttoken endast för appar och åtkomsttoken för användare använder du det valfria anspråketidtyp. Genom att lägga till anspråket idtyp i accessToken fältet och söka efter värdet appkan du identifiera åtkomsttoken för endast appar. ID-token och åtkomsttoken för användare kommer inte att inkludera anspråket idtyp .

Återkallning av token

Uppdateringstoken kan när som helst ogiltigförklaras eller återkallas av olika skäl. Dessa delas in i två huvudkategorier: timeouter och återkallanden.

Tidsgränser för token

Med hjälp av konfiguration av tokenlivslängd kan livslängden för uppdateringstoken ändras. Det är normalt och förväntas att vissa token går utan användning (t.ex. att användaren inte öppnar appen på tre månader) och därför går ut. Appar stöter på scenarier där inloggningsservern avvisar en uppdateringstoken på grund av dess ålder.

  • MaxInactiveTime: Om uppdateringstoken inte har använts inom den tid som bestäms av MaxInactiveTime är uppdateringstoken inte längre giltig.
  • MaxSessionAge: Om MaxAgeSessionMultiFactor eller MaxAgeSessionSingleFactor har ställts in på något annat än standardvärdet (tills det har återkallats) krävs omautentisering efter den tid som angetts i MaxAgeSession* förflutit.
  • Exempel:
    • Klientorganisationen har en MaxInactiveTime på fem dagar och användaren åkte på semester i en vecka, så Azure AD har inte sett en ny tokenbegäran från användaren på 7 dagar. Nästa gång användaren begär en ny token upptäcker de att deras uppdateringstoken har återkallats och de måste ange sina autentiseringsuppgifter igen.
    • Ett känsligt program har en MaxAgeSessionSingleFactor på en dag. Om en användare loggar in på måndag och på tisdag (efter att 25 timmar har gått) måste de autentiseras igen.

Återkallande

Uppdateringstoken kan återkallas av servern på grund av en ändring av autentiseringsuppgifterna eller på grund av användning eller administratörsåtgärd. Uppdateringstoken delas in i två klasser – de som utfärdas till konfidentiella klienter (kolumnen längst till höger) och de som utfärdas till offentliga klienter (alla andra kolumner).

Ändra Lösenordsbaserad cookie Lösenordsbaserad token Icke-lösenordsbaserad cookie Icke-lösenordsbaserad token Konfidentiell klienttoken
Lösenordet upphör att gälla Håller sig vid liv Håller sig vid liv Håller sig vid liv Håller sig vid liv Håller sig vid liv
Lösenordet har ändrats av användaren Revoked Revoked Håller sig vid liv Håller sig vid liv Håller sig vid liv
Användaren utför SSPR Revoked Revoked Håller sig vid liv Håller sig vid liv Håller sig vid liv
Administratören återställer lösenord Revoked Revoked Håller sig vid liv Håller sig vid liv Håller sig vid liv
Användaren återkallar sina uppdateringstoken via PowerShell Revoked Revoked Revoked Revoked Revoked
Administratören återkallar alla uppdateringstoken för en användare via PowerShell Revoked Revoked Revoked Revoked Revoked
Enkel utloggning (v1.0, v2.0 ) på webben Revoked Håller sig vid liv Revoked Håller sig vid liv Håller sig vid liv

Icke-lösenordsbaserad

En icke-lösenordsbaserad inloggning är en inloggning där användaren inte angav något lösenord för att hämta det. Exempel på icke-lösenordsbaserad inloggning är:

  • Använda ditt ansikte med Windows Hello
  • FIDO2-nyckel
  • SMS
  • Röst
  • PIN-KOD

Mer information om primära uppdateringstoken finns i Primära uppdateringstoken .

Nästa steg