Delen via

Optionele claims configureren

  • Artikel

Tokens die door Microsoft Entra worden geretourneerd, worden kleiner gehouden om optimale prestaties te garanderen door clients die ze aanvragen. Als gevolg hiervan zijn verschillende claims niet meer standaard aanwezig in het token en moeten ze specifiek per toepassing worden gevraagd.

U kunt optionele claims voor uw toepassing configureren via de gebruikersinterface of het manifest van het Microsoft Entra-beheercentrum.

Vereisten

Optionele claims configureren in uw toepassing

  1. Meld u als cloudtoepassingsbeheerder aan bij het Microsoft Entra-beheercentrum.
  2. Blader naar identiteitstoepassingen>> App-registraties.
  3. Kies de toepassing waarvoor u optionele claims wilt configureren op basis van uw scenario en het gewenste resultaat.
  1. Selecteer onder Beheren de optie Tokenconfiguratie.
  2. Selecteer Optionele claim toevoegen.
  3. Selecteer het tokentype dat u wilt configureren, zoals Access.
  4. Selecteer de optionele claims die u wilt toevoegen.
  5. Selecteer Toevoegen.

Het optionalClaims object declareert de optionele claims die zijn aangevraagd door een toepassing. Een toepassing kan optionele claims configureren die worden geretourneerd in id-tokens, toegangstokens en SAML 2-tokens. De toepassing kan voor elk tokentype een andere set optionele claims configureren die moeten worden geretourneerd.

Name Type Description
idToken Verzameling De optionele claims die worden geretourneerd in het JWT-id-token.
accessToken Verzameling De optionele claims die worden geretourneerd in het JWT-toegangstoken.
saml2Token Verzameling De optionele claims die worden geretourneerd in het SAML-token.

Als dit wordt ondersteund door een specifieke claim, kunt u ook het gedrag van de optionele claim wijzigen met behulp van het additionalProperties veld.

Name Type Description
name Edm.String De naam van de optionele claim.
source Edm.String De bron (het directory-object) van de claim. Er zijn vooraf gedefinieerde claims en door de gebruiker gedefinieerde claims uit extensie-eigenschappen. Als de bronwaarde 'null' is, is de claim een vooraf gedefinieerde optionele claim. Als de bronwaarde 'user' is, is de waarde in de naameigenschap de extensie-eigenschap uit het gebruikersobject.
essential Edm.Boolean Als de waarde 'true' is, is de claim die door de client is opgegeven nodig om een soepele autorisatie-ervaring te garanderen voor de specifieke taak die door de eindgebruiker is aangevraagd. De standaardwaarde is false.
additionalProperties Verzameling (Edm.String) Andere eigenschappen van de claim. Als er een eigenschap in deze verzameling bestaat, wijzigt deze het gedrag van de optionele claim die is opgegeven in de naameigenschap.

Optionele claims voor directory-extensie configureren

Naast de standaardset optionele claims kunt u tokens ook configureren om Microsoft Graph-extensies op te nemen. Zie Aangepaste gegevens toevoegen aan resources met behulp van extensies voor meer informatie.

Belangrijk

Toegangstokens worden altijd gegenereerd met behulp van het manifest van de resource, niet de client. In de aanvraag ...scope=https://graph.microsoft.com/user.read...is de resource de Microsoft Graph API. Het toegangstoken wordt gemaakt met behulp van het Microsoft Graph API-manifest, niet het manifest van de client. Als u het manifest voor uw toepassing wijzigt, worden tokens voor de Microsoft Graph API nooit anders weergegeven. Als u wilt controleren of uw accessToken wijzigingen van kracht zijn, vraagt u een token aan voor uw toepassing, niet voor een andere app.

Optionele claims ondersteunen extensiekenmerken en directory-extensies. Deze functie is handig voor het toevoegen van meer gebruikersgegevens die uw app kan gebruiken. Bijvoorbeeld andere id's of belangrijke configuratieopties die de gebruiker heeft ingesteld. Als uw toepassingsmanifest een aangepaste extensie aanvraagt en een MSA-gebruiker zich aanmeldt bij uw app, worden deze extensies niet geretourneerd.

Opmaak van directory-extensie

Wanneer u optionele claims voor directory-extensies configureert met behulp van het toepassingsmanifest, gebruikt u de volledige naam van de extensie (in de indeling: extension_<appid>_<attributename>). Dit <appid> is de stripped versie van de appId (of client-id) van de toepassing die de claim aanvraagt.

Binnen de JWT worden deze claims verzonden met de volgende naamnotatie: extn.<attributename>. Binnen de SAML-tokens worden deze claims verzonden met de volgende URI-indeling: http://schemas.microsoft.com/identity/claims/extn.<attributename>

Optionele groepenclaims configureren

Tip

Stappen in dit artikel kunnen enigszins variëren op basis van de portal waaruit u begint.

