mirror/matrix-docker-ansible-deploy
1
0
Fork 0
mirror of https://github.com/spantaleev/matrix-docker-ansible-deploy.git synced 2025-10-31 07:17:57 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #4125 from luixxiul/patch-2

Browse Source 
Update docs for components related to authentication and ma1sd
This commit is contained in:
Slavi Pantaleev
2025-02-28 16:27:39 +02:00
committed by GitHub
parent 8abb8455c7 4d5367fe93
commit 9ba0f51a8f
4 changed files with 61 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
docs/configuring-playbook-ldap-auth.md
View File

@@ -1,10 +1,21 @@
<!--
SPDX-FileCopyrightText: 2018 - 2022 Slavi Pantaleev
SPDX-FileCopyrightText: 2019 - 2023 MDAD project contributors
SPDX-FileCopyrightText: 2020 Marcel Partap
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# 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.
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
@@ -21,20 +32,29 @@ 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
```
## 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).
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
```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).

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

@@ -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.

21
docs/configuring-playbook-rest-auth.md
View File

@@ -1,3 +1,11 @@
<!--
SPDX-FileCopyrightText: 2018 - 2019 Slavi Pantaleev
SPDX-FileCopyrightText: 2019 - 2020 Marcel Partap
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# 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.
@@ -16,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
@@ -36,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).

12
docs/configuring-playbook-shared-secret-auth.md
View File

@@ -1,3 +1,11 @@
<!--
SPDX-FileCopyrightText: 2018 - 2020 Slavi Pantaleev
SPDX-FileCopyrightText: 2020 MDAD project contributors
SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
SPDX-License-Identifier: AGPL-3.0-or-later
-->
# 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.
@@ -15,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