Referens för åtkomsttokenanspråk

  • Artikel

Åtkomsttoken är JSON-webbtoken (JWT). JWT:erna innehåller följande delar:

  • Rubrik – Innehåller information om hur du verifierar token, inklusive information om typen av token och dess signeringsmetod.
  • Payload – innehåller alla viktiga data om användaren eller programmet som försöker anropa tjänsten.
  • Signatur – används råmaterialet för att verifiera token.

Varje del avgränsas med en punkt (.) och separat base 64-kodad.

Anspråk finns bara om det finns ett värde för att fylla det. Ett program bör inte vara beroende av att ett anspråk finns. Exempel är pwd_exp (inte alla klientorganisationer kräver att lösenord upphör att gälla) och family_name (flöden för klientautentiseringsuppgifter är för program som inte har namn). Åtkomsttoken innehåller alltid tillräckliga anspråk för åtkomstutvärdering.

Microsoft platforma za identitete använder vissa anspråk för att skydda token för återanvändning. Beskrivningen av Opaque markerar dessa anspråk som inte för offentlig konsumtion. Dessa anspråk kanske eller kanske inte visas i en token, och nya kan läggas till utan förvarning.

Rubrikanspråk

Anspråk Format beskrivning
typ Sträng – alltid JWT Anger att token är en JWT.
alg String Anger den algoritm som används för att signera token, RS256till exempel .
kid String Anger tumavtrycket för den offentliga nyckel som används för att verifiera tokens signatur. Genereras i både v1.0- och v2.0-åtkomsttoken.
x5t String Fungerar på samma sätt (används och är värde) som kid. x5t och är ett äldre anspråk som endast genereras i v1.0-åtkomsttoken i kompatibilitetssyfte.

Nyttolastanspråk

