Delen 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.
  • Wijzig het gedrag van bepaalde claims die het Microsoft Identity Platform retourneert in tokens.
  • Aangepaste claims voor uw toepassing toevoegen en openen.

Hoewel optionele claims worden ondersteund in zowel v1.0- als v2.0-indelingstokens en SAML-tokens, bieden ze het grootste deel van hun 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 verschillende claims die voorheen zijn opgenomen in de toegangs- en id-tokens niet meer aanwezig in v2.0-tokens en moeten ze specifiek per toepassing worden gevraagd.

Accounttype v1.0-tokens v2.0-tokens
Persoonlijk Microsoft-account N.V.T Ondersteund
Microsoft Entra-account Ondersteund Ondersteund

v1.0 en v2.0 optionele claimset

De set optionele claims die standaard beschikbaar zijn voor toepassingen die moeten worden gebruikt, worden vermeld in de volgende tabel. U kunt aangepaste gegevens gebruiken in extensiekenmerken en directory-extensies 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), worden geen claims aangevraagd door de toepassing. 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.

Naam Beschrijving Tokentype Gebruikerstype Notities
acct Gebruikersaccountstatus in tenant JWT, SAML Als de gebruiker lid is van de tenant, wordt de waarde 0. Als ze een gast zijn, 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 wordt 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 onveranderbaar zijn. Gebruik deze waarde nooit voor autorisatie of om gegevens voor een gebruiker op te slaan. Zie Controleer of de gebruiker gemachtigd is voor toegang tot deze gegevensvoor meer informatie. Als u de e-mailclaim voor autorisatie gebruikt, raden we het uitvoeren van een migratie aan om over te stappen op een veiligere claim. 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 tokens voor alleen-app-toegang De waarde wordt app wanneer het token een app-token is. 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 die u kunt gebruiken voor de parameter login_hint OAuth in alle stromen om eenmalige aanmelding op te halen. Het kan worden doorgegeven tussen toepassingen om ze op de achtergrond eenmalige aanmelding te helpen- toepassing A kan zich aanmelden bij een gebruiker, de login_hint claim lezen en vervolgens de claim en de huidige tenantcontext verzenden naar toepassing B in de querytekenreeks of -fragment wanneer de gebruiker een koppeling selecteert die ze naar toepassing B brengt. Om racevoorwaarden en betrouwbaarheidsproblemen te voorkomen, bevat de login_hint claim niet de huidige tenant voor de gebruiker bevat en de standaardinstellingen voor de thuistenant 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 login_hint-functionaliteit van uw SDK, maar deze wordt weergegeven.
tenant_ctry Land/regio van resourcetenant JWT Hetzelfde als ctry behalve ingesteld op tenantniveau door een beheerder. Moet ook een standaardwaarde van twee letters zijn.
tenant_region_scope Regio van de resourcetenant JWT
upn UserPrincipalName JWT, SAML Een id voor de gebruiker die kan worden gebruikt met de parameter username_hint. 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 Toepassingen en API's beveiligen door claims te validerenvoor meer informatie. Gebruikers die zich aanmelden met een alternatieve aanmeldings-id mogen hun UPN (User Principal Name) niet weergeven. Gebruik in plaats daarvan de volgende id-tokenclaims voor het weergeven van de aanmeldingsstatus voor 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 login_hint gebruik. Leesbare id's zoals UPN zijn onbetrouwbaar.
verified_primary_email Afkomstig van primaryAuthoritativeEmail van de gebruiker JWT
verified_secondary_email Afkomstig uit de SecondaryAuthoritativeEmail van de gebruiker JWT
vnet VNET-aanduidingsgegevens. 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 in het toegangstoken is de gezaghebbende manier om te bepalen dat een clienttoepassing een claimvraag kan afhandelen. Zie Claims-uitdagingen, claimsaanvragen en clientmogelijkhedenvoor 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 geen geverifieerde domeinen hebben. Om deze claim in het token te retourneren, is de aanwezigheid van de email claim vereist.
xms_pdl Voorkeursgegevenslocatie JWT Voor tenants met meerdere geografische gebieden is de voorkeursgegevenslocatie de drieletterige code met de geografische regio waarin de gebruiker zich bevindt. Zie de documentatie Microsoft Entra Connect over voorkeursgegevenslocatievoor meer informatie.
xms_pl Voorkeurstaal van de gebruiker JWT De voorkeurstaal van de gebruiker, indien ingesteld. Afkomstig van hun thuistenant, in scenario's voor gasttoegang. Opgemaakte LL-CC ("en-us").
xms_tpl Voorkeurstaal van tenant JWT De voorkeurstaal van de resourcetenant, indien ingesteld. Opgemaakte LL ("en").
ztdid Implementatie-id van Zero Touch JWT De apparaat-id die wordt gebruikt voor Windows AutoPilot.

Waarschuwing

Gebruik nooit email of upn claimwaarden 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 optionele claimset

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 Naam Beschrijving Notities
ipaddr IP-adres Het IP-adres van de client waaruit is aangemeld.
onprem_sid On-premises beveiligings-id
pwd_exp Verlooptijd van wachtwoord 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 Wachtwoord-URL 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 Signalen als de client zich aanmeldt vanuit het bedrijfsnetwerk. Als dat niet zo is, is de claim niet inbegrepen. Gebaseerd op de vertrouwde IP-adressen instellingen in MFA.
family_name Achternaam Hiermee geeft u de achternaam, achternaam of familienaam van de gebruiker op zoals gedefinieerd in het gebruikersobject. Bijvoorbeeld "family_name":"Miller". Ondersteund in MSA en Microsoft Entra-id. Vereist het profile bereik.
given_name Voornaam Geeft de eerste of 'opgegeven' naam van de gebruiker op, zoals ingesteld op het gebruikersobject. Bijvoorbeeld "given_name": "Frank". Ondersteund in MSA en Microsoft Entra-id. Vereist het profile bereik.
upn User Principal Name Een id voor de gebruiker die kan worden gebruikt met de parameter username_hint. Geen duurzame id voor de gebruiker en mag niet worden gebruikt voor autorisatie of om gebruikersgegevens uniek te identificeren (bijvoorbeeld als databasesleutel). Zie Toepassingen en API's beveiligen door claims te validerenvoor meer informatie. 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 weergeven. Gebruik in plaats daarvan de volgende preferred_username claim voor het weergeven van de aanmeldingsstatus voor de gebruiker. Vereist het profile bereik.

v1.0-specifieke optionele claimset

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

JWT-claim Naam Beschrijving Notities
aud Audiëntie 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 worden gecodeerd bij het uitvoeren van tokenvalidatie. Gebruik additionalProperties voor 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 voorkeursclaim voor gebruikersnaam binnen v1-tokens. Deze claim maakt het eenvoudiger voor apps om hints voor gebruikersnamen te bieden en door mensen leesbare weergavenamen weer te geven, ongeacht hun tokentype. Het is raadzaam om 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 bij clients die geen hashmarkeringen (#) in de UPN kunnen verwerken.

Naam van eigenschap 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 Bevat de UPN van de gast zoals 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 aud claim te wijzigen. Deze claim heeft geen effect in v2-tokens of de id-tokens van een versie, waarbij de aud claim altijd de client-id is. Gebruik deze configuratie om ervoor te zorgen dat uw API eenvoudiger doelgroepvalidatie 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) in GUID-indeling als de aud claim altijd in plaats van dat deze afhankelijk is van runtime. Als een resource bijvoorbeeld deze vlag instelt en de bijbehorende client-id is 00001111-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 van api://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

  • Meer informatie over het configureren van optionele claims .