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.

As of ESS Classic 25.09.01 (Helm version 2.28.1), support for migrating an existing deployment to Matrix Authentication Service is available for Helm installs or other installs which manually manage their ElementDeployment manifests. Support for migrating a existing deployments to Matrix Authentication Service through the UI will come soon.

The migration functionality supports local password authentication and OIDC upstream IdPs. Migrating with LDAP or 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 LDAP or SAML IdPs.

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

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.