Skip to content

Commit

Permalink
Update searchability documentation (#3044)
Browse files Browse the repository at this point in the history
  • Loading branch information
@smatting @supersven
smatting authored and supersven committed Feb 10, 2023
1 parent 5f4c901 commit 14a8028
Showing 1 changed file with 84 additions and 105 deletions.
189 changes: 84 additions & 105 deletions docs/src/understand/searchability.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ You can configure how search is limited or not based on user membership in a giv
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.
- **Out-Bound** searches mean that you are searching for somebody. Configuring the out-bound search visibility means that some admin can configure whether you can find other users or not.

There are different types of matches:

Expand All @@ -14,9 +14,13 @@ There are different types of matches:

## Searching users on the same backend

```{note}
For configuring searching accross federated backends this section is irrelevant.
```

Search visibility is controlled by three parameters on the backend:

- A team outbound configuration flag, `TeamSearchVisibility` with possible values `SearchVisibilityStandard`, `SearchVisibilityNoNameOutsideTeam`
- A team out-bound 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)
Expand All @@ -28,7 +32,7 @@ Search visibility is controlled by three parameters on the backend:

- 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)
- `Note`: For the same backend, this affects inbound and out-bound 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.
Expand All @@ -45,13 +49,13 @@ The flags will influence the behavior of the search API endpoint; clients will o
+------------------------------------+---------------------------------+------------------------------------+------------------------------------------+-------------------------------------------+----------------------------------+--------------------------------------+
| Yes, `tA` | Yes, the same team `tA` | Irrelevant | Irrelevant | Irrelevant | Found | Found |
+------------------------------------+---------------------------------+------------------------------------+------------------------------------------+-------------------------------------------+----------------------------------+--------------------------------------+
| **Outbound search unrestricted** |
| **Out-Bound 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** |
| **Out-Bound search restricted** |
+------------------------------------+---------------------------------+------------------------------------+------------------------------------------+-------------------------------------------+----------------------------------+--------------------------------------+
| Yes, `tA` | Yes, another team tB | true | Irrelevant | Irrelevant | Not found | Not found |
+------------------------------------+---------------------------------+------------------------------------+------------------------------------------+-------------------------------------------+----------------------------------+--------------------------------------+
Expand Down Expand Up @@ -95,45 +99,38 @@ galley:

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.
## Searching users on another federated backend

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 configuration value `FederatedUserSearchPolicy` is per federated domain, e.g. in the values of the wire-server chart:

```yaml
brig:
config:
optSettings:
setFederationDomainConfigs:
- domain: a.example.com
search_policy: no_search
- domain: a.example.com
search_policy: full_search
```

- 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:
- Out-Bound search restrictions (`searchSameTeamOnly`, `TeamSearchVisibility`) do not apply to federated searches


```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

Expand All @@ -152,95 +149,39 @@ It’s worth nothing that if two users are on two separate backend, they are als

## 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):

```
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"
```
### TeamFeature searchVisibilityInbound

The team feature flag `teamSearchVisibility` determines whether it is allowed to change the `searchVisibility` setting or not.
The team feature flag `searchVisibilityInbound` affects whether the team's users are searchable by users from other teams.

The default is `disabled-by-default`.
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}
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
The default setting that applies to all teams on the instance can be defined at configuration.

```yaml
settings:
featureFlags:
teamSearchVisibility: disabled-by-default # or enabled-by-default
galley:
config:
settings:
featureFlags:
searchVisibilityInbound:
defaults:
status: enabled # or "disabled" (default is "disabled")
```

### 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):

```
PUT /i/teams/{tid}/features/search-visibility-inbound
```

With JSON body:

```json
{"status": "enabled"}
Changing this setting in the instance configuration doesn't affect any users that have already been created. To affect these users please toggle the setting on a per-team basis (see below). Switching between "enabled" and "disabled" setting for the team causes a re-indexing of all the users of the team, thereby making the setting effective, e.g. changing to a "disabled" setting first, followed by changing to an "enabled" setting (or vice versa).
```

or
#### Overriding the default setting

```json
{"status": "disabled"}
```
Individual teams can overwrite the default setting with API calls:

Where `enabled` is equivalent to `searchable-by-all-teams` and `disabled` is equivalent to `searchable-by-own-team`.
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.

The default setting that applies to all teams on the instance can be defined at configuration.

```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<https://en.wikipedia.org/wiki/Universally_unique_identifier>` which has format like this `dcbedf9a-af2a-4f43-9fd5-525953a919e1`.
It is an [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) 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.

Expand All @@ -267,9 +208,9 @@ Next, set up a port-forwarding from your local machine's port `9000` to the gall
kubectl port-forward -n wire galley-5f4787fdc7-9l64n 9000:8080
```

Keep this command running until the end of these instuctions.
Keep this command running until the end of these instructions.

Please run the following commands in a seperate terminal while keeping the terminal which establishes the port-forwarding open.
Please run the following commands in a separate terminal while keeping the terminal which establishes the port-forwarding open.

To see team's current setting run:

Expand All @@ -293,3 +234,41 @@ To change the TeamSearchVisibilityInbound to SearchableByOwnTeam for the team ru
curl -XPUT -H 'Content-Type: application/json' -d "{\"status\": \"disabled\"}" http://localhost:9000/i/teams/dcbedf9a-af2a-4f43-9fd5-525953a919e1/features/searchVisibilityInbound
```

### Team searchVisibility

The team flag `searchVisibility` affects the out-bound search of user searches on the same backend. Federated searches are not affected by its setting.

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 providing their exact handle. By default it is set to `standard`, which doesn't put any additional restrictions to out-bound searches.

The setting can be changed via endpoint (for more details on how to make the API calls with `curl`, read further):

```
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

```yaml
settings:
featureFlags:
teamSearchVisibility: disabled-by-default # or enabled-by-default
```

0 comments on commit 14a8028

Please sign in to comment.