In deze sectie worden de configuratieopties onder optionele claims beschreven voor het wijzigen van de groepskenmerken die worden gebruikt in groepsclaims van de standaardgroepsobject-id in kenmerken die zijn gesynchroniseerd vanuit on-premises Windows Active Directory. U kunt optionele groepenclaims voor uw toepassing configureren via de Azure-portal of het toepassingsmanifest. Optionele groepsclaims worden alleen verzonden in de JWT voor gebruikers-principals. Service-principals worden niet opgenomen in optionele groepsclaims die worden verzonden in de JWT.

Belangrijk

Het aantal groepen dat is verzonden in een token, is beperkt tot 150 voor SAML-asserties en 200 voor JWT, inclusief geneste groepen. Zie Groepsclaims configureren voor toepassingen voor meer informatie over groepslimieten en belangrijke opmerkingen voor groepsclaims van on-premises kenmerken.

Voer de volgende stappen uit om optionele groepenclaims te configureren met behulp van Azure Portal:

  1. Selecteer de toepassing waarvoor u optionele claims wilt configureren.
  2. Selecteer onder Beheren de optie Tokenconfiguratie.
  3. Selecteer Groepsclaim toevoegen.
  4. Selecteer de groepstypen die moeten worden geretourneerd (beveiligingsgroepen of directoryrollen, alle groepen en/of groepen die aan de toepassing zijn toegewezen):
    • De optie Groepen die zijn toegewezen aan de toepassing omvat alleen groepen die aan de toepassing zijn toegewezen. De optie Groepen die zijn toegewezen aan de toepassing wordt aanbevolen voor grote organisaties vanwege de limiet voor het aantal groepen in het token. Als u de groepen wilt wijzigen die aan de toepassing zijn toegewezen, selecteert u de toepassing in de lijst Ondernemingstoepassingen. Selecteer Gebruikers en groepen en vervolgens Gebruiker/groep toevoegen. Selecteer de groep(en) die u wilt toevoegen aan de toepassing vanuit Gebruikers en groepen.
    • De optie Alle groepen omvat SecurityGroup, DirectoryRole en DistributionList, maar niet Groepen die zijn toegewezen aan de toepassing.
  5. Optioneel: Selecteer de specifieke eigenschappen van het tokentype om de groepsclaimwaarde te wijzigen zodat deze on-premises groepskenmerken bevat, of om het claimtype te wijzigen in een rol.
  6. Selecteer Opslaan.

Voer de volgende stappen uit om optionele claims te configureren via het toepassingsmanifest:

  1. Selecteer de toepassing waarvoor u optionele claims wilt configureren.

  2. Selecteer onder Beheren de optie Manifest.

  3. Voeg de volgende vermelding toe met behulp van de manifesteditor:

    De geldige waarden zijn:

    • 'Alles' (deze optie omvat SecurityGroup, DirectoryRole en DistributionList)
    • 'SecurityGroup'
    • 'DirectoryRole'
    • 'ApplicationGroup' (deze optie omvat alleen groepen die zijn toegewezen aan de toepassing)

    Voorbeeld:

    "groupMembershipClaims": "SecurityGroup"

    Standaard worden groepsobject-id's verzonden in de groepsclaimwaarde. Als u de claimwaarde wilt wijzigen zodat deze on-premises groepskenmerken bevat of als u het claimtype wilt wijzigen in rol, gebruikt u de optionalClaims configuratie als volgt:

  4. Stel optionele claims voor groepsnaamconfiguratie in.

    Als u wilt dat groepen in het token de on-premises groepskenmerken in de sectie optionele claims bevatten, geeft u op op welk tokentype optionele claim moet worden toegepast. U geeft ook de naam op van de aangevraagde optionele claim en eventuele andere gewenste eigenschappen.

    Er kunnen meerdere tokentypen worden vermeld:

    • idToken voor het OIDC-id-token
    • accessToken voor het OAuth-toegangstoken
    • Saml2Token voor SAML-tokens.

    Het Saml2Token type is van toepassing op zowel SAML1.1- als SAML2.0-indelingstokens.

    Wijzig voor elk relevant tokentype de groepsclaim om de optionalClaims sectie in het manifest te gebruiken. Het optionalClaims-schema is als volgt:

    {
    "name": "groups",
    "source": null,
    "essential": false,
    "additionalProperties": []
}
    Schema voor optionele claims Weergegeven als
    name Moet groups zijn
    source Niet gebruikt. Laat null weg of geef deze op.
    essential Niet gebruikt. Laat onwaar weg of geef deze op.
    additionalProperties Lijst met andere eigenschappen. Geldige opties zijnsam_account_name, dns_domain_and_sam_account_name, emit_as_roles netbios_domain_and_sam_account_nameen cloud_displayname.

    In additionalProperties slechts één van sam_account_name, dns_domain_and_sam_account_namenetbios_domain_and_sam_account_name zijn vereist. Als er meer dan één aanwezig is, wordt de eerste gebruikt en worden alle andere genegeerd. U kunt ook toevoegen cloud_displayname om de weergavenaam van de cloudgroep te verzenden. Deze optie werkt alleen als groupMembershipClaims deze is ingesteld op ApplicationGroup.

    Voor sommige toepassingen is groepsinformatie over de gebruiker in de rolclaim vereist. Als u het claimtype van een groepsclaim wilt wijzigen in een rolclaim, voegt u dit toe emit_as_roles aan additionalProperties. De groepswaarden worden verzonden in de rolclaim.

    Als emit_as_roles deze wordt gebruikt, bevinden alle toepassingsrollen die zijn geconfigureerd dat de gebruiker (of een resourcetoepassing) is toegewezen, zich niet in de rolclaim.

