Konfigurowanie roszczeń grupowych dla aplikacji przy użyciu Microsoft Entra ID

Identyfikator Entra firmy Microsoft może podać informacje o członkostwie w grupach użytkownika w tokenach do użycia w aplikacjach. Ta funkcja obsługuje trzy główne wzorce:

• Grupy zidentyfikowane przez atrybut identyfikatora obiektu Entra firmy Microsoft (OID)
• Grupy zidentyfikowane przez sAMAccountName atrybut lub GroupSID dla grup i użytkowników zsynchronizowanych z usługą Active Directory
• Grupy zidentyfikowane przez ich atrybut Nazwa wyświetlana dla grup przechowywanych wyłącznie w chmurze

Ważne

Liczba grup emitowanych w tokenie jest ograniczona do 150 dla asercji SAML i 200 dla JWT, w tym grup zagnieżdżonych. W większych organizacjach liczba grup, w których użytkownik jest członkiem, może przekroczyć limit, który Microsoft Entra ID stosuje, zanim zostaną wydane załączenia oświadczeń grupowych do tokenu. Przekroczenie tego limitu spowoduje, że Microsoft Entra ID całkowicie pominie wysyłanie oświadczeń grupy w tokenie. Aby uzyskać obejścia tych limitów, przeczytaj więcej w artykule Ważne zastrzeżenia dotyczące tej funkcji.

Ważne zastrzeżenia dotyczące tej funkcji

• Obsługa używania atrybutów sAMAccountName i identyfikatora zabezpieczeń (SID) synchronizowanych ze środowiska lokalnego została zaprojektowana w celu umożliwienia przenoszenia istniejących aplikacji z usług Active Directory Federation Services (AD FS) i innych dostawców tożsamości. Grupy zarządzane w identyfikatorze Entra firmy Microsoft nie zawierają atrybutów niezbędnych do emitowania tych oświadczeń.

• Aby uniknąć limitu liczby grup, jeśli użytkownicy należą do wielu grup, można ograniczyć grupy uwzględnione w oświadczeniach do odpowiednich dla aplikacji. Przeczytaj więcej na temat emitowania grup przypisanych do aplikacji dla tokenów JWT i tokenów SAML. Jeśli przypisywanie grup do aplikacji nie jest możliwe, można również skonfigurować filtr grupy, aby zmniejszyć liczbę grup emitowanych w deklaracji. Filtrowanie grup dotyczy tokenów emitowanych dla aplikacji, w których oświadczenia grup i filtrowanie zostały skonfigurowane w bloku Aplikacje dla przedsiębiorstw w portalu. Należy pamiętać, że w większych organizacjach liczba grup, w których użytkownik jest członkiem, może przekroczyć limit stosowany przez Microsoft Entra ID przed emitowaniem oświadczeń grup w tokenie. Przekroczenie tego limitu spowoduje, że Microsoft Entra ID całkowicie pominie wysyłanie oświadczeń grup w tokenie.

• Roszczenia grupowe mają limit pięciu grup, jeśli token jest wystawiony za pośrednictwem przepływu niejawnego. Tokeny uzyskane z przepływu niejawnego będą miały "hasgroups":true roszczenie tylko wtedy, gdy użytkownik należy do więcej niż pięciu grup.

• Zalecamy oparcie autoryzacji w aplikacji na rolach aplikacji, a nie na grupach, gdy:

  • Tworzysz nową aplikację lub można skonfigurować istniejącą aplikację.
  • Obsługa zagnieżdżonych grup nie jest konieczna.

  Użycie ról aplikacji ogranicza ilość informacji, które muszą przejść do tokenu, jest bezpieczniejsza i oddziela przypisanie użytkownika od konfiguracji aplikacji.

Roszczenia grup dla aplikacji migrujących z AD FS i innych dostawców tożsamości

Wiele aplikacji skonfigurowanych do uwierzytelniania za pomocą usług AD FS polega na informacji o członkostwie w grupie w postaci atrybutów grupy usługi Active Directory systemu Windows Server. Te atrybuty to grupa sAMAccountName, która może być kwalifikowana przez nazwę domeny lub identyfikator zabezpieczeń grupy systemu Windows (GroupSID). Gdy aplikacja jest zintegrowana z usługami AD FS, usługi AD FS używają funkcji TokenGroups do pobierania członkostwa w grupach dla użytkownika.

