Share via

Naslaginformatie over optionele claims

  • Artikel

U kunt optionele claims gebruiken voor het volgende:

  • Selecteer claims die u wilt opnemen in tokens voor uw toepassing.
  • Het gedrag wijzigen van bepaalde claims die Microsoft Identity Platform in tokens retourneert.
  • Aangepaste claims voor uw toepassing toevoegen en openen.

Hoewel optionele claims worden ondersteund in zowel v1.0- en v2.0-indelingstokens als SAML-tokens, bieden ze de meeste waarde bij het overstappen van v1.0 naar v2.0. In het Microsoft Identity Platform worden kleinere tokengrootten gebruikt om optimale prestaties door clients te garanderen. Als gevolg hiervan zijn een aantal claims die voorheen waren opgenomen in de toegangs- en id-tokens, niet meer aanwezig in v2.0-tokens en moet er specifiek naar worden gevraagd per toepassing.

Rekeningsoort v1.0-tokens v2.0-tokens
Persoonlijk Microsoft-account N.v.t. Ondersteund
Microsoft Entra-account Ondersteund Ondersteund

Set optionele claims v1.0 en v2.0

De set optionele claims die standaard beschikbaar zijn voor toepassingen die moeten worden gebruikt, worden vermeld in de volgende tabel. U kunt aangepaste gegevens in extensiekenmerken en directory-extensies gebruiken om optionele claims voor uw toepassing toe te voegen. Wanneer u claims toevoegt aan het toegangstoken, zijn de claims van toepassing op toegangstokens die zijn aangevraagd voor de toepassing (een web-API), niet claims die door de toepassing worden aangevraagd. Ongeacht hoe de client toegang heeft tot uw API, zijn de juiste gegevens aanwezig in het toegangstoken dat wordt gebruikt voor verificatie bij uw API.

Notitie

Het merendeel van deze claims kan worden opgenomen in JWT's voor v1.0- en v2.0-tokens, maar niet SAML-tokens, behalve waar vermeld in de kolom Tokentype. Consumentenaccounts ondersteunen een subset van deze claims, gemarkeerd in de kolom Gebruikerstype. Veel van de vermelde claims zijn niet van toepassing op consumentengebruikers (ze hebben geen tenant, dus tenant_ctry heeft geen waarde).

De volgende tabel bevat de optionele claimset v1.0 en v2.0.

