Valfri anspråksreferens

  • Artikel

Du kan använda valfria anspråk för att:

  • Välj anspråk som ska inkluderas i token för ditt program.
  • Ändra beteendet för vissa anspråk som Microsofts identitetsplattform returnerar i token.
  • Lägga till och få åtkomst till anpassade anspråk för ditt program.

Även om valfria anspråk stöds i både v1.0- och v2.0-formattoken och SAML-token, anger de det mesta av värdet när de flyttas från v1.0 till v2.0. I Microsofts identitetsplattform används mindre tokenstorlekar för att säkerställa optimal prestanda för klienter. Därför finns flera anspråk som tidigare ingick i åtkomst- och ID-token inte längre i v2.0-token och måste efterfrågas specifikt per program.

Kontotyp v1.0-token v2.0-token
Personligt Microsoft-konto Ej tillämpligt Stöds
Microsoft Entra-konto Stöds Stöds

v1.0 och v2.0 valfria anspråksuppsättning

Den uppsättning valfria anspråk som är tillgängliga som standard för program som ska användas visas i följande tabell. Du kan använda anpassade data i tilläggsattribut och katalogtillägg för att lägga till valfria anspråk för ditt program. När du lägger till anspråk i åtkomsttoken gäller anspråken för åtkomsttoken som begärts för programmet (ett webb-API), inte anspråk som begärts av programmet. Oavsett hur klienten kommer åt ditt API finns rätt data i åtkomsttoken som används för att autentisera mot ditt API.

Kommentar

Majoriteten av dessa anspråk kan inkluderas i JWT för v1.0- och v2.0-token, men inte SAML-token, förutom där anges i kolumnen Tokentyp. Konsumentkonton stöder en delmängd av dessa anspråk, markerade i kolumnen Användartyp. Många av de angivna anspråken gäller inte för konsumentanvändare (de har ingen klientorganisation, så tenant_ctry de har inget värde).

I följande tabell visas den valfria anspråksuppsättningen v1.0 och v2.0.