Aplikacja przeniesiona z usług AD FS wymaga oświadczeń w tym samym formacie. Oświadczenia grupy i roli emitowane z identyfikatora Microsoft Entra mogą zawierać atrybut sAMAccountName z kwalifikacją domeny lub zsynchronizowany z usługi Active Directory atrybut GroupSID, zamiast atrybutu objectID identyfikatora Microsoft Entra ID grupy.

Obsługiwane formaty oświadczeń grup to:

• Microsoft Entra group ObjectId: dostępny dla wszystkich grup.
• sAMAccountName: dostępne dla grup synchronizowanych z usługi Active Directory.
• NetbiosDomain\sAMAccountName: dostępne dla grup zsynchronizowanych z usługi Active Directory.
• DNSDomainName\sAMAccountName: dostępne dla grup zsynchronizowanych z usługi Active Directory.
• Identyfikator zabezpieczeń grupy lokalnej: dostępny dla grup synchronizowanych z usługą Active Directory.

Uwaga

sAMAccountName i atrybuty lokalne GroupSID są dostępne tylko w obiektach grup, które są synchronizowane z Active Directory. Nie są one dostępne w grupach utworzonych w usłudze Microsoft Entra ID lub Office 365. Aplikacje skonfigurowane w identyfikatorze Entra firmy Microsoft w celu uzyskania zsynchronizowanych atrybutów grupy lokalnej pobierają je tylko dla zsynchronizowanych grup.

Opcje dla aplikacji do korzystania z informacji o grupie

Aplikacje mogą wywoływać punkt końcowy grupy programu Microsoft Graph, aby uzyskać informacje o grupie dla uwierzytelnioowanego użytkownika. To wywołanie zapewnia, że wszystkie grupy, w których użytkownik jest członkiem, są dostępne nawet wtedy, gdy jest zaangażowana duża liczba grup. Wyliczanie grup jest wtedy niezależne od ograniczeń dotyczących rozmiaru tokenu.

Jeśli jednak istniejąca aplikacja oczekuje korzystania z informacji o grupie za pośrednictwem oświadczeń, możesz skonfigurować identyfikator Entra firmy Microsoft z różnymi formatami oświadczeń. Rozważ następujące opcje:

• Jeśli używasz członkostwa w grupie do autoryzacji w aplikacji, zaleca się użycie atrybutu grupy ObjectID . Atrybut grupy ObjectID jest niezmienny i unikatowy w identyfikatorze Entra firmy Microsoft. Jest ona dostępna dla wszystkich grup.

• Jeśli używasz atrybutu grupy sAMAccountName lokalnej do autoryzacji, użyj nazw kwalifikowanych przez domenę. Zmniejsza to prawdopodobieństwo starcia nazw. sAMAccountName może być unikalny w domenie Active Directory, ale jeśli więcej niż jedna domena Active Directory jest synchronizowana z dzierżawą Microsoft Entra, istnieje możliwość, że więcej niż jedna grupa może mieć tę samą nazwę.

• Rozważ użycie ról aplikacji w celu zapewnienia warstwy pośredniej między członkostwem w grupie a aplikacją. Następnie aplikacja, na podstawie roszczeń ról zawartych w tokenie, podejmuje wewnętrzne decyzje dotyczące autoryzacji.

• Jeśli aplikacja jest skonfigurowana do pobierania atrybutów grupy synchronizowanych z usługi Active Directory, a grupa nie zawiera tych atrybutów, nie zostanie uwzględniona w oświadczeniach.

