Groepsclaims voor toepassingen configureren met behulp van Microsoft Entra-id

  • Artikel

Microsoft Entra ID kan gegevens over het groepslidmaatschap van een gebruiker opgeven in tokens voor gebruik in toepassingen. Deze functie ondersteunt drie hoofdpatronen:

  • Groepen geïdentificeerd door het kenmerk Microsoft Entra-object-id (OID)
  • Groepen geïdentificeerd door het kenmerk sAMAccountName of GroupSID voor door Active Directory gesynchroniseerde groepen en gebruikers
  • Groepen geïdentificeerd door hun kenmerk Weergavenaam voor groepen die alleen in de cloud worden gebruikt

Belangrijk

Het aantal groepen dat is verzonden in een token, is beperkt tot 150 voor SAML-asserties en 200 voor JWT, inclusief geneste groepen. In grotere organisaties kan het aantal groepen waarvan een gebruiker lid is, de limiet overschrijden die door Microsoft Entra-id wordt toegevoegd aan een token. Het overschrijden van een limiet kan leiden tot onvoorspelbare resultaten. Lees Belangrijke opmerkingen voor deze functionaliteit voor tijdelijke oplossingen voor deze limieten.

Belangrijke waarschuwingen voor deze functionaliteit

  • Ondersteuning voor het gebruik van sAMAccountName en SID-kenmerken (beveiligings-id) die vanuit on-premises zijn gesynchroniseerd, is ontworpen om het verplaatsen van bestaande toepassingen vanuit Active Directory Federation Services (AD FS) en andere id-providers mogelijk te maken. Groepen die worden beheerd in Microsoft Entra-id bevatten niet de kenmerken die nodig zijn om deze claims te verzenden.

  • Als u de limiet voor het aantal groepen wilt voorkomen als uw gebruikers een groot aantal groepslidmaatschappen hebben, kunt u de groepen die worden verzonden in claims beperken tot de relevante groepen voor de toepassing. Lees meer over het verzenden van groepen die zijn toegewezen aan de toepassing voor JWT-tokens en SAML-tokens. Als het toewijzen van groepen aan uw toepassingen niet mogelijk is, kunt u ook een groepsfilter configureren om het aantal groepen dat in de claim wordt verzonden, te verminderen. Groepfiltering is van toepassing op tokens die worden verzonden voor apps waarbij groepsclaims en -filtering zijn geconfigureerd op de blade Bedrijfs-apps in de portal.

  • Groepsclaims hebben een limiet van vijf groepen als het token wordt uitgegeven via de impliciete stroom. Tokens die via de impliciete stroom worden aangevraagd, hebben alleen een "hasgroups":true-claim als de gebruiker zich in meer dan vijf groepen bevindt.

  • Het wordt aanbevolen om in de volgende gevallen in-app-autorisatie te baseren op toepassingsrollen in plaats van groepen:

    • U ontwikkelt een nieuwe toepassing of een bestaande toepassing kan hiervoor worden geconfigureerd.
    • Ondersteuning voor geneste groepen is niet vereist.

    Het gebruik van toepassingsrollen beperkt de hoeveelheid informatie die moet worden ingevoerd in het token, is veiliger en scheidt gebruikerstoewijzing van app-configuratie.

Groepsclaims voor toepassingen die worden gemigreerd vanuit AD FS en andere id-providers

Veel toepassingen die zijn geconfigureerd voor verificatie met AD FS, zijn afhankelijk van informatie over groepslidmaatschap in de vorm van Windows Server Active Directory-groepskenmerken. Deze kenmerken zijn de groep sAMAccountName, die kan worden gekwalificeerd op domeinnaam, of de beveiligings-id van de Windows-groep (GroupSID). Wanneer de toepassing is gefedereerd met AD FS, gebruikt AD FS de functie TokenGroups om de groepslidmaatschappen voor de gebruiker op te halen.

