Konfigurera gruppanspråk för program med hjälp av Microsoft Entra-ID

  • Artikel

Microsoft Entra-ID kan ange information om en användares gruppmedlemskap i token för användning i program. Den här funktionen har stöd för tre huvudsakliga mönster:

  • Grupper som identifieras av deras Microsoft Entra-objektidentifierare (OID)
  • Grupper som identifieras med sAMAccountName attributet eller GroupSID för Active Directory-synkroniserade grupper och användare
  • Grupper som identifieras med deras visningsnamnsattribut för endast molngrupper

Viktigt!

Antalet grupper som genereras i en token är begränsat till 150 för SAML-försäkran och 200 för JWT, inklusive kapslade grupper. I större organisationer kan antalet grupper där en användare är medlem överskrida den gräns som Microsoft Entra-ID lägger till i en token. Om du överskrider en gräns kan det leda till oförutsägbara resultat. För lösningar på dessa gränser kan du läsa mer i Viktiga varningar för den här funktionen.

Viktiga varningar för den här funktionen

  • Stöd för användning av sid-attribut (och säkerhetsidentifierare) som synkroniserats lokalt är utformat för att möjliggöra flytt av sAMAccountName befintliga program från Active Directory Federation Services (AD FS) (AD FS) och andra identitetsprovidrar. Grupper som hanteras i Microsoft Entra-ID innehåller inte de attribut som krävs för att generera dessa anspråk.

  • För att undvika antalet grupper om användarna har ett stort antal gruppmedlemskap kan du begränsa de grupper som genereras i anspråk till relevanta grupper för programmet. Läs mer om att generera grupper som tilldelats till programmet för JWT-token och SAML-token. Om det inte går att tilldela grupper till dina program kan du även konfigurera ett gruppfilter för att minska antalet grupper som genereras i anspråket. Gruppfiltrering gäller för token som genereras för appar där gruppanspråk och filtrering har konfigurerats på bladet Företagsappar i portalen.

  • Gruppanspråk har en gräns på fem grupper om token utfärdas via det implicita flödet. Token som begärs via det implicita flödet har endast ett "hasgroups":true anspråk om användaren finns i fler än fem grupper.

  • Vi rekommenderar att du baserar auktorisering i appen på programroller i stället för grupper när:

    • Du utvecklar ett nytt program, eller så kan ett befintligt program konfigureras för det.
    • Stöd för kapslade grupper krävs inte.

    Användning av programroller begränsar mängden information som behöver gå in i token, är säkrare och separerar användartilldelning från appkonfiguration.

Gruppera anspråk för program som migrerar från AD FS och andra identitetsprovidrar

Många program som är konfigurerade för att autentisera med AD FS förlitar sig på gruppmedlemskapsinformation i form av Windows Server Active Directory-gruppattribut. Dessa attribut är gruppen sAMAccountName, som kan vara kvalificerad efter domännamn, eller Windows-gruppens säkerhetsidentifierare (GroupSID). När programmet federeras med AD FS använder TokenGroups AD FS funktionen för att hämta gruppmedlemskapen för användaren.

En app som har flyttats från AD FS behöver anspråk i samma format. Grupp- och rollanspråk som genereras från Microsoft Entra-ID kan innehålla det domänkvalificerade sAMAccountName attributet eller attributet GroupSID som synkroniserats från Active Directory i stället för gruppens Microsoft Entra-ID-attribut objectID .

Format som stöds för gruppanspråk är:

  • Objekt-ID för Microsoft Entra-grupp: Tillgängligt för alla grupper.
  • sAMAccountName: Tillgängligt för grupper som synkroniserats från Active Directory.
  • NetbiosDomain\sAMAccountName: Tillgängligt för grupper som synkroniserats från Active Directory.
  • DNSDomainName\sAMAccountName: Tillgängligt för grupper som synkroniserats från Active Directory.
  • Säkerhetsidentifierare för lokal grupp: Tillgänglig för grupper som synkroniserats från Active Directory.

Kommentar