In de volgende voorbeelden ziet u de manifestconfiguratie voor groepsclaims:

Groepen verzenden als groepsnamen in OAuth-toegangstokens in dnsDomainName\sAMAccountName indeling.

"optionalClaims": {
    "accessToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "dns_domain_and_sam_account_name"
            ]
        }
    ]
}

Groepsnamen verzenden die moeten worden geretourneerd in netbiosDomain\sAMAccountName indeling als de rollenclaim in SAML- en OIDC ID-tokens.

"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ]
}

Groepsnamen verzenden in de indeling van sam_account_name on-premises gesynchroniseerde groepen en cloud_display naam voor cloudgroepen in SAML- en OIDC ID-tokens voor de groepen die aan de toepassing zijn toegewezen.

"groupMembershipClaims": "ApplicationGroup",
"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ]
}

Voorbeeld van optionele claims

Er zijn meerdere opties beschikbaar voor het bijwerken van de eigenschappen van de identiteitsconfiguratie van een toepassing om optionele claims in te schakelen en te configureren:

  • U kunt Azure Portal gebruiken
  • U kunt het manifest gebruiken.
  • Het is ook mogelijk een toepassing te schrijven die gebruikmaakt van de Microsoft Graph-API om uw toepassing bij te werken. Het OptionalClaims-type in de naslaggids van de Microsoft Graph-API kan u helpen bij het configureren van de optionele claims.

In het volgende voorbeeld worden de Azure-portal en het manifest gebruikt om optionele claims toe te voegen aan de toegangs-, id- en SAML-tokens die zijn bedoeld voor uw toepassing. Er worden verschillende optionele claims toegevoegd aan elk type token dat de toepassing kan ontvangen:

  • De ID-tokens bevatten de UPN voor federatieve gebruikers in de volledige vorm (<upn>_<homedomain>#EXT#@<resourcedomain>).
  • De toegangstokens die andere clients voor deze toepassing aanvragen, omvatten de auth_time claim.
  • De SAML-tokens bevatten de skypeId mapschema-extensie (in dit voorbeeld is de app-id voor deze app).ab603c56068041afb2f6832e2a17e237 Het SAML-token toont de Skype-id als extension_ab603c56068041afb2f6832e2a17e237_skypeId.

Claims configureren in Azure Portal:

  1. Selecteer de toepassing waarvoor u optionele claims wilt configureren.
  2. Selecteer onder Beheren de optie Tokenconfiguratie.
  3. Selecteer Optionele claim toevoegen, selecteer het tokentype Id, selecteer upn in de lijst met claims en selecteer vervolgens Toevoegen.
  4. Selecteer Optionele claim toevoegen, selecteer het tokentype Toegang, selecteer auth_time in de lijst met claims en selecteer vervolgens Toevoegen.
  5. Selecteer in het Tokenconfiguratie-overzichtsscherm het potloodpictogram naast upn, selecteer de wisselknop Extern geverifieerd en selecteer vervolgens Opslaan.
  6. Selecteer Optionele claim toevoegen, selecteer het type SAML-token, selecteer extn.skypeID in de lijst met claims (alleen van toepassing als u een Microsoft Entra-gebruikersobject met de naam skypeID hebt gemaakt) en selecteer vervolgens Toevoegen.

Claims configureren in het manifest:

  1. Selecteer de toepassing waarvoor u optionele claims wilt configureren.

  2. Selecteer onder Beheren de optie Manifest om de inline manifesteditor te openen.

  3. U kunt het manifest rechtstreeks bewerken met behulp van deze editor. Het manifest volgt het schema voor de Toepassingsentiteit en maakt het manifest automatisch op zodra het is opgeslagen. Er worden nieuwe elementen toegevoegd aan de optionalClaims eigenschap.

    "optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ],
    "accessToken": [
        {
            "name": "auth_time",
            "essential": false
        }
    ],
    "saml2Token": [
        {
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "source": "user",
            "essential": true
        }
    ]
}

  4. Wanneer u klaar bent met het bijwerken van het manifest, selecteert u Opslaan om het manifest op te slaan.

Beperking

Een toepassing kan maximaal 10 extensiekenmerken uitgeven als optionele claims.

Gerelateerde inhoud