Een app die vanuit AD FS is verplaatst, heeft claims nodig in dezelfde indeling. Groep- en rolclaims die worden verzonden vanuit Microsoft Entra-id, bevatten mogelijk het kenmerk domeingekwalificeerd sAMAccountName of het GroupSID kenmerk dat is gesynchroniseerd vanuit Active Directory, in plaats van het Kenmerk Microsoft Entra ID objectID van de groep.

De ondersteunde indelingen voor groepsclaims zijn:

  • Microsoft Entra group ObjectId: Beschikbaar voor alle groepen.
  • sAMAccountName: beschikbaar voor groepen die zijn gesynchroniseerd vanuit Active Directory.
  • NetbiosDomain\sAMAccountName: beschikbaar voor groepen die zijn gesynchroniseerd vanuit Active Directory.
  • DNSDomainName\sAMAccountName: beschikbaar voor groepen die zijn gesynchroniseerd vanuit Active Directory.
  • On-premises group security identifier: beschikbaar voor groepen die zijn gesynchroniseerd vanuit Active Directory.

Notitie

De kenmerken sAMAccountName en on-premises GroupSID zijn alleen beschikbaar voor groepsobjecten die zijn gesynchroniseerd vanuit Active Directory. Ze zijn niet beschikbaar voor groepen die zijn gemaakt in Microsoft Entra ID of Office 365. Toepassingen die zijn geconfigureerd in Microsoft Entra ID om gesynchroniseerde on-premises groepskenmerken op te halen, krijgen ze alleen voor gesynchroniseerde groepen.

Opties voor toepassingen om groepsgegevens te gebruiken

Toepassingen kunnen het eindpunt van de Microsoft Graph-groep aanroepen om groepsgegevens voor de geverifieerde gebruiker op te halen. Deze aanroep zorgt ervoor dat alle groepen waar een gebruiker lid is, beschikbaar zijn, zelfs wanneer het om een groot aantal groepen gaat. Groepsopsomming is vervolgens onafhankelijk van beperkingen voor tokengrootte.

Als een bestaande toepassing echter verwacht groepsgegevens te gebruiken via claims, kunt u Microsoft Entra-id configureren met verschillende claimindelingen. Overweeg de volgende opties:

  • Wanneer u groepslidmaatschap gebruikt voor autorisatie in toepassingen, is het raadzaam om het groepskenmerk ObjectID te gebruiken. Het groepskenmerk ObjectID is onveranderbaar en uniek in Microsoft Entra-id. Dit is beschikbaar voor alle groepen.

  • Als u het kenmerk sAMAccountName van de on-premises groep gebruikt voor autorisatie, gebruikt u namen die door een domein zijn gekwalificeerd. Het vermindert de kans op conflicten tussen namen. sAMAccountName kan uniek zijn binnen een Active Directory-domein, maar als meer dan één Active Directory-domein wordt gesynchroniseerd met een Microsoft Entra-tenant, is er een mogelijkheid dat meer dan één groep dezelfde naam heeft.

  • Overweeg het gebruik van toepassingsrollen om een laag van indirectie te bieden tussen het groepslidmaatschap en de toepassing. De toepassing neemt vervolgens interne autorisatiebeslissingen op basis van rolclaims in het token.

  • Als de toepassing is geconfigureerd voor het ophalen van groepskenmerken die zijn gesynchroniseerd vanuit Active Directory en een groep deze kenmerken niet bevat, wordt deze niet opgenomen in de claims.

  • Groepsclaims in tokens bevatten geneste groepen, behalve wanneer u de optie gebruikt om de groepsclaims te beperken tot groepen die aan de toepassing zijn toegewezen.

    Als een gebruiker lid is van Groep B en Groep B lid is van Groep A, bevatten de groepsclaims voor de gebruiker zowel Groep A als Groep B. Wanneer de gebruikers van een organisatie een groot aantal groepslidmaatschappen hebben, kan het aantal groepen in het token de grootte van het token vergroten. Microsoft Entra ID beperkt het aantal groepen dat wordt verzonden in een token naar 150 voor SAML-asserties en 200 voor JWT. Als een gebruiker lid is van een groot aantal groepen, worden de groepen weggelaten. In plaats daarvan wordt een koppeling naar het Microsoft Graph-eindpunt opgenomen om groepsgegevens op te halen.

