From 87634922dddf591e1c4268ff96bacf825df2c6eb Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Fri, 28 Feb 2025 22:24:58 +0900 Subject: [PATCH 1/4] Update docs for components related to authentication: add copyright headers Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-ldap-auth.md | 9 +++++++++ docs/configuring-playbook-rest-auth.md | 8 ++++++++ docs/configuring-playbook-shared-secret-auth.md | 8 ++++++++ 3 files changed, 25 insertions(+) diff --git a/docs/configuring-playbook-ldap-auth.md b/docs/configuring-playbook-ldap-auth.md index d3a95d138..7507c8330 100644 --- a/docs/configuring-playbook-ldap-auth.md +++ b/docs/configuring-playbook-ldap-auth.md @@ -1,3 +1,12 @@ + + # Setting up the LDAP authentication password provider module (optional, advanced) The playbook can install and configure the [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) LDAP Auth password provider for you. diff --git a/docs/configuring-playbook-rest-auth.md b/docs/configuring-playbook-rest-auth.md index d15ba586b..6952f3f1e 100644 --- a/docs/configuring-playbook-rest-auth.md +++ b/docs/configuring-playbook-rest-auth.md @@ -1,3 +1,11 @@ + + # Setting up the REST authentication password provider module (optional, advanced) The playbook can install and configure [matrix-synapse-rest-auth](https://github.com/ma1uta/matrix-synapse-rest-password-provider) for you. diff --git a/docs/configuring-playbook-shared-secret-auth.md b/docs/configuring-playbook-shared-secret-auth.md index c7dced046..9f4dfd736 100644 --- a/docs/configuring-playbook-shared-secret-auth.md +++ b/docs/configuring-playbook-shared-secret-auth.md @@ -1,3 +1,11 @@ + + # Setting up the Shared Secret Auth password provider module (optional, advanced) The playbook can install and configure [matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) for you. From 66093857bcf32009b02bde37ff3b4acbdad43e7a Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Fri, 28 Feb 2025 22:25:08 +0900 Subject: [PATCH 2/4] Update docs for components related to authentication: adopt the common descriptions Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-ldap-auth.md | 10 ++++++---- docs/configuring-playbook-rest-auth.md | 6 +++--- docs/configuring-playbook-shared-secret-auth.md | 6 +++--- 3 files changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/configuring-playbook-ldap-auth.md b/docs/configuring-playbook-ldap-auth.md index 7507c8330..ba135cca1 100644 --- a/docs/configuring-playbook-ldap-auth.md +++ b/docs/configuring-playbook-ldap-auth.md @@ -2,7 +2,7 @@ SPDX-FileCopyrightText: 2018 - 2022 Slavi Pantaleev SPDX-FileCopyrightText: 2019 - 2023 MDAD project contributors SPDX-FileCopyrightText: 2020 Marcel Partap -SPDX-FileCopyrightText: 2024 Suguru Hirahara +SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara SPDX-License-Identifier: AGPL-3.0-or-later --> @@ -13,7 +13,9 @@ The playbook can install and configure the [matrix-synapse-ldap3](https://github See the project's [documentation](https://github.com/matrix-org/matrix-synapse-ldap3/blob/main/README.rst) to learn what it does and why it might be useful to you. -If you decide that you'd like to let this playbook install it for you, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): +## Adjusting the playbook configuration + +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): ```yaml matrix_synapse_ext_password_provider_ldap_enabled: true @@ -30,9 +32,9 @@ matrix_synapse_ext_password_provider_ldap_bind_password: "" matrix_synapse_ext_password_provider_ldap_filter: "" ``` -## Authenticating only using a password provider +### Authenticating only using a password provider -If you wish for users to **authenticate only against configured password providers** (like this one), **without consulting Synapse's local database**, feel free to disable it: +If you wish for users to **authenticate only against configured password providers** (like this one), **without consulting Synapse's local database**, you can disable it by adding the following configuration to your `vars.yml` file: ```yaml matrix_synapse_password_config_localdb_enabled: false diff --git a/docs/configuring-playbook-rest-auth.md b/docs/configuring-playbook-rest-auth.md index 6952f3f1e..1ec45d17a 100644 --- a/docs/configuring-playbook-rest-auth.md +++ b/docs/configuring-playbook-rest-auth.md @@ -1,7 +1,7 @@ @@ -24,9 +24,9 @@ matrix_synapse_ext_password_provider_rest_auth_registration_profile_name_autofil matrix_synapse_ext_password_provider_rest_auth_login_profile_name_autofill: false ``` -## Authenticating only using a password provider +### Authenticating only using a password provider -If you wish for users to **authenticate only against configured password providers** (like this one), **without consulting Synapse's local database**, feel free to disable it: +If you wish for users to **authenticate only against configured password providers** (like this one), **without consulting Synapse's local database**, you can disable it by adding the following configuration to your `vars.yml` file: ```yaml matrix_synapse_password_config_localdb_enabled: false diff --git a/docs/configuring-playbook-shared-secret-auth.md b/docs/configuring-playbook-shared-secret-auth.md index 9f4dfd736..07d42d762 100644 --- a/docs/configuring-playbook-shared-secret-auth.md +++ b/docs/configuring-playbook-shared-secret-auth.md @@ -1,7 +1,7 @@ @@ -23,9 +23,9 @@ matrix_synapse_ext_password_provider_shared_secret_auth_enabled: true matrix_synapse_ext_password_provider_shared_secret_auth_shared_secret: YOUR_SHARED_SECRET_GOES_HERE ``` -## Authenticating only using a password provider +### Authenticating only using a password provider -If you wish for users to **authenticate only against configured password providers** (like this one), **without consulting Synapse's local database**, feel free to disable it: +If you wish for users to **authenticate only against configured password providers** (like this one), **without consulting Synapse's local database**, you can disable it by adding the following configuration to your `vars.yml` file: ```yaml matrix_synapse_password_config_localdb_enabled: false From ff1f882d3c638db9262267109d67f38f29a51bfb Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Fri, 28 Feb 2025 22:25:14 +0900 Subject: [PATCH 3/4] Update docs for components related to authentication: tidy up MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Move the recommendation to avoid installing ma1sd from configuring-playbook-ldap-auth.md to configuring-playbook-rest-auth.md It has been long since recommending to install ma1sd was stopped, and the warning message is placed on the documentation about installing ma1sd as well, so it does not really seem to be sensible to advertise the component by repeating the warning… The message can rather be reused on the latter, as it is expected to be implemented with a backend such as ma1sd (see: matrix_synapse_ext_password_provider_rest_auth_endpoint on the file) - Add instruction to install the component to configuring-playbook-ldap-auth.md Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-ldap-auth.md | 17 +++++++++++++---- docs/configuring-playbook-rest-auth.md | 9 +++++++++ 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/docs/configuring-playbook-ldap-auth.md b/docs/configuring-playbook-ldap-auth.md index ba135cca1..f6736a735 100644 --- a/docs/configuring-playbook-ldap-auth.md +++ b/docs/configuring-playbook-ldap-auth.md @@ -40,12 +40,21 @@ If you wish for users to **authenticate only against configured password provide matrix_synapse_password_config_localdb_enabled: false ``` -## Using ma1sd Identity Server for authentication (not recommended) +## Installing -The playbook can instead configure [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server for LDAP authentication. However, **we recommend not bothering with installing it** as ma1sd has been unmaintained for years. +After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: -If you wish to install it anyway, consult the [ma1sd Identity Server configuration](configuring-playbook-ma1sd.md#authentication). + +```sh +ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start +``` -## Handling user registration +The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all` + +`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too. + +## Usage + +### Handling user registration If you wish for users to also be able to make new registrations against LDAP, you may **also** wish to [set up the ldap-registration-proxy](configuring-playbook-matrix-ldap-registration-proxy.md). diff --git a/docs/configuring-playbook-rest-auth.md b/docs/configuring-playbook-rest-auth.md index 1ec45d17a..216b71e37 100644 --- a/docs/configuring-playbook-rest-auth.md +++ b/docs/configuring-playbook-rest-auth.md @@ -44,3 +44,12 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all` `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too. + +## Usage + +### Use ma1sd Identity Server for the backend (not recommended) + +This module does not provide direct integration with any backend. For the backend you can use [ma1sd](https://github.com/ma1uta/ma1sd) Identity Server, which can be configured with the playbook. + +> [!WARNING] +> We recommend not bothering with installing ma1sd as it has been unmaintained for years. If you wish to install it anyway, consult the [ma1sd Identity Server configuration](configuring-playbook-ma1sd.md). From 4d5367fe934b00160df6fadc1beeeecae796fa4c Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Fri, 28 Feb 2025 22:27:56 +0900 Subject: [PATCH 4/4] Update docs/configuring-playbook-ma1sd.md: improve the warning message on top Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-ma1sd.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/configuring-playbook-ma1sd.md b/docs/configuring-playbook-ma1sd.md index 812ef14d4..694a1f39c 100644 --- a/docs/configuring-playbook-ma1sd.md +++ b/docs/configuring-playbook-ma1sd.md @@ -4,14 +4,17 @@ SPDX-FileCopyrightText: 2019 Noah Fleischmann SPDX-FileCopyrightText: 2019 - 2020 MDAD project contributors SPDX-FileCopyrightText: 2020 Marcel Partap SPDX-FileCopyrightText: 2020 Justin Croonenberghs -SPDX-FileCopyrightText: 2024 Suguru Hirahara +SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara SPDX-License-Identifier: AGPL-3.0-or-later --> # Setting up ma1sd Identity Server (optional) -**⚠️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). +> [!WARNING] +> Since ma1sd has been unmaintained for years (the latest commit and release being from 2021) and the future of identity server's role in the Matrix specification is uncertain, **we recommend not bothering with installing it unless it's the only way you can do what you need to do**. +> +> Please note that certain things can be achieved with other components. For example, if you wish to implement LDAP integration, you might as well check out [the LDAP provider module for Synapse](./configuring-playbook-ldap-auth.md) instead. 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.