sAMAccountName och lokala GroupSID attribut är endast tillgängliga för gruppobjekt som synkroniserats från Active Directory. De är inte tillgängliga för grupper som skapats i Microsoft Entra-ID eller Office 365. Program som konfigurerats i Microsoft Entra-ID för att synkronisera lokala gruppattribut hämtar dem endast för synkroniserade grupper.

Alternativ för program att använda gruppinformation

Program kan anropa Microsoft Graph-gruppens slutpunkt för att hämta gruppinformation för den autentiserade användaren. Det här anropet säkerställer att alla grupper där en användare är medlem är tillgängliga, även när ett stort antal grupper är inblandade. Gruppuppräkning är sedan oberoende av begränsningar för tokenstorlek.

Men om ett befintligt program förväntar sig att använda gruppinformation via anspråk kan du konfigurera Microsoft Entra-ID med olika anspråksformat. Överväg följande alternativ:

  • När du använder gruppmedlemskap för auktorisering i programmet är det bättre att använda gruppattributet ObjectID . Gruppattributet ObjectID är oföränderligt och unikt i Microsoft Entra-ID. Den är tillgänglig för alla grupper.

  • Om du använder det lokala gruppattributet sAMAccountName för auktorisering använder du domänkvalificerade namn. Det minskar risken för att namn kolliderar. sAMAccountName kan vara unikt i en Active Directory-domän, men om fler än en Active Directory-domän synkroniseras med en Microsoft Entra-klient finns det en möjlighet för fler än en grupp att ha samma namn.

  • Överväg att använda programroller för att tillhandahålla ett lager av indirektion mellan gruppmedlemskapet och programmet. Programmet fattar sedan interna auktoriseringsbeslut baserat på rollanspråk i token.

  • Om programmet är konfigurerat för att hämta gruppattribut som synkroniseras från Active Directory och en grupp inte innehåller dessa attribut, tas det inte med i anspråken.

  • Gruppanspråk i token inkluderar kapslade grupper, förutom när du använder alternativet för att begränsa gruppanspråken till grupper som har tilldelats till programmet.

    Om en användare är medlem i GroupB och GroupB är medlem i GroupA, kommer gruppanspråken för användaren att innehålla både GroupA och GroupB. När en organisations användare har ett stort antal gruppmedlemskap kan antalet grupper som anges i token öka tokenstorleken. Microsoft Entra ID begränsar antalet grupper som genereras i en token till 150 för SAML-intyg och 200 för JWT. Om en användare är medlem i ett större antal grupper utelämnas grupperna. En länk till Microsoft Graph-slutpunkten för att hämta gruppinformation ingår i stället.

Förutsättningar för att använda gruppattribut som synkroniserats från Active Directory

Anspråk på gruppmedlemskap kan genereras i token för valfri grupp om du använder ObjectId formatet. Om du vill använda gruppanspråk i andra format än grupp ObjectIdmåste grupperna synkroniseras från Active Directory via Microsoft Entra Anslut.

Så här konfigurerar du Microsoft Entra-ID för att generera gruppnamn för Active Directory-grupper:

  1. Synkronisera gruppnamn från Active Directory

    Innan Microsoft Entra-ID kan generera gruppnamn eller lokalt grupp-SID i grupp- eller rollanspråk måste du synkronisera de attribut som krävs från Active Directory. Du måste köra Microsoft Entra Anslut version 1.2.70 eller senare. Tidigare versioner av Microsoft Entra Anslut än 1.2.70 synkroniserar gruppobjekten från Active Directory, men de innehåller inte de obligatoriska gruppnamnsattributen.

  2. Konfigurera programregistreringen i Microsoft Entra-ID för att inkludera gruppanspråk i token

    Du kan konfigurera gruppanspråk i avsnittet Företagsprogram i portalen eller genom att använda programmanifestet i avsnittet Programregistreringar. Information om hur du konfigurerar gruppanspråk i programmanifestet finns i Konfigurera Microsoft Entra-programregistrering för gruppattribut senare i den här artikeln.

Lägga till gruppanspråk till token för SAML-program med SSO-konfiguration

