matrix-docker-ansible-deploy/docs/registering-users.md

Registering users

This documentation page tells you how to create user accounts on your Matrix server.

Table of contents:

• Registering users
  • Registering users manually
  • Managing users via a Web UI
  • Letting certain users register on your private server
  • Enabling public user registration
  • Adding/Removing Administrator privileges to an existing user

Registering users manually

Notes:

• Make sure to adjust USERNAME_HERE and PASSWORD_HERE
• For USERNAME_HERE, use a plain username like alice, not a full identifier (@alice:example.com)
• Use admin=yes or admin=no depending on whether you wish to make the user an administrator of the Matrix server

After registering a user (using one of the methods below), you can log in with that user via the Element Web service that this playbook has installed for you at a URL like this: https://element.example.com/.

Registering users via the Ansible playbook

It's best to register users via the Ansible playbook, because it works regardless of homeserver implementation (Synapse, Dendrite, etc) or usage of Matrix Authentication Service (MAS).

To register a user via this Ansible playbook:

just register-user USERNAME_HERE PASSWORD_HERE <admin access: yes or no>

# Example: `just register-user alice secret-password yes`

or by invoking ansible-playbook manually:

ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=USERNAME_HERE password=PASSWORD_HERE admin=<yes|no>' --tags=register-user

# Example: ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=alice password=secret-password admin=yes' --tags=register-user

Feel free to register as many users (for friends, family, etc.) as you want. Still, perhaps you should grant full administrative access to your user account only (with admin=yes), and others should be created with admin=no.

⚠️ Warning: If you're registering users against Matrix Authentication Service, do note that it still insists on having a verified email address for each user. Upon a user's first login, they will be asked to confirm their email address. This requires that email sending is configured. You can also consult the Working around email deliverability issues section for more information.

Registering users manually for Synapse

If you're using the Synapse homeserver implementation (which is the default), you can register users via the command-line after SSH-ing to your server (requires that all services have been started):

/matrix/synapse/bin/register-user USERNAME_HERE PASSWORD_HERE <admin access: 0 or 1>

# Example: `/matrix/synapse/bin/register-user alice secret-password 1`

Registering users manually for Dendrite

If you're using the Dendrite homeserver implementation, you can register users via the command-line after SSH-ing to your server (requires that all services have been started):

/matrix/dendrite/bin/create-account USERNAME_HERE PASSWORD_HERE <admin access: 0 or 1>

# Example: `/matrix/dendrite/bin/create-account alice secret-password 1`

Registering users manually for Matrix Authentication Service

If you're using the Matrix Authentication Service and your existing homeserver (most likely Synapse) is delegating authentication to it, you can register users via the command-line after SSH-ing to your server (requires that all services have been started):

/matrix/matrix-authentication-service/bin/register-user USERNAME_HERE PASSWORD_HERE <admin access: 0 or 1>

# Example: `/matrix/matrix-authentication-service/bin/register-user alice secret-password 1`

This register-user script actually invokes the mas-cli manage register-user command under the hood. If you'd like more control over the registration process, consider invoking the mas-cli command directly:

/matrix/matrix-authentication-service/bin/mas-cli manage register-user --help

⚠️ Warning: Matrix Authentication Service still insists on having a verified email address for each user. Upon a user's first login, they will be asked to confirm their email address. This requires that email sending is configured. You can also consult the Working around email deliverability issues section for more information.

Managing users via a Web UI

To manage users more easily (via a web user-interace), you can install Synapse Admin.

⚠️ Warning: If you're using Matrix Authentication Service, note that user management via synapse-admin is not fully working yet. See the Expectations section for more information.

Letting certain users register on your private server

If you'd rather keep your server private (public registration closed, as is the default), and let certain people create accounts by themselves (instead of creating user accounts manually like this), consider installing and making use of matrix-registration.

Enabling public user registration

To open up user registration publicly (usually not recommended), add the following configuration to your inventory/host_vars/matrix.example.com/vars.yml file:

For Synapse:

matrix_synapse_enable_registration: true

For Dendrite:

matrix_dendrite_client_api_registration_disabled: false

After configuring the playbook, run it with playbook tags as below:

ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

Notes:

• The shortcut commands with just program are also available: just run-tags install-all,start or just run-tags setup-all,start

  just run-tags install-all,start is useful for maintaining your setup quickly when its components remain unchanged. If you adjust your vars.yml to remove other components, you'd need to run just run-tags setup-all,start, or these components will still remain installed. For more information about just shortcuts, take a look at this page: Running just commands

• If you're opening up registrations publicly like this, you might also wish to configure CAPTCHA protection.

Adding/Removing Administrator privileges to an existing user

Adding/Removing Administrator privileges to an existing user in Synapse

To change the admin privileges for a user in Synapse's local database, you need to run an SQL query like this against the synapse database:

UPDATE users SET admin=ADMIN_VALUE WHERE name = '@USER:example.com';

where:

• ADMIN_VALUE being either 0 (regular user) or 1 (admin)
• USER and example.com pointing to a valid user on your server

If you're using the integrated Postgres server and not an external Postgres server, you can launch a Postgres into the synapse database by:

• running /matrix/postgres/bin/cli - to launch psql
• running \c synapse - to change to the synapse database

You can then proceed to run the query above.

Note: directly modifying the raw data of Synapse (or any other software) could cause the software to break. You've been warned!

Adding/Removing Administrator privileges to an existing user in Matrix Authentication Service

Promoting/demoting a user in Matrix Authentication Service cannot currently (2024-10-19) be done via the mas-cli Management tool.

You can do it via the MAS Admin API's POST /api/admin/v1/users/{id}/set-admin endpoint.