Adjust blank lines: remove duplicated ones
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
This commit is contained in:
Suguru Hirahara
@ -12,7 +12,6 @@ Matrix Authentication Service is an implementation of [MSC3861: Next-generation
|
||||
|
||||
**If you've already been using Synapse** and have user accounts in its database, you can [migrate to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service).
|
||||
|
||||
|
||||
## Reasons to use Matrix Authentication Service
|
||||
|
||||
You may be wondering whether you should make the switch to Matrix Authentication Service (MAS) or keep using your existing authentication flow via Synapse (password-based or [OIDC](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on)-enabled).
|
||||
@ -33,7 +32,6 @@ Below, we'll try to **highlight some potential reasons for switching** to Matrix
|
||||
|
||||
- To reap some of the security benefits that Matrix Authentication Service offers, as outlined in the [Better authentication, session management and permissions in Matrix](https://matrix.org/blog/2023/09/better-auth/) article.
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- ⚠️ the [Synapse](configuring-playbook-synapse.md) homeserver implementation (which is the default for this playbook). Other homeserver implementations ([Dendrite](./configuring-playbook-dendrite.md), [Conduit](./configuring-playbook-conduit.md), etc.) do not support integrating wtih Matrix Authentication Service yet.
|
||||
@ -42,7 +40,6 @@ Below, we'll try to **highlight some potential reasons for switching** to Matrix
|
||||
|
||||
- ❌ **disabling all password providers** for Synapse (things like [shared-secret-auth](./configuring-playbook-shared-secret-auth.md), [rest-auth](./configuring-playbook-rest-auth.md), [LDAP auth](./configuring-playbook-ldap-auth.md), etc.) More details about this are available in the [Expectations](#expectations) section below.
|
||||
|
||||
|
||||
## Expectations
|
||||
|
||||
This section details what you can expect when switching to the Matrix Authentication Service (MAS).
|
||||
@ -84,8 +81,6 @@ This section details what you can expect when switching to the Matrix Authentica
|
||||
|
||||
- ✅ Users that are prepared by the playbook (for bots, bridges, etc.) will continue to be registered automatically as expected. The playbook automatically does the right thing regardless of homeserver implementation (Synapse, Dendrite, etc.) and whether MAS is enabled or not. When MAS is enabled, the playbook will forward user-registration requests to MAS.
|
||||
|
||||
|
||||
|
||||
## Installation flows
|
||||
|
||||
### New homeserver
|
||||
@ -102,7 +97,6 @@ For existing Synapse homeservers:
|
||||
|
||||
- then follow the [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) instructions to perform the installation and migration
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Matrix Authentication Service, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -123,7 +117,6 @@ In the sub-sections that follow, we'll cover some additional configuration optio
|
||||
|
||||
There are many other configuration options available. Consult the [`defaults/main.yml` file](../roles/custom/matrix-authentication-service/defaults/main.yml) in the [matrix-authentication-service role](../roles/custom/matrix-authentication-service/) to discover them.
|
||||
|
||||
|
||||
### Adjusting the Matrix Authentication Service URL
|
||||
|
||||
By default, this playbook installs the Matrix Authentication Service on the `matrix.` subdomain, at the `/auth` path (https://matrix.example.com/auth). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
|
||||
@ -144,7 +137,6 @@ The [configuration above](#adjusting-the-playbook-configuration) instructs exist
|
||||
|
||||
This is done temporarily. The migration steps are described in more detail in the [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) section below.
|
||||
|
||||
|
||||
### Upstream OAuth2 configuration
|
||||
|
||||
To make Matrix Authentication Service delegate to an existing upstream OAuth 2.0/OIDC provider, you can use its [`upstream_oauth2.providers` setting](https://element-hq.github.io/matrix-authentication-service/reference/configuration.html#upstream_oauth2providers).
|
||||
@ -276,7 +268,6 @@ matrix_authentication_service_config_upstream_oauth2_providers:
|
||||
- go through the [migrating an existing homeserver](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) process
|
||||
- remove all Synapse OIDC-related configuration (`matrix_synapse_oidc_*`) to prevent it being in conflict with the MAS OIDC configuration
|
||||
|
||||
|
||||
## Adjusting DNS records
|
||||
|
||||
If you've changed the default hostname, **you may need to adjust your DNS** records to point the Matrix Authentication Service domain to the Matrix server.
|
||||
@ -285,7 +276,6 @@ See [Configuring DNS](configuring-dns.md) for details about DNS changes.
|
||||
|
||||
If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
|
||||
|
||||
|
||||
## Installing
|
||||
|
||||
Now that you've [adjusted the playbook configuration](#adjusting-the-playbook-configuration) and [your DNS records](#adjusting-dns-records), you can run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
@ -305,7 +295,6 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
|
||||
💡 After installation, you should [verify that Matrix Authentication Service is installed correctly](#verify-that-matrix-authentication-service-is-installed-correctly).
|
||||
|
||||
|
||||
## Migrating an existing Synapse homeserver to Matrix Authentication Service
|
||||
|
||||
Our migration guide is loosely based on the upstream [Migrating an existing homeserver](https://element-hq.github.io/matrix-authentication-service/setup/migration.html) guide.
|
||||
@ -344,7 +333,6 @@ The installation + migration steps are like this:
|
||||
|
||||
6. [Verify that Matrix Authentication Service is installed correctly](#verify-that-matrix-authentication-service-is-installed-correctly)
|
||||
|
||||
|
||||
### Migrate your data from Synapse to Matrix Authentication Service using syn2mas
|
||||
|
||||
We **don't** ask you to [run the `syn2mas` migration advisor command](https://element-hq.github.io/matrix-authentication-service/setup/migration.html#run-the-migration-advisor), because it only gives you the green light if your Synapse configuration (`homeserver.yaml`) is configured in a way that's compatible with MAS (delegating authentication to MAS; disabling Synapse's password config; etc.). Until we migrate your data with the `syn2mas` tool, we intentionally avoid doing these changes to allow existing user sessions to work.
|
||||
@ -418,7 +406,6 @@ just run-tags matrix-authentication-service-syn2mas
|
||||
|
||||
Having performed a `syn2mas` migration once, trying to do it again will report errors for users that were already migrated (e.g. "Error: Unknown upstream provider oauth-delegated").
|
||||
|
||||
|
||||
## Verify that Matrix Authentication Service is installed correctly
|
||||
|
||||
After [installation](#installing), run the `doctor` subcommand of the [`mas-cli` command-line tool](https://element-hq.github.io/matrix-authentication-service/reference/cli/index.html) to verify that MAS is installed correctly.
|
||||
@ -453,14 +440,12 @@ This documentation page already mentions:
|
||||
|
||||
There are other sub-commands available. Run `/matrix/matrix-authentication-service/bin/mas-cli` to get an overview.
|
||||
|
||||
|
||||
## User registration
|
||||
|
||||
After Matrix Authentication Service is [installed](#installing), users need to be managed there (unless you're managing them in an [upstream OAuth2 provider](#upstream-oauth2-configuration)).
|
||||
|
||||
You can register users new users as described in the [Registering users](./registering-users.md) documentation (via `mas-cli manage register-user` or the Ansible playbook's `register-user` tag).
|
||||
|
||||
|
||||
## Working around email deliverability issues
|
||||
|
||||
Because Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user, you may need to work around email deliverability issues if [your email-sending configuration](./configuring-playbook-email.md) is not working.
|
||||
|
||||
Reference in New Issue
Block a user