letro/letro-authentication-service
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

syn2mas: document new tool

Browse Source
This commit is contained in:
Olivier 'reivilibre
2025-03-13 17:35:07 +00:00
committed by Quentin Gliech
parent afc625b192
commit f47df35bde
1 changed files with 74 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
docs/setup/migration.md
View File

@@ -18,28 +18,29 @@ There will be tools to help with the migration process itself. But these aren't
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`
### Is your setup ready to be migrated?
The easiest way to get `syn2mas` is through [`npm`](https://www.npmjs.com/package/@vector-im/syn2mas):
#### SAML2 and LDAP Single Sign-On Providers are not supported
```sh
npm install -g @vector-im/syn2mas
```
A deployment which requires SAML or LDAP-based authentication should use a service like [Dex](https://github.com/dexidp/dex) to bridge between the SAML provider and the authentication service.
MAS is different from Synapse in that it does **not** have built-in support for SAML or LDAP-based providers.
### Run the migration advisor
#### Custom password providers are not supported
You can use the advisor mode of the `syn2mas` tool to identify extra configuration steps or issues with the configuration of the homeserver.
If your Synapse homeserver currently uses a custom password provider module, please note that MAS does not support these.
```sh
syn2mas --command=advisor --synapseConfigFile=homeserver.yaml
```
#### SQLite databases are not supported
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.
It is worth noting that MAS currently only supports PostgreSQL as a database backend.
### Install and configure MAS alongside your existing homeserver
Follow the instructions in the [installation guide](installation.md) to install MAS alongside your existing homeserver.
You'll need a blank PostgreSQL database for MAS to use; it does not share the database with the homeserver.
Set up a configuration file but don't start MAS, or create any users, yet.
#### Local passwords
Synapse uses bcrypt as its password hashing scheme while MAS defaults to using the newer argon2id.
@@ -52,7 +53,7 @@ Example passwords configuration:
passwords:
enabled: true
schemes:
- version: 1
- version: 1 # TODO I think v:2 has to come first in this list
algorithm: bcrypt
# Optional, must match the `password_config.pepper` in the Synapse config
#secret: secretPepperValue
@@ -60,57 +61,103 @@ passwords:
algorithm: argon2id
```
If you have a pepper configured in your Synapse password configuration, you'll need to match that on version 1 of the equivalent MAS configuration.
The migration checker will inform you if this has not been configured properly.
### 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.
If you are using an upstream SSO provider, then you will need to configure the upstream provider in MAS manually.
Each upstream provider will need to be given as an `--upstreamProviderMapping` command line option to the import tool.
MAS does not support SAML or LDAP upstream providers.
If you are using one of these, you will need to use an adapter such as Dex at this time,
but we have not yet documented this procedure.
### Prepare the MAS database
Each upstream provider that was used by at least one user in Synapse will need to be configured in MAS.
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:
Set the `synapse_idp_id` attribute on the provider to:
- `"oidc"` if you used an OIDC provider in Synapse's legacy `oidc_config` configuration section.
- `"oidc-myprovider"` if you used an OIDC provider in Synapse's `oidc_providers` configuration list,
with a `provider` of `"myprovider"`.
(This is because Synapse prefixes the provider ID with `oidc-` internally.)
Without the `synapse_idp_id`s being set, syn2mas does not understand which providers
in Synapse correspond to which provider in MAS.
!!!!!!!!! TODO add an example here
The migration checker will inform you if a provider is missing from MAS' config.
### Run the migration checker
You can use the `check` command of the `syn2mas` tool to identify configuration problems before starting the migration.
You do not need to stop Synapse to run this command.
```sh
mas-cli config sync
mas-cli --config mas_config.yaml syn2mas --synapse-config homeserver.yaml check
```
This will either output a list of errors and warnings, or tell you that the check completed with no errors or warnings.
If you have any errors, you must resolve these before starting the migration.
If you have any warnings, please read, understand and possibly resolve them.
With that said, resolving them is not strictly required before starting the migration.
### 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.
!!!!!!! TODO we don't have an exact dry-run mode exposed at the moment...
## 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
### Backup your data and configuration
As with any migration, it is important to backup your data before proceeding.
We also suggest making a backup copy of your homeserver's known good configuration,
before making any changes to enable MAS integration.
### Shutdown the homeserver
This is to ensure that no new sessions are created whilst the migration is in progress.
### Configure the homeserver
### Configure the homeserver to enable MAS integration
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.
Once the homeserver has been stopped, MAS has been configured (but is not running!)
and you have a successful migration check,
run `syn2mas`'s `migrate` command.
Other than the change of command word, the syntax is exactly the same as the `check` command.
```sh
syn2mas --command migrate --synapseConfigFile homeserver.yaml --masConfigFile config.yaml --dryRun false
mas-cli --config mas_config.yaml syn2mas --synapse-config homeserver.yaml migrate
```
#### What to do if it goes wrong
If the migration fails with an error:
- You can either try to fix the error and make another attempt by re-running the command; or
- you can revert your homeserver configuration (so MAS integration is disabled once more)
and abort the migration for now. In this case, you should not start MAS up.
Please report migration failures to the developers.
### Start up the homeserver
Start up the homeserver again with the new configuration.
### Start up MAS
Start up MAS.
### Update or serve the .well-known
The `.well-known/matrix/client` needs to be served as described [here](./well-known.md).