Så här konfigurerar du gruppanspråk för ett galleri eller ett SAML-program som inte är ett galleri via enkel inloggning (SSO):

  1. Öppna Företagsprogram, välj programmet i listan, välj Enkel inloggning konfiguration och välj sedan Användarattribut och anspråk.

  2. Välj Lägg till ett gruppanspråk.

    Skärmbild som visar sidan för användarattribut och anspråk, med knappen för att lägga till ett gruppanspråk valt.

  3. Använd alternativen för att välja vilka grupper som ska ingå i token.

    Skärmbild som visar fönstret Gruppanspråk med gruppalternativ.

    Urval beskrivning
    Alla grupper Genererar säkerhetsgrupper, distributionslistor och roller.
    Säkerhetsgrupper Genererar säkerhetsgrupper som användaren är medlem i i gruppanspråket. Om användaren har tilldelats katalogroller genereras de som objekt-ID.
    Katalogroller Om användaren har tilldelats katalogroller genereras de som ett wids anspråk. (Gruppens anspråk genereras inte.)
    Grupper som tilldelats till programmet Genererar endast de grupper som uttryckligen har tilldelats till programmet och som användaren är medlem i. Rekommenderas för stora organisationer på grund av gruppnummergränsen i token.

    • Om du till exempel vill generera alla säkerhetsgrupper som användaren är medlem i väljer du Säkerhetsgrupper.

      Skärmbild som visar fönstret Gruppanspråk med alternativet för säkerhetsgrupper valt.

      Om du vill generera grupper med hjälp av Active Directory-attribut som synkroniserats från Active Directory i stället för Microsoft Entra ID-attribut objectID väljer du det format som krävs i listrutan Källattribut . Endast grupper som synkroniseras från Active Directory tas med i anspråken.

      Skärmbild som visar den nedrullningsbara menyn för källattributet.

    • Om du bara vill generera grupper som tilldelats programmet väljer du Grupper som tilldelats programmet.

      Skärmbild som visar fönstret Gruppanspråk med alternativet för grupper som tilldelats till programmet valt.

      Grupper som tilldelats till programmet inkluderas i token. Andra grupper som användaren är medlem i utelämnas. Med det här alternativet inkluderas inte kapslade grupper och användaren måste vara direkt medlem i den grupp som tilldelats till programmet.

      Om du vill ändra de grupper som tilldelats programmet väljer du programmet i listan Företagsprogram . Välj sedan Användare och grupper på programmets vänstra meny.

      Mer information om hur du hanterar grupptilldelning till program finns i Tilldela en användare eller grupp till en företagsapp.

Generera visningsnamn för endast molngrupper i token

Du kan konfigurera gruppanspråk för att inkludera gruppvisningsnamnet för de molnbaserade grupperna.

  1. Öppna Företagsprogram, välj programmet i listan, välj Enkel inloggning konfiguration och välj sedan Användarattribut och anspråk.

  2. Om du redan har konfigurerat gruppanspråk väljer du det i avsnittet Ytterligare anspråk . Annars kan du lägga till gruppanspråket enligt beskrivningen i föregående steg.

  3. För den grupptyp som genereras i token väljer du Grupper som tilldelats till programmet:

    Skärmbild som visar fönstret Gruppanspråk med alternativet för grupper som tilldelats till programmet valt.

  4. Om du vill generera gruppvisningsnamn bara för molngrupper går du till listrutan Källattribut och väljer visningsnamnen för gruppen Endast moln:

    Skärmbild som visar listrutan Källattribut för gruppanspråk med alternativet för att konfigurera endast molngruppnamn valt.

  5. För en hybridkonfiguration, för att generera lokalt gruppattribut för synkroniserade grupper och visningsnamn för molngrupper, kan du välja det önskade lokala källattributet och markera kryssrutan Emit group name for cloud-only groups (Generera gruppnamn för endast molngrupper):

    Skärmbild som visar konfigurationen för att generera lokalt gruppattribut för synkroniserade grupper och visningsnamn för molngrupper.

Kommentar

Du kan bara lägga till molngruppsnamn för tilldelade grupper i ett program. Begränsningen till beror på att groups assigned to the application ett gruppnamn inte är unikt och visningsnamn endast kan genereras för grupper som uttryckligen tilldelats till programmet för att minska säkerhetsriskerna. Annars kan alla användare skapa en grupp med dubblettnamn och få åtkomst på programsidan.

