diff --git a/changelog.d/5-internal/restructure-docs b/changelog.d/5-internal/restructure-docs new file mode 100644 index 0000000000..f9c770a9cc --- /dev/null +++ b/changelog.d/5-internal/restructure-docs @@ -0,0 +1 @@ +Restructure docs.wire.com diff --git a/docs/.gitignore b/docs/.gitignore index 4ca8ba1127..2e23a54802 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -6,3 +6,6 @@ build # direnv - nix derivation result + +# this is so that the nix build doesn't copy a dangling symlink +src/changelog/changelog.md diff --git a/docs/diagrams/mmdc b/docs/diagrams/mmdc deleted file mode 120000 index df57a81b6b..0000000000 --- a/docs/diagrams/mmdc +++ /dev/null @@ -1 +0,0 @@ -./node_modules/.bin/mmdc \ No newline at end of file diff --git a/docs/src/changelog/changelog.md b/docs/src/changelog/changelog.md new file mode 120000 index 0000000000..79b747aee1 --- /dev/null +++ b/docs/src/changelog/changelog.md @@ -0,0 +1 @@ +../../../CHANGELOG.md \ No newline at end of file diff --git a/docs/src/changelog/index.md b/docs/src/changelog/index.md new file mode 100644 index 0000000000..8eb248cd07 --- /dev/null +++ b/docs/src/changelog/index.md @@ -0,0 +1,9 @@ +# Releases + +```{toctree} +:caption: 'Contents:' +:glob: true +:maxdepth: 1 + +Releases +``` diff --git a/docs/src/conf.py b/docs/src/conf.py index 750a09f904..c91faf4b90 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -136,5 +136,6 @@ "security-responses/log4shell": "2021-12-15_log4shell.html", "security-responses/cve-2021-44521": "2022-02-21_cve-2021-44521.html", "security-responses/2022-05_website_outage": "2022-05-23_website_outage.html", + "how-to/single-sign-on/index": "../../understand/single-sign-on/index.html", "how-to/scim/index": "../../understand/single-sign-on/main.html#user-provisioning" } diff --git a/docs/src/developer/reference/config-options.md b/docs/src/developer/reference/config-options.md index 98eb07ff17..938ddba131 100644 --- a/docs/src/developer/reference/config-options.md +++ b/docs/src/developer/reference/config-options.md @@ -30,8 +30,7 @@ production. ### MLS private key paths -Note: This developer documentation. Documentation for site operators can be found here: -[Messaging Layer Security (MLS)](../../how-to/install/mls.md). +Note: This developer documentation. Documentation for site operators can be found here: {ref}`mls-message-layer-security` The `mlsPrivateKeyPaths` field should contain a mapping from *purposes* and signature schemes to file paths of corresponding x509 private keys in PEM diff --git a/docs/src/developer/reference/spar-braindump.md b/docs/src/developer/reference/spar-braindump.md index dcee5847e9..05735e98c6 100644 --- a/docs/src/developer/reference/spar-braindump.md +++ b/docs/src/developer/reference/spar-braindump.md @@ -1,7 +1,12 @@ # Spar braindump Reference: {#SparBrainDump} - +/home/stefan/repos/wire-server/docs/src/how-to/install/includes/helm_dns-ingress-troubleshooting.inc.rst:147: WARNING: duplicate label trying things out, other instance in /home/stefan/repos/wire-server/docs/src/how-to/install/helm.md +/home/stefan/repos/wire-server/docs/src/how-to/install/includes/helm_dns-ingress-troubleshooting.inc.rst:170: WARNING: duplicate label troubleshooting, other instance in /home/stefan/repos/wire-server/docs/src/how-to/install/helm.md +/home/stefan/repos/wire-server/docs/src/developer/reference/config-options.md:33: WARNING: 'myst' reference target not found: ../../how-to/install/mls.md +/home/stefan/repos/wire-server/docs/src/developer/reference/spar-braindump.md:116: WARNING: 'myst' reference target not found: ../../how-to/single-sign-on/understand/main.rst +/home/stefan/repos/wire-server/docs/src/how-to/install/ansible-VMs.md:97: WARNING: undefined label: 'checks' +/home/stefan/repos/wire-server/docs/src/understand/federation/api.md:162: WARNING: 'myst' reference target not found: ../../how-to/install/mls _Author: Matthias Fischmann_ --- @@ -113,7 +118,8 @@ export IDP_ID=... Copy the new metadata file to one of your spar instances. -Ssh into it. If you can't, [the sso docs](../../how-to/single-sign-on/understand/main.rst) explain how you can create a + +Ssh into it. If you can't, {ref}`the sso docs ` explain how you can create a bearer token if you have the admin's login credentials. If you follow that approach, you need to replace all mentions of `-H'Z-User ...'` with `-H'Authorization: Bearer ...'` in the following, and you won't need diff --git a/docs/src/how-to/install/index.md b/docs/src/how-to/install/index.md index 2758ad819a..b45b694832 100644 --- a/docs/src/how-to/install/index.md +++ b/docs/src/how-to/install/index.md @@ -7,22 +7,22 @@ How to plan an installation Version requirements dependencies -(demo) How to install kubernetes -(demo) How to install wire-server using Helm -(production) Introduction -(production) How to install kubernetes and databases -(production) How to configure AWS services -(production) How to install wire-server using Helm -(production) How to monitor wire-server -(production) How to see centralized logs for wire-server -Server and team feature settings -Messaging Layer Security (MLS) + +How to install kubernetes (Demo) +How to install wire-server using Helm (Demo) + +Introduction +How to install kubernetes and databases +How to configure AWS services +How to install wire-server using Helm +Infrastructure configuration +How to monitor wire-server +How to see centralized logs for wire-server + Web app settings sft restund -configure-federation tls -How to install and set up Legal Hold Managing authentication with ansible Using tinc Troubleshooting during installation diff --git a/docs/src/configuration-options.md b/docs/src/how-to/install/infrastructure-configuration.md similarity index 50% rename from docs/src/configuration-options.md rename to docs/src/how-to/install/infrastructure-configuration.md index 1eeee72383..0e9d9a0029 100644 --- a/docs/src/configuration-options.md +++ b/docs/src/how-to/install/infrastructure-configuration.md @@ -1,6 +1,6 @@ (configuration-options)= -# Part 3 - configuration options in a production setup +# Infrastructure configuration options This contains instructions to configure specific aspects of your production setup depending on your needs. @@ -288,39 +288,6 @@ websockets: enabled: false ``` -## Blocking creation of personal users, new teams - -### In Brig - -There are some unauthenticated end-points that allow arbitrary users on the open internet to do things like create a new team. This is desired in the cloud, but if you run an on-prem setup that is open to the world, you may want to block this. - -Brig has a server option for this: - -```yaml -optSettings: - setRestrictUserCreation: true -``` - -If `setRestrictUserCreation` is `true`, creating new personal users or new teams on your instance from outside your backend installation is impossible. (If you want to be more technical: requests to `/register` that create a new personal account or a new team are answered with `403 forbidden`.) - -On instances with restricted user creation, the site operator with access to the internal REST API can still circumvent the restriction: just log into a brig service pod via ssh and follow the steps in `hack/bin/create_test_team_admins.sh.` - -```{note} -Once the creation of new users and teams has been disabled, it will still be possible to use the [team creation process](https://support.wire.com/hc/en-us/articles/115003858905-Create-a-team) (enter the new team name, email, password, etc), but it will fail/refuse creation late in the creation process (after the «Create team» button is clicked). -``` - -### In the WebApp - -Another way of disabling user registration is by this webapp setting, in `values.yaml`, changing this value from `true` to `false`: - -```yaml -FEATURE_ENABLE_ACCOUNT_REGISTRATION: "false" -``` - -```{note} -If you only disable the creation of users in the webapp, but do not do so in Brig/the backend, a malicious user would be able to use the API to create users, so make sure to disable both. -``` - ## You may want - more server resources to ensure @@ -666,342 +633,6 @@ brig: retryAfter: 86400 ``` -## 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 - -```{eval-rst} -+------------------------------------+---------------------------------+------------------------------------+------------------------------------------+-------------------------------------------+----------------------------------+--------------------------------------+ -| 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: - -```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: - -```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: - -```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): - -``` -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 -``` - -#### 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"} -``` - -or - -```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. - -```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: - -```sh -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: - -```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: - -```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: - -```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: - -```sh -curl -XPUT -H 'Content-Type: application/json' -d "{\"status\": \"disabled\"}" http://localhost:9000/i/teams/dcbedf9a-af2a-4f43-9fd5-525953a919e1/features/searchVisibilityInbound -``` - -## Configuring classified domains - -As a backend administrator, if you want to control which other backends (identified by their domain) are "classified", - -change the following `galley` configuration in the `value.yaml.gotmpl` file of the wire-server chart: - -```yaml -galley: - replicaCount: 1 - config: - ... - featureFlags: - ... - classifiedDomains: - status: enabled - config: - domains: ["domain-that-is-classified.link"] - ... -``` - -This is not only a `backend` configuration, but also a `team` configuration/feature. - -This means that different combinations of configurations will have different results. - -Here is a table to navigate the possible configurations: - -| Backend Config enabled/disabled | Backend Config Domains | Team Config enabled/disabled | Team Config Domains | User's view | -| ------------------------------- | ---------------------------------------------- | ---------------------------- | ----------------------- | -------------------------------- | -| Enabled | \[domain1.example.com\] | Not configured | Not configured | Enabled, \[domain1.example.com\] | -| Enabled | \[domain1.example.com\]\[domain1.example.com\] | Enabled | Not configured | Enabled, \[domain1.example.com\] | -| Enabled | \[domain1.example.com\] | Enabled | \[domain2.example.com\] | Enabled, Undefined | -| Enabled | \[domain1.example.com\] | Disabled | Anything | Undefined | -| Disabled | Anything | Not configured | Not configured | Disabled, no domains | -| Disabled | Anything | Enabled | \[domain2.example.com\] | Undefined | - -The table assumes the following: - -- When backend level config says that this feature is enabled, it is illegal to not specify domains at the backend level. -- When backend level config says that this feature is disabled, the list of domains is ignored. -- When team level feature is disabled, the accompanying domains are ignored. - ## S3 Addressing Style S3 can either by addressed in path style, i.e. diff --git a/docs/src/index.md b/docs/src/index.md index da0c17e170..bb8d35a63b 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -15,24 +15,19 @@ The targeted audience of this documentation is: If you are a developer, you may want to check out the "Notes for developers" first. -This documentation may be expanded in the future to cover other aspects of Wire. +Release notes of `wire-server` can be found [here](https://github.com/wireapp/wire-server/releases). ```{toctree} :caption: 'Contents:' :glob: true :maxdepth: 1 -Release notes - +Security responses +Release Notes Installation Administration -Connecting Wire Clients -Optional Configuration -Understanding wire-server components -Single-Sign-On and user provisioning -API documentation -Security responses -Notes for developers +Reference +Developers Notes ``` % Overview diff --git a/docs/src/release-notes.md b/docs/src/release-notes.md deleted file mode 100644 index 478db87668..0000000000 --- a/docs/src/release-notes.md +++ /dev/null @@ -1,13 +0,0 @@ -(release-notes)= - -# Release notes - -This page previously contained the release notes for the project, and they were manually updated each time a new release was done, due to limitations in Github's «releases» feature. - -However, Github since updated the feature, making this page un-necessary. - -Go to → [GitHub - wireapp/wire-server: Wire back-end services](https://github.com/wireapp/wire-server/) - -→ Look at releases on right hand side. They are shown by date of release. [Release Notes](https://github.com/wireapp/wire-server/releases) - -→ Open the CHANGELOG.md. This will give you chart version. diff --git a/docs/src/how-to/associate/custom-backend-for-desktop-client.md b/docs/src/understand/associate/custom-backend-for-desktop-client.md similarity index 100% rename from docs/src/how-to/associate/custom-backend-for-desktop-client.md rename to docs/src/understand/associate/custom-backend-for-desktop-client.md diff --git a/docs/src/how-to/associate/custom-certificates.md b/docs/src/understand/associate/custom-certificates.md similarity index 100% rename from docs/src/how-to/associate/custom-certificates.md rename to docs/src/understand/associate/custom-certificates.md diff --git a/docs/src/how-to/associate/deeplink.md b/docs/src/understand/associate/deeplink.md similarity index 100% rename from docs/src/how-to/associate/deeplink.md rename to docs/src/understand/associate/deeplink.md diff --git a/docs/src/how-to/associate/index.md b/docs/src/understand/associate/index.md similarity index 100% rename from docs/src/how-to/associate/index.md rename to docs/src/understand/associate/index.md diff --git a/docs/src/understand/block-user-creation.md b/docs/src/understand/block-user-creation.md new file mode 100644 index 0000000000..5c1e563aab --- /dev/null +++ b/docs/src/understand/block-user-creation.md @@ -0,0 +1,34 @@ +# Block personal user creation + +## In Brig + +There are some unauthenticated end-points that allow arbitrary users on the open internet to do things like create a new team. This is desired in the cloud, but if you run an on-prem setup that is open to the world, you may want to block this. + +Brig has a server option for this: + +```yaml +optSettings: + setRestrictUserCreation: true +``` + +If `setRestrictUserCreation` is `true`, creating new personal users or new teams on your instance from outside your backend installation is impossible. (If you want to be more technical: requests to `/register` that create a new personal account or a new team are answered with `403 forbidden`.) + +On instances with restricted user creation, the site operator with access to the internal REST API can still circumvent the restriction: just log into a brig service pod via ssh and follow the steps in `hack/bin/create_test_team_admins.sh.` + +```{note} +Once the creation of new users and teams has been disabled, it will still be possible to use the [team creation process](https://support.wire.com/hc/en-us/articles/115003858905-Create-a-team) (enter the new team name, email, password, etc), but it will fail/refuse creation late in the creation process (after the «Create team» button is clicked). +``` + +## In the WebApp + +Another way of disabling user registration is by this webapp setting, in `values.yaml`, changing this value from `true` to `false`: + +```yaml +FEATURE_ENABLE_ACCOUNT_REGISTRATION: "false" +``` + +```{note} +If you only disable the creation of users in the webapp, but do not do so in Brig/the backend, a malicious user would be able to use the API to create users, so make sure to disable both. +``` + + diff --git a/docs/src/understand/classified-domains.md b/docs/src/understand/classified-domains.md new file mode 100644 index 0000000000..5d27945abb --- /dev/null +++ b/docs/src/understand/classified-domains.md @@ -0,0 +1,40 @@ +# Classified Domains + +As a backend administrator, if you want to control which other backends (identified by their domain) are "classified", + +change the following `galley` configuration in the `value.yaml.gotmpl` file of the wire-server chart: + +```yaml +galley: + replicaCount: 1 + config: + ... + featureFlags: + ... + classifiedDomains: + status: enabled + config: + domains: ["domain-that-is-classified.link"] + ... +``` + +This is not only a `backend` configuration, but also a `team` configuration/feature. + +This means that different combinations of configurations will have different results. + +Here is a table to navigate the possible configurations: + +| Backend Config enabled/disabled | Backend Config Domains | Team Config enabled/disabled | Team Config Domains | User's view | +| ------------------------------- | ---------------------------------------------- | ---------------------------- | ----------------------- | -------------------------------- | +| Enabled | \[domain1.example.com\] | Not configured | Not configured | Enabled, \[domain1.example.com\] | +| Enabled | \[domain1.example.com\]\[domain1.example.com\] | Enabled | Not configured | Enabled, \[domain1.example.com\] | +| Enabled | \[domain1.example.com\] | Enabled | \[domain2.example.com\] | Enabled, Undefined | +| Enabled | \[domain1.example.com\] | Disabled | Anything | Undefined | +| Disabled | Anything | Not configured | Not configured | Disabled, no domains | +| Disabled | Anything | Enabled | \[domain2.example.com\] | Undefined | + +The table assumes the following: + +- When backend level config says that this feature is enabled, it is illegal to not specify domains at the backend level. +- When backend level config says that this feature is disabled, the list of domains is ignored. +- When team level feature is disabled, the accompanying domains are ignored. diff --git a/docs/src/how-to/install/configure-federation.md b/docs/src/understand/configure-federation.md similarity index 99% rename from docs/src/how-to/install/configure-federation.md rename to docs/src/understand/configure-federation.md index 69396c92b5..6d0042eaad 100644 --- a/docs/src/how-to/install/configure-federation.md +++ b/docs/src/understand/configure-federation.md @@ -1,5 +1,5 @@ (configure-federation)= -# Configure Wire-Server for Federation +# Federation See also {ref}`federation-understand`, which explains the architecture and concepts. diff --git a/docs/src/understand/federation/api.md b/docs/src/understand/federation/api.md index e48e642294..7b576d9234 100644 --- a/docs/src/understand/federation/api.md +++ b/docs/src/understand/federation/api.md @@ -159,7 +159,7 @@ the backend. - `get-user-clients`: Given a list of user ids, return a list of all their clients with public information - `send-connection-action`: Make and also respond to user connection requests - `on-user-deleted-connections`: Notify users that are connected to remote user about that user's deletion -- `get-mls-clients`: Request all [MLS](../../how-to/install/mls)-capable clients for a given user +- `get-mls-clients`: Request all {ref}`MLS `-capable clients for a given user - `claim-key-packages`: Claim a previously-uploaded KeyPackage of a remote user. User for adding users to MLS conversations. See [the brig source diff --git a/docs/src/how-to/install/img/legalhold-screencast.gif b/docs/src/understand/img/legalhold-screencast.gif similarity index 100% rename from docs/src/how-to/install/img/legalhold-screencast.gif rename to docs/src/understand/img/legalhold-screencast.gif diff --git a/docs/src/how-to/install/img/legalhold-step01-click-customization.png b/docs/src/understand/img/legalhold-step01-click-customization.png similarity index 100% rename from docs/src/how-to/install/img/legalhold-step01-click-customization.png rename to docs/src/understand/img/legalhold-step01-click-customization.png diff --git a/docs/src/how-to/install/img/legalhold-step02-goto-legalhold.png b/docs/src/understand/img/legalhold-step02-goto-legalhold.png similarity index 100% rename from docs/src/how-to/install/img/legalhold-step02-goto-legalhold.png rename to docs/src/understand/img/legalhold-step02-goto-legalhold.png diff --git a/docs/src/how-to/install/img/legalhold-step03-click-arrow.png b/docs/src/understand/img/legalhold-step03-click-arrow.png similarity index 100% rename from docs/src/how-to/install/img/legalhold-step03-click-arrow.png rename to docs/src/understand/img/legalhold-step03-click-arrow.png diff --git a/docs/src/how-to/install/img/legalhold-step04-click-manage-configuration.png b/docs/src/understand/img/legalhold-step04-click-manage-configuration.png similarity index 100% rename from docs/src/how-to/install/img/legalhold-step04-click-manage-configuration.png rename to docs/src/understand/img/legalhold-step04-click-manage-configuration.png diff --git a/docs/src/how-to/install/img/legalhold-step05-fill-info.png b/docs/src/understand/img/legalhold-step05-fill-info.png similarity index 100% rename from docs/src/how-to/install/img/legalhold-step05-fill-info.png rename to docs/src/understand/img/legalhold-step05-fill-info.png diff --git a/docs/src/understand/index.md b/docs/src/understand/index.md index f7ca56369a..dd9474bceb 100644 --- a/docs/src/understand/index.md +++ b/docs/src/understand/index.md @@ -1,17 +1,19 @@ (understand)= -# Understanding wire-server components - -This section is almost empty, more documentation will come soon... +# Reference ```{toctree} :glob: true -:maxdepth: 1 +:maxdepth: 2 -Overview +Architecture Overview +Single Sign-On and User Provisioning Audio/video calling, restund servers (TURN/STUN) Conference Calling 2.0 (SFT) Minio Helm Federation +Connecting Wire Clients +Client API documentation +* ``` diff --git a/docs/src/how-to/install/legalhold.md b/docs/src/understand/legalhold.md similarity index 100% rename from docs/src/how-to/install/legalhold.md rename to docs/src/understand/legalhold.md diff --git a/docs/src/how-to/install/mls.md b/docs/src/understand/mls.md similarity index 98% rename from docs/src/how-to/install/mls.md rename to docs/src/understand/mls.md index 9e4543b011..591451a0ab 100644 --- a/docs/src/how-to/install/mls.md +++ b/docs/src/understand/mls.md @@ -1,3 +1,5 @@ +(mls-message-layer-security)= + # Messaging Layer Security (MLS) To enable support for [MLS](https://datatracker.ietf.org/wg/mls/documents/) diff --git a/docs/src/understand/overview.md b/docs/src/understand/overview.md index 56f203f707..6926a81280 100644 --- a/docs/src/understand/overview.md +++ b/docs/src/understand/overview.md @@ -1,6 +1,6 @@ (overview)= -# Overview +# Architecture Overview ## Introduction diff --git a/docs/src/understand/searchability.md b/docs/src/understand/searchability.md new file mode 100644 index 0000000000..083faa030f --- /dev/null +++ b/docs/src/understand/searchability.md @@ -0,0 +1,295 @@ +# 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. +- **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 + +```{eval-rst} ++------------------------------------+---------------------------------+------------------------------------+------------------------------------------+-------------------------------------------+----------------------------------+--------------------------------------+ +| 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: + +```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: + +```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: + +```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): + +``` +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 +``` + +### 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"} +``` + +or + +```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. + +```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: + +```sh +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: + +```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: + +```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: + +```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: + +```sh +curl -XPUT -H 'Content-Type: application/json' -d "{\"status\": \"disabled\"}" http://localhost:9000/i/teams/dcbedf9a-af2a-4f43-9fd5-525953a919e1/features/searchVisibilityInbound +``` + diff --git a/docs/src/how-to/single-sign-on/adfs/fig-00.jpg b/docs/src/understand/single-sign-on/adfs/fig-00.jpg similarity index 100% rename from docs/src/how-to/single-sign-on/adfs/fig-00.jpg rename to docs/src/understand/single-sign-on/adfs/fig-00.jpg diff --git a/docs/src/how-to/single-sign-on/adfs/fig-01.jpg b/docs/src/understand/single-sign-on/adfs/fig-01.jpg similarity index 100% rename from docs/src/how-to/single-sign-on/adfs/fig-01.jpg rename to docs/src/understand/single-sign-on/adfs/fig-01.jpg diff --git a/docs/src/how-to/single-sign-on/adfs/fig-02.jpg b/docs/src/understand/single-sign-on/adfs/fig-02.jpg similarity index 100% rename from docs/src/how-to/single-sign-on/adfs/fig-02.jpg rename to docs/src/understand/single-sign-on/adfs/fig-02.jpg diff --git a/docs/src/how-to/single-sign-on/adfs/fig-03.jpg b/docs/src/understand/single-sign-on/adfs/fig-03.jpg similarity index 100% rename from docs/src/how-to/single-sign-on/adfs/fig-03.jpg rename to docs/src/understand/single-sign-on/adfs/fig-03.jpg diff --git a/docs/src/how-to/single-sign-on/adfs/fig-04.jpg b/docs/src/understand/single-sign-on/adfs/fig-04.jpg similarity index 100% rename from docs/src/how-to/single-sign-on/adfs/fig-04.jpg rename to docs/src/understand/single-sign-on/adfs/fig-04.jpg diff --git a/docs/src/how-to/single-sign-on/adfs/fig-05.jpg b/docs/src/understand/single-sign-on/adfs/fig-05.jpg similarity index 100% rename from docs/src/how-to/single-sign-on/adfs/fig-05.jpg rename to docs/src/understand/single-sign-on/adfs/fig-05.jpg diff --git a/docs/src/how-to/single-sign-on/adfs/fig-06.jpg b/docs/src/understand/single-sign-on/adfs/fig-06.jpg similarity index 100% rename from docs/src/how-to/single-sign-on/adfs/fig-06.jpg rename to docs/src/understand/single-sign-on/adfs/fig-06.jpg diff --git a/docs/src/how-to/single-sign-on/adfs/fig-07.jpg b/docs/src/understand/single-sign-on/adfs/fig-07.jpg similarity index 100% rename from docs/src/how-to/single-sign-on/adfs/fig-07.jpg rename to docs/src/understand/single-sign-on/adfs/fig-07.jpg diff --git a/docs/src/how-to/single-sign-on/adfs/fig-08.jpg b/docs/src/understand/single-sign-on/adfs/fig-08.jpg similarity index 100% rename from docs/src/how-to/single-sign-on/adfs/fig-08.jpg rename to docs/src/understand/single-sign-on/adfs/fig-08.jpg diff --git a/docs/src/how-to/single-sign-on/adfs/fig-09.jpg b/docs/src/understand/single-sign-on/adfs/fig-09.jpg similarity index 100% rename from docs/src/how-to/single-sign-on/adfs/fig-09.jpg rename to docs/src/understand/single-sign-on/adfs/fig-09.jpg diff --git a/docs/src/how-to/single-sign-on/adfs/fig-10.jpg b/docs/src/understand/single-sign-on/adfs/fig-10.jpg similarity index 100% rename from docs/src/how-to/single-sign-on/adfs/fig-10.jpg rename to docs/src/understand/single-sign-on/adfs/fig-10.jpg diff --git a/docs/src/how-to/single-sign-on/adfs/fig-11.jpg b/docs/src/understand/single-sign-on/adfs/fig-11.jpg similarity index 100% rename from docs/src/how-to/single-sign-on/adfs/fig-11.jpg rename to docs/src/understand/single-sign-on/adfs/fig-11.jpg diff --git a/docs/src/how-to/single-sign-on/adfs/main.md b/docs/src/understand/single-sign-on/adfs/main.md similarity index 100% rename from docs/src/how-to/single-sign-on/adfs/main.md rename to docs/src/understand/single-sign-on/adfs/main.md diff --git a/docs/src/how-to/single-sign-on/azure/01.png b/docs/src/understand/single-sign-on/azure/01.png similarity index 100% rename from docs/src/how-to/single-sign-on/azure/01.png rename to docs/src/understand/single-sign-on/azure/01.png diff --git a/docs/src/how-to/single-sign-on/azure/02.png b/docs/src/understand/single-sign-on/azure/02.png similarity index 100% rename from docs/src/how-to/single-sign-on/azure/02.png rename to docs/src/understand/single-sign-on/azure/02.png diff --git a/docs/src/how-to/single-sign-on/azure/03.png b/docs/src/understand/single-sign-on/azure/03.png similarity index 100% rename from docs/src/how-to/single-sign-on/azure/03.png rename to docs/src/understand/single-sign-on/azure/03.png diff --git a/docs/src/how-to/single-sign-on/azure/04.png b/docs/src/understand/single-sign-on/azure/04.png similarity index 100% rename from docs/src/how-to/single-sign-on/azure/04.png rename to docs/src/understand/single-sign-on/azure/04.png diff --git a/docs/src/how-to/single-sign-on/azure/05.png b/docs/src/understand/single-sign-on/azure/05.png similarity index 100% rename from docs/src/how-to/single-sign-on/azure/05.png rename to docs/src/understand/single-sign-on/azure/05.png diff --git a/docs/src/how-to/single-sign-on/azure/06.png b/docs/src/understand/single-sign-on/azure/06.png similarity index 100% rename from docs/src/how-to/single-sign-on/azure/06.png rename to docs/src/understand/single-sign-on/azure/06.png diff --git a/docs/src/how-to/single-sign-on/azure/07.png b/docs/src/understand/single-sign-on/azure/07.png similarity index 100% rename from docs/src/how-to/single-sign-on/azure/07.png rename to docs/src/understand/single-sign-on/azure/07.png diff --git a/docs/src/how-to/single-sign-on/azure/08.png b/docs/src/understand/single-sign-on/azure/08.png similarity index 100% rename from docs/src/how-to/single-sign-on/azure/08.png rename to docs/src/understand/single-sign-on/azure/08.png diff --git a/docs/src/how-to/single-sign-on/azure/09.png b/docs/src/understand/single-sign-on/azure/09.png similarity index 100% rename from docs/src/how-to/single-sign-on/azure/09.png rename to docs/src/understand/single-sign-on/azure/09.png diff --git a/docs/src/how-to/single-sign-on/azure/10.png b/docs/src/understand/single-sign-on/azure/10.png similarity index 100% rename from docs/src/how-to/single-sign-on/azure/10.png rename to docs/src/understand/single-sign-on/azure/10.png diff --git a/docs/src/how-to/single-sign-on/azure/11.png b/docs/src/understand/single-sign-on/azure/11.png similarity index 100% rename from docs/src/how-to/single-sign-on/azure/11.png rename to docs/src/understand/single-sign-on/azure/11.png diff --git a/docs/src/how-to/single-sign-on/azure/12.png b/docs/src/understand/single-sign-on/azure/12.png similarity index 100% rename from docs/src/how-to/single-sign-on/azure/12.png rename to docs/src/understand/single-sign-on/azure/12.png diff --git a/docs/src/how-to/single-sign-on/azure/13.png b/docs/src/understand/single-sign-on/azure/13.png similarity index 100% rename from docs/src/how-to/single-sign-on/azure/13.png rename to docs/src/understand/single-sign-on/azure/13.png diff --git a/docs/src/how-to/single-sign-on/azure/14.png b/docs/src/understand/single-sign-on/azure/14.png similarity index 100% rename from docs/src/how-to/single-sign-on/azure/14.png rename to docs/src/understand/single-sign-on/azure/14.png diff --git a/docs/src/how-to/single-sign-on/azure/15.png b/docs/src/understand/single-sign-on/azure/15.png similarity index 100% rename from docs/src/how-to/single-sign-on/azure/15.png rename to docs/src/understand/single-sign-on/azure/15.png diff --git a/docs/src/how-to/single-sign-on/azure/main.md b/docs/src/understand/single-sign-on/azure/main.md similarity index 100% rename from docs/src/how-to/single-sign-on/azure/main.md rename to docs/src/understand/single-sign-on/azure/main.md diff --git a/docs/src/how-to/single-sign-on/centrify/001.png b/docs/src/understand/single-sign-on/centrify/001.png similarity index 100% rename from docs/src/how-to/single-sign-on/centrify/001.png rename to docs/src/understand/single-sign-on/centrify/001.png diff --git a/docs/src/how-to/single-sign-on/centrify/002.png b/docs/src/understand/single-sign-on/centrify/002.png similarity index 100% rename from docs/src/how-to/single-sign-on/centrify/002.png rename to docs/src/understand/single-sign-on/centrify/002.png diff --git a/docs/src/how-to/single-sign-on/centrify/003.png b/docs/src/understand/single-sign-on/centrify/003.png similarity index 100% rename from docs/src/how-to/single-sign-on/centrify/003.png rename to docs/src/understand/single-sign-on/centrify/003.png diff --git a/docs/src/how-to/single-sign-on/centrify/004.png b/docs/src/understand/single-sign-on/centrify/004.png similarity index 100% rename from docs/src/how-to/single-sign-on/centrify/004.png rename to docs/src/understand/single-sign-on/centrify/004.png diff --git a/docs/src/how-to/single-sign-on/centrify/005.png b/docs/src/understand/single-sign-on/centrify/005.png similarity index 100% rename from docs/src/how-to/single-sign-on/centrify/005.png rename to docs/src/understand/single-sign-on/centrify/005.png diff --git a/docs/src/how-to/single-sign-on/centrify/006.png b/docs/src/understand/single-sign-on/centrify/006.png similarity index 100% rename from docs/src/how-to/single-sign-on/centrify/006.png rename to docs/src/understand/single-sign-on/centrify/006.png diff --git a/docs/src/how-to/single-sign-on/centrify/007.png b/docs/src/understand/single-sign-on/centrify/007.png similarity index 100% rename from docs/src/how-to/single-sign-on/centrify/007.png rename to docs/src/understand/single-sign-on/centrify/007.png diff --git a/docs/src/how-to/single-sign-on/centrify/008.png b/docs/src/understand/single-sign-on/centrify/008.png similarity index 100% rename from docs/src/how-to/single-sign-on/centrify/008.png rename to docs/src/understand/single-sign-on/centrify/008.png diff --git a/docs/src/how-to/single-sign-on/centrify/009.png b/docs/src/understand/single-sign-on/centrify/009.png similarity index 100% rename from docs/src/how-to/single-sign-on/centrify/009.png rename to docs/src/understand/single-sign-on/centrify/009.png diff --git a/docs/src/how-to/single-sign-on/centrify/010.png b/docs/src/understand/single-sign-on/centrify/010.png similarity index 100% rename from docs/src/how-to/single-sign-on/centrify/010.png rename to docs/src/understand/single-sign-on/centrify/010.png diff --git a/docs/src/how-to/single-sign-on/centrify/011.png b/docs/src/understand/single-sign-on/centrify/011.png similarity index 100% rename from docs/src/how-to/single-sign-on/centrify/011.png rename to docs/src/understand/single-sign-on/centrify/011.png diff --git a/docs/src/how-to/single-sign-on/centrify/main.md b/docs/src/understand/single-sign-on/centrify/main.md similarity index 100% rename from docs/src/how-to/single-sign-on/centrify/main.md rename to docs/src/understand/single-sign-on/centrify/main.md diff --git a/docs/src/how-to/single-sign-on/generic-setup.md b/docs/src/understand/single-sign-on/generic-setup.md similarity index 100% rename from docs/src/how-to/single-sign-on/generic-setup.md rename to docs/src/understand/single-sign-on/generic-setup.md diff --git a/docs/src/how-to/single-sign-on/index.md b/docs/src/understand/single-sign-on/index.md similarity index 92% rename from docs/src/how-to/single-sign-on/index.md rename to docs/src/understand/single-sign-on/index.md index 2cdb939676..01317c99b5 100644 --- a/docs/src/how-to/single-sign-on/index.md +++ b/docs/src/understand/single-sign-on/index.md @@ -1,3 +1,5 @@ +(sso-main-documentation)= + # Single Sign-On and User Provisioning ```{toctree} diff --git a/docs/src/how-to/single-sign-on/okta/001-applications-screen.png b/docs/src/understand/single-sign-on/okta/001-applications-screen.png similarity index 100% rename from docs/src/how-to/single-sign-on/okta/001-applications-screen.png rename to docs/src/understand/single-sign-on/okta/001-applications-screen.png diff --git a/docs/src/how-to/single-sign-on/okta/002-add-application.png b/docs/src/understand/single-sign-on/okta/002-add-application.png similarity index 100% rename from docs/src/how-to/single-sign-on/okta/002-add-application.png rename to docs/src/understand/single-sign-on/okta/002-add-application.png diff --git a/docs/src/how-to/single-sign-on/okta/003-add-application-1.png b/docs/src/understand/single-sign-on/okta/003-add-application-1.png similarity index 100% rename from docs/src/how-to/single-sign-on/okta/003-add-application-1.png rename to docs/src/understand/single-sign-on/okta/003-add-application-1.png diff --git a/docs/src/how-to/single-sign-on/okta/004-add-application-step1.png b/docs/src/understand/single-sign-on/okta/004-add-application-step1.png similarity index 100% rename from docs/src/how-to/single-sign-on/okta/004-add-application-step1.png rename to docs/src/understand/single-sign-on/okta/004-add-application-step1.png diff --git a/docs/src/how-to/single-sign-on/okta/005-add-application-step2.png b/docs/src/understand/single-sign-on/okta/005-add-application-step2.png similarity index 100% rename from docs/src/how-to/single-sign-on/okta/005-add-application-step2.png rename to docs/src/understand/single-sign-on/okta/005-add-application-step2.png diff --git a/docs/src/how-to/single-sign-on/okta/006-add-application-step3.png b/docs/src/understand/single-sign-on/okta/006-add-application-step3.png similarity index 100% rename from docs/src/how-to/single-sign-on/okta/006-add-application-step3.png rename to docs/src/understand/single-sign-on/okta/006-add-application-step3.png diff --git a/docs/src/how-to/single-sign-on/okta/007-application-sign-on.png b/docs/src/understand/single-sign-on/okta/007-application-sign-on.png similarity index 100% rename from docs/src/how-to/single-sign-on/okta/007-application-sign-on.png rename to docs/src/understand/single-sign-on/okta/007-application-sign-on.png diff --git a/docs/src/how-to/single-sign-on/okta/008-assignment.png b/docs/src/understand/single-sign-on/okta/008-assignment.png similarity index 100% rename from docs/src/how-to/single-sign-on/okta/008-assignment.png rename to docs/src/understand/single-sign-on/okta/008-assignment.png diff --git a/docs/src/how-to/single-sign-on/okta/main.md b/docs/src/understand/single-sign-on/okta/main.md similarity index 100% rename from docs/src/how-to/single-sign-on/okta/main.md rename to docs/src/understand/single-sign-on/okta/main.md diff --git a/docs/src/how-to/single-sign-on/trouble-shooting.md b/docs/src/understand/single-sign-on/trouble-shooting.md similarity index 100% rename from docs/src/how-to/single-sign-on/trouble-shooting.md rename to docs/src/understand/single-sign-on/trouble-shooting.md diff --git a/docs/src/how-to/single-sign-on/understand/Wire_SAML_Flow (lucidchart).svg b/docs/src/understand/single-sign-on/understand/Wire_SAML_Flow (lucidchart).svg similarity index 100% rename from docs/src/how-to/single-sign-on/understand/Wire_SAML_Flow (lucidchart).svg rename to docs/src/understand/single-sign-on/understand/Wire_SAML_Flow (lucidchart).svg diff --git a/docs/src/how-to/single-sign-on/understand/Wire_SAML_Flow.png b/docs/src/understand/single-sign-on/understand/Wire_SAML_Flow.png similarity index 100% rename from docs/src/how-to/single-sign-on/understand/Wire_SAML_Flow.png rename to docs/src/understand/single-sign-on/understand/Wire_SAML_Flow.png diff --git a/docs/src/how-to/single-sign-on/understand/main.md b/docs/src/understand/single-sign-on/understand/main.md similarity index 100% rename from docs/src/how-to/single-sign-on/understand/main.md rename to docs/src/understand/single-sign-on/understand/main.md diff --git a/docs/src/how-to/single-sign-on/understand/token-step-01.png b/docs/src/understand/single-sign-on/understand/token-step-01.png similarity index 100% rename from docs/src/how-to/single-sign-on/understand/token-step-01.png rename to docs/src/understand/single-sign-on/understand/token-step-01.png diff --git a/docs/src/how-to/single-sign-on/understand/token-step-02.png b/docs/src/understand/single-sign-on/understand/token-step-02.png similarity index 100% rename from docs/src/how-to/single-sign-on/understand/token-step-02.png rename to docs/src/understand/single-sign-on/understand/token-step-02.png diff --git a/docs/src/how-to/single-sign-on/understand/token-step-03.png b/docs/src/understand/single-sign-on/understand/token-step-03.png similarity index 100% rename from docs/src/how-to/single-sign-on/understand/token-step-03.png rename to docs/src/understand/single-sign-on/understand/token-step-03.png diff --git a/docs/src/how-to/single-sign-on/understand/token-step-04.png b/docs/src/understand/single-sign-on/understand/token-step-04.png similarity index 100% rename from docs/src/how-to/single-sign-on/understand/token-step-04.png rename to docs/src/understand/single-sign-on/understand/token-step-04.png diff --git a/docs/src/how-to/single-sign-on/understand/token-step-05.png b/docs/src/understand/single-sign-on/understand/token-step-05.png similarity index 100% rename from docs/src/how-to/single-sign-on/understand/token-step-05.png rename to docs/src/understand/single-sign-on/understand/token-step-05.png diff --git a/docs/src/how-to/single-sign-on/understand/token-step-06.png b/docs/src/understand/single-sign-on/understand/token-step-06.png similarity index 100% rename from docs/src/how-to/single-sign-on/understand/token-step-06.png rename to docs/src/understand/single-sign-on/understand/token-step-06.png diff --git a/docs/src/how-to/install/team-feature-settings.md b/docs/src/understand/team-feature-settings.md similarity index 100% rename from docs/src/how-to/install/team-feature-settings.md rename to docs/src/understand/team-feature-settings.md diff --git a/nix/default.nix b/nix/default.nix index bd35e4aaf2..c377bf7102 100644 --- a/nix/default.nix +++ b/nix/default.nix @@ -49,7 +49,9 @@ let nativeBuildInputs = docsPkgs ++ [ pkgs.gnumake ]; } '' - cp -r ${pkgs.nix-gitignore.gitignoreSource [] ../docs}/* . + cp -rH ${pkgs.nix-gitignore.gitignoreSource [] ../docs}/* . + chmod -R +w ./src + cp ${../CHANGELOG.md} ./src/changelog/changelog.md make docs-all mkdir $out cp -r build/* $out/