* 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>
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).
## 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
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 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
matrix_ma1sd_matrixorg_forwarding_enabled: true
```
### Customizing email templates
### Additional features
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.
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.
## Adjusting DNS records
A few variables can be toggled in this playbook to alter the ma1sd configuration that gets generated.
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)
Still, ma1sd can do much more. You can refer to the [ma1sd website](https://github.com/ma1uta/ma1sd) for more details and configuration options.
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.
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.
**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
#### Customizing email templates
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
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.
## ma1sd-controlled Registration
#### 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:
@@ -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).
## 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.
[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:
To enable authentication against an LDAP server, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
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
#### 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 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.
After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all`
## 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 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:
Suguru Hirahara
1 год назад
GitHub