使用 Microsoft Entra ID 設定應用程式的群組宣告

Microsoft Entra ID 可以在令牌中提供使用者的群組成員資格資訊，以在應用程式內使用。 此功能支援三個主要模式：

• 由其 Microsoft Entra 物件識別碼 （OID） 屬性識別的群組
• Active sAMAccountName Directory 同步處理群組和使用者的 或 GroupSID 屬性所識別的群組
• 僅限雲端群組的顯示名稱屬性所識別的群組

重要

令牌中發出的群組數目限制為 150 個 SAML 判斷提示，JWT 則限製為 200 個，包括巢狀群組。 在較大的組織中，用戶是成員的群組數目可能會超過 Microsoft Entra ID 新增至令牌的限制。 超過限制可能會導致無法預期的結果。 如需這些限制的因應措施，請參閱 這項功能的重要注意事項。

這項功能的重要注意事項

• 支援使用sAMAccountName與內部部署同步處理的安全性標識碼 （SID） 屬性，其設計目的是讓現有應用程式從 Active Directory 同盟服務 （AD FS） 和其他識別提供者移動。 在 Microsoft Entra 識別碼中管理的群組不包含發出這些宣告所需的屬性。

• 若要避免使用者擁有大量群組成員資格的群組限制，您可以將宣告中發出的群組限制為應用程式的相關群組。 深入瞭解如何針對 JWT 令牌和 SAML 令牌發出指派給應用程式的群組。 如果無法將群組指派給您的應用程式，您也可以設定 群組篩選 ，以減少宣告中發出的群組數目。 群組篩選適用於針對在入口網站 [ 企業應用程式] 刀鋒視窗中設定群組宣告和篩選的應用程式 發出的令牌。

• 如果令牌是透過隱含流程發出，群組宣告會有五個群組限制。 只有用戶位於五個 "hasgroups":true 以上的群組時，透過隱含流程要求的令牌才會有宣告。

• 我們建議在應用程式角色上以應用程式內授權為基礎，而不是在下列情況下分組：

  • 您正在開發新的應用程式，或可以為其設定現有的應用程式。
  • 不需要巢狀群組的支援。

  使用應用程式角色會限制需要進入令牌的資訊量、更安全，並將使用者指派與應用程式組態分開。

從 AD FS 和其他識別提供者移轉之應用程式的群組宣告

許多設定為使用AD FS進行驗證的應用程式都依賴 Windows Server Active Directory 群組屬性形式的群組成員資格資訊。 這些屬性是群組 sAMAccountName，可能由功能變數名稱或 Windows 群組安全性識別碼 （GroupSID） 限定。 當應用程式與 AD FS 同盟時，AD FS 會使用 函 TokenGroups 式來擷取使用者的群組成員資格。

已從 AD FS 行動應用程式需要相同格式的宣告。 從 Microsoft Entra ID 發出的群組和角色宣告可能包含從 Active Directory 同步處理的網域限定 sAMAccountName 屬性或 GroupSID 屬性，而不是群組的 Microsoft Entra ID objectID 屬性。

群組宣告支援的格式如下：

• Microsoft Entra 群組 ObjectId：適用於所有群組。
• sAMAccountName：適用於從 Active Directory 同步處理的群組。
• NetbiosDomain\sAMAccountName：適用於從 Active Directory 同步處理的群組。
• DNSDomainName\sAMAccountName：適用於從 Active Directory 同步處理的群組。
• 內部部署群組安全性標識碼：適用於從 Active Directory 同步處理的群組。

注意

sAMAccountName 和內部部署 GroupSID 屬性僅適用於從 Active Directory 同步處理的群組物件。 無法在 Microsoft Entra ID 或 Office 365 中建立的群組上使用。 在 Microsoft Entra 識別碼中設定的應用程式，以取得同步的內部部署群組屬性，只取得同步群組的應用程式。

應用程式取用群組信息的選項

應用程式可以呼叫 Microsoft Graph 群組的端點，以取得已驗證使用者的群組資訊。 此呼叫可確保使用者是成員的所有群組都可供使用，即使涉及大量群組也一直存在。 然後，群組列舉與令牌大小的限制無關。

不過，如果現有的應用程式預期透過宣告取用群組資訊，您可以使用各種宣告格式來設定 Microsoft Entra ID。 請考慮下列選項：

