Migrating from Legacy Authentication to Next-Gen User Management and Authentication with Matrix Authentication Service

Matrix Authentication Service (MAS) is an implementation of next-gen user management and authentication based on MSC3861 and its sub-proposals.

Next-gen user management and authentication provides the following benefits:

Support for Element X clients
Better security with industry-standard authentication (OpenID Connect)
QR code login feature to seamlessly sign in new devices

Using MAS in Matrix stacks is recommended going forward. Legacy authentication should only be used if there is a specific requirement for it.

The migration functionality supports local password authentication, OIDC upstream IdPs and LDAP authentication. Migrating with SAML IdPs is not supported at this time. Please reach out to Element Support if you wish to migrate to next-gen user management and authentication and have SAML IdPs.

Do I have to migrate or am I running Matrix Authentication Service already?

Matrix Authentication Service (MAS) has been shipped to both, ESS Classic (since the 24.09 release) and ESS Community/Pro (since its first release) some time ago. New deployments usually would have started off with MAS unless specified differently. Hence - depending on how long you have been operating your ESS environment - you might already be running on MAS and there's nothing to do for you here. See below to find out whether you are running MAS or not.

ESS Pro makes use of marker transitions (see Marker Transitions) to determine the state of MAS usage.

kubectl -n ess-enterprise get configmap/ess-markers -o 'jsonpath={.data.MATRIX_STACK_MSC3861}'

The namespace ess & the ess prefix on ess-markers are the default namespace and release name from the Setting up ESS Pro documentation. They will need to be adjusted if you have changed either of them.

If the above outputs delegated_auth, your deployment already runs with MAS and you can skip this guide. If it outputs legacy_auth you should continue reading this guide carefully and conduct the migration.

Overview

The migration from Synapse's legacy authentication to Matrix Authentication Service (MAS) is a multi-step process that must be executed carefully. The syn2mas feature in the Helm chart provides a controlled way to perform this migration.

The deployment-markers mechanism will refuse to setup Matrix Authentication Service if your stack was setup with Synapse only. You first have to go through the syn2mas procedure.

The syn2mas migration will run in a couple of minutes. It involves three key steps, and the correct configuration of the Helm values is essential to ensure a smooth and safe upgrade.

Step	Action	Result
1	Setup Matrix Authentication Service and enable `syn2mas` in dryRun mode	System remains in `legacy_auth`. Matrix Authentication Service is deployed in `read-only` mode. It initializes the database. Users are still able to login using the legacy authentication.
2	Run migration (dry run disabled)	System transitions to `syn2mas_migrated`. Users now login using the delegated authentication. Rollback to legacy authentication is not possible any more. syn2mas cannot be run any more.
3	Disable syn2mas	System finalizes to `delegated_auth`.

Important Notes

Please make sure to backup the Synapse database before running the migration. See the Backup and Restore guide for more information.
The migration is a one-way process.Once the system is in the delegated_auth state, it cannot be rolled back to legacy_auth.
It is recommended that you use authentication to configure your OIDC and LDAP providers in Synapse. The ESS Pro syn2mas migration process will then automatically configure Matrix Authentication Service appropriately, and the migration will be transparent for you.

Step-by-Step Upgrade Process

To make use of the example values files (in charts/matrix-stack/ci/fragments), you should download them first as outlined in the Setting up ESS Pro guide.

Step 1: Setup Matrix Authentication Service and prepare the migration

You need to enable Matrix Authentication Service. The minimal settings required are described in charts/matrix-stack/ci/fragments/matrix-authentication-service-minimal.yaml. This is a minimal configuration that you can use if:
The initSecrets job is enabled (default)
You are using the chart-managed Postgres Server (we recommend using an external Postgres Server)
To migrate passwords from Synapse to Matrix Authentication Service, you need to enable Synapse passwords scheme into Matrix Authentication Service. Configure them using the following values:

matrixAuthenticationService:
  additional:
    password-scheme.yml:
      config: |
        passwords:
          schemes:
            - version: 1
              algorithm: bcrypt
            - version: 2
              algorithm: argon2id

If you are using an external Postgres database, please refer to the quick-setup example in charts/matrix-stack/ci/fragments/quick-setup-postgresql.yaml to configure the Matrix Authentication Service database.
If you have disabled the initSecrets job, please refer to the example in charts/matrix-stack/ci/fragments/matrix-authentication-service-secrets-in-helm.yaml to configure the secrets manually.
Run the helm upgrade command and enable syn2mas with --set matrixAuthenticationService.syn2mas.enabled=true:

helm upgrade --install --namespace "ess" ess oci://registry.element.io/matrix-stack -f ~/ess-config-values/hostnames.yaml <optional additional values files to pass> --wait --set matrixAuthenticationService.syn2mas.enabled=true

This step will deploy the following resources:
Matrix Authentication Service is deployed in read-only mode. It initializes the database.
The syn2mas job runs in dry-run mode. It makes sure that the migration is ready to run.
Synapse is remains available, and users are still able to login using the legacy authentication.
The system will remain in the legacy_auth state until the migration is complete.
You can check that Matrix Authentication Service is reachable on the host you configured in matrixAuthenticationService.ingress.host

Step 2: Execute the syn2mas Migration

Run the helm upgrade command with --reuse-values and --set matrixAuthenticationService.syn2mas.dryRun=false

helm upgrade --namespace "ess" ess oci://registry.element.io/matrix-stack --reuse-values --wait --set matrixAuthenticationService.syn2mas.dryRun=false

If you configured an OAuth Provider without using authentication high-level values, the config check hook will throw an error "SSO cannot be enabled when OAuth delegation is enabled". To proceed also add --set synapse.checkConfigHook.enabled=false. This will cause the synapse service to not start after the migration.

helm upgrade --namespace "ess" ess oci://registry.element.io/matrix-stack --reuse-values --wait --set matrixAuthenticationService.syn2mas.dryRun=false --set synapse.checkConfigHook.enabled=false

This step will deploy the following resources:
The migration job is executed as a pre-upgrade hook.
The job will downscale Synapse and its workers to 0 replicas while the migration runs.
At the end of the migration, Synapse will be scaled back up to its original number of replicas.
Matrix Authentication Service restarts and is ready to serve the delegated authentication
The MATRIX_STACK_MSC3861 marker is updated to reflect the syn2mas_migrated state.

Your users are now able to login using the delegated authentication. It is not possible to rollback to legacy_auth any more, nor to run the syn2mas migration again.

Step 3: Disable syn2mas

When in syn2mas_migrated state, running helm upgrade will prevent any deployment until syn2mas is disabled and the state becomes delegated_auth.

Run the helm upgrade command without syn2mas arguments:

If you configured an OAuth Provider without using authentication high-level values, remember to remove any synapse.additional configuration referencing an OAuth Provider.

helm upgrade --install --namespace "ess" ess oci://registry.element.io/matrix-stack -f ~/ess-config-values/hostnames.yaml <optional additional values files to pass> --wait

This step will deploy the following resources:
No change happens on Synapse and Matrix Authentication Service workloads.
The MATRIX_STACK_MSC3861 marker is updated to reflect the delegated_auth state. It is not possible to run syn2mas any more, nor to rollback to legacy_auth.

Marker Transitions

If the deploymentMarkers feature is enabled, the MATRIX_STACK_MSC3861 marker transitions will occur during the migration process:

Start – legacy_auth (initial state)
After Step 1 – legacy_auth (migration not yet executed)
After Step 2 – syn2mas_migrated (migration completed)
After Step 3 – delegated_auth (migration finalized)

⚠️ Note: The MATRIX_STACK_MSC3861 marker will:

Prevent running syn2mas migration again after it has run successfully and is in syn2mas_migrated state
Prevent downgrading from syn2mas_migrated/delegated_auth back to legacy_auth