Skip to content

Latest commit

 

History

History
143 lines (110 loc) · 6.05 KB

session.md

File metadata and controls

143 lines (110 loc) · 6.05 KB
Raw

3PID Sessions

Overview

When adding an email, a phone number or any other kind of 3PID (Third-Party Identifier) in a Matrix client, the identity server is contacted to validate the 3PID.

To validate the 3PID, the identity server creates a session associated with a secret token. That token is sent via a message to the 3PID (e.g. an email) with a the necessary info so the user can submit them to the Identity Server, confirm ownership of the 3PID.

Once this 3PID is validated, the Homeserver will request that the Identity Server links the provided user Matrix ID with the 3PID session and finally add the 3PID to its own data store.

This serves two purposes:

  • Add the 3PID as an administrative/login info for the Homeserver directly
  • Links, called Bind, the 3PID so it can be queried from Homeservers and clients when inviting someone in a room by a 3PID, allowing it to be resolved to a Matrix ID.

Restrictions

Bindings

ma1sd does not store bindings directly. While a user can see its email, phone number or any other 3PID in its settings/profile, it does NOT mean it is published/saved anywhere or can be used to invite/search the user.

Identity stores are the ones holding such data, irrelevant if a user added a 3PID to their profile. When queried for bindings, ma1sd will query Identity stores which are responsible to store this kind of information.

Therefore, by default, any 3PID added to a user profile which is NOT within a configured and enabled Identity backend will simply not be usable for search or invites, even on the same Homeserver!

To have such 3PID bindings available for search and invite queries on synapse, use its dedicated Identity store.

Federation

In a federated set up, identity servers must cooperate to find the Matrix ID associated with a 3PID.

Federation is based on the principle that each server is responsible for its own (dns) domain. Therefore only those 3PID can be federated that can be distinguished by their domain such as email addresses.

Example: a user from Homeserver example.org adds an email john@example.com.
Federated identity servers would try to find the identity server at example.com and ask it for the Matrix ID of associated with john@example.com.

Nevertheless, Matrix users might add 3PIDs that are not associated to a domain, for example telephone numbers. Or they might even add 3PIDs associated to a different domain (such as an email address hosted by Gmail). Such 3PIDs cannot be resolved in a federated way and will not be found from other servers.

Example: a user from Homeserver example.org adds an email john@gmail.com.
If a federated lookup was performed, Identity servers would try to find the 3PID bind at the gmail.com server, and not example.org.

As ma1sd is built for self-hosted use cases, mainly for orgs/corps, this is usually not a problem for emails.
Sadly, there is currently no mechanism to make this work for phone numbers.

Notifications

3PIDs are validated by sending a pre-formatted message containing a token to that 3PID address, which must be given to the Identity server that received the request. This is usually done by means of a URL to visit for email or a short number received by SMS for phone numbers.

ma1sd use two components for this:

  • Generator which produces the message to be sent with the necessary information the user needs to validate their session.
  • Connector which actually send the notification (e.g. SMTP for email).

Built-in generators and connectors for supported 3PID types:

Email

Generators:

Connectors:

MSISDN (Phone numbers)

Generators:

Connectors:

Usage

Configuration

The following example of configuration shows which items are relevant for 3PID sessions.

IMPORTANT: Most configuration items shown have default values and should not be included in your own configuration file unless you want to specifically overwrite them.

# CONFIGURATION EXAMPLE
# DO NOT COPY/PASTE AS-IS IN YOUR CONFIGURATION

session:
  policy:
    validation:
      enabled: true
    unbind:
      notifications: true
      enabled: true

# DO NOT COPY/PASTE AS-IS IN YOUR CONFIGURATION
# CONFIGURATION EXAMPLE

session.policy.validation is the core configuration to control what users configured to use your Identity server are allowed to do in terms of 3PID sessions. The policy has a global on/off switch for 3PID sessions using .enabled

unbind controls warning notifications for 3PID removal. Setting notifications for unbind to false will prevent unbind emails from sending.

Web views

Once a user click on a validation link, it is taken to the Identity Server validation page where the token is submitted.
If the session or token is invalid, an error page is displayed.
Workflow pages are also available for the remote 3PID session process.

See the dedicated document on how to configure/customize/brand those pages to your liking.

Scenarios

Sessions disabled

This configuration would disable 3PID sessions altogether, preventing users from validating emails and/or phone numbers and any subsequent actions that requires them, like adding them to their profiles.

This would be used if ma1sd is also performing authentication for the Homeserver, typically with synapse and the REST password provider, where 3PID mappings would be auto-populated.

Use the following values to enable this mode:

session:
  policy:
    validation:
      enabled: false