共用方式為

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

  • 發行項

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

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

重要

token 中所發出的群組數目限制為 150（適用於 SAML 聲明）和 200（適用於 JWT，包括巢狀群組）。 在較大的組織中，用戶作為成員的群組數目可能會超過 Microsoft Entra ID 在發出令牌中的群組宣告之前所施加的限制。 超過此限制將導致 Microsoft Entra ID 完全省略在令牌中傳送群組宣告。 如需這些限制的因應措施，請深入閱讀此功能的重要注意事項。

此功能的重要注意事項

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

  • 若您的使用者擁有大量群組成員資格，為了避免群組數目限制，您可以將宣告中發出的群組限制為與應用程式相關的群組。 深入了解如何針對 JWT 權杖和 SAML 權杖發出指派給應用程式的群組。 如果無法將群組指派給應用程式，則您也可以設定群組篩選，以減少宣告中所發出的群組數目。 群組篩選適用於為應用程式發出的權杖，其中群組宣告和篩選已在入口網站的 [企業應用程式] 面板中設定。 請記住，在較大的組織中，使用者所屬的群組數可能會超過 Microsoft Entra ID 在發出令牌中的群組宣告之前所施加的限制。 超過此限制會導致Microsoft Entra ID 完全省略令牌中的傳送群組宣告。

  • 若權杖是透過隱含流程發出的，則群組聲明會有最多五個群組的限制。 只有在使用者位於五個以上的群組時，透過隱含流程所要求的權杖才會具有 "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 應用程式的 Token

若要透過單一登入 (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 取代和擷取群組的詳細資訊，請參閱規則運算式物件模型：擷取的群組。

注意事項

如 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 ID 權杖
    • 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"]
    }]
}

下一步