diff --git a/docs/src/how-to/install/configuration-options.rst b/docs/src/how-to/install/configuration-options.rst index 39d442912c..6948089542 100644 --- a/docs/src/how-to/install/configuration-options.rst +++ b/docs/src/how-to/install/configuration-options.rst @@ -576,3 +576,315 @@ Second, also set the option under the `account-pages` section: account-pages: envVars: IS_SELF_HOSTED: "true" + +Configuring searchability +------------------------- + +You can configure how search is limited or not based on user membership in a given team. + +There are two types of searches based on the direction of search: + +* **Inbound** searches mean that somebody is searching for you. Configuring the inbound search visibility means that you (or some admin) can configure whether others can find you or not. +* **Outbound** searches mean that you are searching for somebody. Configuring the outbound search visibility means that some admin can configure whether you can find other users or not. + +There are different types of matches: + +* **Exact handle** search means that the user is found only if the search query is exactly the user handle (e.g. searching for `mc` will find `@mc` but not `@mccaine`). This search returns zero or one results. +* **Full text** search means that the user is found if the search query contains some subset of the user display name and handle. (e.g. the query `mar` will find `Marco C`, `Omar`, `@amaro`) + +Searching users on the same backend +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Search visibility is controlled by three parameters on the backend: + +* A team outbound configuration flag, `TeamSearchVisibility` with possible values `SearchVisibilityStandard`, `SearchVisibilityNoNameOutsideTeam` + + * `SearchVisibilityStandard` means that the user can find other people outside of the team, if the searched-person inbound search allows it + * `SearchVisibilityNoNameOutsideTeam` means that the user can not find any user outside the team by full text search (but exact handle search still works) + +* A team inbound configuration flag, `SearchVisibilityInbound` with possible values `SearchableByOwnTeam`, `SearchableByAllTeams` + + * `SearchableByOwnTeam` means that the user can be found only by users in their own team. + * `SearchableByAllTeams` means that the user can be found by users in any/all teams. + +* A server configuration flag `searchSameTeamOnly` with possible values true, false. + + * ``Note``: For the same backend, this affects inbound and outbound searches (simply because all teams will be subject to this behavior) + * Setting this to `true` means that the all teams on that backend can only find users that belong to their team + +These flag are set on the backend and the clients do not need to be aware of them. + +The flags will influence the behavior of the search API endpoint; clients will only need to parse the results, that are already filtered for them by the backend. + +Table of possible outcomes +.......................... + ++------------------------------------+---------------------------------+------------------------------------+------------------------------------------+-------------------------------------------+----------------------------------+--------------------------------------+ +| Is search-er (`uA`) in team (tA)? | Is search-ed (`uB`) in a team? | Backend flag `searchSameTeamOnly` | Team `tA`'s flag `TeamSearchVisibility` | Team tB's flag `SearchVisibilityInbound` | Result of exact search for `uB` | Result of full-text search for `uB` | ++====================================+=================================+====================================+==========================================+===========================================+==================================+======================================+ +| **Search within the same team** | ++------------------------------------+---------------------------------+------------------------------------+------------------------------------------+-------------------------------------------+----------------------------------+--------------------------------------+ +| Yes, `tA` | Yes, the same team `tA` | Irrelevant | Irrelevant | Irrelevant | Found | Found | ++------------------------------------+---------------------------------+------------------------------------+------------------------------------------+-------------------------------------------+----------------------------------+--------------------------------------+ +| **Outbound search unrestricted** | ++------------------------------------+---------------------------------+------------------------------------+------------------------------------------+-------------------------------------------+----------------------------------+--------------------------------------+ +| Yes, `tA` | Yes, another team tB | false | `SearchVisibilityStandard` | `SearchableByAllTeams` | Found | Found | ++------------------------------------+---------------------------------+------------------------------------+------------------------------------------+-------------------------------------------+----------------------------------+--------------------------------------+ +| Yes, `tA` | Yes, another team tB | false | `SearchVisibilityStandard` | `SearchableByOwnTeam` | Found | Not found | ++------------------------------------+---------------------------------+------------------------------------+------------------------------------------+-------------------------------------------+----------------------------------+--------------------------------------+ +| **Outbound search restricted** | ++------------------------------------+---------------------------------+------------------------------------+------------------------------------------+-------------------------------------------+----------------------------------+--------------------------------------+ +| Yes, `tA` | Yes, another team tB | true | Irrelevant | Irrelevant | Not found | Not found | ++------------------------------------+---------------------------------+------------------------------------+------------------------------------------+-------------------------------------------+----------------------------------+--------------------------------------+ +| Yes, `tA` | Yes, another team tB | false | `SearchVisibilityNoNameOutsideTeam` | Irrelevant | Found | Not found | ++------------------------------------+---------------------------------+------------------------------------+------------------------------------------+-------------------------------------------+----------------------------------+--------------------------------------+ +| Yes, `tA` | No | false | `SearchVisibilityNoNameOutsideTeam` | There’s no team B | Found | Not found | ++------------------------------------+---------------------------------+------------------------------------+------------------------------------------+-------------------------------------------+----------------------------------+--------------------------------------+ + + +Changing the configuration on the server +........................................ + +To change the `searchSameTeamOnly` setting on the backend, edit the `values.yaml.gotmpl` file for the wire-server chart at this nested level of the configuration: + +.. code:: yaml + + brig: + # ... + config: + # ... + optSettings: + # ... + setSearchSameTeamOnly: true + +If `setSearchSameTeamOnly` is set to `true` then `TeamSearchVisibility` is forced be in the `SearchVisibilityNoNameOutsideTeam` setting for all teams. + +Changing the default configuration for all teams +................................................ + +If `setSearchSameTeamOnly` is set to `false` (or missing from the configuration) then the default value `TeamSearchVisibility` can be configured at this level of the configuration of the `value.yaml.gotmpl` file of the wire-server chart: + + +.. code:: yaml + + galley: + #... + config: + #... + settings: + #... + featureFlags: + #... + teamSearchVisibility: enabled-by-default + +This default value applies to all teams for which no explicit configuration of the `TeamSearchVisibility` has been set. + + +Searching users on another (federated) backend +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For federated search the table above does not apply, see following table. + +.. note:: + + Incoming federated searches (i.e. searches from one backend to another) are considered always as being performed from a team user, even if they are performed from a personal user. + + This is because the incoming search request does not carry the information whether the user performing the search was in a team or not. + + So we have to make one assumption, and we assume that they were in a team. + +Allowing search is done at the backend configuration level by the sysadmin: + +* Outbound search restrictions (`searchSameTeamOnly`, `TeamSearchVisibility`) do not apply to federated searches +* A configuration setting `FederatedUserSearchPolicy` per federating domain with these possible values: + + * `no_search` The federating backend is not allowed to search any users (either by exact handle or full-text). + * `exact_handle_search` The federating backend may only search by exact handle + * `full_search` The federating backend may search users by full text search on display name and handle. The search search results are additionally affected by `SearchVisibilityInbound` setting of each team on the backend. +* The `SearchVisibilityInbound` setting applies. Since the default value for teams is `SearchableByOwnTeam` this means that for a team to be full-text searchable by users on a federating backend both + + * `FederatedUserSearchPolicy` needs to be set to to full_search for the federating backend + * Any team that wants to be full-text searchable needs to be set to `SearchableByAllTeams` + +The configuration value `FederatedUserSearchPolicy` is per federated domain, e.g. in the values of the wire-server chart: + +.. code:: yaml + + brig: + config: + optSettings: + setFederationDomainConfigs: + - domain: a.example.com + search_policy: no_search + - domain: a.example.com + search_policy: full_search + +Table of possible outcomes +.......................... + +In the following table, user `uA` on backend A is searching for user `uB` on team `tB` on backend B. + +Any of the flags set for searching users on the same backend are ignored. + +It’s worth nothing that if two users are on two separate backend, they are also guaranteed to be on two separate teams, as teams can not spread across backends. + ++-------------------------+---------------------------------------------+---------------------------------------------+----------------------------------+--------------------------------------+ +| Who is searching | Backend B flag `FederatedUserSearchPolicy` | Team `tB`'s flag `SearchVisibilityInbound` | Result of exact search for `uB` | Result of full-text search for `uB` | ++=========================+=============================================+=============================================+==================================+======================================+ +| user `uA` on backend A | `no_search` | Irrelevant | Not found | Not found | ++-------------------------+---------------------------------------------+---------------------------------------------+----------------------------------+--------------------------------------+ +| user `uA` on backend A | `exact_handle_search` | Irrelevant | Found | Not found | ++-------------------------+---------------------------------------------+---------------------------------------------+----------------------------------+--------------------------------------+ +| user `uA` on backend A | `full_search` | SearchableByOwnTeam | Found | Not found | ++-------------------------+---------------------------------------------+---------------------------------------------+----------------------------------+--------------------------------------+ +| user `uA` on backend A | `full_search` | SearchableByAllTeams | Found | Found | ++-------------------------+---------------------------------------------+---------------------------------------------+----------------------------------+--------------------------------------+ + +Changing the settings for a given team +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you need to change searchabilility for a specific team (rather than the entire backend, as above), you need to make specific calls to the API. + +Team searchVisibility +..................... + +The team flag `searchVisibility` affects the outbound search of user searches. + +If it is set to `no-name-outside-team` for a team then all users of that team will no longer be able to find users that are not part of their team when searching. + +This also includes finding other users by by providing their exact handle. By default it is set to `standard`, which doesn't put any additional restrictions to outbound searches. + +The setting can be changed via endpoint (for more details on how to make the API calls with `curl`, read further): + +.. code:: + + GET /teams/{tid}/search-visibility + -- Shows the current TeamSearchVisibility value for the given team + + PUT /teams/{tid}/search-visibility + -- Set specific search visibility for the team + + pull-down-menu "body": + "standard" + "no-name-outside-team" + +The team feature flag `teamSearchVisibility` determines whether it is allowed to change the `searchVisibility` setting or not. + +The default is `disabled-by-default`. + +.. note:: + + Whenever this feature setting is disabled the `searchVisibility` will be reset to standard. + +The default setting that applies to all teams on the instance can be defined at configuration + +.. code:: yaml + + settings: + featureFlags: + teamSearchVisibility: disabled-by-default # or enabled-by-default + +TeamFeature searchVisibilityInbound +................................... + +The team feature flag `searchVisibilityInbound` affects if the team's users are searchable by users from other teams. + +The default setting is `searchable-by-own-team` which hides users from search results by users from other teams. + +If it is set to `searchable-by-all-teams` then users of this team may be included in the results of search queries by other users. + +.. note:: + + The configuration of this flag does not affect search results when the search query matches the handle exactly. + + If the handle is provdided then any user on the instance can find users. + +This team feature flag can only by toggled by site-administrators with direct access to the galley instance (for more details on how to make the API calls with `curl`, read further): + +.. code:: + + PUT /i/teams/{tid}/features/search-visibility-inbound + +With JSON body: + +.. code:: json + + {"status": "enabled"} + +or + +.. code:: json + + {"status": "disabled"} + +Where `enabled` is equivalent to `searchable-by-all-teams` and `disabled` is equivalent to `searchable-by-own-team`. + +The default setting that applies to all teams on the instance can be defined at configuration. + +.. code:: yaml + + searchVisibilityInbound: + defaults: + status: enabled # OR disabled + +Individual teams can overwrite the default setting with API calls as per above. + +Making the API calls +.................... + +To make API calls to set an explicit configuration for` TeamSearchVisibilityInbound` per team, you first need to know the Team ID, which can be found in the team settings app. + +It is an `UUID` which has format like this `dcbedf9a-af2a-4f43-9fd5-525953a919e1`. + +In the following we will be using this Team ID as an example, please replace it with your own team id. + +Next find the name of a `galley` pod by looking at the output of running this command: + +.. code:: sh + + kubectl -n wire get pods + +The output will look something like this: + +.. code:: + + ... + galley-5f4787fdc7-9l64n ... + galley-migrate-data-lzz5j ... + ... + +Select any of the galley pods, for example we will use `galley-5f4787fdc7-9l64n`. + +Next, set up a port-forwarding from your local machine's port `9000` to the galley's port `8080` by running: + +.. code:: sh + + kubectl port-forward -n wire galley-5f4787fdc7-9l64n 9000:8080 + +Keep this command running until the end of these instuctions. + +Please run the following commands in a seperate terminal while keeping the terminal which establishes the port-forwarding open. + +To see team's current setting run: + +.. code:: sh + + curl -XGET http://localhost:9000/i/teams/dcbedf9a-af2a-4f43-9fd5-525953a919e1/features/searchVisibilityInbound + + # {"lockStatus":"unlocked","status":"disabled"} + +Where `disabled` corresponds to `SearchableByOwnTeam` and enabled corresponds to `SearchableByAllTeams`. + +To change the `TeamSearchVisibilityInbound` to `SearchableByAllTeams` for the team run: + +.. code:: sh + + curl -XPUT -H 'Content-Type: application/json' -d "{\"status\": \"enabled\"}" http://localhost:9000/i/teams/dcbedf9a-af2a-4f43-9fd5-525953a919e1/features/searchVisibilityInbound + +To change the TeamSearchVisibilityInbound to SearchableByOwnTeam for the team run: + +.. code:: sh + + curl -XPUT -H 'Content-Type: application/json' -d "{\"status\": \"disabled\"}" http://localhost:9000/i/teams/dcbedf9a-af2a-4f43-9fd5-525953a919e1/features/searchVisibilityInbound + + \ No newline at end of file