Skip to content

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.

Migration is supported for both installer UI driven and pure Helm installations, with instructions below. 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.

Installations configured using the installer UI

For ESS Classic installations that have been set up using the installer UI, there is a UI-based wizard that will guide you through the migration step-by-step, giving you all the information you need.

Image

Preparation

Please ensure to upgrade to at minimum 25.10.01 LTS. After this you will see the migration tool appear in the left sidebar.

Migration steps

The migration tool has several steps outlined below. Please pay attention to information and guidance on the screen before continuing forwards.

There are no data changes or downtime for users before the actual migration in step four. The whole migration process involves two full reconciliation runs.

1. Configuration

In the first step, after clicking the start migration button, you will need to configure the new Matrix Authentication Service component, which will appear in the section list. At minimum you will need to;

  • Choose a subdomain for the service to run on
  • Decide how to deal with TLS
  • Give MAS a database to run on
  • Configure email deliver if your instance allows local accounts with registration or password reset
  • If you have configured OIDC upstreams, you will need to also add new redirect uri's to your IdP's at this stage. The new redirect uri's will be presented on the screen once Matrix Authentication Service has been configured.

2. Setup and dry-run

In this step you will need to wait for a full reconciliation to happen. It will handle creating the MAS deployment and will run a the migration tool in dry-run mode. At this stage users will not be disrupted and it is still possible to abort the process afterwards, removing the MAS deployment from the cluster.

3. Ready to migrate

Before continuing from this step, take a backup of your database. It is not possible to rollback after this step except using backups. Users will see an estimated 5-30 minutes of downtime, depending on the installation.

4. Migration

During the migration phase Synapse and other components will be taken offline, and the actual copying of user accounts from Synapse to the Matrix User Authentication will happen. Actual downtime for users depends on the installation size and resources available to the cluster.

5. Complete

The migration has completed successfully and your system is up and running again, now using MAS for authentication and user management, ready for Element X.

Helm and installs which manage their ElementDeployment manifest without the installer UI

Requires ESS Classic 25.09.01 (Helm version 2.28.1) or later. LDAP migration support was added in 25.10.1 (Helm version 2.29.0).

Preparation

  • Take a backup of your database
  • Create a Postgres database for Matrix Authentication Service
    • This can be a distinct database within the same Postgres instance as Synapse or an entirely separate Postgres instance
  • Ensure your ElementDeployment has fully reconciled
    • kubectl describe ElementDeployment -A and under Status -> Conditions ensure that the Available and Successful conditions have a Status of True
  • Ensure your OIDC upstream IdPs also support Matrix Authentication Service's redirect URL
    • The redirect URLs will be https://<components.matrixAuthenticationService.k8s.ingress.fqdn>/upstream/callback/<idpId> where the IdP ID is idpId in each entry in components.synapse.config.delegatedAuth.oidc.
    • Synapse's redirect URL can be left in place until after the migration has been successfully completed.

Test the migration

Update your ElementDeployment using the ESS Classic Helm chart installation adding the following sections:

secrets:
  matrixAuthenticationService:
    content:
      encryptionSecret: # (1)!
      rsaPrivateKey: # (2)!
      postgresPassword: # (3)!
      certificate: # (4)!
      privateKey: # (5)!

components:
  matrixAuthenticationService:
    config:
      active: false
      postgresql:
        database: # (6)!
        host: # (7)!
        port: 5432
        user: # (8)!
    k8s:
      ingress:
        fqdn: # (9)!
  1. A 32 byte hex-encoded string. Must not change after installation. Can be generated with e.g. openssl rand 32 | od -An -v -tx1 -w64 | tr -d ' \n'
  2. A RSA private key. Can be generated with openssl genrsa
  3. The password for your Postgres instance
  4. The TLS certificate, in PEM format, for the Matrix Authentication Service Ingress along with any intermediate certificates
  5. The corresponding private key, in PEM format, for the TLS certificate for the Matrix Authentication Service Ingress
  6. The name of the database for Matrix Authentication Service within the Postgres instance
  7. The hostname of the Postgres instance containing the database for Matrix Authentication Service
  8. The username for your Postgres instance
  9. The fully-qualified domain name that the Matrix Authentication Service instance will be available at

Apply the updated values to the Helm installation after configuring these values. The deployment will perform a dry-run migration and report back any errors in the Status of the ElementDeployment.

If the dry-run migration has succeeded the ElementDeployment will have fully reconciled again with no errors.

The Matrix Authentication Service URL configured at components.matrixAuthenticationService.k8s.ingress.fqdn should be visited and checked that it is accessible. Logins will not work at this point as no data has been migrated to Matrix Authentication Service.

Performing the migration

The dry-run migration must have succeeded before the actual migration can be attempted. If this hasn't happened, any attempt to perform the migration will end in an error.

To perform the actual migration edit your ElementDeployment to change active to true

components:
  matrixAuthenticationService:
    config:
      active: true

All other settings should remain the same.

Apply the updated values to the Helm installation after making this change.

The deployment will

  • Stop all Synapse processes
  • Perform the migration
  • Reconfigure all components in the deployment to use Matrix Authentication Service
  • Restart all Synapse processes

The deployment will report back any errors in the Status of the ElementDeployment. If there are errors it is safe to changes active back to false after saving the details of the errors.

If the migration has succeeded the ElementDeployment will have fully reconciled again with no errors and mas_active under Status will now be true

Congratulations, all existing logins will have been migrated to Matrix Authentication Service and new logins will happen via Matrix Authentication Service.