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

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

• 其 Microsoft Entra 物件識別碼 (OID) 屬性所識別的群組
• Active Directory 同步群組和使用者 sAMAccountName 或 GroupSID 屬性所識別的群組
• 針對僅限雲端群組的顯示名稱，已由其屬性識別的群組

重要

權杖中所發出的群組數目限制為 150 (適用於 SAML 判斷提示) 和 200 (適用於 JWT，包括巢狀群組)。 在大型組織中，使用者所屬群組的數目可能會超過 Microsoft Entra ID 將新增至權杖的限制。 超過限制時可能會導致無法預測的結果。 如需這些限制的因應措施，請深入閱讀此功能的重要注意事項。

此功能的重要注意事項

• 支援使用從內部部署同步的 sAMAccountName 和安全性識別碼 (SID) 屬性，旨在讓您能夠從 Active Directory Federation Services (AD FS) 和其他身分識別提供者移動現有應用程式。 Microsoft Entra ID 中所管理的群組不包含發出這些宣告所需的屬性。

• 若要避免使用者擁有大量群組成員資格時的群組數目限制，您可以將宣告中所發出的群組限制為應用程式的相關群組。 深入了解如何針對 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 ID 中設定來取得同步內部部署群組屬性的應用程式，只會針對同步的群組取得它們。

應用程式取用群組資訊的選項

應用程式可以呼叫 Microsoft Graph 群組端點，為已驗證的使用者取得群組資訊。 此呼叫可確保即使涉及大量群組，使用者所屬的所有群組仍然可用。 然後，群組列舉會與權杖大小限制無關。

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

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

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

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

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

• 除非使用選項將群組宣告限制為指派給應用程式的群組，否則權杖中的群組宣告會包括巢狀群組。

  如果使用者是 GroupB 的成員，而 GroupB 是 GroupA 的成員，則使用者的群組宣告將包含 GroupA 和 GroupB。 當組織的使用者具有大量的群組成員資格時，權杖中列出的群組數目可能會增長權杖大小。 Microsoft Entra ID 會將其在權杖中發出的群組數目限制為 150 (適用於 SAML 判斷提示) 和 200 (適用於 JWT)。 如果使用者是大量群組的成員，則會發出這些群組。 會改為包括 Microsoft Graph 端點取得群組資訊的連結。

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

如果您使用 ObjectId 格式，則可在權杖中針對任何群組發出群組成員資格宣告。 若要以群組 ObjectId 以外的格式來使用群組宣告，必須透過 Microsoft Entra Connect 從 Active Directory 同步群組。

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

1. 從 Active Directory 同步群組名稱

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

2. 在 Microsoft Entra ID 中設定應用程式註冊，以在權杖中包括群組宣告

   您可以在入口網站的 [企業應用程式] 區段中，或使用 [應用程式註冊] 區段中的應用程式資訊清單來設定群組宣告。 若要在應用程式資訊清單中設定群組宣告，請參閱本文稍後的針對群組屬性設定 Microsoft Entra 應用程式註冊 (部分機器翻譯)。

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

若要透過單一登入 (SSO) 設定資源庫或非資源庫 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 ID 中的呈現格式不同。 若要支援此需求，您可以將轉換套用至將在群組宣告中發出的每個群組。 做法是允許在自訂群組宣告上設定規則運算式 (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"、"dns_domain_and_sam_account_name"、"netbios_domain_and_sam_account_name"、"cloud_displayname" 和 "emit_as_roles"。

   在 additionalProperties，只需要 "sam_account_name"、"dns_domain_and_sam_account_name" 或 "netbios_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"]
    }]
}

在 SAML 和 OIDC 識別碼權杖中發出以 NetbiosDomain\sAMAccountName 格式傳回的群組名稱作為角色宣告：

"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 應用程式 (程式碼範例) (英文)
• 將使用者或群組指派給企業應用程式
• 設定角色宣告