You've already forked authentication-service
mirror of
https://github.com/matrix-org/matrix-authentication-service.git
synced 2025-08-07 17:03:01 +03:00
194f6d71a1
- Removes mentions of the `mas-cli templates save` command - Removes the old `experimental` flags - Removes the old `policy.data.passwords` configs - Document the `policy.data.client_registration` flags - Remove references to the pre-built macOS binaries - Explains how to get syn2mas - State that you need to prepare the database before importing data - Clean up the reverse proxy documentation - Clarify that you don't need to provede templates/policy/assets manually when running the docker image
97 lines
3.3 KiB
Markdown
97 lines
3.3 KiB
Markdown
# Migrating an existing homeserver
|
|
|
|
One of the design goals of MAS has been to allow it to be used to migrate an existing homeserver to an OIDC-based architecture.
|
|
|
|
Specifically without requiring users to re-authenticate and that non-OIDC clients continue to work.
|
|
|
|
Features that are provided to support this include:
|
|
|
|
- Ability to import existing password hashes from Synapse
|
|
- Ability to import existing sessions and devices
|
|
- Ability to import existing access tokens linked to devices (ie not including short-lived admin puppeted access tokens)
|
|
- Ability to import existing upstream IdP subject ID mappings
|
|
- Provides a compatibility layer for legacy Matrix authentication
|
|
|
|
There will be tools to help with the migration process itself. But these aren't quite ready yet.
|
|
|
|
## Preparing for the migration
|
|
|
|
The deployment is non-trivial so it is important to read through and understand the steps involved and make a plan before starting.
|
|
|
|
### Get `syn2mas`
|
|
|
|
The easiest way to get `syn2mas` is through [`npm`](https://www.npmjs.com/package/@matrix-org/syn2mas):
|
|
|
|
```sh
|
|
npm install -g @matrix-org/syn2mas
|
|
```
|
|
|
|
### Run the migration advisor
|
|
|
|
You can use the advisor mode of the `syn2mas` tool to identify extra configuration steps or issues with the configuration of the homeserver.
|
|
|
|
```sh
|
|
syn2mas --command=advisor --synapseConfigFile=homeserver.yaml
|
|
```
|
|
|
|
This will output `WARN` entries for any identified actions and `ERROR` entries in the case of any issues that will prevent the migration from working.
|
|
|
|
### Install and configure MAS alongside your existing homeserver
|
|
|
|
Follow the instructions in the [installation guide](installation.md) to install MAS alongside your existing homeserver.
|
|
|
|
### Map any upstream SSO providers
|
|
|
|
If you are using an upstream SSO provider then you will need to provision the upstream provide in MAS manually.
|
|
|
|
Each upstream provider will need to be given as an `--upstreamProviderMapping` command line option to the import tool.
|
|
|
|
### Prepare the MAS database
|
|
|
|
Once the database is created, it still needs to have its schema created and synced with the configuration.
|
|
This can be done with the following command:
|
|
|
|
```sh
|
|
mas-cli config sync
|
|
```
|
|
|
|
### Do a dry-run of the import to test
|
|
|
|
```sh
|
|
syn2mas --command migrate --synapseConfigFile homeserver.yaml --masConfigFile config.yaml --dryRun
|
|
```
|
|
|
|
If no errors are reported then you can proceed to the next step.
|
|
|
|
## Doing the migration
|
|
|
|
Having done the preparation, you can now proceed with the actual migration. Note that this will require downtime for the homeserver and is not easily reversible.
|
|
|
|
### Backup your data
|
|
|
|
As with any migration, it is important to backup your data before proceeding.
|
|
|
|
### Shutdown the homeserver
|
|
|
|
This is to ensure that no new sessions are created whilst the migration is in progress.
|
|
|
|
### Configure the homeserver
|
|
|
|
Follow the instructions in the [homeserver configuration guide](homeserver.md) to configure the homeserver to use MAS.
|
|
|
|
### Do the import
|
|
|
|
Run `syn2mas` in non-dry-run mode.
|
|
|
|
```sh
|
|
syn2mas --command migrate --synapseConfigFile homeserver.yaml --masConfigFile config.yaml --dryRun false
|
|
```
|
|
|
|
### Start up the homeserver
|
|
|
|
Start up the homeserver again with the new configuration.
|
|
|
|
### Update or serve the .well-known
|
|
|
|
The `.well-known/matrix/client` needs to be served as described [here](./well-known.md).
|