• Roszczenia grupowe w tokenach obejmują grupy zagnieżdżone, z wyjątkiem sytuacji, gdy używasz opcji ograniczenia roszczeń grupowych do grup przypisanych do aplikacji.

  Jeśli użytkownik jest członkiem GrupyB, a GrupaB jest członkiem GrupyA, oświadczenia grupy dla użytkownika będą zawierać zarówno GroupA, jak i GroupB. Gdy użytkownicy organizacji mają dużą liczbę członkostwa w grupach, liczba grup wymienionych w tokenie może zwiększyć rozmiar tokenu. Microsoft Entra ID ogranicza liczbę grup, które będą emitować w tokenie do 150 dla asercji SAML i 200 dla JWT. Jeśli użytkownik jest członkiem większej liczby grup, grupy zostaną pominięte. Zamiast tego znajduje się link do punktu końcowego programu Microsoft Graph w celu uzyskania informacji o grupie.

Wymagania wstępne dotyczące używania atrybutów grupy synchronizowanych z usługi Active Directory

Oświadczenia członkostwa w grupach mogą być emitowane w tokenach dla dowolnej grupy, jeśli używasz ObjectId formatu. Aby można było używać oświadczeń grup w formatach innych niż grupa ObjectId, grupy muszą być synchronizowane z usługi Active Directory za pośrednictwem programu Microsoft Entra Connect.

Aby skonfigurować Microsoft Entra ID do udostępniania nazw grup dla grup domeny Active Directory:

1. Synchronizowanie nazw grup z usługi Active Directory

   Zanim Microsoft Entra ID będzie mógł wydawać nazwy grup lub SID grupy lokalnej w oświadczeniach grupy lub roli, należy zsynchronizować wymagane atrybuty z Active Directory. Musisz uruchomić program Microsoft Entra Connect w wersji 1.2.70 lub nowszej. Wcześniejsze wersje programu Microsoft Entra Connect niż 1.2.70 będą synchronizować obiekty grupy z usługi Active Directory, ale nie będą zawierać wymaganych atrybutów nazwy grupy.

2. Skonfiguruj rejestrację aplikacji w Microsoft Entra ID, aby uwzględniała oświadczenia grup w tokenach

   Oświadczenia grup można skonfigurować w sekcji Aplikacje dla przedsiębiorstw w portalu lub za pomocą manifestu aplikacji w sekcji Rejestracje aplikacji. Aby skonfigurować oświadczenia grupy w manifeście aplikacji, zobacz w dalszej części tego artykułu Konfigurowanie rejestracji aplikacji Microsoft Entra dla atrybutów grupy.

Dodawanie roszczeń grupowych do tokenów dla aplikacji SAML przy użyciu konfiguracji SSO

Aby skonfigurować oświadczenia grup dla galerii lub aplikacji SAML spoza galerii za pomocą logowania jednokrotnego:

1. Otwórz Aplikacje korporacyjne, wybierz aplikację z listy, wybierz Konfigurację logowania jednokrotnego, a następnie wybierz Atrybuty i roszczenia użytkownika.

2. Wybierz Dodaj oświadczenie grupy.

   

3. Użyj opcji, aby wybrać grupy, które mają być uwzględnione w tokenie.

   

   Wybór	opis
   Wszystkie grupy	Generuje grupy zabezpieczeń, listy dystrybucyjne i role.
   Grupy zabezpieczeń	Emituje grupy zabezpieczeń, których użytkownik należy do oświadczenia grup. Jeśli użytkownik ma przypisane role katalogu, są emitowane jako identyfikator obiektu.
   Role katalogu	Jeśli użytkownikowi przypisano role katalogu, są one emitowane jako wids roszczenie. (Oświadczenie grupy nie zostanie wyemitowane).
   Grupy przypisane do aplikacji	Emituje tylko grupy, które są jawnie przypisane do aplikacji i w których użytkownik jest członkiem. Zalecane dla dużych organizacji ze względu na limit liczby grup w tokenie.

   • Aby na przykład emitować wszystkie grupy zabezpieczeń, do których należy użytkownik, wybierz pozycję Grupy zabezpieczeń.

     

     Aby emitować grupy przy użyciu atrybutów Active Directory synchronizowanych z Active Directory zamiast atrybutów Microsoft Entra ID objectID, wybierz wymagany format z listy rozwijanej Źródłowy atrybut. W oświadczeniach będą uwzględniane tylko grupy zsynchronizowane z usługą Active Directory.

     

   • Aby emitować tylko grupy przypisane do aplikacji, wybierz pozycję Grupy przypisane do aplikacji.

     

     Grupy przypisane do aplikacji będą uwzględniane w tokenie. Inne grupy, do których należy użytkownik, zostaną pominięte. W przypadku tej opcji grupy zagnieżdżone nie są uwzględniane, a użytkownik musi być bezpośrednim członkiem grupy przypisanej do aplikacji.

     Aby zmienić grupy przypisane do aplikacji, wybierz aplikację z listy Aplikacje dla przedsiębiorstw. Następnie wybierz pozycję Użytkownicy i grupy z menu po lewej stronie aplikacji.

     Aby uzyskać więcej informacji na temat zarządzania przypisaniem grupy do aplikacji, zobacz Przypisywanie użytkownika lub grupy do aplikacji dla przedsiębiorstw.

