Dela via

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ägg 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. På Microsofts identitetsplattform används mindre tokenstorlekar för att säkerställa optimala 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ödd
Microsoft Entra-konto Stödd Stödd

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ärs för programmet (ett webb-API), inte anspråk som begärs 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.

Not

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 har inget värde).

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

Namn Beskrivning Tokentyp Användartyp Anteckningar
acct Kontostatus för användare i klientorganisationen JWT, SAML Om användaren är medlem i klientorganisationen är värdet 0. Om de är en gäst är värdet 1.
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 xms_cc anspråk.
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 utföra 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 Det groups anspråket 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 parametern login_hint OAuth 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 login_hint anspråk 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 login_hint anspråket inte inkludera den aktuella klientorganisationen för användaren och standardinställningen för användarens hemklientorganisation 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 som det exponeras för.
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 användaren 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 Säkra program och API:er genom att verifiera anspråk. Användare som loggar in med ett alternativt inloggnings-ID bör inte visas deras användarnamn (UPN). 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 login_hint anspråk för login_hint användning – läsbara identifierare för människor 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. Det används ofta tillsammans med anspråk 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 inte har verifierade domäner. För att det här anspråket ska returneras i token krävs förekomsten av det email anspråket.
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 Microsoft Entra Connect 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 aldrig email 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 Namn Beskrivning Anteckningar
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 iat anspråk 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 Inuti företagsnätverket Signaler om klienten loggar in från företagsnätverket. Om de inte är det inkluderas inte anspråket. Baserat på betrodda IP-adresser inställningar i MFA.
family_name Efternamn Innehåller användarens efternamn, efternamn eller efternamn enligt definitionen i användarobjektet. Till exempel "family_name":"Miller". Stöds i MSA- och Microsoft Entra-ID. Kräver profile omfång.
given_name Förnamn Anger användarens första eller "angivna" namn, enligt inställningen för användarobjektet. Till exempel "given_name": "Frank". Stöds i MSA- och Microsoft Entra-ID. Kräver profile omfång.
upn Användarens huvudnamn En identifierare för användaren 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 Säkra 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 deras användarnamn (UPN). Använd i stället följande preferred_username anspråk för att visa inloggningstillstånd för användaren. Kräver profile omfång.

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 Namn Beskrivning Anteckningar
aud Publik 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. Till exempel hjälper include_externally_authenticated_upn_without_hash 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. Till 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 formatet för aud anspråk. Det här anspråket har ingen effekt i v2-token eller någon av versionernas ID-token, där det aud anspråket alltid är klient-ID:t. 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-3333cccc4444tar alla appar som begär en åtkomsttoken för 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/, api://myapi.com/AdditionalRegisteredField eller något annat värde som angetts 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 idtyp anspråk 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 innehåller ett upn anspråk med den andra informationen om hemklientorganisationen och resursklientorganisationen. Det upn anspråket ändras bara i token om användaren är gäst i klientorganisationen (som använder en annan IDP för autentisering).

Se även

Nästa steg