From 4911e85caa75809f9b19cb243a8681ecc0dd72cf Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 10 Nov 2024 14:47:43 +0900 Subject: [PATCH 1/7] Update docs/configuring-playbook-ma1sd.md: edit top paragraphs Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-ma1sd.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/configuring-playbook-ma1sd.md b/docs/configuring-playbook-ma1sd.md index d834e6e32..b8773a77c 100644 --- a/docs/configuring-playbook-ma1sd.md +++ b/docs/configuring-playbook-ma1sd.md @@ -1,12 +1,10 @@ # Setting up ma1sd Identity Server (optional) -The playbook can configure the [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server for you. +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. -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). +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. -This server 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). From 974350366fd8f4fc9d5922271ae961cd7fcbd468 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 18 Nov 2024 22:14:04 +0900 Subject: [PATCH 2/7] Update docs/configuring-playbook-ma1sd.md: use common expressions for instruction to add configuration Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-ma1sd.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/configuring-playbook-ma1sd.md b/docs/configuring-playbook-ma1sd.md index b8773a77c..c73f2b7d6 100644 --- a/docs/configuring-playbook-ma1sd.md +++ b/docs/configuring-playbook-ma1sd.md @@ -22,7 +22,7 @@ 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 @@ -65,7 +65,9 @@ To use the [Registration](https://github.com/ma1uta/ma1sd/blob/master/docs/featu ## 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 matrix_synapse_ext_password_provider_rest_auth_enabled: true @@ -133,7 +135,7 @@ If email address validation emails sent by ma1sd are not reaching you, you shoul 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 matrix_ma1sd_verbose_logging: true From 16e9b9a0df66d40e9ab5b8a8533084b86c22d1a3 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 18 Nov 2024 22:15:39 +0900 Subject: [PATCH 3/7] Update docs/configuring-playbook-ma1sd.md: move instructions up Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-ma1sd.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/configuring-playbook-ma1sd.md b/docs/configuring-playbook-ma1sd.md index c73f2b7d6..7aec952fb 100644 --- a/docs/configuring-playbook-ma1sd.md +++ b/docs/configuring-playbook-ma1sd.md @@ -32,20 +32,6 @@ matrix_ma1sd_matrixorg_forwarding_enabled: true 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 - -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: @@ -129,6 +115,20 @@ matrix_ma1sd_configuration_extension_yaml: | whitelist: ~ ``` +## Adjusting DNS records + +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` + ## 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). From 41309799b6df41e0085e948ab59e226f5cbf3658 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 18 Nov 2024 22:18:20 +0900 Subject: [PATCH 4/7] 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 --- docs/configuring-playbook-ma1sd.md | 31 +++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/docs/configuring-playbook-ma1sd.md b/docs/configuring-playbook-ma1sd.md index 7aec952fb..fd029a927 100644 --- a/docs/configuring-playbook-ma1sd.md +++ b/docs/configuring-playbook-ma1sd.md @@ -28,11 +28,22 @@ To enable matrix.org forwarding, add the following configuration to your `invent 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. -## 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: @@ -49,7 +60,7 @@ 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. @@ -73,17 +84,7 @@ matrix_ma1sd_configuration_extension_yaml: | 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](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: @@ -99,7 +100,7 @@ matrix_ma1sd_configuration_extension_yaml: | 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. From 53130c6dfb29d6fb5552aa19bab2597c53b7ebf3 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Thu, 21 Nov 2024 16:30:50 +0900 Subject: [PATCH 5/7] Update docs/configuring-playbook-ma1sd.md Co-authored-by: Slavi Pantaleev --- docs/configuring-playbook-ma1sd.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/configuring-playbook-ma1sd.md b/docs/configuring-playbook-ma1sd.md index fd029a927..b4cb47e4f 100644 --- a/docs/configuring-playbook-ma1sd.md +++ b/docs/configuring-playbook-ma1sd.md @@ -2,6 +2,8 @@ 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. +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 using ma1sd 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 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. See the project's [documentation](https://github.com/ma1uta/ma1sd) to learn what it does and why it might be useful to you. From 27ce92f179ae1de1660057848c4d96eeb9de48f8 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Thu, 21 Nov 2024 17:17:22 +0900 Subject: [PATCH 6/7] Update configuring-playbook-ma1sd.md: adjust to follow other examples such as on configuring-playbook-bridge-appservice-webhooks.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/configuring-playbook-ma1sd.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuring-playbook-ma1sd.md b/docs/configuring-playbook-ma1sd.md index b4cb47e4f..42d3cb26d 100644 --- a/docs/configuring-playbook-ma1sd.md +++ b/docs/configuring-playbook-ma1sd.md @@ -1,8 +1,8 @@ # Setting up ma1sd Identity Server (optional) -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. +**⚠️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 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 using ma1sd 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). +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. 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. From 97740ec800491d8c2f8658f7ed6ecc21b02fbc7c Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Thu, 21 Nov 2024 17:40:22 +0900 Subject: [PATCH 7/7] Update docs/configuring-playbook-ma1sd.md: move instruction to configure DNS settings up Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-ma1sd.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/configuring-playbook-ma1sd.md b/docs/configuring-playbook-ma1sd.md index 42d3cb26d..bae241988 100644 --- a/docs/configuring-playbook-ma1sd.md +++ b/docs/configuring-playbook-ma1sd.md @@ -10,6 +10,16 @@ See the project's [documentation](https://github.com/ma1uta/ma1sd) to learn what **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 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. + ## Adjusting the playbook configuration To enable ma1sd, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -118,16 +128,6 @@ matrix_ma1sd_configuration_extension_yaml: | whitelist: ~ ``` -## Adjusting DNS records - -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`