Anspråk Format beskrivning Auktoriseringsöverväganden
acrs JSON-matris med strängar Anger Auth-kontext-ID:t för de åtgärder som innehavaren är berättigad att utföra. Autentiseringskontext-ID:er kan användas för att utlösa ett krav på stegvis autentisering inifrån ditt program och dina tjänster. Används ofta tillsammans med anspråket xms_cc .
aud Sträng, en program-ID-URI eller GUID Identifierar tokens avsedda målgrupp. I v2.0-token är det här värdet alltid api:ets klient-ID. I v1.0-token kan det vara klient-ID:t eller resurs-URI:n som används i begäran. Värdet kan bero på hur klienten begärde token. Det här värdet måste verifieras, avvisa token om värdet inte matchar den avsedda målgruppen.
iss Sträng, en URI för säkerhetstokentjänsten (STS) Identifierar den STS som konstruerar och returnerar token och Microsoft Entra-klientorganisationen för den autentiserade användaren. 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. Programmet kan använda GUID-delen av anspråket för att begränsa den uppsättning klienter som kan logga in på programmet, 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 såvida inte användarkontot inte finns i samma klientorganisation som utfärdaren, till exempel gäster. Använd värdet iss för om anspråket inte finns. För personliga konton som används i en organisationskontext (till exempel ett personligt konto som bjuds in till en Microsoft Entra-klientorganisation) kan anspråket idp vara "live.com" eller en STS-URI som innehåller Microsoft-kontoklientorganisationen 9188040d-6c67-4c5b-b112-36a304b66dad.
iat int, en Unix-tidsstämpel Anger när autentiseringen för den här token inträffade.
nbf int, en Unix-tidsstämpel Anger den tid efter vilken JWT kan bearbetas.
exp int, en Unix-tidsstämpel Anger förfallotiden innan JWT kan godkännas för bearbetning. En resurs kan också avvisa token före den här tiden. Avvisningen kan ske för en nödvändig ändring i autentiseringen eller när en token återkallas.
aio Ogenomskinlig sträng Ett internt anspråk som används av Microsoft Entra-ID 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, en 0 eller 1, finns endast i v1.0-token Värdet 0 för anspråket "Autentiseringskontextklass" anger att slutanvändarautentiseringen inte uppfyllde kraven i ISO/IEC 29115.
amr JSON-matris med strängar, som endast finns i v1.0-token Identifierar autentiseringsmetoden för tokens ämne.
appid Sträng, ett GUID, som endast finns 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 Microsoft Entra-ID. appid kan användas i auktoriseringsbeslut.
azp Sträng, ett GUID, som endast finns 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 Microsoft Entra-ID. azp kan användas i auktoriseringsbeslut.
appidacr Sträng, en 0, 1, eller 2, som endast finns i v1.0-token Anger klientens autentiseringsmetod. För en offentlig klient är 0värdet . När du använder klient-ID och klienthemlighet är 1värdet . När du använder ett klientcertifikat för autentisering är 2värdet .
azpacr Sträng, en 0, 1eller 2, som endast finns i v2.0-token En ersättning för appidacr. Anger klientens autentiseringsmetod. För en offentlig klient är 0värdet . När du använder klient-ID och klienthemlighet är 1värdet . När du använder ett klientcertifikat för autentisering är 2värdet .
preferred_username Sträng, som endast finns i v2.0-token. Det primära användarnamnet som representerar användaren. Värdet kan vara en e-postadress, ett telefonnummer eller ett allmänt användarnamn utan ett angivet format. Använd värdet för användarnamnstips och i användargränssnittet som användarnamn. Använd omfånget för att ta emot det här anspråket profile . Eftersom det här värdet är föränderligt ska du inte använda det för att fatta auktoriseringsbeslut.
name String Ger ett värde som kan läsas av människor och som identifierar tokens ämne. Värdet kan variera, det är föränderligt och är endast i visningssyfte. Använd omfånget för att ta emot det här anspråket profile . Använd inte det här värdet för att fatta auktoriseringsbeslut.
scp Sträng, en blankstegsavgränsad lista över omfång Den uppsättning omfång som exponeras av programmet som klientprogrammet har begärt (och tagit emot) medgivande för. Ingår endast för användartoken. Programmet bör kontrollera att dessa omfång är giltiga som exponeras av programmet och fatta auktoriseringsbeslut baserat på värdet för dessa omfång.
roles Matris med strängar, en lista med behörigheter Den uppsättning behörigheter som exponeras av programmet som det begärande programmet eller användaren har fått behörighet att anropa. Klientautentiseringsflödet använder den här uppsättningen behörigheter i stället för användaromfattningar för programtoken. För användartoken innehåller den här uppsättningen värden användarens tilldelade roller i målprogrammet. Dessa värden kan användas för att hantera åtkomst, till exempel framtvinga auktorisering för åtkomst till en resurs.
wids Matris med RoleTemplateID-GUID :er Anger de klientomfattande roller som tilldelats den här användaren, från avsnittet med roller som finns i inbyggda Microsoft Entra-roller. Egenskapen groupMembershipClaims för programmanifestet konfigurerar det här anspråket per program. Ange anspråket till All eller DirectoryRole. Dessa värden kan användas för att hantera åtkomst, till exempel framtvinga auktorisering för åtkomst till en resurs.
groups JSON-matris med GUID:er Tillhandahåller objekt-ID:t som representerar gruppmedlemskapen i ämnet. Egenskapen groupMembershipClaims för programmanifestet konfigurerar gruppanspråket per program. Värdet null exkluderar alla grupper, värdet SecurityGroup inkluderar katalogroller och Active Directory Security Group-medlemskap, och värdet All inkluderar både säkerhetsgrupper och Microsoft 365-distributionslistor. För andra flöden, om antalet grupper som användaren är i går över 150 för SAML och 200 för JWT, lägger Microsoft Entra ID till ett överförbrukningsanspråk till anspråkskällorna. Anspråkskällorna pekar på den Microsoft Graph-slutpunkt som innehåller listan med användarens grupper. Dessa värden kan användas för att hantera åtkomst, till exempel framtvinga auktorisering för åtkomst till en resurs.
hasgroups Booleskt Om det finns anger alltid true, om användaren finns i minst en grupp. Anger att klienten ska använda Microsoft Graph-API:et för att fastställa användarens grupper (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects).
groups:src1 JSON-objekt Innehåller en länk till listan med fullständiga grupper för användaren när tokenbegäranden är för stora för token. För JWTs 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 String Det huvudnamn som är associerat med token. Till exempel användaren av ett program. Det här värdet är oföränderligt, omtilldela eller återanvänd inte. Ämnet är en parvis identifierare som är unik för ett visst program-ID. Om en enskild användare loggar in i två olika program med två olika klient-ID får dessa program två olika värden för ämnesanspråket. Att använda de två olika värdena beror på arkitektur- och sekretesskrav. Se även anspråket oid , som förblir detsamma mellan program i en klientorganisation. Det här värdet kan användas för att utföra auktoriseringskontroller, till exempel när token används för att komma åt en resurs och kan användas som en nyckel i databastabeller.
oid Sträng, ett GUID Den oföränderliga identifieraren för beställaren, som är den verifierade identiteten för användaren eller tjänstens huvudnamn. Det här ID:t identifierar beställaren unikt i olika program. Två olika program som loggar in samma användare får samma värde i anspråket oid . oid Kan användas när du gör frågor till Microsoft usluge na mreži, till exempel Microsoft Graph. Microsoft Graph returnerar detta ID som id egenskap för ett visst användarkonto. oid Eftersom tillåter flera program att korrelera huvudnamn, för att ta emot det här anspråket för användare använder omfångetprofile. Om det finns en enskild användare i flera klientorganisationer innehåller användaren ett annat objekt-ID i varje klientorganisation. Även om användaren loggar in på varje konto med samma autentiseringsuppgifter är kontona olika. Det här värdet kan användas för att utföra auktoriseringskontroller, till exempel när token används för att komma åt en resurs och kan användas som en nyckel i databastabeller.
tid Sträng, ett GUID Representerar den klientorganisation som användaren loggar in på. För arbets- och skolkonton är GUID det oföränderliga klientorganisations-ID 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 . För att ta emot det här anspråket måste programmet begära omfånget profile . Det här värdet bör beaktas i kombination med andra anspråk i auktoriseringsbeslut.
unique_name Sträng som endast finns i v1.0-token Innehåller ett läsbart värde som identifierar subjektet för token. Det här värdet kan skilja sig åt inom en klientorganisation och endast använda det i visningssyfte.
uti String 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 återskapa 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.
xms_cc JSON-matris med strängar Anger om klientprogrammet som förvärvade token kan hantera anspråksutmaningar. Den används ofta tillsammans med anspråket acrs. Det här anspråket används ofta i scenarier med villkorsstyrd åtkomst och utvärdering av kontinuerlig åtkomst. Resursservern eller tjänstprogrammet som token utfärdas för styr förekomsten av det här anspråket i en token. Värdet cp1 i åtkomsttoken är det auktoritativa sättet att identifiera att ett klientprogram kan hantera en anspråksutmaning. Mer information finns i Anspråksutmaningar, anspråksbegäranden och klientfunktioner.

