cqrenet/mxids

Fork 0

Files

Max Dor 635f6fdbe7 Implementation for blocking fraudulent 3PID /unbind attempts

2019-02-01 02:34:52 +01:00

13 KiB

Raw Blame History

3PID Sessions

Overview
Purpose
Federation
- 3PID scope
- Session scope
Notifications
- Email
- Phone numbers
Usage

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 sends a message to the 3PID (e.g. an email) with a hyperlink back to a web-page managed by the identity server to confirm ownership of the 3PID.

Once this 3PID is validated, the Homeserver will publish the user Matrix ID on the Identity Server and add this 3PID to the Matrix account which initiated the request.

This serves two purposes:

Add the 3PID as an administrative/login info for the Homeserver directly
Publish, or 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.

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.

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.

In order to resolve such 3PIDs, i.e. 3PIDs that cannot be resolved in a Federated way, an identity server can be configured such that

3PIDs that cannot be resolved locally or using federation, are fowarded to another global identity server.
registration of new 3PIDs that cannot be looked up in a federated fashion, is forwarded to another global identity server.

By forwarding a 3PIDs registration the identity creates a Remote session and Remote bind, effectively starting a new 3PID session with another Identity server on behalf of the user.

To ensure lookup works consistency within the current Matrix network, the central Matrix.org Identity Server should be used to store remote sessions and binds.

However, at the time of writing, the Matrix specification and the central Matrix.org servers do not allow to remote a 3PID bind. This means that once a 3PID is published (email, phone number, etc.), it cannot be easily removed and would require contacting the Matrix.org administrators for each bind individually. This poses a privacy, control and security concern, especially for groups/corporations that want to keep a tight control on where such identifiers can be made publicly visible.

To ensure full control, validation management relies on two concepts:

The scope of 3PID being validated
The scope of 3PID sessions that should be possible/offered

3PID scope

3PID can either be scoped as local or remote.

Local means that they can be looked up using federation and that such a federation call would end up on the local Identity Server.
Remote means that they cannot be lookup using federation or that a federation call would not end up on the local Identity Server.

Email addresses can either be local or remote 3PID, depending on the domain. If the address is one from the configured domain in the Identity server, it will be scoped as local. If it is from another domain, it will be as remote.

Phone number can only be scoped as remote, since there is currently no way to perform DNS queries that would lead back to the Identity server who validated the phone number.

Session scope

Sessions can be scoped as:

Local only - validate 3PIDs directly, do not allow the creation of 3PID sessions on a remote Identity server.
Local and Remote - validate 3PIDs directly, offer users to option to also validate and bind 3PID on another server.
Remote only - validate and bind 3PIDs on another server, no validation or bind done locally.

IMPORTANT NOTE: mxisd 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 anywhere and can be used to invite/search the user. Identity stores are the ones holding such data.
If you still want added arbitrary 3PIDs to be discoverable on a synapse Homeserver, use the corresponding Identity store.

See the Scenarios for more info on how and why.

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.

mxisd 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:

Template

Connectors:

SMTP

MSISDN (Phone numbers)

Generators:

Template

Connectors:

Twilio with SMS

Usage

Configuration

The following example of configuration (incomplete extract) 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 THIS IN YOUR CONFIGURATION
session:
  policy:
    validation:
      enabled: true
      forLocal:
        enabled: true
        toLocal: true
        toRemote:
          enabled: true
          server: 'configExample'  # Not to be included in config! Already present in default config!
      forRemote:
        enabled: true
        toLocal: true
        toRemote:
          enabled: true
          server: 'configExample'  # Not to be included in config! Already present in default config!
    unbind:
      fraudulent:
        sendWarning: true
# DO NOT COPY/PASTE THIS 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
It is also divided into two sections: forLocal and forRemote which refers to the 3PID scopes.

Each scope is divided into three parts:

global on/off switch for 3PID sessions using .enabled
toLocal allowing or not local 3PID session validations
toRemote allowing or not remote 3PID session validations and to which server such sessions should be sent.
.server takes a Matrix Identity server list label. Only the first server in the list is currently used.

If both toLocal and toRemote are enabled, the user will be offered to initiate a remote session once their 3PID locally validated.

unbind.fraudulent controls warning notifications if an illegal/fraudulent 3PID removal is attempted on the Identity server.
This is directly related to synapse disregard for privacy and new GDPR laws in Europe in an attempt to inform users about potential privacy leaks.

For more information, see the corresponding synapse issue.

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

It is important to keep in mind that mxisd does not create bindings, irrelevant if a user added a 3PID to their profile.
Instead, when queried for bindings, mxisd will query Identity stores which are responsible to store this kind of information.

This has the side effect that 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!
mxisd does not store binds on purpose, as one of its primary goal is to ensure maximum compatibility with federation and the rest of the Matrix ecosystem is preserved.

Nonetheless, because mxisd also aims at offering support for tight control over identity data, it is possible to have such 3PID bindings available for search and invite queries on synapse with the corresponding Identity store.

See the Local sessions only use case for more information on how to configure.

Default

By default, mxisd allows the following:

	Local Session	Remote Session
Local 3PID	Yes	Yes, offered
Remote 3PID	No, Remote forced	Yes

This is usually what people expect and will feel natural to users and does not involve further integration.

This allows to stay in control for e-mail addresses which domain matches your Matrix environment, still making them discoverable with federation but not recorded in a 3rd party Identity server which is not under your control.
Users still get the possibility to publish globally their address if needed.

Other e-mail addresses and phone number will be redirected to remote sessions to ensure full compatibility with the Matrix ecosystem and other federated servers.

Local sessions only

NOTE: This does not affect 3PID lookups (queries to find Matrix IDs). See Federation to disable remote lookup for those.

This configuration ensures maximum confidentiality and privacy. Typical use cases:

Private Homeserver, not federated
Internal Homeserver without direct Internet access
Custom product based on Matrix which does not federate

No 3PID will be sent to a remote Identity server and all validation will be performed locally.
On the flip side, people with Remote 3PID scopes will not be found from other servers.

Use the following values:

session:
  policy:
    validation:
      enabled: true
      forLocal:
        enabled: true
        toLocal: true
        toRemote:
          enabled: false
      forRemote:
        enabled: true
        toLocal: true
        toRemote:
          enabled: false

IMPORTANT: When using local-only mode and if you are using synapse, you will also need to enable its dedicated Identity store if you want user searches and invites to work. To do so, see the dedicated document.

Remote sessions only

This configuration ensures all 3PID are made public for maximum compatibility and reach within the Matrix ecosystem, at the cost of confidentiality and privacy.

Typical use cases:

Public Homeserver
Homeserver with registration enabled