Konfigurowanie oświadczeń grup dla aplikacji przy użyciu identyfikatora Entra firmy Microsoft

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 tylko 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 dodany przez identyfikator Entra firmy Microsoft do tokenu. Przekroczenie limitu może prowadzić do nieprzewidywalnych wyników. 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 identyfikatora zabezpieczeń (SID) synchronizowanego ze środowiska lokalnego sAMAccountName 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 mają dużą liczbę członkostwa w grupach, można ograniczyć grupy emitowane w oświadczeniach do odpowiednich grup 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 oświadczeniu. 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.

• Oświadczenia grup mają limit pięciu grup, jeśli token jest wystawiany za pośrednictwem przepływu niejawnego. Tokeny żądane za pośrednictwem przepływu niejawnego będą miały "hasgroups":true oświadczenie tylko wtedy, gdy użytkownik znajduje się w więcej niż pięciu grupach.

• 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 wymagana.

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

Oświadczenia grup dla aplikacji migrujących z usług 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 federacyjna z usługami AD FS, usługi AD FS używa TokenGroups funkcji 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 Entra firmy Microsoft mogą zawierać atrybut kwalifikowany sAMAccountName do domeny lub GroupSID atrybut zsynchronizowany z usługi Active Directory, a nie atrybut Microsoft Entra ID objectID 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 atrybuty lokalne GroupSID są dostępne tylko w obiektach grupy synchronizowanych z usługą 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ć unikatowa w domenie usługi Active Directory, ale jeśli więcej niż jedna domena usługi Active Directory jest synchronizowana z dzierżawą firmy Microsoft Entra, istnieje możliwość, że więcej niż jedna grupa ma taką 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 podejmuje wewnętrzne decyzje dotyczące autoryzacji na podstawie oświadczeń ról w tokenie.

• 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.

• Oświadczenia grup w tokenach obejmują grupy zagnieżdżone, z wyjątkiem sytuacji, gdy używasz opcji ograniczenia oświadczeń grupy 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ż grupaObjectId, grupy muszą być synchronizowane z usługi Active Directory za pośrednictwem usługi Microsoft Entra Połączenie.

Aby skonfigurować identyfikator entra firmy Microsoft w celu emitowania nazw grup dla grup usługi Active Directory:

1. Synchronizowanie nazw grup z usługi Active Directory

   Zanim identyfikator entra firmy Microsoft może emitować nazwy grup lub identyfikator SID grupy lokalnej w oświadczeniach grupy lub roli, należy zsynchronizować wymagane atrybuty z usługi Active Directory. Musisz uruchomić program Microsoft Entra Połączenie w wersji 1.2.70 lub nowszej. Wcześniejsze wersje usługi Microsoft Entra Połączenie 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. Konfigurowanie rejestracji aplikacji w identyfikatorze Entra firmy Microsoft w celu uwzględnienia oświadczeń 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 Konfigurowanie rejestracji aplikacji Microsoft Entra dla atrybutów grupy w dalszej części tego artykułu.

Dodawanie oświadczeń grup do tokenów dla aplikacji SAML przy użyciu konfiguracji logowania jednokrotnego

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

1. Otwórz pozycję Aplikacje dla przedsiębiorstw, wybierz aplikację z listy, wybierz pozycję Logowanie jednokrotne konfiguracji, a następnie wybierz pozycję Atrybuty użytkownika i oświadczenia.

2. Wybierz pozycję Dodaj oświadczenie grupy.

   

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

   

   Wybór	opis
   Wszystkie grupy	Emituje grupy zabezpieczeń i 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żytkownik ma przypisane role katalogu, są one emitowane jako wids oświadczenie. (Oświadczenie grupy nie zostanie wyemitowane).
   Grupy przypisane do aplikacji	Emituje tylko grupy, które są jawnie przypisane do aplikacji i że 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 usługi Active Directory synchronizowanych z usługi Active Directory zamiast atrybutów identyfikatora objectID Entra firmy Microsoft, wybierz wymagany format z listy rozwijanej Atrybut źródłowy. 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 pozycję Aplikacje dla przedsiębiorstw, wybierz aplikację z listy, wybierz pozycję Logowanie jednokrotne konfiguracji, a następnie wybierz pozycję 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 emitować nazwę wyświetlaną grupy tylko dla grup w chmurze, na liście rozwijanej Atrybut źródłowy wybierz nazwy wyświetlane grupy tylko 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. Ograniczeniem jest groups assigned to the application to, że nazwa grupy nie jest unikatowa, a nazwy wyświetlane mogą być emitowane tylko dla grup jawnie przypisanych do aplikacji w celu zmniejszenia 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

