c07c927d9f
ma1sd requires the openid endpoints for certain functionality.
Example: 90b2b5301c/src/main/java/io/kamax/mxisd/auth/AccountManager.java (L67-L99)
If federation is disabled, we still need to expose these openid APIs on the
federation port.
Previously, we were doing similar magic for Dimension.
As per its documentation, when running unfederated, one is to enable
the openid listener as well. As per their recommendation, people
are advised to do enable it on the Client-Server API port
and use the `federationUrl` variable to override where the federation
port is (making federation requests go to the Client-Server API).
Because ma1sd always uses the federation port (unless you do some
DNS overwriting magic using its configuration -- which we'd rather not
do), it's better if we just default to putting the `openid` listener
where it belongs - on the federation port.
With this commit, we retain the "automatically enable openid APIs" thing
we've been doing for Dimension, but move it to the federation port instead.
We also now do the same thing when ma1sd is enabled.
6.7 KiB
Adjusting ma1sd Identity Server configuration (optional)
By default, this playbook configures an ma1sd Identity Server for you.
This server is private by default, potentially at the expense of user discoverability.
ma1sd is a fork of mxisd which was pronounced end of life 2019-06-21.
Note: enabling ma1sd (which is also the default), means that the openid API endpoints will be exposed on the Matrix Federation port (usually 8448), even if federation is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port 8448 is accessible).
Disabling ma1sd
ma1sd, being an Identity Server, is not strictly needed. It is only used for 3PIDs (3rd party identifiers like E-mail and phone numbers) and some enhanced features.
If you'd like for the playbook to not install ma1sd (or to uninstall it if it was previously installed), you can disable it in your configuration file (inventory/host_vars/matrix.<your-domain>/vars.yml):
matrix_ma1sd_enabled: false
Matrix.org lookup forwarding
To ensure maximum discovery, you can make your identity server also forward lookups to the central matrix.org Identity server (at the cost of potentially leaking all your contacts information).
Enabling this is discouraged and you'd better learn more before proceeding.
Enabling matrix.org forwarding can happen with the following configuration:
matrix_ma1sd_matrixorg_forwarding_enabled: true
Customizing email templates
If you'd like to change the default email templates used by ma1sd, take a look at the matrix_ma1sd_threepid_medium_email_custom_ variables
(in the roles/matrix-ma1sd/defaults/main.yml file.
ma1sd-controlled Registration
To use the Registration feature of ma1sd, you can make use of the following variables:
-
matrix_synapse_enable_registration- to enable user-initiated registration in Synapse -
matrix_synapse_enable_registration_captcha- to validate registering users using reCAPTCHA, as described in the enabling reCAPTCHA documentation. -
matrix_synapse_registrations_require_3pid- to control the types of 3pid ('email','msisdn') required by the Synapse server for registering -
variables prefixed with
matrix_nginx_proxy_proxy_matrix_3pid_registration_(e.g.matrix_nginx_proxy_proxy_matrix_3pid_registration_enabled) - to configure the integrated nginx webserver to send registration requests to ma1sd (instead of Synapse), so it can apply its additional functionality -
matrix_ma1sd_configuration_extension_yaml- to configure ma1sd as required. See the Registration feature's docs for inspiration. Also see the Additional features section below to learn more about how to usematrix_ma1sd_configuration_extension_yaml.
Note: For this to work, either the homeserver needs to federate or the openid APIs need to exposed on the federation port. When federation is disabled and ma1sd is enabled, we automatically expose the openid APIs (only!) on the federation port. Make sure the federation port (usually https://matrix.DOMAIN:8448) is whitelisted in your firewall (even if you don't actually use/need federation).
Authentication
Authentication provides the possibility to use your own Identity Stores (for example LDAP) to authenticate users on your Homeserver. The following configuration can be used to authenticate against an LDAP server:
matrix_synapse_ext_password_provider_rest_auth_enabled: true
# matrix-ma1sd is the hostname of the ma1sd Docker container
matrix_synapse_ext_password_provider_rest_auth_endpoint: "http://matrix-ma1sd:8090"
matrix_ma1sd_configuration_extension_yaml: |
ldap:
enabled: true
connection:
host: ldapHostnameOrIp
tls: false
port: 389
baseDNs: ['OU=Users,DC=example,DC=org']
bindDn: CN=My ma1sd User,OU=Users,DC=example,DC=org
bindPassword: TheUserPassword
Additional features
What this playbook configures for your is some bare minimum Identity Server functionality, so that you won't need to rely on external 3rd party services.
A few variables can be toggled in this playbook to alter the ma1sd configuration that gets generated.
Still, ma1sd can do much more. You can refer to the ma1sd website for more details and configuration options.
To use a more custom configuration, you can define a matrix_ma1sd_configuration_extension_yaml string variable
and put your configuration in it.
To learn more about how to do this, refer to the information about matrix_ma1sd_configuration_extension_yaml in the default variables file of the ma1sd component.
Example: SMS verification
If your use case requires mobile verification, it is quite simple to integrate ma1sd with Twilio, an online telephony services gateway. Their prices are reasonable for low-volume projects and integration can be done with the following configuration:
matrix_ma1sd_configuration_extension_yaml: |
threepid:
medium:
msisdn:
connectors:
twilio:
account_sid: '<secret-SID>'
auth_token: '<secret-token>'
number: '+<msisdn-number>'
Example: Open Registration for every Domain
If you want to open registration for any domain, you have to setup the allowed domains with ma1sd's blacklist and whitelist. The default behavior when neither the blacklist, nor the whitelist match, is to allow registration. Beware: you can't block toplevel domains (aka .xy) because the internal architecture of ma1sd doesn't allow that.
matrix_ma1sd_configuration_extension_yaml: |
register:
policy:
allowed: true
threepid:
email:
domain:
blacklist: ~
whitelist: ~
Troubleshooting
If email address validation emails sent by ma1sd are not reaching you, you should look into Adjusting email-sending settings.
If you'd like additional logging information, temporarily enable verbose logging for ma1sd.
Example configuration (inventory/host_vars/matrix.DOMAIN/vars.yml):
matrix_ma1sd_verbose_logging: true