User 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.

  • 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:

  • 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

Note

For configuring searching accross federated backends this section is irrelevant.

Search visibility is controlled by three parameters on the backend:

  • 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’t find any user outside the team by full text search (but exact username search still works)

  • A team inbound configuration flag, SearchVisibilityInbound with possible values SearchableByOwnTeam, SearchableByAllTeams

    • SearchableByOwnTeam means that the user can be found with full text search only by users in their own team

    • SearchableByAllTeams means that the user can be found with full text search by all users in any/all teams.

  • A server configuration flag searchSameTeamOnly with possible values true, false.

    • 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 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.

Some configuration values supersede others. The table below clarifies how the various values interact with each other, highlighting the outcome of each search for the various combinations of values.

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

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

Out-Bound 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:

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:

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

  • Setting the search policy for individual remote federated backends is done via a internal brig api end-points by a sysadmin (see Configure federation strategy (whom to federate with) in brig}.

  • 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

  • Out-Bound search restrictions (searchSameTeamOnly, TeamSearchVisibility) do not apply to federated searches

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

TeamFeature searchVisibilityInbound

The team feature flag searchVisibilityInbound affects whether 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.

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

galley:
  config:
    settings:
      featureFlags:
        searchVisibilityInbound:
          defaults:
            status: enabled # or "disabled" (default is "disabled")

Note

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).

Overriding the default setting

Individual teams can overwrite the default setting with API calls:

To make API calls to set an explicit configuration for SearchVisibilityInbound 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:

kubectl -n wire get pods

The output will look something like this:

...
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:

kubectl port-forward -n wire galley-5f4787fdc7-9l64n 9000:8080

Keep this command running until the end of these instructions.

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:

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 SearchVisibilityInbound to SearchableByAllTeams for the team run:

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 SearchVisibilityInbound to SearchableByOwnTeam for the team run:

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

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