Emituj nazwę wyświetlaną grupy tylko w chmurze w tokenie

Oświadczenie grupy można skonfigurować tak, aby uwzględnić nazwę wyświetlaną grupy dla grup tylko w chmurze.

1. Otwórz Aplikacje dla przedsiębiorstw, wybierz aplikację z listy, wybierz Konfigurację jednokrotnego logowania, a następnie Atrybuty użytkownika i oświadczenia.

2. Jeśli masz już skonfigurowane oświadczenia grupy, wybierz je w sekcji Dodatkowe oświadczenia . W przeciwnym razie możesz dodać oświadczenie grupy zgodnie z opisem w poprzednich krokach.

3. Dla typu grupy emitowanego w tokenie wybierz pozycję Grupy przypisane do aplikacji:

   

4. Aby wyświetlić nazwę wyświetlaną tylko dla grup w chmurze, w rozwijanym polu Atrybut Źródłowy wybierz Nazwy wyświetlane tylko dla grup w chmurze.

   

5. W przypadku konfiguracji hybrydowej, aby emitować atrybut grupy lokalnej dla zsynchronizowanych grup i nazwę wyświetlaną dla grup w chmurze, można wybrać żądany atrybut źródeł lokalnych i zaznaczyć pole wyboru Emituj nazwę grupy dla grup tylko w chmurze:

   

Uwaga

Do aplikacji można dodawać tylko nazwy grup przypisanych do chmury. Ograniczenie do groups assigned to the application jest spowodowane tym, że nazwa grupy nie jest unikatowa, a nazwa wyświetlana może być widoczna tylko dla grup jawnie przypisanych do aplikacji w celu ograniczenia ryzyka bezpieczeństwa. W przeciwnym razie każdy użytkownik może utworzyć grupę z zduplikowaną nazwą i uzyskać dostęp po stronie aplikacji.

Ustawianie opcji zaawansowanych

Dostosuj nazwę roszczenia grupy

Możesz zmodyfikować sposób emitowania oświadczeń grup przy użyciu ustawień w obszarze Opcje zaawansowane.

Jeśli wybierzesz pozycję Dostosuj nazwę oświadczenia grupy, możesz określić inny typ oświadczenia dla oświadczeń grupy. Wprowadź typ roszczenia w polu Nazwa i opcjonalną przestrzeń nazw dla roszczenia w polu Przestrzeń nazw.

Niektóre aplikacje wymagają, aby informacje o członkostwie w grupie pojawiały się w oświadczeniu roli. Opcjonalnie możesz emitować grupy użytkownika jako roszczenia ról, zaznaczając pole wyboru Emituj grupy jako roszczenia ról.

Uwaga

Jeśli używasz opcji do emitowania danych grupy jako ról, tylko grupy będą wyświetlane w oświadczeniu roli. Wszystkie role aplikacji przypisane do użytkownika nie będą wyświetlane w oświadczeniu roli.

Filtrowanie grup

Filtrowanie grup umożliwia precyzyjną kontrolę nad listą grup uwzględnionych w ramach oświadczenia grupy. Po skonfigurowaniu filtru tylko grupy zgodne z filtrem zostaną uwzględnione w oświadczeniu grupy, które jest wysyłane do tej aplikacji. Filtr zostanie zastosowany do wszystkich grup niezależnie od hierarchii grup.

Uwaga