Name Beschrijving Tokentype Gebruikerstype Opmerkingen
acct De accountstatus van de gebruiker in de tenant JWT, SAML Als de gebruiker lid is van de tenant, is de waarde 0. Als de gebruiker een gast is, is de waarde 1.
acrs Verificatiecontext-id's JWT Microsoft Entra ID Geeft de verificatiecontext-id's aan van de bewerkingen die de bearer in aanmerking komt om uit te voeren. Verificatiecontext-id's kunnen worden gebruikt om een vraag naar stapsgewijze verificatie vanuit uw toepassing en services te activeren. Vaak gebruikt samen met de xms_cc claim.
auth_time Tijdstip waarop de gebruiker voor het laatst is geverifieerd. JWT
ctry Land/regio van gebruiker JWT Deze claim wordt geretourneerd als deze aanwezig is en de waarde van het veld een standaard tweeletterige land-/regiocode is, zoals FR, JP, SZ, enzovoort.
email Het gerapporteerde e-mailadres voor deze gebruiker JWT, SAML MSA, Microsoft Entra-id Deze waarde is standaard opgenomen als de gebruiker een gast in de tenant is. Voor beheerde gebruikers (de gebruikers in de tenant) moet deze worden aangevraagd via deze optionele claim of – alleen op v2.0 – met het OpenID-bereik. Deze waarde is niet gegarandeerd correct en kan in de loop van de tijd veranderlijk zijn. Gebruik deze waarde nooit voor autorisatie of om gegevens voor een gebruiker op te slaan. Zie Valideren dat de gebruiker gemachtigd is om toegang te krijgen tot deze gegevens voor meer informatie. Als u de e-mailclaim voor autorisatie gebruikt, raden we u aan een migratie uit te voeren om naar een veiligere claim te gaan. Als u een adresseerbaar e-mailadres in uw app nodig hebt, vraagt u deze gegevens rechtstreeks aan bij de gebruiker, waarbij u deze claim gebruikt als suggestie of vooraf invult in uw UX.
fwd IP-adres JWT Hiermee voegt u het oorspronkelijke adres van de aanvragende client toe (wanneer u zich in een VNET bevindt).
groups Optionele opmaak voor groepsclaims JWT, SAML De groups claim wordt gebruikt met de instelling GroupMembershipClaims in het toepassingsmanifest, dat ook moet worden ingesteld.
idtyp Tokentype JWT-toegangstokens Speciaal: alleen in alleen-app-toegangstokens De waarde is app wanneer het token een token is dat alleen voor apps geldt. Deze claim is de meest nauwkeurige manier voor een API om te bepalen of een token een app-token of een app+gebruikerstoken is.
login_hint Aanmeldingshint JWT MSA, Microsoft Entra-id Een ondoorzichtige, betrouwbare aanmeldingshint claim dat base 64 is gecodeerd. Wijzig deze waarde niet. Deze claim is de beste waarde om te gebruiken voor de OAuth-parameter login_hint in alle stromen om eenmalige aanmelding op te halen. Het kan ook worden doorgegeven tussen toepassingen zodat eenmalige aanmelding op de achtergrond kan worden uitgevoerd: toepassing A kan een gebruiker aanmelden, de login_hint-claim lezen en vervolgens de claim en de huidige tenantcontext verzenden naar toepassing B in de querytekenreeks of het fragment wanneer de gebruiker een koppeling selecteert die hem/haar naar toepassing B brengt. Om racevoorwaarden en betrouwbaarheidsproblemen te voorkomen, bevat de login_hint-claim niet de huidige tenant voor de gebruiker en wordt de claim standaard ingesteld op de starttenant van de gebruiker wanneer deze wordt gebruikt. In een gastscenario waarin de gebruiker afkomstig is van een andere tenant, moet er een tenant-id worden opgegeven in de aanmeldingsaanvraag. en geef hetzelfde door aan apps waarmee u partner bent. Deze claim is bedoeld voor gebruik met de bestaande functionaliteit login_hint van uw SDK, hoe dan ook deze beschikbaar wordt gesteld.
sid Sessie-id, gebruikt voor afmelding per sessie JWT Persoonlijke en Microsoft Entra-accounts.
tenant_ctry Land/regio van resourcetenant JWT Hetzelfde als ctry, behalve dat deze door een beheerder wordt ingesteld op tenantniveau. Moet ook een standaard tweeletterige waarde zijn.
tenant_region_scope Regio van de resourcetenant JWT
upn UserPrincipalName JWT, SAML Een id voor de gebruiker die kan worden gebruikt met de username_hint parameter. Geen duurzame id voor de gebruiker en mag niet worden gebruikt voor autorisatie of om gebruikersgegevens uniek te identificeren (bijvoorbeeld als databasesleutel). Gebruik in plaats daarvan de gebruikersobject-id (oid) als databasesleutel. Zie Beveiligde toepassingen en API's voor meer informatie door claims te valideren. Gebruikers die zich aanmelden met een alternatieve aanmeldings-id, mogen hun UPN (User Principal Name) niet zien. Gebruik in plaats daarvan de volgende id-tokenclaims om de aanmeldingsstatus weer te geven aan de gebruiker: preferred_username of unique_name voor v1-tokens en preferred_username voor v2-tokens. Hoewel deze claim automatisch wordt opgenomen, kunt u deze opgeven als een optionele claim om andere eigenschappen te koppelen om het gedrag ervan in de gastgebruikerscase te wijzigen. U moet de login_hint-claim gebruiken voor gebruik van login_hint – door mensen leesbare id's zoals UPN zijn onbetrouwbaar.
verified_primary_email Opgehaald uit de PrimaryAuthoritativeEmail van de gebruiker JWT
verified_secondary_email Opgehaald uit de SecondaryAuthoritativeEmail van de gebruiker JWT
vnet Gegevens van VNET-aanduiding. JWT
xms_cc Clientmogelijkheden JWT Microsoft Entra ID Geeft aan of de clienttoepassing die het token heeft verkregen, in staat is om problemen met claims te verwerken. Het wordt vaak samen met claim acrsgebruikt. Deze claim wordt vaak gebruikt in scenario's voor voorwaardelijke toegang en continue toegangsevaluatie. De bronserver of servicetoepassing die het token wordt uitgegeven voor het beheren van de aanwezigheid van deze claim in een token. Een waarde van cp1 het toegangstoken is de gezaghebbende manier om te bepalen dat een clienttoepassing een claimvraag kan afhandelen. Zie Claims-uitdagingen, claimsaanvragen en clientmogelijkheden voor meer informatie.
xms_edov Booleaanse waarde die aangeeft of de eigenaar van het e-maildomein van de gebruiker is geverifieerd. JWT Een e-mail wordt beschouwd als domeinverificatie als deze deel uitmaakt van de tenant waar het gebruikersaccount zich bevindt en de tenantbeheerder heeft verificatie van het domein uitgevoerd. Bovendien moet het e-mailbericht afkomstig zijn van een Microsoft-account (MSA), een Google-account of worden gebruikt voor verificatie met behulp van de eenmalige wachtwoordcodestroom (OTP). Facebook- en SAML-/WS-Fed-accounts hebben geen geverifieerde domeinen. Om deze claim in het token te retourneren, is de aanwezigheid van de email claim vereist.
xms_pdl Voorkeursgegevenslocatie JWT Voor Multi-Geo-tenants is de voorkeursgegevenslocatie de drieletterige code die de geografische regio weergeeft waarin de gebruiker zich bevindt. Zie de documentatie van Microsoft Entra Verbinding maken over voorkeursgegevenslocatie voor meer informatie.
xms_pl Voorkeurstaal voor gebruiker JWT De voorkeurstaal van de gebruiker, indien ingesteld. Opgehaald uit zijn/haar starttenant, in scenario's voor gasttoegang. Opgemaakte LL-CC ('en-us').
xms_tpl Voorkeurstaal voor tenant JWT De voorkeurstaal van de resourcetenant, indien ingesteld. Opgemaakte LL ('en').
ztdid Zero-Touch implementatie-id JWT De apparaat-id die wordt gebruikt voor Windows AutoPilot.