• 當您使用群組成員資格進行應用程式內授權時，最好使用群組 ObjectID 屬性。 群組 ObjectID 屬性在 Microsoft Entra ID 中是不可變且唯一的。 它適用於所有群組。

• 如果您使用內部部署群組 sAMAccountName 屬性進行授權，請使用網域限定名稱。 這可減少名稱衝突的機會。 sAMAccountName 在 Active Directory 網域內可能是唯一的，但如果多個 Active Directory 網域與 Microsoft Entra 租使用者同步處理，可能會有多個群組具有相同名稱。

• 請考慮使用 應用程式角色 來提供群組成員資格與應用程式之間的間接層。 然後，應用程式會根據令牌中的角色宣告，做出內部授權決策。

• 如果應用程式設定為取得從 Active Directory 同步處理的群組屬性，且群組未包含這些屬性，則不會包含在宣告中。

• 令牌中的群組宣告包含巢狀群組，但當您使用 選項將群組宣告限制為指派給應用程式的群組時除外。

  如果使用者是 GroupB 的成員，而 GroupB 是 GroupA 的成員，則使用者的群組宣告將同時包含 GroupA 和 GroupB。 當組織的用戶擁有大量群組成員資格時，令牌中列出的群組數目可能會增加令牌大小。 Microsoft Entra ID 會將令牌中針對 SAML 判斷提示發出的群組數目限制為 150，JWT 則限制為 200 個。 如果使用者是較大群組的成員，則會省略群組。 會改為包含 Microsoft Graph 端點以取得群組信息的連結。

使用從 Active Directory 同步處理的群組屬性的必要條件

如果您使用 ObjectId 格式，可以在任何群組的令牌中發出群組成員資格宣告。 若要以群組ObjectId以外的格式使用群組宣告，群組必須透過 Microsoft Entra 連線 從 Active Directory 同步處理。

若要設定 Microsoft Entra ID 以發出 Active Directory 群組的組名：

1. 從 Active Directory 同步處理組名

   在 Microsoft Entra ID 可以發出群組或角色宣告中的組名或內部部署群組 SID 之前，您需要從 Active Directory 同步處理必要的屬性。 您必須執行 Microsoft Entra 連線 1.2.70 版或更新版本。 舊版 Microsoft Entra 連線 1.2.70 會同步處理 Active Directory 中的群組物件，但不會包含必要的組名屬性。

2. 在 Microsoft Entra ID 中設定應用程式註冊，以在令牌中包含群組宣告

   您可以在入口網站的 [企業應用程式] 區段中，或使用 [應用程式註冊] 區段中的應用程式指令清單來設定群組宣告。 若要在應用程式指令清單中設定群組宣告，請參閱 本文稍後的設定群組屬性 的 Microsoft Entra 應用程式註冊。

使用 SSO 設定將群組宣告新增至 SAML 應用程式的權杖

若要透過單一登入設定資源庫或非資源庫 SAML 應用程式的群組宣告：

1. 開啟 [企業應用程式]，選取清單中的應用程式，選取 [單一登入 組態]，然後選取 [使用者屬性與宣告]。

2. 選取 [ 新增群組宣告]。

   

3. 使用選項來選取令牌中應包含哪些群組。

   

   選取項目	描述
   所有群組	發出安全組和通訊組清單和角色。
   安全性群組	發出使用者是群組宣告中成員的安全組。 如果用戶獲指派目錄角色，則會以物件標識碼的形式發出。
   目錄角色	如果用戶獲指派目錄角色，則會以宣告的形式 wids 發出。 （不會發出該組織的索賠。
   指派給應用程式的群組	只發出明確指派給應用程式的群組，且使用者是的成員。 由於令牌中的群組數目限制，建議用於大型組織。

   • 例如，若要發出使用者所屬的所有安全組，請選取 [安全組]。

     

     若要使用從 Active Directory 同步處理的 Active Directory 屬性而非 Microsoft Entra ID objectID 屬性發出群組，請從 [來源屬性 ] 下拉式清單中選取所需的格式。 只有從 Active Directory 同步處理的群組才會包含在宣告中。

     

   • 若要只發出指派給應用程式的群組，請選取 [指派給應用程式的群組]。

     

     指派給應用程式的群組將會包含在令牌中。 將會省略用戶所屬的其他群組。 使用此選項時，不會包含巢狀群組，而且用戶必須是指派給應用程式的群組直接成員。

     若要變更指派給應用程式的群組，請從 [企業應用程式 ] 清單中選取應用程式。 然後，從應用程式的左側功能表中選取 [使用者和群組 ]。

     如需管理群組指派給應用程式的詳細資訊，請參閱 將使用者或群組指派給企業應用程式。