Vereisten voor het gebruik van groepskenmerken die vanuit Active Directory zijn gesynchroniseerd

Claims voor groepslidmaatschappen kunnen voor elke groep in tokens worden verzonden als u de ObjectId-indeling gebruikt. Als u groepsclaims wilt gebruiken in andere indelingen dan groepObjectId, moeten de groepen worden gesynchroniseerd vanuit Active Directory via Microsoft Entra Verbinding maken.

Microsoft Entra-id configureren voor het verzenden van groepsnamen voor Active Directory-groepen:

  1. Groepsnamen synchroniseren vanuit Active Directory

    Voordat Microsoft Entra ID de groepsnamen of on-premises groeps-SID in groeps- of rolclaims kan verzenden, moet u de vereiste kenmerken uit Active Directory synchroniseren. U moet Microsoft Entra Verbinding maken versie 1.2.70 of hoger uitvoeren. Eerdere versies van Microsoft Entra Verbinding maken dan 1.2.70 synchroniseren de groepsobjecten uit Active Directory, maar bevatten niet de vereiste groepsnaamkenmerken.

  2. De toepassingsregistratie in Microsoft Entra-id configureren om groepsclaims op te nemen in tokens

    U kunt groepsclaims configureren in de sectie Bedrijfstoepassingen van de portal of met behulp van het toepassingsmanifest in de sectie Toepassingsregistraties. Zie Microsoft Entra-toepassingsregistratie configureren voor groepskenmerken verderop in dit artikel voor het configureren van groepsclaims in het toepassingsmanifest .

Groepsclaims toevoegen aan tokens voor SAML-toepassingen met behulp van SSO-configuratie

U kunt als volgt groepsclaims configureren voor SAML-toepassing in een galerie of buiten een galerie via eenmalige aanmelding (SSO):

  1. Open Bedrijfstoepassingen, selecteer de toepassing in de lijst, selecteer Single sign-on configuratie en selecteer vervolgens Gebruikerskenmerken & Claims.

  2. Selecteer Een groepsclaim toevoegen.

    Schermopname met de pagina voor gebruikerskenmerken en claims, met de knop voor het toevoegen van een groepsclaim geselecteerd.

  3. Gebruik de opties om te selecteren welke groepen moeten worden opgenomen in het token.

    Schermopname met het venster Groepsclaims met groepsopties.

    Selectie Beschrijving
    Alle groepen Hiermee worden beveiligingsgroepen, distributielijsten en rollen verzonden.
    Beveiligingsgroepen Hiermee worden beveiligingsgroepen verzonden waarvan de gebruiker lid is in de groepsclaim. Als de gebruiker directoryrollen heeft toegewezen, worden ze verzonden als object-id.
    Directory-rollen Als directory-rollen aan de gebruiker zijn toegewezen, worden deze verzonden als een wids-claim. (De claim van de groep wordt niet verzonden.)
    Groepen die zijn toegewezen aan de toepassing Verzendt alleen de groepen die expliciet zijn toegewezen aan de toepassing en waarvan de gebruiker lid is. Aanbevolen voor grote organisaties vanwege de limiet voor het aantal groepen in het token.

    • Als u bijvoorbeeld alle beveiligingsgroepen wilt verzenden waarvan de gebruiker lid is, selecteert u Beveiligingsgroepen.

      Schermopname met het venster Groepsclaims, met de optie voor beveiligingsgroepen geselecteerd.

      Als u groepen wilt verzenden met behulp van Active Directory-kenmerken die zijn gesynchroniseerd vanuit Active Directory in plaats van Microsoft Entra ID-kenmerken objectID , selecteert u de vereiste indeling in de vervolgkeuzelijst Bronkenmerk . Alleen groepen die vanuit Active Directory zijn gesynchroniseerd, worden opgenomen in de claims.

      Schermopname met het vervolgkeuzemenu voor het bronkenmerk.

    • Als u alleen groepen wilt verzenden die aan de toepassing zijn toegewezen, selecteert u Groepen die zijn toegewezen aan de toepassing.

      Schermopname met het venster Groepsclaims, met de opties voor groepen die aan de toepassing zijn toegewezen, geselecteerd.

      Groepen die aan de toepassing zijn toegewezen, worden opgenomen in het token. Andere groepen waarvan de gebruiker lid is, worden weggelaten. Met deze optie worden geneste groepen niet opgenomen en moet de gebruiker een direct lid zijn van de groep die is toegewezen aan de toepassing.

      Als u de groepen wilt wijzigen die aan de toepassing zijn toegewezen, selecteert u de toepassing in de lijst Ondernemingstoepassingen. Selecteer vervolgens Gebruikers en groepen in het linkermenu van de toepassing.

      Zie Een gebruiker of groep toewijzen aan een bedrijfs-app voor meer informatie over het beheren van groepstoewijzingen aan toepassingen.