Waarschuwing

email Gebruik of upn claim nooit waarden om op te slaan of te bepalen of de gebruiker in een toegangstoken toegang moet hebben tot gegevens. Veranderlijke claimwaarden zoals deze kunnen na verloop van tijd veranderen, waardoor ze onveilig en onbetrouwbaar zijn voor autorisatie.

v2.0-specifieke set optionele claims

Deze claims worden altijd opgenomen in v1.0-tokens, maar niet opgenomen in v2.0-tokens, tenzij aangevraagd. Deze claims zijn alleen van toepassing op JWT's (ID-tokens en toegangstokens).

JWT-claim Name Beschrijving Opmerkingen
ipaddr IP-adres Het IP-adres waarvandaan de client is aangemeld.
onprem_sid On-premises beveiligings-id
pwd_exp Wachtwoordverlooptijd Het aantal seconden na de tijd in de iat claim waarop het wachtwoord verloopt. Deze claim wordt alleen opgenomen wanneer het wachtwoord binnenkort verloopt (zoals gedefinieerd door 'meldingsdagen' in het wachtwoordbeleid).
pwd_url URL voor Wachtwoord wijzigen Een URL die de gebruiker kan bezoeken om het wachtwoord te wijzigen. Deze claim wordt alleen opgenomen wanneer het wachtwoord binnenkort verloopt (zoals gedefinieerd door 'meldingsdagen' in het wachtwoordbeleid).
in_corp Binnen bedrijfsnetwerk Geeft aan of de client zich aanmeldt vanuit het bedrijfsnetwerk. Zo niet, dan wordt de claim niet opgenomen. Gebaseerd op de instellingen voor vertrouwde IP-adressen in MFA.
family_name Achternaam Hiermee wordt de achternaam of familienaam van de gebruiker opgegeven, zoals gedefinieerd in het gebruikersobject. Bijvoorbeeld: "family_name":"Miller". Ondersteund in MSA en Microsoft Entra-id. Vereist het bereik profile.
given_name Voornaam Hiermee wordt de voornaam van de gebruiker opgegeven, zoals ingesteld voor het gebruikersobject. Bijvoorbeeld: "given_name": "Frank". Ondersteund in MSA en Microsoft Entra-id. Vereist het bereik profile.
upn User Principal Name Een id voor de gebruiker die kan worden gebruikt met de username_hint parameter. Geen duurzame id voor de gebruiker en mag niet worden gebruikt voor autorisatie of om gebruikersgegevens uniek te identificeren (bijvoorbeeld als databasesleutel). Zie Beveiligde toepassingen en API's voor meer informatie door claims te valideren. Gebruik in plaats daarvan de gebruikersobject-id (oid) als databasesleutel. Gebruikers die zich aanmelden met een alternatieve aanmeldings-id, mogen hun UPN (User Principal Name) niet zien. Gebruik in plaats daarvan de volgende preferred_username-claim om de aanmeldingsstatus weer te geven aan de gebruiker. Vereist het bereik profile.

v1.0-specifieke set optionele claims