Kommentar

Anspråken roles, groups, scpoch wids är inte en fullständig lista över hur en resurs kan auktorisera en användare eller ett program, och de är inte heller en fullständig lista över behörigheter som beviljats anroparen. Målresursen kan använda en annan metod för att auktorisera åtkomst till dess skyddade resurser.

Överförbrukningsanspråk för grupper

Microsoft Entra-ID begränsar antalet objekt-ID:t som ingår i gruppanspråket för att hålla sig inom storleksgränsen för HTTP-huvudet. Om en användare är medlem i fler grupper än överförbrukningsgränsen (150 för SAML-token, 200 för JWT-token) genererar Inte Microsoft Entra-ID 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:et 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]"
        }   
    }
    ...
}

Använd den BulkCreateGroups.ps1 som anges i mappen Skript för appskapande för att testa överförbrukningsscenarier.

Kommentar

Url:en som returneras är en Azure AD Graph-URL (det vill graph.windows.net). I stället för att förlita sig på den här URL:en bör tjänsterna i stället använda det valfria anspråket idtyp (som identifierar om token är en app eller app+användartoken) för att skapa en Microsoft Graph-URL för att fråga den fullständiga listan över grupper.

v1.0 grundläggande anspråk

V1.0-token innehåller följande anspråk om tillämpligt, men inte v2.0-token som standard. Om du vill använda dessa anspråk för v2.0 begär programmet dem med hjälp av valfria anspråk.

Anspråk Format beskrivning
ipaddr String 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. Använd det här anspråket 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 String En URL där användarna kan återställa sitt lösenord.
in_corp boolean Signaler om klienten loggar in från företagsnätverket.
nickname String Ett annat namn för användaren, separat från för- eller efternamn.
family_name String Innehåller användarens efternamn, efternamn eller efternamn enligt definitionen i användarobjektet.
given_name String Anger användarens för- eller förnamn enligt inställningen för användarobjektet.
upn String Användarens användarnamn. Kan vara ett telefonnummer, en e-postadress eller en oformaterad sträng. Använd endast i visningssyfte och tillhandahålla användarnamnstips i omautentiseringsscenarier.

amr-anspråk

Identiteter kan autentiseras på olika sätt, vilket kan vara relevant för programmet. 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 klienthemlighet för ett program.
rsa Autentiseringen baserades på beviset på en RSA-nyckel, till exempel med Microsoft Authenticator-appen. Det här värdet anger också användningen av ett självsignerat JWT med ett tjänstägt X509-certifikat i autentisering.
otp Engångslösenord med ett e-postmeddelande eller ett sms.
fed Anger användningen av en federerad autentiseringskontroll (till exempel JWT eller SAML).
wia Windows-integrerad autentisering
mfa Anger användningen av multifaktorautentisering. Innehåller de andra autentiseringsmetoderna när det här anspråket finns.
ngcmfa mfaMotsvarar , som 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 Anger ingen slutförd autentisering.

Nästa steg