Weergavenaam van de cloudgroep in token verzenden

U kunt groepsclaim configureren om de weergavenaam van de groep op te nemen voor de cloudgroepen.

  1. Open Bedrijfstoepassingen, selecteer de toepassing in de lijst, selecteer Single sign-on configuratie en selecteer vervolgens Gebruikerskenmerken & Claims.

  2. Als u al groepsclaims hebt geconfigureerd, selecteert u deze in de sectie Aanvullende claims . Anders kunt u de groepsclaim toevoegen zoals beschreven in de vorige stappen.

  3. Voor het groepstype dat in het token wordt verzonden, selecteert u Groepen die aan de toepassing zijn toegewezen:

    Schermopname met het venster Groepsclaims, met de opties voor groepen die aan de toepassing zijn toegewezen, geselecteerd.

  4. Als u alleen de weergavenaam van een groep wilt verzenden voor cloudgroepen, selecteert u in de vervolgkeuzelijst Bronkenmerk de weergavenamen van de cloudgroep:

    Schermopname van de vervolgkeuzelijst bronkenmerk Groepsclaims, met de optie voor het configureren van alleen groepsnamen in de cloud geselecteerd.

  5. Als u voor een hybride installatie een on-premises groepskenmerk wilt verzenden voor gesynchroniseerde groepen en de weergavenaam voor cloudgroepen, kunt u het gewenste kenmerk voor on-premises bronnen selecteren en het selectievakje Groepsnaam verzenden voor cloudgroepen inschakelen:

    Schermopname van de configuratie voor het verzenden van een on-premises groepskenmerk voor gesynchroniseerde groepen en de weergavenaam voor cloudgroepen.

Notitie

U kunt alleen cloudgroepnamen van toegewezen groepen toevoegen aan een toepassing. De beperking hiervoor groups assigned to the application is dat een groepsnaam niet uniek is en weergavenamen alleen kunnen worden verzonden voor groepen die expliciet aan de toepassing zijn toegewezen om de beveiligingsrisico's te verminderen. Anders kan elke gebruiker een groep met dubbele naam maken en toegang krijgen tot de toepassingszijde.

Geavanceerde opties instellen

Naam van groepsclaim aanpassen

U kunt de manier wijzigen waarop groepsclaims worden verzonden met behulp van de instellingen onder Geavanceerde opties.

Als u De naam van de groepsclaim aanpassen selecteert, kunt u een ander claimtype opgeven voor groepsclaims. Voer in het vak Naam het claimtype in en voer in het vak Naamruimte de optionele naamruimte voor de claim in.

Schermopname met geavanceerde opties, met de optie voor het aanpassen van de naam van de groepsclaim geselecteerd en de waarden voor naam en naamruimte ingevoerd.

Voor sommige toepassingen moeten de gegevens van het groepslidmaatschap worden weergegeven in de rolclaim. U kunt de groepen van de gebruiker desgewenst als rollen verzenden door het selectievakje Groepen verzenden als rolclaims in te schakelen.

