From 8dae7a42febdd05420856b91ea56f0328bc04a6b Mon Sep 17 00:00:00 2001 From: Shinsuke Sugaya Date: Sun, 16 Aug 2026 19:26:24 +0900 Subject: [PATCH] docs(sso): say what a directory role name needs from Microsoft Graph entraid.permission.fields is described as naming group/role fields, and the advice for security groups is to add displayName because they carry no mail. Applied to a directory role that does nothing. With the permissions this page asks for -- User.Read plus GroupMember.Read.All, or the Group.Read.All / Directory.Read.All substitutes named in the note above -- Microsoft Graph answers /me/memberOf with displayName null for a #microsoft.graph.directoryRole entry, so a directory role only ever contributes its GUID, and it does so silently: a missing field is not an error. Granting RoleManagement.Read.Directory, or Directory.Read.All, makes Graph return the name, and the role's displayName then becomes a permission value. Both were confirmed against a live tenant. Say so where the permissions are listed, in all seven languages. --- de/15.8/config/sso-entraid.rst | 7 +++++++ en/15.8/config/sso-entraid.rst | 7 +++++++ es/15.8/config/sso-entraid.rst | 7 +++++++ fr/15.8/config/sso-entraid.rst | 8 ++++++++ ja/15.8/config/sso-entraid.rst | 7 +++++++ ko/15.8/config/sso-entraid.rst | 6 ++++++ zh-cn/15.8/config/sso-entraid.rst | 6 ++++++ 7 files changed, 48 insertions(+) diff --git a/de/15.8/config/sso-entraid.rst b/de/15.8/config/sso-entraid.rst index f27759d1..de703662 100644 --- a/de/15.8/config/sso-entraid.rst +++ b/de/15.8/config/sso-entraid.rst @@ -234,6 +234,13 @@ Konfigurieren der API-Berechtigungen ``Group.Read.All`` jedoch nicht autorisiert, sodass ``User.Read`` in jedem Fall erforderlich ist. +.. note:: + Die oben genannten Berechtigungen decken den ``displayName`` einer Verzeichnisrolle nicht ab: + Microsoft Graph gibt ihn als null zurück. ``displayName`` in ``entraid.permission.fields`` + bewirkt daher für eine Verzeichnisrolle nichts, und nur die ID (GUID) der Rolle wird zu einer + Berechtigung. Um Rollennamen als Berechtigungswerte zu verwenden, erteilen Sie zusätzlich + ``RoleManagement.Read.Directory`` (oder ``Directory.Read.All``). + .. note:: |Fess| fordert beim Token-Abruf den Scope ``https://graph.microsoft.com/.default`` an. Ab 15.8 wird zusätzlich ``openid profile offline_access https://graph.microsoft.com/.default`` an den Autorisierungsendpunkt gesendet, sodass die Zustimmung für denselben Umfang eingeholt wird. diff --git a/en/15.8/config/sso-entraid.rst b/en/15.8/config/sso-entraid.rst index 3e7386ee..9f978a25 100644 --- a/en/15.8/config/sso-entraid.rst +++ b/en/15.8/config/sso-entraid.rst @@ -228,6 +228,13 @@ Configuring API Permissions work. However, ``/me/memberOf`` is not authorized by ``Group.Read.All``, so ``User.Read`` is required in either case. +.. note:: + The permissions above do not cover the ``displayName`` of a directory role: Microsoft Graph + returns it as null. Naming ``displayName`` in ``entraid.permission.fields`` therefore adds + nothing for a directory role, and only the role's ID (GUID) becomes a permission. To use role + names as permission values, also grant ``RoleManagement.Read.Directory`` (or + ``Directory.Read.All``). + .. note:: |Fess| requests the ``https://graph.microsoft.com/.default`` scope when acquiring a token, and from 15.8 it also sends ``openid profile offline_access https://graph.microsoft.com/.default`` to the authorization endpoint so that consent is requested for the same set. This means that all access permissions configured and consented to on the app registration are used. Therefore, to retrieve group information, you must add the permissions above to the app registration and grant administrator consent. diff --git a/es/15.8/config/sso-entraid.rst b/es/15.8/config/sso-entraid.rst index 17b6cb9b..5c22eb25 100644 --- a/es/15.8/config/sso-entraid.rst +++ b/es/15.8/config/sso-entraid.rst @@ -232,6 +232,13 @@ Configurar permisos de API anidados siguen funcionando. Sin embargo, ``/me/memberOf`` no está autorizado por ``Group.Read.All``, por lo que ``User.Read`` es necesario en cualquier caso. +.. note:: + Los permisos anteriores no cubren el ``displayName`` de un rol de directorio: Microsoft Graph + lo devuelve como null. Por lo tanto, indicar ``displayName`` en ``entraid.permission.fields`` + no aporta nada para un rol de directorio y solo el ID (GUID) del rol se convierte en un + permiso. Para usar los nombres de rol como valores de permiso, conceda además + ``RoleManagement.Read.Directory`` (o ``Directory.Read.All``). + .. note:: |Fess| solicita el ámbito ``https://graph.microsoft.com/.default`` al adquirir un token. Desde la versión 15.8, también se envía ``openid profile offline_access https://graph.microsoft.com/.default`` al endpoint de autorización, de modo que el consentimiento se solicita para el mismo conjunto. diff --git a/fr/15.8/config/sso-entraid.rst b/fr/15.8/config/sso-entraid.rst index e36b261f..abedf087 100644 --- a/fr/15.8/config/sso-entraid.rst +++ b/fr/15.8/config/sso-entraid.rst @@ -234,6 +234,14 @@ Configuration des autorisations d'API imbriqués fonctionnent également. En revanche, ``/me/memberOf`` n'est pas autorisé par ``Group.Read.All``, si bien que ``User.Read`` reste nécessaire dans tous les cas. +.. note:: + Les autorisations ci-dessus ne couvrent pas le ``displayName`` d'un rôle d'annuaire : + Microsoft Graph le renvoie à null. Indiquer ``displayName`` dans + ``entraid.permission.fields`` n'apporte donc rien pour un rôle d'annuaire, et seul + l'identifiant (GUID) du rôle devient une autorisation. Pour utiliser les noms de rôle comme + valeurs d'autorisation, accordez également ``RoleManagement.Read.Directory`` (ou + ``Directory.Read.All``). + .. note:: |Fess| demande le scope ``https://graph.microsoft.com/.default`` lors de l'acquisition d'un jeton. Depuis la version 15.8, ``openid profile offline_access https://graph.microsoft.com/.default`` est également envoyé au point de terminaison d'autorisation, afin que le consentement soit demandé pour le même ensemble. diff --git a/ja/15.8/config/sso-entraid.rst b/ja/15.8/config/sso-entraid.rst index 7629572f..5a02f3fe 100644 --- a/ja/15.8/config/sso-entraid.rst +++ b/ja/15.8/config/sso-entraid.rst @@ -227,6 +227,13 @@ APIアクセス許可の設定 一方、\ ``/me/memberOf`` は ``Group.Read.All`` では認可されないため、 いずれの場合も ``User.Read`` は必要です。 +.. note:: + 上記のアクセス許可では、ディレクトリロールの ``displayName`` はMicrosoft Graphから返されません。 + そのため、\ ``entraid.permission.fields`` に ``displayName`` を指定しても、 + ディレクトリロールから権限になるのはロールのID（GUID）だけです。 + ロール名を権限値として使用する場合は、\ ``RoleManagement.Read.Directory`` + （または ``Directory.Read.All``\ ）も付与してください。 + .. note:: |Fess| はトークン取得時に ``https://graph.microsoft.com/.default`` スコープを要求します。 15.8 以降は、認可エンドポイントにも ``openid profile offline_access https://graph.microsoft.com/.default`` diff --git a/ko/15.8/config/sso-entraid.rst b/ko/15.8/config/sso-entraid.rst index f2d55ea2..10fec9f8 100644 --- a/ko/15.8/config/sso-entraid.rst +++ b/ko/15.8/config/sso-entraid.rst @@ -227,6 +227,12 @@ API 접근 권한 설정 그룹 속성의 취득과 중첩된 그룹의 해결은 동작합니다. 다만 ``/me/memberOf`` 는 ``Group.Read.All`` 로는 인가되지 않으므로 어느 경우에도 ``User.Read`` 는 필요합니다. +.. note:: + 위의 접근 권한으로는 디렉터리 역할의 ``displayName`` 을 Microsoft Graph가 반환하지 않습니다. + 따라서 ``entraid.permission.fields`` 에 ``displayName`` 을 지정해도 디렉터리 역할에서 + 권한이 되는 것은 역할의 ID（GUID）뿐입니다. 역할 이름을 권한 값으로 사용하려면 + ``RoleManagement.Read.Directory``\ （또는 ``Directory.Read.All``\ ）도 부여하십시오. + .. note:: |Fess| 는 토큰 취득 시 ``https://graph.microsoft.com/.default`` 스코프를 요청합니다. 15.8 이상에서는 인가 엔드포인트에도 ``openid profile offline_access https://graph.microsoft.com/.default`` diff --git a/zh-cn/15.8/config/sso-entraid.rst b/zh-cn/15.8/config/sso-entraid.rst index 431f46b1..67778e69 100644 --- a/zh-cn/15.8/config/sso-entraid.rst +++ b/zh-cn/15.8/config/sso-entraid.rst @@ -223,6 +223,12 @@ Entra ID侧配置 组属性的获取与嵌套组的解析同样可以正常工作。但 ``/me/memberOf`` 无法通过 ``Group.Read.All`` 授权，因此无论采用哪种方式都需要 ``User.Read``\ 。 +.. note:: + 上述权限不包含目录角色的 ``displayName``\ ，Microsoft Graph 会将其返回为 null。 + 因此，即使在 ``entraid.permission.fields`` 中指定 ``displayName``\ ， + 目录角色也只有角色的 ID（GUID）会成为权限。 + 若要将角色名称用作权限值，请同时授予 ``RoleManagement.Read.Directory``\ （或 ``Directory.Read.All``\ ）。 + .. note:: |Fess| 在获取令牌时会请求 ``https://graph.microsoft.com/.default`` 作用域。 15.8 及以后版本还会向授权端点发送 ``openid profile offline_access https://graph.microsoft.com/.default``\ ，以便针对同一组权限请求同意。