Filtrowanie grup dotyczy tokenów emitowanych dla aplikacji, w których oświadczenia grup i filtrowanie zostały skonfigurowane w portalu, w sekcji aplikacje dla przedsiębiorstw.
Filtrowanie grup nie ma zastosowania do ról firmy Microsoft Entra.

Filtry można skonfigurować tak, aby były stosowane do nazwy wyświetlanej lub SAMAccountName atrybutu grupy. Obsługiwane są następujące operacje filtrowania:

• Prefiks: pasuje do początku wybranego atrybutu.
• Sufiks: pasuje do końca wybranego atrybutu.
• Zawiera: Pasuje do dowolnej lokalizacji w wybranym atrybucie.

Przekształcenie grupy

Niektóre aplikacje mogą wymagać grup w innym formacie niż sposób ich reprezentowania w identyfikatorze Entra firmy Microsoft. Aby obsłużyć to wymaganie, można zastosować przekształcenie do każdej grupy, która będzie uwzględniona w deklaracji grupy. Można to osiągnąć, zezwalając na konfigurację wyrażenia regularnego (regex) i wartość zastępczą w oświadczeniach grupy niestandardowej.

\

• Wzorzec wyrażenia regularnego: użyj wyrażenia regularnego, aby przeanalizować ciągi tekstowe zgodnie ze wzorcem, który ustawiasz w tym polu. Jeśli wzorzec wyrażenia regularnego, który zdefiniujesz, przyjmie wartość true, zostanie uruchomiony zamiennik wyrażenia regularnego.
• Wzorzec zamiany wyrażeń regularnych: Przedstaw w notacji wyrażeń regularnych, jak chcesz zastąpić ciąg, jeśli wzorzec wyrażenia regularnego, który przedstawiłeś, daje wartość true. Użyj grup przechwytywania, aby dopasować podwyrażenia w tym zastępczym wyrażeniu regularnym.

Aby uzyskać więcej informacji na temat grup zastępowania i przechwytywania wyrażeń regularnych, zobacz Model obiektów wyrażeń regularnych: przechwycona grupa.

Uwaga

Zgodnie z opisem w dokumentacji Microsoft Entra, nie można zmodyfikować ograniczonego roszczenia przy użyciu zasad. Nie można zmienić źródła danych i nie jest stosowane żadne przekształcenie podczas generowania tych oświadczeń. Roszczenie grupowe jest nadal ograniczonym roszczeniem, więc musisz dostosować nazwy grup. Jeśli wybierzesz ograniczoną nazwę dla nazwy niestandardowego roszczenia grupy, roszczenie zostanie zignorowane w czasie wykonywania.

Można również użyć funkcji transformacji wyrażeń regularnych jako filtru, ponieważ jakiekolwiek grupy, które nie pasują do wzorca wyrażenia regularnego, nie będą uwzględniane w wynikowym zgłoszeniu.

Jeśli przekształcenie zastosowane do oryginalnego roszczenia grupowego spowoduje powstanie nowego roszczenia niestandardowego, oryginalne roszczenie grupowe zostanie pominięte w tokenie. Jeśli jednak skonfigurowane wyrażenie regularne nie pasuje do żadnej wartości na oryginalnej liście, niestandardowy atrybut roszczenia nie będzie obecny, a roszczenie dla oryginalnych grup zostanie uwzględnione w tokenie.

Edytuj konfigurację uprawnień grupy

Po dodaniu konfiguracji oświadczenia grupy do konfiguracji Atrybuty użytkownika i oświadczenia opcja dodania oświadczenia grupy będzie niedostępna. Aby zmienić konfigurację oświadczenia grupy, wybierz oświadczenie grupy na liście Dodatkowe oświadczenia .

Konfiguracja rejestracji aplikacji Microsoft Entra dla atrybutów grupy

Można również skonfigurować oświadczenia grup w sekcji opcjonalnych oświadczeń w manifeście aplikacji.

1. W portalu wybierz Tożsamość>Aplikacje>Rejestracje aplikacji>Wybierz manifest aplikacji.>