Schermopname met geavanceerde opties, met de selectievakjes ingeschakeld voor het aanpassen van de naam van de groepsclaim en het verwijderen van groepen als rolclaims.

Notitie

Als u de optie gebruikt om groepsgegevens als rollen te verzenden, worden alleen groepen weergegeven in de rolclaim. Toepassingsrollen waaraan de gebruiker is toegewezen, worden niet weergegeven in de rolclaim.

Groepsfilters

Met groepsfilters kunt u de lijst met groepen die deel uitmaken van de groepsclaim nauwkeurig beheren. Wanneer een filter is geconfigureerd, worden alleen groepen die overeenkomen met het filter opgenomen in de claim van de groep die naar die toepassing wordt verzonden. Het filter wordt toegepast op alle groepen, ongeacht de groepshiërarchie.

Notitie

Groepsfiltering is van toepassing op tokens die worden verzonden voor apps waarbij groepsclaims en filters zijn geconfigureerd op de blade Bedrijfs-apps in de portal.
Groepsfiltering is niet van toepassing op Microsoft Entra-rollen.

U kunt filters configureren die moeten worden toegepast op de weergavenaam of het kenmerk SAMAccountName van de groep. De volgende filterbewerkingen worden ondersteund:

  • Voorvoegsel: komt overeen met het begin van het geselecteerde kenmerk.
  • Achtervoegsel: komt overeen met het einde van het geselecteerde kenmerk.
  • Bevat: komt overeen met een locatie in het geselecteerde kenmerk.

Schermopname met filteropties.

Groepstransformatie

Voor sommige toepassingen zijn mogelijk de groepen in een andere indeling vereist dan de manier waarop ze worden weergegeven in Microsoft Entra-id. Ter ondersteuning van deze vereiste kunt u een transformatie toepassen op elke groep die wordt verzonden in de groepsclaim. U bereikt dit door de configuratie van een reguliere expressie (regex) en een vervangingswaarde voor aangepaste groepsclaims toe te staan.

Schermopname van groepstransformatie, waarbij regex-informatie is toegevoegd.\

  • Regex-patroon: gebruik een regex (reguliere expressie) om teksttekenreeksen te parseren naar het patroon dat u in dit vak instelt. Als het regex-patroon dat u beschrijft, wordt geëvalueerd naar true, wordt het regex-vervangingspatroon uitgevoerd.
  • Regex-vervangingspatroon: geef in de regex-indeling aan hoe uw tekenreeks moet worden vervangen als het regex-patroon dat u opgeeft, wordt geëvalueerd naar true. Gebruik Groepen vastleggen om subexpressies in deze vervangende regex te vinden.

Zie Het objectmodel reguliere expressie: de vastgelegde groep voor meer informatie over regex-vervanging en het vastleggen van groepen.

Notitie

Zoals beschreven in de Documentatie van Microsoft Entra, kunt u een beperkte claim niet wijzigen met behulp van een beleid. De gegevensbron kan niet worden gewijzigd en er wordt geen transformatie toegepast wanneer u deze claims genereert. De groepsclaim is nog steeds een beperkte claim, dus u moet de groepen aanpassen door de naam te wijzigen. Als u een beperkte naam selecteert voor de naam van uw aangepaste groepsclaim, wordt de claim tijdens runtime genegeerd.

U kunt de regex-transformatiefunctie ook gebruiken als filter, omdat groepen die niet overeenkomen met het regex-patroon niet worden verzonden in de resulterende claim.

Als de transformatie die op de oorspronkelijke groepenclaim wordt toegepast, resulteert in een nieuwe aangepaste claim, wordt de oorspronkelijke groepsclaim weggelaten uit het token. Als de geconfigureerde regex echter niet overeenkomt met een waarde in de oorspronkelijke lijst, is de aangepaste claim niet aanwezig en wordt de oorspronkelijke groepsclaim opgenomen in het token.

De configuratie van de groepsclaim bewerken

