Official NixOS Wiki

Matrix: Difference between revisions

← Older edit
Hatch01 (talk | contribs)
3 edits
VisualWikitext
add instructions to setup livekit for use withe element-call or Element X
Hatch01 (talk | contribs)
3 edits
Update mas config for the new upcomming fix pr #537261
 
(6 intermediate revisions by 5 users not shown)
Line 13: Line 13:
=== Desktop clients ===
=== Desktop clients ===


These clients are known to work: <code>element-desktop</code> [https://element.io/] and <code>fractal</code> [https://gitlab.gnome.org/World/fractal]
The clients <code>element-desktop</code> [https://element.io/] and <code>fractal</code> [https://gitlab.gnome.org/World/fractal] are known to work and are kept up to date.


Most of the other clients packaged in Nixpkgs, such as <code>matrix-commander</code>, <code>neochat</code>, <code>nheko</code>, rely on the '''insecure''' and '''deprecated''' <code>olm</code> library susceptible to various security vulnerabilities.[https://nvd.nist.gov/vuln/detail/CVE-2024-45191][https://nvd.nist.gov/vuln/detail/CVE-2024-45193][https://nvd.nist.gov/vuln/detail/CVE-2024-45192]
Other clients packaged in Nixpkgs, such as <code>matrix-commander</code>, <code>neochat</code>, <code>nheko</code>, depend on the insecure <code>olm</code> library susceptible to various security vulnerabilities.[https://nvd.nist.gov/vuln/detail/CVE-2024-45191][https://nvd.nist.gov/vuln/detail/CVE-2024-45193][https://nvd.nist.gov/vuln/detail/CVE-2024-45192]
 
If this is not a concern, the guide to [https://nixos.org/manual/nixpkgs/stable/#sec-allow-insecure install insecure packages] may be followed.


If this isn't a problem for you, you can install them as usual, and upon evaluation, Nix will helpfully guide you on how to [https://nixos.org/manual/nixpkgs/stable/#sec-allow-insecure install insecure packages].
=== Web clients ===
=== Web clients ===
There is a web version of the client [https://element.io/ Element], <code>element-web</code> on Nixpkgs, which you can use as a regular web application.  See [https://nixos.org/nixos/manual/index.html#module-services-matrix-element-web the NixOS manual entry].<syntaxhighlight lang="nixos">
There is a web version of the client [https://element.io/ Element], <code>element-web</code> on Nixpkgs, which you can use as a regular web application.  See [https://nixos.org/nixos/manual/index.html#module-services-matrix-element-web the NixOS manual entry].<syntaxhighlight lang="nixos">
Line 165: Line 166:
</syntaxhighlight>
</syntaxhighlight>


==== Livekit ====
 
 
==== Synapse with Workers ====
There's an external module to automatically set up synapse and configure nginx with workers:
https://github.com/dali99/nixos-matrix-modules
 
==== Synapse Admin with Caddy ====
Setting up [https://github.com/etkecc/synapse-admin Synapse Admin] with [[Caddy]] is quite easy!
 
The example uses the newer <code>pkgs.synapse-admin-etkecc</code> which may not be what you want if you have heard of the old one which is available at: <code>pkgs.synapse-admin</code>
{{File|3={ pkgs, ... }:
let
  synapse-admin = pkgs.synapse-admin-etkecc.withConfig {
    restrictBaseUrl = [
      "https://matrix.example.com" # Synapse domain
    ];
  };
in
{
  services.caddy.virtualHosts."synapse-admin.example.com".extraConfig = ''
    root * ${synapse-admin}
    file_server
  '';
}|name=/etc/nixos/configuration.nix|lang=nix}}
== Homeserver Independent ==
=== Livekit ===
In order to set up element call or for calls to work in Element X it is necessary to set up and announce livekit. To set up livekit for matrix in nixos use<syntaxhighlight lang="nix" line="1">
In order to set up element call or for calls to work in Element X it is necessary to set up and announce livekit. To set up livekit for matrix in nixos use<syntaxhighlight lang="nix" line="1">
{ config, lib, pkgs, ... }: let
{ config, lib, pkgs, ... }: let
Line 173: Line 199:
     enable = true;
     enable = true;
     openFirewall = true;
     openFirewall = true;
    settings.room.auto_create = false;
     inherit keyFile;
     inherit keyFile;
   };
   };
Line 187: Line 214:
     path = with pkgs; [ livekit coreutils gawk ];
     path = with pkgs; [ livekit coreutils gawk ];
     script = ''
     script = ''
      if [ -f ${keyFile} ]; then
        echo "Key exists"
      else
         echo "Key missing, generating key"
         echo "Key missing, generating key"
         echo "lk-jwt-service: $(livekit-server generate-keys | tail -1 | awk '{print $3}')" > "${keyFile}"
         echo "lk-jwt-service: $(livekit-server generate-keys | tail -1 | awk '{print $3}')" > "${keyFile}"
      fi
     '';
     '';
     serviceConfig.Type = "oneshot";
     serviceConfig.Type = "oneshot";
    unitConfig.ConditionPathExists = "!${keyFile}";
   };
   };
   # restrict access to livekit room creation to a homeserver
   # restrict access to livekit room creation to a homeserver
Line 238: Line 262:
</syntaxhighlight>
</syntaxhighlight>


==== Synapse with Workers ====
=== Matrix Authentication Service (MAS) ===
There's an external module to automatically set up synapse and configure nginx with workers:
<blockquote>MAS module is only available since nixos 26.11</blockquote>The Matrix Authentication Service (MAS) is an OAuth 2.1 and OpenID Connect provider designed for Matrix homeservers. It is intended to become the authentication component used by Matrix homeservers implementing MSC3861.
https://github.com/dali99/nixos-matrix-modules
 
MAS provides a modern authentication layer for Matrix and enables features such as:
 
* Single Sign-On (SSO) using external OpenID Connect providers;
* Account management independent from the homeserver implementation;
* Passwordless deployments relying entirely on upstream identity providers;
* Future Matrix authentication features based on MSC3861 and MSC4108.
 
MAS stores its own state in PostgreSQL and communicates with the homeserver using a shared secret.
 
==== Basic configuration ====
A minimal configuration can be achieved with:<syntaxhighlight lang="nixos">
# MAS part
services.matrix-authentication-service = {
  enable = true;
  createDatabase = true;
  credentials."matrix_secret" = config.age.secrets.mas_matrix_secret.path;
  settings = {
    http.public_base = "https://auth.example.com/";
    http.issuer = "https://auth.example.com/";
    matrix = {
      homeserver = "example.com";
      endpoint = "http://127.0.0.1:8008/";
      secret_file = "/run/credentials/matrix-authentication-service.service/matrix_secret";
    };
  };
};
# Synapse part
services.matrix-synapse.settings = {
  matrix_authentication_service = {
    enabled = true;
    endpoint = "http://127.0.0.1:8089/";
    secret_path = config.age.secrets.mas_matrix_secret.path;
  };
};
</syntaxhighlight>The following parameters are required:
 
* <code>matrix.homeserver</code> should match the Synapse <code>server_name</code>.
* <code>matrix.endpoint</code> must point to the homeserver's internal HTTP endpoint.
* <code>matrix.secret_file</code> contains the shared secret used by MAS to authenticate to Synapse.
** The secret should be a long, randomly generated value. For example: <code>openssl rand -hex 32</code>
 
* <code>http.public_base</code> is the public URL used by clients to reach MAS.
 
==== Using an upstream OpenID Connect provider ====
MAS can delegate authentication to an external OpenID Connect provider.
 
The example below configures MAS to authenticate users through Authelia and disables the internal password database.<syntaxhighlight lang="nixos">
services.matrix-authentication-service = {
  enable = true;
  settings = {
    passwords.enabled = false;
    upstream_oauth2.providers = [
      {
        id = "XXXX";
        human_name = "Authelia";
        issuer = "https://auth.example.com";
        client_id = "xxxxxxxx";
        client_secret_file = "/run/credentials/matrix-authentication-service.service/xxxx";
        # client_secret = "xxxxxxxx";
        token_endpoint_auth_method = "client_secret_basic";
        discovery_mode = "insecure";
        fetch_userinfo = true;
        scope = "openid profile email";
        claims_imports = {
          localpart = {
            action = "require";
            template = "{{ user.preferred_username }}";
          };
          displayname = {
            action = "suggest";
            template = "{{ user.name }}";
          };
          email = {
            action = "suggest";
            template = "{{ user.email }}";
            set_email_verification = "always";
          };
        };
      }
    ];
  };
};
</syntaxhighlight>An OpenID Connect client must also be declared in Authelia:<syntaxhighlight lang="nixos">
{
  client_name = "Matrix";
 
  client_id = "<client-id>";
  client_secret = "<client-secret>";
 
  public = false;
 
  authorization_policy = "two_factor";
 
  redirect_uris = [
    "https://auth.example.com/upstream/callback/XXXX"
  ];
 
  scopes = [
    "openid"
    "profile"
    "email"
    "offline_access"
  ];
 
  grant_types = [
    "authorization_code"
    "refresh_token"
  ];
 
  response_types = [ "code" ];
}
</syntaxhighlight>With this setup:
 
* Users authenticate against Authelia.
* MAS consumes the OIDC claims exposed by Authelia.
* Matrix accounts are associated with the imported <code>preferred_username</code>, display name and email address.
* No password is stored locally in MAS.
 
==== Secret management ====
Secrets such as encryption keys, OIDC client secrets, and Matrix shared secrets should not be stored in the Nix store.
 
Please use a secret management solution: [[Comparison of secret managing schemes]]
 
See the [https://search.nixos.org/options?channel=unstable&query=matrix-authentication-service MAS configuration reference] for the complete list of available options.
 
==== Example configuration ====
This configuration is provided for demonstration purposes only (mas+synapse+authelia with agenix for secret management): https://github.com/hatch01/flake/blob/d8e8a74b8b3df01283b79a777c46513dd78c9d10/apps/matrix/mas.nix


== Application services (a.k.a. bridges) ==
== Application services (a.k.a. bridges) ==
Retrieved from "https://wiki.nixos.org/wiki/Matrix"