diff --git a/de/15.8/config/sso-entraid.rst b/de/15.8/config/sso-entraid.rst index 1bdee392..f27759d1 100644 --- a/de/15.8/config/sso-entraid.rst +++ b/de/15.8/config/sso-entraid.rst @@ -109,10 +109,10 @@ Die folgenden Einstellungen können bei Bedarf hinzugefügt werden. - Standardrollen (kommagetrennt). Werden auf jeden Entra ID-Benutzer angewendet. - (Keine) * - ``entraid.permission.fields`` - - Gruppen-/Rollenfelder (kommagetrennt), die zusätzlich als Berechtigungswerte verwendet werden. Die Gruppen-/Rollen-ID (GUID) wird stets als Berechtigung verwendet; die hier angegebenen Felder (z.B. ``mail``) werden zusätzlich hinzugefügt. + - Gruppen-/Rollenfelder (kommagetrennt), die zusätzlich als Berechtigungswerte verwendet werden. Die Gruppen-/Rollen-ID (GUID) wird stets als Berechtigung verwendet; die hier angegebenen Felder (z.B. ``mail``) werden zusätzlich hinzugefügt. Verwendbar sind nur Felder, deren Wert eine Zeichenkette ist. Microsoft Graph liefert ein Feld wie ``securityEnabled`` als booleschen Wert und ``groupTypes`` als Liste; keines von beiden kann ein Berechtigungswert werden, ein solches Feld wird daher ignoriert und eine Warnung mit seinem Namen ins Protokoll geschrieben. - ``mail`` * - ``entraid.use.ds`` - - Domänendienst-Integration. Bei ``true`` wird für Berechtigungswerte im Format ``name@domain`` auch der lokale Teil (``name``) ohne den Domänenanteil als Berechtigung hinzugefügt. + - Domänendienst-Integration. Bei ``true`` wird für Berechtigungswerte im Format ``name@domain`` auch der lokale Teil (``name``) ohne den Domänenanteil als Berechtigung hinzugefügt. Das gilt nicht nur für Gruppen und Rollen, sondern auch für den angemeldeten Benutzer selbst: Der lokale Teil seines Benutzerprinzipalnamens (UPN) wird als benutzerbezogene Berechtigung hinzugefügt. Mit ``false`` entfällt daher auch diese benutzerbezogene Berechtigung, nicht nur die der Gruppen. - ``true`` .. note:: @@ -258,9 +258,9 @@ Die abgerufenen Gruppen-IDs und Gruppennamen können für die rollenbasierte Suc Verschachtelte Gruppen ---------------------- -|Fess| ruft nicht nur Gruppen ab, zu denen Benutzer direkt gehören, sondern auch übergeordnete Gruppen (verschachtelte Gruppen) rekursiv. +|Fess| ruft nicht nur Gruppen ab, zu denen Benutzer direkt gehören, sondern auch die übergeordneten Gruppen, zu denen diese wiederum gehören (verschachtelte Gruppen). Sowohl die direkte Mitgliedschaftsabfrage als auch die Suche nach übergeordneten Gruppen laufen nach der Anmeldung in derselben Hintergrundaufgabe, sodass die Anmeldung selbst nie durch Microsoft Graph verzögert wird. -Die übergeordneten Gruppen werden bis zu einer bestimmten Hierarchietiefe ermittelt, und die abgerufenen Ergebnisse werden für einen bestimmten Zeitraum zwischengespeichert. +Die Suche nach übergeordneten Gruppen verwendet den Microsoft Graph-Vorgang ``getMemberGroups``, der transitiv auflöst: Ein Aufruf je direkt zugewiesener Gruppe liefert alle darüberliegenden Gruppen, unabhängig davon, wie tief die Verschachtelung reicht. Die abgerufenen Ergebnisse werden für einen bestimmten Zeitraum zwischengespeichert. Sobald diese Hintergrundaufgabe abgeschlossen ist, werden die Berechtigungen des Benutzers neu berechnet. Standardgruppeneinstellungen @@ -388,7 +388,15 @@ Gruppeninformationen können nicht abgerufen werden „Nicht vollständig“ ist bewusst gewählt: Die Auflösung gilt nur dann als erfolgreich, wenn sowohl die Abfrage der direkten Mitgliedschaften als auch der Durchlauf der verschachtelten Gruppen gelungen ist — ein Benutzer, der seine direkten Gruppen, aber nicht seine übergeordneten Gruppen - besitzt, erhält diesen Hinweis also ebenfalls. Häufigste Ursache des Teilfalls ist Drosselung: + besitzt, erhält diesen Hinweis also ebenfalls. Ein Fall ist davon ausgenommen, und zwar genau + der aus dem vorherigen Punkt: Verweigert Microsoft Graph die Abfrage der verschachtelten Gruppen + mit ``Authorization_RequestDenied``, weil ``GroupMember.Read.All`` nie erteilt wurde, wertet + |Fess| das nicht als Fehlschlag, sondern als Antwort, die besagt, dass die Gruppe keine + übergeordneten Gruppen hat. Die Auflösung gilt dann als erfolgreich und **es wird kein Hinweis + angezeigt**, obwohl die Berechtigungen der übergeordneten Gruppen fehlen. Das einzige Anzeichen + ist die Warnung ``Not allowed to read the parent groups of ...`` im Protokoll; prüfen Sie das + Protokoll deshalb darauf, wann immer verschachtelte Gruppen im Einsatz sind. Häufigste Ursache des + Teilfalls ist Drosselung: Ein einziges HTTP 429 oder 503 von Microsoft Graph lässt |Fess| so lange pausieren, wie es der Header ``Retry-After`` verlangt (60 Sekunden, wenn er nichts Verwertbares nennt, höchstens 60 Minuten), und in dieser Zeit wird in der gesamten |Fess|-Instanz jede Abfrage verschachtelter diff --git a/en/15.8/config/sso-entraid.rst b/en/15.8/config/sso-entraid.rst index 11f08d27..3e7386ee 100644 --- a/en/15.8/config/sso-entraid.rst +++ b/en/15.8/config/sso-entraid.rst @@ -108,10 +108,10 @@ The following settings can be added as needed. - Default roles (comma-separated). Applied to every Entra ID user. - (None) * - ``entraid.permission.fields`` - - Group/role fields (comma-separated) to additionally use as permission values. The group/role ID (GUID) is always used as a permission, and the values of the fields specified here (e.g., ``mail``) are added. + - Group/role fields (comma-separated) to additionally use as permission values. The group/role ID (GUID) is always used as a permission, and the values of the fields specified here (e.g., ``mail``) are added. Only a field whose value is a string can be used. Microsoft Graph answers a field such as ``securityEnabled`` with a boolean and ``groupTypes`` with a list, and neither can become a permission value, so such a field is ignored and a warning naming it is written to the log. - ``mail`` * - ``entraid.use.ds`` - - Domain service integration. When ``true``, for permission values in the ``name@domain`` format, the local part (``name``) with the domain part removed is also added as a permission. + - Domain service integration. When ``true``, for permission values in the ``name@domain`` format, the local part (``name``) with the domain part removed is also added as a permission. This applies to the signed-in user as well as to groups and roles: the local part of the user principal name is added as a user-level permission. Setting it to ``false`` therefore removes that user-level permission too, not only the group ones. - ``true`` .. note:: @@ -249,9 +249,9 @@ The retrieved group IDs and group names can be used for |Fess| role-based search Nested Groups ------------- -|Fess| retrieves not only groups that users directly belong to, but also parent groups (nested groups) recursively. +|Fess| retrieves not only groups that users directly belong to, but also the parent groups those belong to (nested groups). Both the direct membership lookup and the parent group lookup run in the same background task after login, so login itself is never slowed down by Microsoft Graph. -The parent group lookup targets up to a certain number of levels, and the retrieved results are cached for a certain period. +The parent group lookup uses the Microsoft Graph ``getMemberGroups`` operation, which resolves transitively: one call per directly assigned group returns every group above it, however deep the nesting goes. The retrieved results are cached for a certain period. When that background task completes, the user's permissions are recalculated. Default Group Settings @@ -373,8 +373,15 @@ Cannot Retrieve Group Information permissions could not be fully loaded, asks them to log out and log in again, and to contact an administrator if it keeps happening. "Not fully" is deliberate: the resolution counts as failed unless both the direct membership lookup and the nested group walk succeeded, so a user who - holds their direct groups but not their parent groups gets that message too. Throttling is the - usual cause of the partial case — a single HTTP 429 or 503 from Microsoft Graph makes |Fess| back + holds their direct groups but not their parent groups gets that message too. One case is + exempt, and it is the one the previous item describes: when Microsoft Graph refuses the nested + group lookup with ``Authorization_RequestDenied`` because ``GroupMember.Read.All`` was never + granted, |Fess| takes that as an answer meaning the group has no parents rather than as a + failure. Resolution then counts as successful and **no message is shown**, even though the + parent group permissions are missing. The only sign is the + ``Not allowed to read the parent groups of ...`` warning in the log, so check for it whenever + nested groups are in use. Throttling is the usual cause of the partial case — a single HTTP 429 + or 503 from Microsoft Graph makes |Fess| back off for as long as the ``Retry-After`` header asks (60 seconds when it says nothing usable, 60 minutes at most), and every nested group lookup in the whole |Fess| instance is skipped for that time while the direct lookups keep answering. The diff --git a/es/15.8/config/sso-entraid.rst b/es/15.8/config/sso-entraid.rst index 29ad6e66..17b6cb9b 100644 --- a/es/15.8/config/sso-entraid.rst +++ b/es/15.8/config/sso-entraid.rst @@ -109,10 +109,10 @@ Las siguientes configuraciones pueden agregarse según sea necesario. - Roles por defecto (separados por comas). Se aplican a todos los usuarios de Entra ID. - (Ninguno) * - ``entraid.permission.fields`` - - Campos de grupo/rol (separados por comas) que se utilizan adicionalmente como valores de permiso. El ID de grupo/rol (GUID) siempre se usa como permiso, y los valores de los campos especificados aquí (ej: ``mail``) se agregan. + - Campos de grupo/rol (separados por comas) que se utilizan adicionalmente como valores de permiso. El ID de grupo/rol (GUID) siempre se usa como permiso, y los valores de los campos especificados aquí (ej: ``mail``) se agregan. Solo pueden utilizarse campos cuyo valor sea una cadena de texto. Microsoft Graph devuelve un campo como ``securityEnabled`` en forma de booleano y ``groupTypes`` en forma de lista, y ninguno de los dos puede convertirse en un valor de permiso, por lo que un campo así se ignora y se escribe en el registro una advertencia que indica su nombre. - ``mail`` * - ``entraid.use.ds`` - - Integración con el servicio de dominio. Cuando es ``true``, para los valores de permiso en formato ``name@domain``, la parte local (``name``) con la parte del dominio eliminada también se agrega como permiso. + - Integración con el servicio de dominio. Cuando es ``true``, para los valores de permiso en formato ``name@domain``, la parte local (``name``) con la parte del dominio eliminada también se agrega como permiso. Esto se aplica no solo a los grupos y roles, sino también al propio usuario que ha iniciado sesión: la parte local de su nombre principal de usuario (UPN) se agrega como permiso a nivel de usuario. Por lo tanto, establecerlo en ``false`` elimina también ese permiso a nivel de usuario, no solo los de los grupos. - ``true`` .. note:: @@ -256,9 +256,9 @@ Los IDs de grupo y nombres de grupo recuperados pueden usarse para la búsqueda Grupos anidados --------------- -|Fess| recupera no solo los grupos a los que los usuarios pertenecen directamente, sino también los grupos padre (grupos anidados) de forma recursiva. +|Fess| recupera no solo los grupos a los que los usuarios pertenecen directamente, sino también los grupos padre a los que estos pertenecen (grupos anidados). Tanto la búsqueda de la pertenencia directa como la búsqueda de grupos padre se ejecutan en la misma tarea en segundo plano después del inicio de sesión, de modo que el inicio de sesión nunca se ve retrasado por Microsoft Graph. -La búsqueda de grupos padre abarca hasta un número determinado de niveles, y los resultados obtenidos se almacenan en caché durante un período determinado. +La búsqueda de grupos padre utiliza la operación ``getMemberGroups`` de Microsoft Graph, que resuelve de forma transitiva: una sola llamada por cada grupo asignado directamente devuelve todos los grupos que están por encima de él, sea cual sea la profundidad del anidamiento. Los resultados obtenidos se almacenan en caché durante un período determinado. Cuando esa tarea en segundo plano finaliza, los permisos del usuario se recalculan. Configuración de grupos por defecto @@ -384,7 +384,14 @@ No se puede recuperar la información de grupo vuelva a iniciarla, y que contacte con el administrador si el problema persiste. Lo de «por completo» es deliberado: la resolución solo se considera correcta si han tenido éxito tanto la consulta de pertenencias directas como el recorrido de los grupos anidados, así que un usuario - que tiene sus grupos directos pero no sus grupos padre también recibe ese mensaje. La causa + que tiene sus grupos directos pero no sus grupos padre también recibe ese mensaje. Hay un caso + exento, y es precisamente el que describe el punto anterior: cuando Microsoft Graph rechaza la + consulta de grupos anidados con ``Authorization_RequestDenied`` porque nunca se otorgó + ``GroupMember.Read.All``, |Fess| lo interpreta como una respuesta que significa que el grupo no + tiene grupos padre, y no como un fallo. La resolución se considera entonces correcta y **no se + muestra ningún mensaje**, aunque falten los permisos de los grupos padre. La única señal es la + advertencia ``Not allowed to read the parent groups of ...`` en el registro, así que conviene + buscarla siempre que se utilicen grupos anidados. La causa habitual del caso parcial es la limitación de peticiones: un solo HTTP 429 o 503 de Microsoft Graph hace que |Fess| espere el tiempo que pida la cabecera ``Retry-After`` (60 segundos si no indica nada utilizable, 60 minutos como máximo), y durante ese tiempo se omite toda consulta de diff --git a/fr/15.8/config/sso-entraid.rst b/fr/15.8/config/sso-entraid.rst index f22fcc38..e36b261f 100644 --- a/fr/15.8/config/sso-entraid.rst +++ b/fr/15.8/config/sso-entraid.rst @@ -109,10 +109,10 @@ Les paramètres suivants peuvent être ajoutés si nécessaire. - Rôles par défaut (séparés par des virgules). Appliqués à tous les utilisateurs Entra ID. - (Aucun) * - ``entraid.permission.fields`` - - Champs de groupe/rôle (séparés par des virgules) à utiliser en plus comme valeurs de permission. L'ID (GUID) du groupe/rôle est toujours utilisé comme permission, et les valeurs des champs indiqués ici (ex : ``mail``) sont ajoutées. + - Champs de groupe/rôle (séparés par des virgules) à utiliser en plus comme valeurs de permission. L'ID (GUID) du groupe/rôle est toujours utilisé comme permission, et les valeurs des champs indiqués ici (ex : ``mail``) sont ajoutées. Seuls les champs dont la valeur est une chaîne de caractères peuvent être utilisés. Microsoft Graph renvoie un champ tel que ``securityEnabled`` sous forme de booléen et ``groupTypes`` sous forme de liste ; ni l'un ni l'autre ne peut devenir une valeur de permission, un tel champ est donc ignoré et un avertissement mentionnant son nom est écrit dans le journal. - ``mail`` * - ``entraid.use.ds`` - - Intégration avec le service de domaine. Quand ``true``, pour les valeurs de permission au format ``name@domain``, la partie locale (``name``) sans la partie domaine est également ajoutée comme permission. + - Intégration avec le service de domaine. Quand ``true``, pour les valeurs de permission au format ``name@domain``, la partie locale (``name``) sans la partie domaine est également ajoutée comme permission. Cela s'applique non seulement aux groupes et aux rôles, mais aussi à l'utilisateur connecté lui-même : la partie locale de son nom principal d'utilisateur (UPN) est ajoutée comme permission au niveau utilisateur. Le passage à ``false`` supprime donc également cette permission au niveau utilisateur, et pas seulement celles des groupes. - ``true`` .. note:: @@ -258,9 +258,9 @@ Les ID de groupe et noms de groupe récupérés peuvent être utilisés pour la Groupes imbriqués ----------------- -|Fess| récupère non seulement les groupes auxquels les utilisateurs appartiennent directement, mais aussi les groupes parents (groupes imbriqués) de manière récursive. +|Fess| récupère non seulement les groupes auxquels les utilisateurs appartiennent directement, mais aussi les groupes parents auxquels ceux-ci appartiennent (groupes imbriqués). La recherche de l'appartenance directe et la recherche des groupes parents s'exécutent toutes deux dans la même tâche en arrière-plan après la connexion, si bien que la connexion elle-même n'est jamais ralentie par Microsoft Graph. -La recherche des groupes parents cible un certain nombre de niveaux hiérarchiques, et les résultats récupérés sont mis en cache pendant une certaine durée. Lorsque cette tâche en arrière-plan est terminée, les permissions de l'utilisateur sont recalculées. +La recherche des groupes parents utilise l'opération ``getMemberGroups`` de Microsoft Graph, qui résout de manière transitive : un seul appel par groupe directement attribué renvoie tous les groupes situés au-dessus de lui, quelle que soit la profondeur de l'imbrication. Les résultats récupérés sont mis en cache pendant une certaine durée. Lorsque cette tâche en arrière-plan est terminée, les permissions de l'utilisateur sont recalculées. Paramètres de groupe par défaut ------------------------------- @@ -387,7 +387,15 @@ Impossible de récupérer les informations de groupe « Entièrement » est délibéré : la résolution n'est considérée comme réussie que si la requête des appartenances directes et le parcours des groupes imbriqués ont tous deux abouti ; un utilisateur qui possède ses groupes directs mais pas ses groupes parents reçoit donc aussi ce - message. La cause habituelle du cas partiel est la limitation de débit : un seul HTTP 429 ou 503 + message. Un cas fait exception, et c'est celui que décrit le point précédent : lorsque + Microsoft Graph refuse la recherche des groupes imbriqués avec ``Authorization_RequestDenied`` + parce que ``GroupMember.Read.All`` n'a jamais été accordé, |Fess| l'interprète non pas comme un + échec, mais comme une réponse signifiant que le groupe n'a pas de groupe parent. La résolution + est alors considérée comme réussie et **aucun message n'est affiché**, bien que les + autorisations des groupes parents manquent. Le seul indice est l'avertissement + ``Not allowed to read the parent groups of ...`` dans le journal ; vérifiez donc sa présence dès + que des groupes imbriqués sont utilisés. La cause habituelle du cas partiel est la limitation de + débit : un seul HTTP 429 ou 503 de Microsoft Graph fait patienter |Fess| aussi longtemps que l'exige l'en-tête ``Retry-After`` (60 secondes s'il n'indique rien d'exploitable, 60 minutes au maximum), et pendant ce temps toute recherche de groupes imbriqués est ignorée dans l'ensemble de l'instance |Fess| alors que diff --git a/ja/15.8/config/sso-entraid.rst b/ja/15.8/config/sso-entraid.rst index 60725818..7629572f 100644 --- a/ja/15.8/config/sso-entraid.rst +++ b/ja/15.8/config/sso-entraid.rst @@ -107,10 +107,10 @@ Entra IDから取得した情報を設定します。 - デフォルトロール（カンマ区切り）。すべてのEntra IDユーザーに適用されます。 - （なし） * - ``entraid.permission.fields`` - - 権限値として追加で使用するグループ/ロールのフィールド（カンマ区切り）。グループ/ロールのID（GUID）は常に権限として使用され、ここで指定したフィールド（例: ``mail``）の値が追加されます。 + - 権限値として追加で使用するグループ/ロールのフィールド（カンマ区切り）。グループ/ロールのID（GUID）は常に権限として使用され、ここで指定したフィールド（例: ``mail``）の値が追加されます。指定できるのは、値が文字列であるフィールドだけです。``securityEnabled`` は真偽値、``groupTypes`` は配列としてMicrosoft Graphから返るため権限値にはできず、これらを指定した場合は無視され、該当のフィールド名を示す警告がログに出力されます。 - ``mail`` * - ``entraid.use.ds`` - - ドメインサービス連携。\ ``true`` の場合、``name@domain`` 形式の権限値から、ドメイン部を除いたローカル部（``name``）も権限として追加します。 + - ドメインサービス連携。\ ``true`` の場合、``name@domain`` 形式の権限値から、ドメイン部を除いたローカル部（``name``）も権限として追加します。これはグループ・ロールだけでなく、サインインしたユーザー自身にも適用され、UPNのローカル部がユーザーレベルの権限として追加されます。そのため ``false`` にすると、グループの権限だけでなくこのユーザーレベルの権限も追加されなくなります。 - ``true`` .. note:: @@ -253,9 +253,9 @@ Entra ID認証では、Microsoft Graph APIを使用してユーザーが所属 ネストされたグループ -------------------- -|Fess| は、ユーザーが直接所属するグループだけでなく、そのグループが所属する親グループ（ネストされたグループ）も再帰的に取得します。 +|Fess| は、ユーザーが直接所属するグループだけでなく、そのグループが所属する親グループ（ネストされたグループ）も取得します。 直接所属するグループの取得と親グループの探索は、いずれもログイン後の同一のバックグラウンド処理として実行されるため、ログイン自体がMicrosoft Graphによって遅延することはありません。 -親グループの探索は一定の階層数までを対象とし、取得結果は一定時間キャッシュされます。 +親グループの取得にはMicrosoft Graphの ``getMemberGroups`` を使用します。これは推移的に解決されるため、直接所属するグループ1件につき1回の呼び出しで、その上位にあるすべての親グループが階層の深さに関わらず返ります。取得結果は一定時間キャッシュされます。 このバックグラウンド処理が完了すると、ユーザーの権限が再計算されます。 デフォルトグループの設定 @@ -360,7 +360,7 @@ Entra ID認証では、Microsoft Graph APIを使用してユーザーが所属 - ユーザーがEntra ID上でグループに所属しているか確認してください - ネストされた親グループを解決できない場合は、\ ``Not allowed to read the parent groups of ...`` という警告がログに出力されます。この場合は ``GroupMember.Read.All`` を付与してください - |Fess| はグループ・ロールの権限解決をログイン完了後にバックグラウンドで実行するため、ログイン自体がMicrosoft Graphの応答を待つことはありません。解決が完了するまでの間、ユーザーが保持するのは、ユーザー自身のユーザーレベルの権限と、\ ``entraid.default.groups``\ ・\ ``entraid.default.roles``\ に設定したグループ・ロールだけです。どちらも未設定（同梱の既定値）の場合、この間の検索は1件もヒットしません。\ ``role.search.default.permissions`` は既定で空であり、同梱の ``role.search.default.display.permissions`` のまま作成したクロール設定でクロールした文書には ``{role}guest`` が付与されますが、ログイン済みユーザーはこのロールを持たないためです。この時間は、最大で約1秒のスケジューリング遅延に加えて、Microsoft Graphの呼び出しそのもの（直接所属の取得で1回、さらにネストしたグループをたどるために直接所属グループごとに1回ずつを順番に実行。キャッシュが未作成の場合）だけかかるため、ユーザーが所属するグループ数に応じて長くなります。この間、検索画面には、グループ・ロール権限を読み込み中である旨と、しばらくしてから再検索するよう促すメッセージが表示されます -- 解決が完全には成功しなかった場合は、検索画面に、グループ・ロール権限をすべて取得できなかった旨と、いったんログアウトしてからログインし直すよう、また繰り返し発生する場合は管理者に問い合わせるよう促すメッセージが表示されます。「すべて」は意図的な表現です。直接所属の取得とネストしたグループの探索の両方が成功しない限り解決は失敗として扱われるため、直接所属のグループは取得できていても親グループを取得できなかったユーザーにも、このメッセージが表示されます。部分的にしか解決できない主な原因はスロットリングです。Microsoft Graphが1回でもHTTP 429または503を返すと、\ |Fess| は ``Retry-After`` ヘッダーが要求する時間（解釈できる値がない場合は60秒、最大60分）待機し、その間は直接所属の取得が成功していても、\ |Fess| 全体でネストしたグループの取得がスキップされます。ただし、失敗が最終的なものになるとは限りません。アクセストークンが更新されるたびに解決が再実行され、その後成功すればメッセージは消え、欠けていた権限も回復します。すぐに再試行したい場合は、いったんログアウトしてからログインし直してください（ログインしたままSSOのログインURLを開いても、検索画面にリダイレクトされるだけです） +- 解決が完全には成功しなかった場合は、検索画面に、グループ・ロール権限をすべて取得できなかった旨と、いったんログアウトしてからログインし直すよう、また繰り返し発生する場合は管理者に問い合わせるよう促すメッセージが表示されます。「すべて」は意図的な表現です。直接所属の取得とネストしたグループの探索の両方が成功しない限り解決は失敗として扱われるため、直接所属のグループは取得できていても親グループを取得できなかったユーザーにも、このメッセージが表示されます。ただし1つだけ例外があり、それは前項で説明した状況です。``GroupMember.Read.All`` が付与されておらず、Microsoft Graphがネストされたグループの取得を ``Authorization_RequestDenied`` で拒否した場合、\ |Fess| はこれを失敗ではなく「そのグループに親グループは無い」という回答として扱います。この場合、親グループの権限が欠けているにもかかわらず解決は成功として扱われ、\ **このメッセージは表示されません**\ 。手がかりはログに出力される ``Not allowed to read the parent groups of ...`` の警告だけですので、ネストされたグループを使用している場合は、この警告が出ていないかを確認してください。部分的にしか解決できない主な原因はスロットリングです。Microsoft Graphが1回でもHTTP 429または503を返すと、\ |Fess| は ``Retry-After`` ヘッダーが要求する時間（解釈できる値がない場合は60秒、最大60分）待機し、その間は直接所属の取得が成功していても、\ |Fess| 全体でネストしたグループの取得がスキップされます。ただし、失敗が最終的なものになるとは限りません。アクセストークンが更新されるたびに解決が再実行され、その後成功すればメッセージは消え、欠けていた権限も回復します。すぐに再試行したい場合は、いったんログアウトしてからログインし直してください（ログインしたままSSOのログインURLを開いても、検索画面にリダイレクトされるだけです） デバッグ設定 ------------ diff --git a/ko/15.8/config/sso-entraid.rst b/ko/15.8/config/sso-entraid.rst index 4ba60fad..f2d55ea2 100644 --- a/ko/15.8/config/sso-entraid.rst +++ b/ko/15.8/config/sso-entraid.rst @@ -108,10 +108,10 @@ Entra ID에서 취득한 정보를 설정합니다. - 기본 역할（쉼표 구분）. 모든 Entra ID 사용자에게 적용됩니다. - （없음） * - ``entraid.permission.fields`` - - 권한 값으로 추가로 사용할 그룹/역할 필드（쉼표 구분）. 그룹/역할의 ID（GUID）는 항상 권한으로 사용되며, 여기서 지정한 필드（예: ``mail``）의 값이 추가됩니다. + - 권한 값으로 추가로 사용할 그룹/역할 필드（쉼표 구분）. 그룹/역할의 ID（GUID）는 항상 권한으로 사용되며, 여기서 지정한 필드（예: ``mail``）의 값이 추가됩니다. 지정할 수 있는 것은 값이 문자열인 필드뿐입니다. ``securityEnabled`` 는 불리언, ``groupTypes`` 는 배열로 Microsoft Graph에서 반환되므로 권한 값으로 사용할 수 없으며, 이러한 필드를 지정한 경우에는 무시되고 해당 필드 이름을 알리는 경고가 로그에 출력됩니다. - ``mail`` * - ``entraid.use.ds`` - - 도메인 서비스 연동. ``true`` 인 경우, ``name@domain`` 형식의 권한 값에서 도메인 부분을 제거한 로컬 부분（``name``）도 권한으로 추가합니다. + - 도메인 서비스 연동. ``true`` 인 경우, ``name@domain`` 형식의 권한 값에서 도메인 부분을 제거한 로컬 부분（``name``）도 권한으로 추가합니다. 이는 그룹·역할뿐만 아니라 로그인한 사용자 본인에게도 적용되어, 사용자 주체 이름（UPN）의 로컬 부분이 사용자 수준 권한으로 추가됩니다. 따라서 ``false`` 로 설정하면 그룹의 권한뿐만 아니라 이 사용자 수준 권한도 추가되지 않습니다. - ``true`` .. note:: @@ -253,9 +253,9 @@ Entra ID 인증에서는 Microsoft Graph API를 사용하여 사용자가 소속 중첩 그룹 -------------------- -|Fess| 는 사용자가 직접 소속된 그룹뿐만 아니라 해당 그룹이 소속된 상위 그룹（중첩 그룹）도 재귀적으로 취득합니다. +|Fess| 는 사용자가 직접 소속된 그룹뿐만 아니라 해당 그룹이 소속된 상위 그룹（중첩 그룹）도 취득합니다. 직접 소속된 그룹의 취득과 상위 그룹의 탐색은 모두 로그인 후 동일한 백그라운드 작업으로 실행되므로, 로그인 자체가 Microsoft Graph로 인해 지연되는 일은 없습니다. -상위 그룹 탐색은 일정 계층 수까지를 대상으로 하며, 취득 결과는 일정 시간 동안 캐시됩니다. +상위 그룹의 취득에는 Microsoft Graph의 ``getMemberGroups`` 를 사용합니다. 이는 추이적으로 해결되므로, 직접 소속된 그룹 1건당 1회의 호출로 그 상위에 있는 모든 상위 그룹이 계층의 깊이와 관계없이 반환됩니다. 취득 결과는 일정 시간 동안 캐시됩니다. 이 백그라운드 작업이 완료되면 사용자의 권한이 재계산됩니다. 기본 그룹 설정 @@ -360,7 +360,7 @@ Entra ID 인증에서는 Microsoft Graph API를 사용하여 사용자가 소속 - 사용자가 Entra ID에서 그룹에 소속되어 있는지 확인하십시오 - 중첩된 상위 그룹을 해결할 수 없는 경우에는 ``Not allowed to read the parent groups of ...`` 경고가 로그에 출력됩니다. 이 경우에는 ``GroupMember.Read.All`` 을 부여하십시오 - |Fess| 는 로그인이 완료된 후 백그라운드에서 사용자의 그룹·역할 소속을 해결하므로, 로그인 자체가 Microsoft Graph의 응답을 기다리는 일은 없습니다. 해결이 완료될 때까지 사용자가 보유하는 것은 사용자 본인의 사용자 수준 권한과 ``entraid.default.groups`` 및 ``entraid.default.roles`` 에 설정한 그룹·역할뿐입니다. 둘 다 설정하지 않은 경우（기본 제공 설정값）, 이 시간대의 검색은 한 건도 결과가 나오지 않습니다. ``role.search.default.permissions`` 는 기본적으로 비어 있고, 기본 제공 ``role.search.default.display.permissions`` 그대로 만든 크롤 설정으로 크롤링한 문서에는 ``{role}guest`` 가 부여되지만 로그인한 사용자는 이 역할을 갖고 있지 않기 때문입니다. 이 시간대는 최대 약 1초의 스케줄링 지연에 더해 Microsoft Graph 호출 자체（직접 소속 조회 1회, 여기에 중첩 그룹을 따라가기 위해 직접 소속 그룹마다 1회씩 순차 실행. 캐시가 없는 경우）가 걸리므로, 사용자가 소속된 그룹 수에 따라 길어집니다. 그동안 검색 화면에는 그룹·역할 권한을 아직 불러오는 중이라는 사실과 잠시 후 다시 검색하라는 안내 메시지가 표시됩니다 -- 해결이 완전히 성공하지 못한 경우에는 검색 화면에 그룹·역할 권한을 모두 불러오지 못했다는 사실과, 로그아웃한 후 다시 로그인하라는 안내, 그리고 반복해서 발생하는 경우 관리자에게 문의하라는 안내 메시지가 표시됩니다. 「모두」는 의도적인 표현입니다. 직접 소속 조회와 중첩 그룹 탐색이 모두 성공하지 않는 한 해결은 실패로 처리되므로, 직접 소속 그룹은 가져왔지만 상위 그룹을 가져오지 못한 사용자에게도 이 메시지가 표시됩니다. 부분적으로만 해결되는 주된 원인은 스로틀링입니다. Microsoft Graph가 한 번이라도 HTTP 429 또는 503을 반환하면 |Fess| 는 ``Retry-After`` 헤더가 요구하는 시간（해석할 수 있는 값이 없으면 60초, 최대 60분）만큼 대기하며, 그동안에는 직접 소속 조회가 계속 성공하더라도 |Fess| 인스턴스 전체에서 중첩 그룹 조회가 건너뛰어집니다. 다만 실패가 최종적인 것이 되지는 않습니다. 액세스 토큰이 갱신될 때마다 해결이 다시 실행되며, 그 후 성공하면 메시지는 사라지고 없던 권한도 복구됩니다. 바로 다시 시도하려면 일단 로그아웃한 후 다시 로그인하십시오（로그인한 상태로 SSO 로그인 URL을 열어도 검색 화면으로 리다이렉트될 뿐입니다） +- 해결이 완전히 성공하지 못한 경우에는 검색 화면에 그룹·역할 권한을 모두 불러오지 못했다는 사실과, 로그아웃한 후 다시 로그인하라는 안내, 그리고 반복해서 발생하는 경우 관리자에게 문의하라는 안내 메시지가 표시됩니다. 「모두」는 의도적인 표현입니다. 직접 소속 조회와 중첩 그룹 탐색이 모두 성공하지 않는 한 해결은 실패로 처리되므로, 직접 소속 그룹은 가져왔지만 상위 그룹을 가져오지 못한 사용자에게도 이 메시지가 표시됩니다. 다만 한 가지 예외가 있으며, 그것은 앞 항목에서 설명한 상황입니다. ``GroupMember.Read.All`` 이 부여되지 않아 Microsoft Graph가 중첩 그룹 조회를 ``Authorization_RequestDenied`` 로 거부한 경우, |Fess| 는 이를 실패가 아니라 「해당 그룹에는 상위 그룹이 없다」는 응답으로 처리합니다. 이 경우 상위 그룹의 권한이 누락되었음에도 해결은 성공으로 처리되며, **이 메시지는 표시되지 않습니다**. 단서는 로그에 출력되는 ``Not allowed to read the parent groups of ...`` 경고뿐이므로, 중첩 그룹을 사용하고 있는 경우에는 이 경고가 출력되지 않았는지 확인하십시오. 부분적으로만 해결되는 주된 원인은 스로틀링입니다. Microsoft Graph가 한 번이라도 HTTP 429 또는 503을 반환하면 |Fess| 는 ``Retry-After`` 헤더가 요구하는 시간（해석할 수 있는 값이 없으면 60초, 최대 60분）만큼 대기하며, 그동안에는 직접 소속 조회가 계속 성공하더라도 |Fess| 인스턴스 전체에서 중첩 그룹 조회가 건너뛰어집니다. 다만 실패가 최종적인 것이 되지는 않습니다. 액세스 토큰이 갱신될 때마다 해결이 다시 실행되며, 그 후 성공하면 메시지는 사라지고 없던 권한도 복구됩니다. 바로 다시 시도하려면 일단 로그아웃한 후 다시 로그인하십시오（로그인한 상태로 SSO 로그인 URL을 열어도 검색 화면으로 리다이렉트될 뿐입니다） 디버그 설정 ------------ diff --git a/zh-cn/15.8/config/sso-entraid.rst b/zh-cn/15.8/config/sso-entraid.rst index 9cbaeb21..431f46b1 100644 --- a/zh-cn/15.8/config/sso-entraid.rst +++ b/zh-cn/15.8/config/sso-entraid.rst @@ -107,10 +107,10 @@ Entra ID认证的工作原理 - 默认角色（逗号分隔）。会应用于每一个Entra ID用户。 - （无） * - ``entraid.permission.fields`` - - 额外用作权限值的组/角色字段（逗号分隔）。组/角色的ID（GUID）始终作为权限使用，此处指定的字段（例如 ``mail``）的值将被追加添加。 + - 额外用作权限值的组/角色字段（逗号分隔）。组/角色的ID（GUID）始终作为权限使用，此处指定的字段（例如 ``mail``）的值将被追加添加。只能指定值为字符串的字段。Microsoft Graph会将 ``securityEnabled`` 返回为布尔值、将 ``groupTypes`` 返回为数组，二者均无法作为权限值，因此指定这类字段时会被忽略，并在日志中输出指明该字段名的警告。 - ``mail`` * - ``entraid.use.ds`` - - 域服务集成。设为 ``true`` 时，对于 ``name@domain`` 格式的权限值，会同时将去除域部分后的本地部分（``name``）也添加为权限。 + - 域服务集成。设为 ``true`` 时，对于 ``name@domain`` 格式的权限值，会同时将去除域部分后的本地部分（``name``）也添加为权限。这不仅适用于组和角色，也适用于已登录的用户本人：用户主体名称（UPN）的本地部分会作为用户级权限被添加。因此设为 ``false`` 时，不仅是组的权限，该用户级权限也不会再被添加。 - ``true`` .. note:: @@ -247,9 +247,9 @@ Entra ID侧配置 嵌套组 ------ -|Fess| 不仅获取用户直接所属的组，还会递归获取父组（嵌套组）。 +|Fess| 不仅获取用户直接所属的组，还会获取这些组所属的父组（嵌套组）。 直接所属关系的查找与父组的查找都在登录后的同一个后台任务中执行，因此登录本身不会被Microsoft Graph拖慢。 -父组的查找最多涵盖一定层级数，获取结果将被缓存一段时间。该后台任务完成后，用户的权限将被重新计算。 +父组的查找使用Microsoft Graph的 ``getMemberGroups`` 操作，该操作以传递方式解析：每个直接所属的组只需调用一次，即可返回其上层的所有父组，无论嵌套有多深。获取结果将被缓存一段时间。该后台任务完成后，用户的权限将被重新计算。 默认组设置 ---------- @@ -364,6 +364,11 @@ Entra ID侧配置 - 如果解析未能完全成功，搜索界面会提示用户无法完整加载其组和角色权限，请其注销后重新登录， 并在问题反复出现时联系管理员。「完全」是特意的措辞：只有直接所属查询和嵌套组遍历都成功， 解析才算成功，因此已取得直接所属的组、但未能取得父组的用户也会看到该提示。 + 但有一个例外，即上一条所描述的情况：当因未授予 ``GroupMember.Read.All`` 而导致 + Microsoft Graph以 ``Authorization_RequestDenied`` 拒绝嵌套组查询时，\ |Fess| 不会将其视为失败， + 而是视为「该组没有父组」的回答。此时即使缺少父组的权限，解析也会被视为成功，\ **不会显示该提示**\ 。 + 唯一的线索是日志中输出的 ``Not allowed to read the parent groups of ...`` 警告， + 因此在使用嵌套组时，请确认是否出现了该警告。 部分解析失败最常见的原因是限流：Microsoft Graph只要返回一次HTTP 429或503，\ |Fess| 就会按 ``Retry-After`` 标头要求的时间（无可用值时为60秒，最长60分钟）退避，在此期间即使直接所属查询仍能成功， 整个 |Fess| 实例也会跳过嵌套组查询。但失败并不一定就是最终结果：