Dostosowywanie nazwy oświadczenia 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 oświadczenia w polu Nazwa i opcjonalną przestrzeń nazw oświadczenia 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 role, zaznaczając pole wyboru Emituj grupy jako oświadczenia roli.

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 bloku Aplikacje dla przedsiębiorstw w portalu.
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 emitowana w oświadczeniu 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 ustawionym w tym polu. Jeśli wzorzec wyrażenia regularnego, który konspekt zostanie obliczony na truewartość , zostanie uruchomiony wzorzec wymiany wyrażeń regularnych.
• Wzorzec zamiany wyrażeń regularnych: konspekt w notacji wyrażeń regularnych, w jaki chcesz zastąpić ciąg, jeśli wzorzec wyrażenia regularnego, który został opisany, 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 firmy Microsoft Entra nie można zmodyfikować oświadczenia z ograniczeniami przy użyciu zasad. Nie można zmienić źródła danych i nie jest stosowane żadne przekształcenie podczas generowania tych oświadczeń. Oświadczenie grupy jest nadal ograniczonym oświadczeniem, więc musisz dostosować grupy, zmieniając nazwę. Jeśli wybierzesz ograniczoną nazwę oświadczenia grupy niestandardowej, oświadczenie zostanie zignorowane w czasie wykonywania.

Można również użyć funkcji przekształcania wyrażeń regularnych jako filtru, ponieważ wszystkie grupy, które nie pasują do wzorca wyrażenia regularnego, nie będą emitowane w wynikowym oświadczeniu.

Jeśli przekształcenie zastosowane do oryginalnych grup oświadczenia spowoduje wystąpienie nowego oświadczenia niestandardowego, oryginalne oświadczenie grup zostanie pominięte z tokenu. Jeśli jednak skonfigurowane wyrażenie regularne nie jest zgodne z żadną wartością na oryginalnej liście, oświadczenie niestandardowe nie będzie obecne, a oryginalne oświadczenie grup zostanie uwzględnione w tokenie.

Edytowanie konfiguracji oświadczenia 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 .

Konfigurowanie rejestracji aplikacji Entra firmy Microsoft dla atrybutów grupy

Oświadczenia grup można również skonfigurować w sekcji opcjonalnych oświadczeń manifestu aplikacji.

1. W portalu wybierz pozycję Aplikacje> tożsamości>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 firmy Microsoft Entra, których użytkownik należy do oświadczenia grupy.
   DirectoryRole	Jeśli użytkownik ma przypisane role katalogu, są one emitowane jako wids oświadczenie. (Oświadczenie grupy nie zostanie wyemitowane).
   ApplicationGroup	Emituje tylko grupy, które są jawnie przypisane do aplikacji i że użytkownik jest członkiem.
   None	Nie są zwracane żadne grupy. (Nie jest uwzględniana wielkość liter, więc none działa również. Można ją ustawić bezpośrednio w manifeście aplikacji).

   Na przykład:

   "groupMembershipClaims": "SecurityGroup"
   

   Domyślnie atrybuty grupy ObjectID będą emitowane w wartości oświadczenia 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 grupy lokalna usługa Active Directory, określ, które opcjonalne oświadczenie typu tokenu należy zastosować w optionalClaims sekcji . 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, aby użyć optionalClaims sekcji 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 wartość null.
   essential	Nie używany. Pomiń lub określ wartość false.
   additionalProperties	Lista dodatkowych właściwości. Prawidłowe opcje to "sam_account_name", , "dns_domain_and_sam_account_name", "cloud_displayname""netbios_domain_and_sam_account_name", i "emit_as_roles".

   W additionalPropertiessystemie wymagany jest tylko jeden z "sam_account_name"elementów , "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 emitować nazwę wyświetlaną grupy dla grup tylko w chmurze, można dodać "cloud_displayname" do programu additional properties. Ta opcja będzie działać tylko wtedy, gdy “groupMembershipClaims” jest ustawiona wartość 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
• Konfigurowanie oświadczeń roli