Nadat u een groepsclaimconfiguratie hebt toegevoegd aan de configuratie gebruikerskenmerken en claims , is de optie om een groepsclaim toe te voegen niet beschikbaar. Als u de configuratie van de groepsclaim wilt wijzigen, selecteert u de groepsclaim in de lijst Aanvullende claims.

Schermopname van het gebied voor gebruikerskenmerken en claims, met de naam van een groepsclaim gemarkeerd.

De registratie van de Microsoft Entra-toepassing configureren voor groepskenmerken

U kunt ook groepsclaims configureren in de sectie optionele claims van het toepassingsmanifest.

  1. Selecteer in de portal identiteitstoepassingen>> App-registraties> Selecteer toepassingsmanifest.>

  2. Schakel claims voor groepslidmaatschap in door groupMembershipClaims te wijzigen.

    Geldige waarden zijn:

    Selectie Beschrijving
    All Hiermee worden beveiligingsgroepen, distributielijsten en rollen verzonden.
    SecurityGroup Verzendt beveiligingsgroepen en Microsoft Entra-rollen waarvan de gebruiker lid is in de groepsclaim.
    DirectoryRole Als directory-rollen aan de gebruiker zijn toegewezen, worden deze verzonden als een wids-claim. (Er wordt geen groepsclaim verzonden.)
    ApplicationGroup Verzendt alleen de groepen die expliciet zijn toegewezen aan de toepassing en waarvan de gebruiker lid is.
    None Er worden geen groepen geretourneerd. (Dit is niet hoofdlettergevoelig, dus none werkt ook. Dit kan rechtstreeks in het toepassingsmanifest worden ingesteld.)

    Voorbeeld:

    "groupMembershipClaims": "SecurityGroup"

    Standaard worden ObjectID-kenmerken van een groep verzonden in de waarde van de groepsclaim. Als u de claimwaarde wilt wijzigen zodat deze on-premises groepskenmerken bevat, of als u het claimtype wilt wijzigen in een rol, gebruikt u de optionalClaims-configuratie die in de volgende stap wordt beschreven.

  3. Stel optionele claims in voor groepsnaamconfiguratie.

    Als u wilt dat de groepen in het token de on-premises Active Directory-groepskenmerken bevatten, geeft u op welke optionele claim voor tokentypen moet worden toegepast in de sectie optionalClaims. U kunt meerdere tokentypen weergeven:

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

    Notitie

    Het Saml2Token-type is van toepassing op tokens in zowel SAML1.1- als SAML2.0-indeling.

    Wijzig voor elk relevant tokentype de groepsclaim zodat deze de sectie optionalClaims in het manifest gebruikt. 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. Weglaten of null opgeven.
    essential Niet gebruikt. Weglaten of false opgeven.
    additionalProperties Lijst met aanvullende eigenschappen. Geldige opties zijn"sam_account_name", , , "netbios_domain_and_sam_account_name"en "emit_as_roles""cloud_displayname""dns_domain_and_sam_account_name".

    In additionalProperties is slechts één van de opties "sam_account_name", "dns_domain_and_sam_account_name" of "netbios_domain_and_sam_account_name" vereist. Als er meer dan één aanwezig is, wordt de eerste gebruikt en worden alle andere genegeerd.

    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 deze toe "emit_as_roles" aan aanvullende eigenschappen. De groepswaarden worden verzonden in de rolclaim.

    Als u de weergavenaam van een groep wilt verzenden voor groepen in de cloud, kunt u toevoegen "cloud_displayname" aan additional properties. Deze optie werkt alleen als “groupMembershipClaims” deze is ingesteld op ApplicationGroup

    Notitie

    Als u "emit_as_roles" gebruikt, worden alle geconfigureerde toepassingsrollen waaraan de gebruiker is toegewezen, niet weergegeven in de rolclaim.

Voorbeelden

Groepen verzenden als groepsnamen in OAuth-toegangstokens in de DNSDomainName\sAMAccountName-indeling:

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

Groepsnamen verzenden die in de NetbiosDomain\sAMAccountName-indeling moeten worden geretourneerd als de rolclaim 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"]
    }]
}

Volgende stappen