You've already forked authentication-service
mirror of
https://github.com/matrix-org/matrix-authentication-service.git
synced 2025-08-06 06:02:40 +03:00
80 lines
2.9 KiB
Markdown
80 lines
2.9 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.
|
|
|
|
### 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.
|
|
|
|
### 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).
|