Name beskrivning Tokentyp Användartyp Kommentar
acct Kontostatus för användare i klientorganisationen JWT, SAML Om användaren är medlem i klientorganisationen är 0värdet . Om de är en gäst är 1värdet .
acrs Autentiseringskontext-ID:t JWT Microsoft Entra ID 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 .
auth_time Tid då användaren senast autentiserades. JWT
ctry Användarens land/region JWT Det här anspråket returneras om det finns och värdet för fältet är en standardkod för land/region med två bokstäver, till exempel FR, JP, SZ och så vidare.
email Den rapporterade e-postadressen för den här användaren JWT, SAML MSA, Microsoft Entra ID Det här värdet ingår som standard om användaren är gäst i klientorganisationen. För hanterade användare (användarna i klientorganisationen) måste det begäras via det här valfria anspråket eller, endast på v2.0, med OpenID-omfånget. Det här värdet är inte garanterat korrekt och kan ändras med tiden – använd det aldrig för auktorisering eller för att spara data för en användare. Mer information finns i Verifiera att användaren har behörighet att komma åt dessa data. Om du använder e-postanspråket för auktorisering rekommenderar vi att du utför en migrering för att övergå till ett säkrare anspråk. Om du behöver en adresserbar e-postadress i din app begär du dessa data direkt från användaren med det här anspråket som ett förslag eller ifyllning i ditt användargränssnitt.
fwd IP-adress JWT Lägger till den ursprungliga adressen för den begärande klienten (när den finns i ett VNET).
groups Valfri formatering för gruppanspråk JWT, SAML Anspråket groups används med inställningen GroupMembershipClaims i programmanifestet, som också måste anges.
idtyp Tokentyp JWT-åtkomsttoken Special: endast i åtkomsttoken endast för appar Värdet är app när token är en apptoken. Det här anspråket är det mest exakta sättet för ett API att avgöra om en token är en apptoken eller en app+användartoken.
login_hint Inloggningstips JWT MSA, Microsoft Entra ID Ett ogenomskinlig, tillförlitligt inloggningstipsanspråk som är base 64-kodat. Ändra inte det här värdet. Det här anspråket är det bästa värdet som ska användas för login_hint OAuth-parametern i alla flöden för att hämta enkel inloggning. Det kan skickas mellan program för att hjälpa dem tyst enkel inloggning också - program A kan logga in en användare, läsa anspråket login_hint och sedan skicka anspråket och den aktuella klientkontexten till program B i frågesträngen eller fragmentet när användaren väljer på en länk som tar dem till program B. För att undvika konkurrensvillkor och tillförlitlighetsproblem inkluderar anspråket login_hintinte den aktuella klientorganisationen för användaren, och standardinställningen är användarens hemklient när den används. I ett gästscenario där användaren kommer från en annan klientorganisation måste en klientidentifierare anges i inloggningsbegäran. och skicka samma till appar som du samarbetar med. Det här anspråket är avsett att användas med SDK:ts befintliga login_hint funktioner, men det exponeras.
sid Sessions-ID som används för utloggning av användare per session JWT Personliga konton och Microsoft Entra-konton.
tenant_ctry Resursklientens land/region JWT Samma som ctry förutom att anges på klientnivå av en administratör. Måste också vara ett standardvärde med två bokstäver.
tenant_region_scope Region för resursklientorganisationen JWT
upn UserPrincipalName JWT, SAML En identifierare för den användare som kan användas med parametern username_hint . Inte en varaktig identifierare för användaren och bör inte användas för auktorisering eller för att unikt identitetsanvändarinformation (till exempel som en databasnyckel). Använd i stället användarobjektets ID (oid) som en databasnyckel. Mer information finns i Skydda program och API:er genom att verifiera anspråk. Användare som loggar in med ett alternativt inloggnings-ID bör inte visas sitt UPN (User Principal Name). Använd i stället följande ID-tokenanspråk för att visa inloggningstillstånd för användaren: preferred_username eller unique_name för v1-token och preferred_username för v2-token. Även om det här anspråket inkluderas automatiskt kan du ange det som ett valfritt anspråk för att bifoga andra egenskaper för att ändra dess beteende i gästanvändarfallet. Du bör använda anspråket login_hint för login_hint användning – läsbara identifierare som UPN är otillförlitliga.
verified_primary_email Hämtas från användarens PrimaryAuthoritativeEmail JWT
verified_secondary_email Hämtas från användarens SecondaryAuthoritativeEmail JWT
vnet Information om VNET-specificerare. JWT
xms_cc Klientfunktioner JWT Microsoft Entra ID 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.
xms_edov Booleskt värde som anger om användarens e-postdomänägare har verifierats. JWT Ett e-postmeddelande anses vara domänverifierat om det tillhör den klientorganisation där användarkontot finns och klientadministratören har verifierat domänen. E-postmeddelandet måste också komma från ett Microsoft-konto (MSA), ett Google-konto eller användas för autentisering med hjälp av engångslösenordsflödet (OTP). Facebook- och SAML/WS-Fed-konton har inte verifierade domäner. För att det här anspråket ska returneras i token krävs förekomsten av anspråket email .
xms_pdl Önskad dataplats JWT För Multi-Geo-klienter är den önskade dataplatsen koden med tre bokstäver som visar den geografiska region som användaren befinner sig i. Mer information finns i dokumentationen för Microsoft Entra Anslut om önskad dataplats.
xms_pl Användar föredraget språk JWT Användarens föredragna språk, om det anges. Hämtas från sin hemklientorganisation i gäståtkomstscenarier. Formaterad LL-CC ("en-us").
xms_tpl Önskat språk för klientorganisation JWT Resursklientens föredragna språk, om det anges. Formaterad LL ("en").
ztdid Zero-touch-distributions-ID JWT Enhetsidentiteten som används för Windows AutoPilot.

Varning

Använd email aldrig eller upn anspråksvärden för att lagra eller 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.

v2.0-specifik valfri anspråksuppsättning

Dessa anspråk ingår alltid i v1.0-token, men ingår inte i v2.0-token om de inte begärs. Dessa anspråk gäller endast för JWTs (ID-token och åtkomsttoken).

JWT-anspråk Name beskrivning Kommentar
ipaddr IP-adress IP-adressen som klienten loggade in från.
onprem_sid Lokal säkerhetsidentifierare
pwd_exp Förfallotid för lösenord Antalet sekunder efter tiden i anspråket iat där lösenordet upphör att gälla. Det här anspråket ingår endast när lösenordet snart upphör att gälla (enligt definitionen av "meddelandedagar" i lösenordsprincipen).
pwd_url Ändra lösenords-URL En URL som användaren kan besöka för att ändra sitt lösenord. Det här anspråket ingår endast när lösenordet snart upphör att gälla (enligt definitionen av "meddelandedagar" i lösenordsprincipen).
in_corp Inifrån företagsnätverket Signaler om klienten loggar in från företagsnätverket. Om de inte är det inkluderas inte anspråket. Baserat på inställningarna för betrodda IP-adresser i MFA.
family_name Efternamn Innehåller användarens efternamn, efternamn eller efternamn enligt definitionen i användarobjektet. Exempel: "family_name":"Miller" Stöds i MSA- och Microsoft Entra-ID. Kräver omfånget profile .
given_name Förnamn Anger användarens första eller "angivna" namn, enligt inställningen för användarobjektet. Exempel: "given_name": "Frank" Stöds i MSA- och Microsoft Entra-ID. Kräver omfånget profile .
upn Användarhuvudnamn En identifierare för den användare som kan användas med parametern username_hint . Inte en varaktig identifierare för användaren och bör inte användas för auktorisering eller för att unikt identitetsanvändarinformation (till exempel som en databasnyckel). Mer information finns i Skydda program och API:er genom att verifiera anspråk. Använd i stället användarobjektets ID (oid) som en databasnyckel. Användare som loggar in med ett alternativt inloggnings-ID bör inte visas sitt UPN (User Principal Name). Använd i stället följande preferred_username anspråk för att visa inloggningstillstånd för användaren. Kräver omfånget profile .