Ställ in avancerade alternativ

Anpassa namn på gruppanspråk

Du kan ändra hur gruppanspråk genereras med hjälp av inställningarna under Avancerade alternativ.

Om du väljer Anpassa namnet på gruppanspråket kan du ange en annan anspråkstyp för gruppanspråk. Ange anspråkstypen i rutan Namn och det valfria namnområdet för anspråket i rutan Namnområde .

Skärmbild som visar avancerade alternativ med alternativet att anpassa namnet på gruppanspråket valt och de angivna värdena för namn och namnområde.

Vissa program kräver att gruppmedlemskapsinformationen visas i rollanspråket. Du kan också generera användarens grupper som roller genom att markera kryssrutan Generera grupper som rollanspråk .

Skärmbild som visar avancerade alternativ med kryssrutorna markerade för att anpassa namnet på gruppanspråket och generera grupper som rollanspråk.

Kommentar

Om du använder alternativet för att generera gruppdata som roller visas endast grupper i rollanspråket. Programroller som användaren har tilldelats visas inte i rollanspråket.

Gruppfiltrering

Gruppfiltrering möjliggör fin kontroll över listan över grupper som ingår som en del av gruppanspråket. När ett filter har konfigurerats inkluderas endast grupper som matchar filtret i gruppens anspråk som skickas till programmet. Filtret tillämpas mot alla grupper oavsett grupphierarki.

Kommentar

Gruppfiltrering gäller för token som genereras för appar där gruppanspråk och filtrering har konfigurerats på bladet Företagsappar i portalen.
Gruppfiltrering gäller inte för Microsoft Entra-roller.

Du kan konfigurera filter som ska tillämpas på gruppens visningsnamn eller SAMAccountName attribut. Följande filtreringsåtgärder stöds:

  • Prefix: Matchar början av det valda attributet.
  • Suffix: Matchar slutet av det valda attributet.
  • Innehåller: Matchar valfri plats i det valda attributet.

Skärmbild som visar filtreringsalternativ.

Gruppomvandling

Vissa program kan kräva grupper i ett annat format än hur de representeras i Microsoft Entra-ID. För att stödja det här kravet kan du tillämpa en transformering på varje grupp som ska genereras i gruppanspråket. Du uppnår det genom att tillåta konfigurationen av ett reguljärt uttryck (regex) och ett ersättningsvärde för anpassade gruppanspråk.

Skärmbild av gruppomvandling med regex-information tillagd.\

  • Regex-mönster: Använd en regex för att parsa textsträngar enligt det mönster som du anger i den här rutan. Om regex-mönstret som du beskriver utvärderas till truekörs regex-ersättningsmönstret.
  • Regex-ersättningsmönster: Disposition i regex-notation hur du vill ersätta strängen om regex-mönstret som du beskrev utvärderas till true. Använd avbildningsgrupper för att matcha underuttryck i den här ersättningsredomänen.

Mer information om regex replace and capture-grupper finns i Objektmodellen för reguljära uttryck: Den insamlade gruppen.

Kommentar

Som beskrivs i Microsoft Entra-dokumentationen kan du inte ändra ett begränsat anspråk med hjälp av en princip. Datakällan kan inte ändras och ingen transformering tillämpas när du genererar dessa anspråk. Gruppanspråket är fortfarande ett begränsat anspråk, så du måste anpassa grupperna genom att ändra namnet. Om du väljer ett begränsat namn för namnet på ditt anpassade gruppanspråk ignoreras anspråket vid körning.

Du kan också använda regex-transformeringsfunktionen som ett filter, eftersom grupper som inte matchar regex-mönstret inte genereras i det resulterande anspråket.

Om den transformering som tillämpas på det ursprungliga gruppanspråket resulterar i ett nytt anpassat anspråk utelämnas det ursprungliga gruppanspråket från token. Men om den konfigurerade regexen inte matchar något värde i den ursprungliga listan kommer det anpassade anspråket inte att finnas och det ursprungliga gruppanspråket inkluderas i token.