在令牌中發出僅限雲端群組顯示名稱

您可以設定群組宣告，以包含僅限雲端群組的群組顯示名稱。

1. 開啟 [企業應用程式]，選取清單中的應用程式，選取 [單一登入 組態]，然後選取 [使用者屬性與宣告]。

2. 如果您已經設定群組宣告，請從 [ 其他宣告 ] 區段中選取它。 否則，您可以新增群組宣告，如先前步驟所述。

3. 針對令牌中發出的群組類型，選取 指派給應用程式的群組：

   

4. 若要只針對雲端群組發出群組顯示名稱，請在 [ 來源屬性 ] 下拉式清單中選取 僅限雲端的群組顯示名稱：

   

5. 針對混合式設定，若要針對同步群組發出內部部署群組屬性，以及雲端群組的顯示名稱，您可以選取所需的內部部署來源屬性，並核取 [針對僅限雲端群組發出組名] 複選框：

   

注意

您只能將指派群組的雲端組名新增至應用程式。 的限制 groups assigned to the application 是，因為組名不是唯一的，而且只能針對明確指派給應用程式的群組發出顯示名稱，以減少安全性風險。 否則，任何使用者都可以建立具有重複名稱的群組，並在應用程式端取得存取權。

設定進階選項

自訂群組宣告名稱

您可以使用 [進階選項] 下的設定，修改群組宣告發出的方式。

如果您選取 [ 自定義群組宣告的名稱]，您可以為群組宣告指定不同的宣告類型。 在 [ 名稱 ] 方塊中輸入宣告類型，並在 [命名空間] 方塊中 輸入宣告的選擇性命名空間 。

某些應用程式需要群組成員資格資訊才能出現在角色宣告中。 您可以選擇性地將使用者的群組發出為角色，方法是選取 [發出群組作為角色宣告] 複選框。

注意

如果您使用 選項發出群組數據作為角色，則只有群組會出現在角色宣告中。 使用者指派給的任何應用程式角色都不會出現在角色宣告中。

群組篩選

群組篩選可讓您精細控制包含在群組宣告中之群組的清單。 設定篩選時，只有符合篩選條件的群組才會包含在傳送至該應用程式的群組宣告中。 不論群組階層為何，篩選都會套用到所有群組。

注意

群組篩選適用於針對在入口網站的 [企業應用程式] 刀鋒視窗中設定群組宣告和篩選的應用程式發出的令牌。
群組篩選不適用於 Microsoft Entra 角色。

您可以將篩選設定為套用至群組的顯示名稱或 SAMAccountName 屬性。 支援下列篩選工作：

• 前置詞：符合所選屬性的開頭。
• 後綴：符合所選屬性的結尾。
• 包含：比對所選屬性中的任何位置。

群組轉換

某些應用程式可能需要群組的格式與 Microsoft Entra 識別碼中的表示方式不同。 若要支援這項需求，您可以將轉換套用至群組宣告中發出的每個群組。 您可以藉由允許設定正則表示式 （regex） 和自定義群組宣告的取代值來達成此目的。

\

• Regex 模式：使用 regex 根據您在此方塊中設定的模式來剖析文字字串。 如果您概述的 regex 模式評估為 true，則會執行 regex 取代模式。
• Regex 取代模式：如果您概述的 regex 模式評估為 true，則以 regex 表示法來取代字串的大綱。 使用此擷取群組來比對此取代 regex 中的子表達式。

如需 regex 取代和擷取群組的詳細資訊，請參閱 正則表示式物件模型：擷取的群組。

注意

如 Microsoft Entra 檔中所述，您無法使用原則來修改受限制的宣告。 數據源無法變更，而且當您產生這些宣告時，不會套用任何轉換。 群組宣告仍然是受限制的宣告，因此您必須變更名稱來自定義群組。 如果您選取自定義群組宣告名稱的限制名稱，則會在運行時間忽略宣告。

