Skip to content

Latest commit

 

History

History
155 lines (134 loc) · 7.46 KB

authentication.md

File metadata and controls

155 lines (134 loc) · 7.46 KB
Raw

Authentication

Description

Authentication is an enhanced feature of mxisd to ensure coherent and centralized identity management.
It allows to use Identity stores configured in mxisd to authenticate users on your Homeserver.

Authentication is divided into two parts:

  • Basic: authenticate with a regular username.
  • Advanced: same as basic with extra ability to authenticate using a 3PID.

Basic

Authentication by username is possible by linking synapse and mxisd together using a specific module for synapse, also known as password provider.

Overview

An overview of the Basic Authentication process:

                                                                                    Identity stores
 Client                                                                             +------+
   |                                            +-------------------------+    +--> | LDAP |
   |   +---------------+  /_matrix/identity     | mxisd                   |    |    +------+
   +-> | Reverse proxy | >------------------+   |                         |    |
       +--|------------+                    |   |                         |    |    +--------+
          |                                 +-----> Check ID stores     >------+--> | SQL DB |
     Login request                          |   |                         |    |    +--------+
          |                                 |   |     |                   |    |
          |   +--------------------------+  |   +-----|-------------------+    +-->  ...
          +-> | Homeserver               |  |         |
              |                          |  |         |
              | - Validate credentials >----+         |
              |   Using REST auth module |            |
              |                          |            |
              | - Auto-provision <-------------------<+
              |   user profiles          |    If valid credentials and supported by Identity store(s)
              +--------------------------+

Performed on synapse with REST auth module

Synapse

  • Install the password provider
  • Edit your synapse configuration:
    • As described by the auth module documentation
    • Set endpoint to http://mxisdAddress:8090 - Replace mxisdAddress by an IP/host name that provides a direct connection to mxisd.
      This MUST NOT be a public address, and SHOULD NOT go through a reverse proxy.
  • Restart synapse

mxisd

Validate

Login on the Homeserver using credentials present in one of your Identity stores.

Next steps

Profile auto-fill

Auto-filling user profile depends on its support by your configured Identity stores.
See your Identity store documentation on how to enable the feature.

Advanced

The Authentication feature allows users to login to their Homeserver by using their 3PIDs in a configured Identity store.

Overview

This is performed by intercepting the Homeserver endpoint /_matrix/client/r0/login as depicted below:

            +----------------------------+
            |  Reverse Proxy             |
            |                            |
            |                            |     Step 1    +---------------------------+     Step 2
            |                            |               |                           |
Client+---->| /_matrix/client/r0/login +---------------->|                           | Look up address  +---------+
            |                      ^     |               |  mxisd - Identity server  +----------------->| Backend |
            |                      |     |               |                           |                  +---------+
            | /_matrix/* +--+      +---------------------+                           |
            |               |            |               +---------------+-----------+
            |               |            |     Step 4                    |
            |               |            |                               | Step 3
            +---------------|------------+                               |
                            |                                            | /_matrix/client/r0/login
                            |                       +--------------+     |
                            |                       |              |     |
                            +---------------------->|  Homeserver  |<----+
                                                    |              |
                                                    +--------------+

Steps of user authentication using a 3PID:

  1. The intercepted login request is directly sent to mxisd instead of the Homeserver.
  2. Identity stores are queried for a matching user identity in order to modify the request to use the user name.
  3. The Homeserver, from which the request was intercepted, is queried using the request at previous step. Its address is resolved using the DNS Overwrite feature to reach its internal address on a non-encrypted port.
  4. The response from the Homeserver is sent back to the client, believing it was the HS which directly answered.

Requirements

Configuration

Reverse Proxy

Apache2

The specific configuration to put under the relevant VirtualHost:

ProxyPass /_matrix/client/r0/login http://localhost:8090/_matrix/client/r0/login

ProxyPreserveHost or equivalent must be enabled to detect to which Homeserver mxisd should talk to when building results.

Your VirtualHost should now look similar to:

<VirtualHost *:443>
    ServerName example.org
    
    ...
    
    ProxyPreserveHost on
    ProxyPass /_matrix/client/r0/login http://localhost:8090/_matrix/client/r0/login
    ProxyPass /_matrix/identity http://localhost:8090/_matrix/identity
    ProxyPass /_matrix http://localhost:8008/_matrix
</VirtualHost>

DNS Overwrite

Just like you need to configure a reverse proxy to send client requests to mxisd, you also need to configure mxisd with the internal IP of the Homeserver so it can talk to it directly to integrate its directory search.

To do so, put the following configuration in your mxisd configuration:

dns.overwrite.homeserver.client:
  - name: 'example.org'
    value: 'http://localhost:8008'

name must be the hostname of the URL that clients use when connecting to the Homeserver. You can use ${server.name} to auto-populate the value using the server.name configuration option and avoid duplicating it. In case the hostname is the same as your Matrix domain and server.name is not explicitely set in the config, server.name will default to matrix.domain and will still probably have the correct value.

value is the base internal URL of the Homeserver, without any /_matrix/.. or trailing /.