v1.0-specifik valfri anspråksuppsättning

Några av förbättringarna av v2-tokenformatet är tillgängliga för appar som använder v1-tokenformatet, eftersom de bidrar till att förbättra säkerhet och tillförlitlighet. Dessa förbättringar gäller endast för JWT:er, inte SAML-token.

JWT-anspråk Name beskrivning Kommentar
aud Målgrupp Finns alltid i JWTs, men i v1-åtkomsttoken kan den genereras på olika sätt – alla appID-URI:er, med eller utan ett avslutande snedstreck och resursens klient-ID. Den här slumpmässigheten kan vara svår att koda mot när du utför tokenvalidering. Använd additionalProperties för det här anspråket för att säkerställa att det alltid är inställt på resursens klient-ID i v1-åtkomsttoken. v1 Endast JWT-åtkomsttoken
preferred_username Föredraget användarnamn Tillhandahåller det önskade användarnamnsanspråket i v1-token. Det här påståendet gör det enklare för appar att ge användarnamnstips och visa läsbara visningsnamn, oavsett tokentyp. Vi rekommenderar att du använder det här valfria anspråket i stället för att använda, upn eller unique_name. v1-ID-token och åtkomsttoken

additionalProperties av valfria anspråk

Vissa valfria anspråk kan konfigureras för att ändra hur anspråket returneras. Dessa additionalProperties används främst för att hjälpa migrering av lokala program med olika dataförväntningar. Du kan till exempel include_externally_authenticated_upn_without_hash hjälpa till med klienter som inte kan hantera hash-markeringar (#) i UPN.

Egenskapsnamn additionalProperty Namn beskrivning
upn Kan användas för både SAML- och JWT-svar och för v1.0- och v2.0-token.
include_externally_authenticated_upn Innehåller gäst-UPN som lagras i resursklientorganisationen. Exempel: foo_hometenant.com#EXT#@resourcetenant.com
include_externally_authenticated_upn_without_hash Samma som tidigare, förutom att hash-märkena (#) ersätts med understreck (_), till exempel foo_hometenant.com_EXT_@resourcetenant.com.
aud I v1-åtkomsttoken används det här anspråket för att ändra anspråkets aud format. Det här anspråket har ingen effekt i v2-token eller någon av versionernas ID-token, där anspråket aud alltid är klient-ID. Använd den här konfigurationen för att säkerställa att ditt API enklare kan utföra målgruppsverifiering. Liksom alla valfria anspråk som påverkar åtkomsttoken måste resursen i begäran ange det här valfria anspråket, eftersom resurserna äger åtkomsttoken.
use_guid Genererar klient-ID för resursen (API) i GUID-format som aud anspråket alltid i stället för att det är körningsberoende. Om en resurs till exempel anger den här flaggan och dess klient-ID är 00001111-aaaa-2222-bbbb-3333cccc4444, tar alla appar som begär en åtkomsttoken för den resursen emot en åtkomsttoken med aud : 00001111-aaaa-2222-bbbb-3333cccc4444. Utan den här anspråksuppsättningen kan ett API hämta token med ett aud anspråk på api://MyApi.com, api://myapi.com/AdditionalRegisteredFieldapi://MyApi.com/eller något annat värde som anges som en app-ID-URI för det API:et och resursens klient-ID.
idtyp Det här anspråket används för att hämta typen av token (app, användare, enhet). Som standard genereras endast för apptoken. Liksom alla valfria anspråk som påverkar åtkomsttoken måste resursen i begäran ange det här valfria anspråket, eftersom resurserna äger åtkomsttoken.
include_user_token Genererar anspråket idtyp för användartoken. Utan den här valfria ytterligare egenskapen för idtyp-anspråksuppsättningen hämtar ett API endast anspråket för apptoken.

additionalProperties Exempel

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ]
}

Det här optionalClaims objektet gör att ID-token som returneras till klienten inkluderar ett upn anspråk med den andra hemklient- och resursklientinformationen. Anspråket upn ändras endast i token om användaren är gäst i klientorganisationen (som använder en annan IDP för autentisering).

Se även

Nästa steg