ansol/matrix-docker-ansible-deploy
7
0
Fork 0
mirror of https://github.com/spantaleev/matrix-docker-ansible-deploy.git synced 2025-01-03 01:57:18 +00:00
Code Issues Projects Releases Wiki Activity

Update docs/configuring-playbook-ma1sd.md (#3795)

Browse Source 
* Update docs/configuring-playbook-ma1sd.md: edit top paragraphs

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-ma1sd.md: use common expressions for instruction to add configuration

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-ma1sd.md: move instructions up

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-ma1sd.md: move the instruction for additional features up

Move instructions for features which use the "matrix_ma1sd_configuration_extension_yaml" variable under "Additional features".

Also: adjust headers' level

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-ma1sd.md

Co-authored-by: Slavi Pantaleev <slavi@devture.com>

* Update configuring-playbook-ma1sd.md: adjust to follow other examples such as on configuring-playbook-bridge-appservice-webhooks.md

This commit:

- Move the note about installing to the top
- Add warning emoji (⚠️: U+26A0 FE0F)
- Use a common expression to discourage installing

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-ma1sd.md: move instruction to configure DNS settings up

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Fix typo and add an extra newline

---------

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
Co-authored-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
Co-authored-by: Slavi Pantaleev <slavi@devture.com>
This commit is contained in:
Suguru Hirahara 2024-11-21 18:14:00 +09:00 committed by GitHub
parent ccd6c003ab
commit e2d31ec9c3
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 40 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
docs/configuring-playbook-ma1sd.md
View File

@ -1,15 +1,26 @@
# Setting up ma1sd Identity Server (optional) # Setting up ma1sd Identity Server (optional)
The playbook can configure the [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server for you. **⚠️Note**: ma1sd itself has also been unmaintained for years (the latest commit and release being from 2021). The role of identity servers in the Matrix specification also has an uncertain future. **We recommend not bothering with installing it unless it's the only way you can do what you need to do**. For example, certain things like LDAP integration can also be implemented via [the LDAP provider module for Synapse](./configuring-playbook-ldap-auth.md).
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](https://github.com/ma1uta/ma1sd/#features). The playbook can configure the [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server for you. It is a fork of [mxisd](https://github.com/kamax-io/mxisd) which was pronounced end of life 2019-06-21.
This server is private by default, potentially at the expense of user discoverability. ma1sd is used for 3PIDs (3rd party identifiers like E-mail and phone numbers) and some [enhanced features](https://github.com/ma1uta/ma1sd/#features). It is private by default, potentially at the expense of user discoverability.
*ma1sd is a fork of [mxisd](https://github.com/kamax-io/mxisd) which was pronounced end of life 2019-06-21.* See the project's [documentation](https://github.com/ma1uta/ma1sd) to learn what it does and why it might be useful to you.
**Note**: enabling ma1sd, means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible). **Note**: enabling ma1sd, means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible).
## Adjusting DNS records
To make the ma1sd Identity Server enable its federation features, set up a SRV record that looks like this:
- Name: `_matrix-identity._tcp` (use this text as-is)
- Content: `10 0 443 matrix.example.com` (replace `example.com` with your own)
See [ma1sd's documentation](https://github.com/ma1uta/ma1sd/wiki/mxisd-and-your-privacy#choices-are-never-easy) for information on the privacy implications of setting up this SRV record.
**Note**: This `_matrix-identity._tcp` SRV record for the identity server is different from the `_matrix._tcp` that can be used for Synapse delegation. See [howto-server-delegation.md](howto-server-delegation.md) for more information about delegation.
## Adjusting the playbook configuration ## Adjusting the playbook configuration
To enable ma1sd, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: To enable ma1sd, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@ -24,31 +35,28 @@ To ensure maximum discovery, you can make your identity server also forward look
Enabling this is discouraged and you'd better [learn more](https://github.com/ma1uta/ma1sd/blob/master/docs/features/identity.md#lookups) before proceeding. Enabling this is discouraged and you'd better [learn more](https://github.com/ma1uta/ma1sd/blob/master/docs/features/identity.md#lookups) before proceeding.
Enabling matrix.org forwarding can happen with the following configuration: To enable matrix.org forwarding, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml ```yaml
matrix_ma1sd_matrixorg_forwarding_enabled: true matrix_ma1sd_matrixorg_forwarding_enabled: true
``` ```
### Customizing email templates ### 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](https://github.com/ma1uta/ma1sd) 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](../roles/custom/matrix-ma1sd/defaults/main.yml) of the ma1sd component.
#### 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/custom/matrix-ma1sd/defaults/main.yml` file. 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/custom/matrix-ma1sd/defaults/main.yml` file.
## Adjusting DNS records #### ma1sd-controlled Registration
To make the ma1sd Identity Server enable its federation features, set up an SRV record that looks like this:
- Name: `_matrix-identity._tcp` (use this text as-is)
- Content: `10 0 443 matrix.example.com` (replace `example.com` with your own)
See [ma1sd's documentation](https://github.com/ma1uta/ma1sd/wiki/mxisd-and-your-privacy#choices-are-never-easy) for information on the privacy implications of setting up this SRV record.
**Note**: This `_matrix-identity._tcp` SRV record for the identity server is different from the `_matrix._tcp` that can be used for Synapse delegation. See [howto-server-delegation.md](howto-server-delegation.md) for more information about delegation.
## Installing
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
## ma1sd-controlled Registration
To use the [Registration](https://github.com/ma1uta/ma1sd/blob/master/docs/features/registration.md) feature of ma1sd, you can make use of the following variables: To use the [Registration](https://github.com/ma1uta/ma1sd/blob/master/docs/features/registration.md) feature of ma1sd, you can make use of the following variables:
@ -65,9 +73,11 @@ To use the [Registration](https://github.com/ma1uta/ma1sd/blob/master/docs/featu
**Note**: For this to work, either the homeserver needs to [federate](configuring-playbook-federation.md) 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.example.com:8448`) is whitelisted in your firewall (even if you don't actually use/need federation). **Note**: For this to work, either the homeserver needs to [federate](configuring-playbook-federation.md) 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.example.com:8448`) is whitelisted in your firewall (even if you don't actually use/need federation).
## Authentication #### Authentication
[Authentication](https://github.com/ma1uta/ma1sd/blob/master/docs/features/authentication.md) provides the possibility to use your own [Identity Stores](https://github.com/ma1uta/ma1sd/blob/master/docs/stores/README.md) (for example LDAP) to authenticate users on your Homeserver. The following configuration can be used to authenticate against an LDAP server: [Authentication](https://github.com/ma1uta/ma1sd/blob/master/docs/features/authentication.md) provides the possibility to use your own [Identity Stores](https://github.com/ma1uta/ma1sd/blob/master/docs/stores/README.md) (for example LDAP) to authenticate users on your Homeserver.
To enable authentication against an LDAP server, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml ```yaml
matrix_synapse_ext_password_provider_rest_auth_enabled: true matrix_synapse_ext_password_provider_rest_auth_enabled: true
@ -87,17 +97,7 @@ matrix_ma1sd_configuration_extension_yaml: |
bindPassword: TheUserPassword bindPassword: TheUserPassword
``` ```
## Additional features #### Example: SMS verification
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](https://github.com/ma1uta/ma1sd) 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](../roles/custom/matrix-ma1sd/defaults/main.yml) of the ma1sd component.
## Example: SMS verification
If your use case requires mobile verification, it is quite simple to integrate ma1sd with [Twilio](https://www.twilio.com/), an online telephony services gateway. Their prices are reasonable for low-volume projects and integration can be done with the following configuration: If your use case requires mobile verification, it is quite simple to integrate ma1sd with [Twilio](https://www.twilio.com/), an online telephony services gateway. Their prices are reasonable for low-volume projects and integration can be done with the following configuration:
@ -113,7 +113,7 @@ matrix_ma1sd_configuration_extension_yaml: |
number: '+<msisdn-number>' number: '+<msisdn-number>'
``` ```
## Example: Open Registration for every Domain #### 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. 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.
@ -129,13 +129,17 @@ matrix_ma1sd_configuration_extension_yaml: |
whitelist: ~ whitelist: ~
``` ```
## Installing
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
## Troubleshooting ## Troubleshooting
If email address validation emails sent by ma1sd are not reaching you, you should look into [Adjusting email-sending settings](configuring-playbook-email.md). If email address validation emails sent by ma1sd are not reaching you, you should look into [Adjusting email-sending settings](configuring-playbook-email.md).
If you'd like additional logging information, temporarily enable verbose logging for ma1sd. If you'd like additional logging information, temporarily enable verbose logging for ma1sd.
Example configuration (`inventory/host_vars/matrix.example.com/vars.yml`): To enable it, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml ```yaml
matrix_ma1sd_verbose_logging: true matrix_ma1sd_verbose_logging: true