2. Włącz oświadczenia członkostwa w grupie, zmieniając wartość groupMembershipClaims.

   Prawidłowe wartości to:

   Wybór	opis
   All	Emituje grupy zabezpieczeń, listy dystrybucyjne i role.
   SecurityGroup	Emituje grupy zabezpieczeń i role Microsoft Entra, których użytkownik jest członkiem, w ramach roszczenia grupowego.
   DirectoryRole	Jeśli użytkownik ma przypisane role katalogu, emitowane jest to jako wids żądanie. (Oświadczenie grupy nie zostanie wyemitowane).
   ApplicationGroup	Emituje tylko grupy, które są jawnie przypisane do aplikacji i do których użytkownik należy.
   None	Nie są zwracane żadne grupy. (Nie jest uwzględniana wielkość znaków, więc none działa również. Można to ustawić bezpośrednio w ustawieniach manifestu aplikacji).

   Na przykład:

   "groupMembershipClaims": "SecurityGroup"
   

   Domyślnie atrybuty grupy ObjectID będą wydawane w wartości roszczenia grupy. Aby zmodyfikować wartość oświadczenia tak, aby zawierała atrybuty grupy lokalnej lub zmienić typ oświadczenia na rolę, użyj optionalClaims konfiguracji opisanej w następnym kroku.

3. Ustaw opcjonalne oświadczenia dla konfiguracji nazwy grupy.

   Jeśli chcesz, aby grupy w tokenie zawierały atrybuty grup lokalnego Active Directory, określ, które opcjonalne oświadczenie typu tokenu należy zastosować w sekcji optionalClaims. Możesz wyświetlić listę wielu typów tokenów:

   • idToken dla tokenu identyfikatora OIDC
   • accessToken dla tokenu dostępu OAuth/OIDC
   • Saml2Token dla tokenów SAML

   Uwaga

   Typ Saml2Token dotyczy tokenów w formacie SAML1.1 i SAML2.0.

   Dla każdego odpowiedniego typu tokenu zmodyfikuj oświadczenie grupy tak, aby korzystało z sekcji optionalClaims w manifeście. Schemat optionalClaims jest następujący:

   {
   "name": "groups",
   "source": null,
   "essential": false,
   "additionalProperties": []
   }
   

   Schemat opcjonalnych oświadczeń	Wartość
   name	Musi mieć wartość "groups".
   source	Nie używany. Pomiń lub określ null.
   essential	Nie używany. Pomiń lub określ false.
   additionalProperties	Lista dodatkowych właściwości. Prawidłowe opcje to "sam_account_name", , "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name""cloud_displayname", i "emit_as_roles".

   W systemie additionalProperties wymagany jest tylko jeden z "sam_account_name", "dns_domain_and_sam_account_name" lub "netbios_domain_and_sam_account_name". Jeśli istnieje więcej niż jeden element, pierwszy jest używany, a wszystkie inne są ignorowane.

   Niektóre aplikacje wymagają informacji o grupie użytkownika w oświadczeniu roli. Aby zmienić typ oświadczenia z oświadczenia grupy na oświadczenie roli, dodaj "emit_as_roles" do dodatkowych właściwości. Wartości grupy będą emitowane w oświadczeniu roli.

   Aby wyświetlać nazwę wyświetlaną grupy dla grup dostępnych tylko w chmurze, można dodać "cloud_displayname" do additional properties. Ta opcja będzie działać tylko wtedy, gdy “groupMembershipClaims” jest ustawiony na ApplicationGroup

   Uwaga

   Jeśli używasz programu "emit_as_roles", wszystkie skonfigurowane role aplikacji przypisane do użytkownika nie będą wyświetlane w oświadczeniu roli.

Przykłady

Emituj grupy jako nazwy grup w tokenach dostępu OAuth w DNSDomainName\sAMAccountName formacie:

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

Emituj nazwy grup, które mają być zwracane w NetbiosDomain\sAMAccountName formacie jako oświadczenie roli w tokenach SAML i OIDC ID:

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

Następne kroki

• Dodawanie autoryzacji przy użyciu oświadczeń grup i grup do aplikacji internetowej ASP.NET Core (przykład kodu)
• Przypisywanie użytkownika lub grupy do aplikacji dla przedsiębiorstw
• Konfiguracja oświadczeń roli