您也可以使用 regex 轉換功能做為篩選，因為任何不符合 regex 模式的群組都不會在產生的宣告中發出。

如果套用至原始群組宣告的轉換會產生新的自定義宣告，則會從令牌中省略原始群組宣告。 不過，如果設定的 regex 不符合原始清單中的任何值，則自定義宣告將不會存在，原始群組宣告將會包含在令牌中。

編輯群組宣告組態

將群組宣告組態新增至 使用者屬性和宣告 設定之後，新增群組宣告的選項將無法使用。 若要變更群組宣告組態，請在 [ 其他宣告] 列表中選取群組宣告 。

設定群組屬性的 Microsoft Entra 應用程式註冊

您也可以在應用程式指令清單的選擇性宣告區段中設定群組宣告。

1. 在入口網站中，選取 [身分>識別應用程式> 應用程式註冊> 選取應用程式>指令清單。

2. 藉由變更 groupMembershipClaims來啟用群組成員資格宣告。

   有效值為：

   選取項目	描述
   All	發出安全組、通訊組清單和角色。
   SecurityGroup	發出使用者屬於群組宣告成員的安全組和 Microsoft Entra 角色。
   DirectoryRole	如果用戶獲指派目錄角色，則會以宣告的形式 wids 發出。 （不會發出群組索賠。
   ApplicationGroup	只發出明確指派給應用程式的群組，且使用者是的成員。
   None	不會傳回任何群組。 （不區分大小寫，所以 none 也有效。它可以直接在應用程式指令清單中設定。

   例如：

   "groupMembershipClaims": "SecurityGroup"
   

   根據預設，群組 ObjectID 屬性會在群組宣告值中發出。 若要修改宣告值以包含內部部署群組屬性，或將宣告類型變更為角色，請使用 optionalClaims 下一個步驟中所述的組態。

3. 設定組名組態的選擇性宣告。

   如果您想要令牌中的群組包含 內部部署的 Active Directory 群組屬性，請指定區段中應該套用optionalClaims哪些令牌類型選擇性宣告。 您可以列出多個權杖型態：

   • idToken 用於 OIDC 識別碼令牌
   • accessToken 適用於 OAuth/OIDC 存取令牌
   • Saml2Token 適用於 SAML 令牌

   注意

   此 Saml2Token 類型同時適用於 SAML1.1 和 SAML2.0 格式的令牌。

   針對每個相關的令牌類型，修改群組宣告以使用 optionalClaims 指令清單中的 區段。 架構 optionalClaims 如下所示：

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

   選擇性宣告架構	值
   name	必須是 "groups"。
   source	未使用。 省略或指定 null。
   essential	未使用。 省略或指定 false。
   additionalProperties	其他屬性的清單。 有效的選項為"sam_account_name"、、"netbios_domain_and_sam_account_name""dns_domain_and_sam_account_name"、 "cloud_displayname"和 "emit_as_roles"。

   在 中additionalProperties，只需要 、 或 "netbios_domain_and_sam_account_name" 的"sam_account_name""dns_domain_and_sam_account_name"其中一個。 如果有一個以上，則會使用第一個 ，並忽略任何其他專案。

   某些應用程式需要角色宣告中用戶的相關群組資訊。 若要將宣告類型從群組宣告變更為角色宣告，請將 新增 "emit_as_roles" 至其他屬性。 群組值將會在角色宣告中發出。

   若要發出僅限雲端群組的群組顯示名稱，您可以將 新增 "cloud_displayname" 至 additional properties。 只有在 設定為 時 “groupMembershipClaims” ，此選項才能運作 ApplicationGroup

   注意

   如果您使用 "emit_as_roles"，則使用者指派給的任何已設定應用程式角色都不會出現在角色宣告中。

範例

以 OAuth 存取權杖 DNSDomainName\sAMAccountName 格式發出群組作為群組名稱：

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

發出要以格式傳回 NetbiosDomain\sAMAccountName 的組名作為 SAML 和 OIDC 識別碼令牌中的角色宣告：

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

下一步

• 使用群組與群組宣告將授權新增至 ASP.NET Core Web 應用程式 （程式代碼範例）
• 將使用者或群組指派給企業應用程式
• 設定角色宣告