Redigera konfigurationen för gruppanspråk

När du har lagt till en konfiguration av gruppanspråk i konfigurationen För användarattribut och anspråk är alternativet för att lägga till ett gruppanspråk inte tillgängligt. Om du vill ändra konfigurationen för gruppanspråk väljer du gruppanspråket i listan Ytterligare anspråk .

Skärmbild av området för användarattribut och anspråk, med namnet på ett gruppanspråk markerat.

Konfigurera Microsoft Entra-programregistrering för gruppattribut

Du kan också konfigurera gruppanspråk i det valfria anspråksavsnittet i programmanifestet.

  1. I portalen väljer du Identitetsprogram>> Appregistreringar> Välj programmanifest.>

  2. Aktivera anspråk för gruppmedlemskap genom att ändra groupMembershipClaims.

    Giltiga värden är:

    Urval beskrivning
    All Genererar säkerhetsgrupper, distributionslistor och roller.
    SecurityGroup Genererar säkerhetsgrupper och Microsoft Entra-roller som användaren är medlem i i gruppanspråket.
    DirectoryRole Om användaren har tilldelats katalogroller genereras de som ett wids anspråk. (Ett gruppanspråk genereras inte.)
    ApplicationGroup Genererar endast de grupper som uttryckligen har tilldelats till programmet och som användaren är medlem i.
    None Inga grupper returneras. (Det är inte skiftlägeskänsligt, så none fungerar också. Den kan anges direkt i programmanifestet.)

    Till exempel:

    "groupMembershipClaims": "SecurityGroup"

    Som standard genereras gruppattribut ObjectID i gruppanspråksvärdet. Om du vill ändra anspråksvärdet så att det innehåller lokala gruppattribut eller ändra anspråkstypen till en roll använder du konfigurationen optionalClaims som beskrivs i nästa steg.

  3. Ange valfria anspråk för konfiguration av gruppnamn.

    Om du vill att grupperna i token ska innehålla lokal Active Directory gruppattribut anger du vilket valfritt anspråk av tokentyp som ska tillämpas i optionalClaims avsnittet. Du kan lista flera tokentyper:

    • idToken för OIDC-ID-token
    • accessToken för OAuth/OIDC-åtkomsttoken
    • Saml2Token för SAML-token

    Kommentar

    Typen Saml2Token gäller för token i både SAML1.1- och SAML2.0-format.

    För varje relevant tokentyp ändrar du gruppanspråket så att det optionalClaims använder avsnittet i manifestet. Schemat optionalClaims är följande:

    {
"name": "groups",
"source": null,
"essential": false,
"additionalProperties": []
}
    Valfritt anspråksschema Värde
    name Måste vara "groups".
    source Inte använd. Utelämna eller ange null.
    essential Inte använd. Utelämna eller ange false.
    additionalProperties Lista över ytterligare egenskaper. Giltiga alternativ är "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name", "cloud_displayname"och "emit_as_roles".

    I additionalPropertieskrävs bara en av "sam_account_name", "dns_domain_and_sam_account_name"eller "netbios_domain_and_sam_account_name" . Om fler än en finns används den första och andra ignoreras.

    Vissa program kräver gruppinformation om användaren i rollanspråket. Om du vill ändra anspråkstypen från ett gruppanspråk till ett rollanspråk lägger du till "emit_as_roles" ytterligare egenskaper. Gruppvärdena genereras i rollanspråket.

    Om du vill generera gruppvisningsnamn för endast molngrupper kan du lägga till "cloud_displayname" i additional properties. Det här alternativet fungerar bara när “groupMembershipClaims” är inställt på ApplicationGroup

    Kommentar

    Om du använder "emit_as_roles"visas inte några konfigurerade programroller som användaren har tilldelats till i rollanspråket.

Exempel

Generera grupper som gruppnamn i OAuth-åtkomsttoken i DNSDomainName\sAMAccountName format:

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

Generera gruppnamn som ska returneras i NetbiosDomain\sAMAccountName format som rollanspråk i SAML- och OIDC-ID-token:

"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"]
    }]
}

Nästa steg