Sommige van de verbeteringen van de v2-tokenindeling zijn beschikbaar voor apps die de v1-tokenindeling gebruiken, omdat ze de beveiliging en betrouwbaarheid helpen verbeteren. Deze verbeteringen zijn alleen van toepassing op JWT's, niet op SAML-tokens.

JWT-claim Name Beschrijving Opmerkingen
aud Doelgroep Altijd aanwezig in JWT's, maar in v1-toegangstokens kan het op verschillende manieren worden verzonden: elke appID-URI, met of zonder een afsluitende slash, en de client-id van de resource. Deze randomisatie kan moeilijk zijn om voor te coderen wanneer tokenvalidatie wordt uitgevoerd. Gebruik additionalProperties deze claim om ervoor te zorgen dat deze altijd is ingesteld op de client-id van de resource in v1-toegangstokens. Alleen v1 JWT-toegangstokens
preferred_username Voorkeursgebruikersnaam Biedt de claim voor voorkeursgebruikersnaam binnen v1-tokens. Deze claim maakt het eenvoudiger voor apps om hints voor gebruikersnamen te bieden en door mensen leesbare weergavenamen te tonen, ongeacht het tokentype. Het is raadzaam deze optionele claim te gebruiken in plaats van te gebruiken, upn of unique_name. v1 ID-tokens en toegangstokens

additionalProperties van optionele claims

Sommige optionele claims kunnen worden geconfigureerd om de manier te wijzigen waarop de claim wordt geretourneerd. Deze additionalProperties worden meestal gebruikt om de migratie van on-premises toepassingen met verschillende gegevensverwachtingen te helpen. include_externally_authenticated_upn_without_hash helpt bijvoorbeeld met clients die hekjes (#) in de UPN niet kunnen verwerken.

Eigenschapsnaam additionalProperty Naam Beschrijving
upn Kan worden gebruikt voor zowel SAML- als JWT-antwoorden, en voor v1.0- en v2.0-tokens.
include_externally_authenticated_upn Hiermee wordt de gast-UPN opgenomen zoals deze is opgeslagen in de resourcetenant. Bijvoorbeeld: foo_hometenant.com#EXT#@resourcetenant.com.
include_externally_authenticated_upn_without_hash Hetzelfde als eerder vermeld, behalve dat de hashmarkeringen (#) worden vervangen door onderstrepingstekens (_bijvoorbeeld foo_hometenant.com_EXT_@resourcetenant.com.
aud In v1-toegangstokens wordt deze claim gebruikt om de indeling van de claim aud te wijzigen. Deze claim heeft geen effect in v2-tokens of de id-tokens van een van beide versies, waarbij de aud-claim altijd de client-id is. Gebruik deze configuratie om ervoor te zorgen dat uw API doelgroepvalidatie gemakkelijker kan uitvoeren. Net als alle optionele claims die van invloed zijn op het toegangstoken, moet de resource in de aanvraag deze optionele claim instellen, omdat resources eigenaar zijn van het toegangstoken.
use_guid Verzendt de client-id van de resource (API) altijd in GUID-indeling als de aud-claim in plaats van dat deze afhankelijk is van runtime. Als een resource bijvoorbeeld deze vlag instelt en de bijbehorende client-id is00001111-aaaa-2222-bbbb-3333cccc4444, ontvangt elke app die een toegangstoken voor die resource aanvraagt een toegangstoken met aud : . 00001111-aaaa-2222-bbbb-3333cccc4444 Zonder deze claimset kan een API tokens ophalen met een aud claim vanapi://MyApi.com, api://MyApi.com/api://myapi.com/AdditionalRegisteredField of een andere waarde die is ingesteld als een app-id-URI voor die API en de client-id van de resource.
idtyp Deze claim wordt gebruikt om het type token op te halen (app, gebruiker, apparaat). Standaard worden deze alleen verzonden voor tokens die alleen voor apps zijn verzonden. Net als alle optionele claims die van invloed zijn op het toegangstoken, moet de resource in de aanvraag deze optionele claim instellen, omdat resources eigenaar zijn van het toegangstoken.
include_user_token Hiermee wordt de idtyp claim voor het token van gebruikers verzonden. Zonder deze optionele aanvullende eigenschap voor de idtyp-claimset krijgt een API alleen de claim voor app-tokens.

additionalProperties Voorbeeld

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

Dit optionalClaims object zorgt ervoor dat het id-token dat naar de client wordt geretourneerd, een upn claim bevat met de andere tenant- en resourcetenantgegevens. De upn-claim wordt alleen gewijzigd in het token als de gebruiker een gast in de tenant is (die een andere IdP gebruikt voor verificatie).

Zie ook

Volgende stappen