overmind
/
matrix-docker-ansible-deploy
ミラー元 https://github.com/spantaleev/matrix-docker-ansible-deploy
1
0
フォーク 0
コード 課題 0 リリース 0 Wiki アクティビティ
Matrix Docker Ansible eploy
選択できるのは25トピックまでです。 トピックは、先頭が英数字で、英数字とダッシュ('-')を使用した35文字以内のものにしてください。
10090 コミット
18 ブランチ
1.5 GiB
 
 
ツリー: ec00a76b14
ブランチ タグ
${ item.name }
ブランチ ${ searchTerm } を作成
'ec00a76b14' から
${ noResults }
matrix-docker-ansible-deploy/i18n/locales/jp/LC_MESSAGES/docs/configuring-playbook-matrix...

623 行
42 KiB
Raw Blame 履歴 

  1. # SOME DESCRIPTIVE TITLE.

  2. # Copyright (C) 2018-2024, Slavi Pantaleev, Aine Etke, MDAD community

  3. # members

  4. # This file is distributed under the same license as the

  5. # matrix-docker-ansible-deploy package.

  6. # FIRST AUTHOR <EMAIL@ADDRESS>, 2024.

  7. #

  8. #, fuzzy

  9. msgid ""

  10. msgstr ""

  11. "Project-Id-Version: matrix-docker-ansible-deploy \n"

  12. "Report-Msgid-Bugs-To: \n"

  13. "POT-Creation-Date: 2025-01-27 09:54+0200\n"

  14. "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"

  15. "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"

  16. "Language: jp\n"

  17. "Language-Team: jp <LL@li.org>\n"

  18. "MIME-Version: 1.0\n"

  19. "Content-Type: text/plain; charset=utf-8\n"

  20. "Content-Transfer-Encoding: 8bit\n"

  21. "Generated-By: Babel 2.16.0\n"

  22. 

  23. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:1

  24. msgid "Setting up Matrix Authentication Service (optional)"

  25. msgstr ""

  26. 

  27. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:3

  28. msgid "The playbook can install and configure [Matrix Authentication Service](https://github.com/element-hq/matrix-authentication-service/) (MAS) — a service operating alongside your existing [Synapse](./configuring-playbook-synapse.md) homeserver and providing [better authentication, session management and permissions in Matrix](https://matrix.org/blog/2023/09/better-auth/)."

  29. msgstr ""

  30. 

  31. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:5

  32. msgid "Matrix Authentication Service is an implementation of [MSC3861: Next-generation auth for Matrix, based on OAuth 2.0/OIDC](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and still work in progress, tracked at the [areweoidcyet.com](https://areweoidcyet.com/) website."

  33. msgstr ""

  34. 

  35. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:7

  36. msgid "**Before going through with starting to use Matrix Authentication Service**, make sure to read:"

  37. msgstr ""

  38. 

  39. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:9

  40. msgid "the [Reasons to use Matrix Authentication Service](#reasons-to-use-matrix-authentication-service) section below"

  41. msgstr ""

  42. 

  43. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:10

  44. msgid "the [Expectations](#expectations) section below"

  45. msgstr ""

  46. 

  47. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:11

  48. msgid "the [FAQ section on areweoidcyet.com](https://areweoidcyet.com/#faqs)"

  49. msgstr ""

  50. 

  51. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:13

  52. msgid "**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)."

  53. msgstr ""

  54. 

  55. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:15

  56. msgid "Reasons to use Matrix Authentication Service"

  57. msgstr ""

  58. 

  59. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:17

  60. msgid "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)."

  61. msgstr ""

  62. 

  63. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:19

  64. msgid "Matrix Authentication Service is **still an experimental service** and **not a default** for this Ansible playbook."

  65. msgstr ""

  66. 

  67. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:21

  68. msgid "The [Expectations](#expectations) section contains a list of what works and what doesn't (**some services don't work with MAS yet**), as well as the **relative irreversability** of the migration process."

  69. msgstr ""

  70. 

  71. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:23

  72. msgid "Below, we'll try to **highlight some potential reasons for switching** to Matrix Authentication Service:"

  73. msgstr ""

  74. 

  75. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:25

  76. msgid "To use SSO in [Element X](https://element.io/blog/element-x-ignition/). The old [Synapse OIDC](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on) login flow is only supported in old Element clients and will not be supported in Element X. Element X will only support the new SSO-based login flow provided by MAS, so if you want to use SSO with Element X, you will need to switch to MAS."

  77. msgstr ""

  78. 

  79. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:27

  80. msgid "To help drive adoption of the \"Next-generation auth for Matrix\" by switching to what's ultimately coming anyway"

  81. msgstr ""

  82. 

  83. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:29

  84. msgid "To help discover (and potentially fix) MAS integration issues with this Ansible playbook"

  85. msgstr ""

  86. 

  87. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:31

  88. msgid "To help discover (and potentially fix) MAS integration issues with various other Matrix components (bridges, bots, clients, etc.)"

  89. msgstr ""

  90. 

  91. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:33

  92. msgid "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."

  93. msgstr ""

  94. 

  95. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:35

  96. msgid "Prerequisites"

  97. msgstr ""

  98. 

  99. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:37

  100. msgid "⚠️ 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."

  101. msgstr ""

  102. 

  103. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:39

  104. msgid "⚠️ **email sending** configured (see [Adjusting email-sending settings](./configuring-playbook-email.md)), 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** going through the new SSO-based login flow. It's also possible to [work around email deliverability issues](#working-around-email-deliverability-issues) if your email configuration is not working."

  105. msgstr ""

  106. 

  107. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:41

  108. msgid "❌ **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."

  109. msgstr ""

  110. 

  111. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:43

  112. msgid "Expectations"

  113. msgstr ""

  114. 

  115. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:45

  116. msgid "This section details what you can expect when switching to the Matrix Authentication Service (MAS)."

  117. msgstr ""

  118. 

  119. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:47

  120. msgid "❌ **Synapse password providers will need to be disabled**. You can no longer use [shared-secret-auth](./configuring-playbook-shared-secret-auth.md), [rest-auth](./configuring-playbook-rest-auth.md), [LDAP auth](./configuring-playbook-ldap-auth.md), etc. When the authentication flow is handled by MAS (not by Synapse anymore), it doesn't make sense to extend the Synapse authentication flow with additional modules. Many bridges used to rely on shared-secret-auth for doing double-puppeting (impersonating other users), but most (at least the mautrix bridges) nowadays use [Appservice Double Puppet](./configuring-playbook-appservice-double-puppet.md) as a better alternative. Older/maintained bridges may still rely on shared-secret-auth, as do other services like [matrix-corporal](./configuring-playbook-matrix-corporal.md)."

  121. msgstr ""

  122. 

  123. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:49

  124. msgid "❌ Certain **tools like [synapse-admin](./configuring-playbook-synapse-admin.md) do not have full compatibility with MAS yet**. synapse-admin already supports [login with access token](https://github.com/etkecc/synapse-admin/pull/58), browsing users (which Synapse will internally fetch from MAS) and updating user avatars. However, editing users (passwords, etc.) now needs to happen directly against MAS using the [MAS Admin API](https://element-hq.github.io/matrix-authentication-service/api/index.html), which synapse-admin cannot interact with yet."

  125. msgstr ""

  126. 

  127. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:51

  128. msgid "❌ **Some services experience issues when authenticating via MAS**:"

  129. msgstr ""

  130. 

  131. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:53

  132. msgid "[Postmoogle](./configuring-playbook-bridge-postmoogle.md) works the first time around, but it consistently fails after restarting:"

  133. msgstr ""

  134. 

  135. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:55

  136. msgid "cannot initialize matrix bot error=\"olm account is marked as shared, keys seem to have disappeared from the server\""

  137. msgstr ""

  138. 

  139. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:57

  140. msgid "[matrix-reminder-bot](./configuring-playbook-bot-matrix-reminder-bot.md) fails to start (see [element-hq/matrix-authentication-service#3439](https://github.com/element-hq/matrix-authentication-service/issues/3439))"

  141. msgstr ""

  142. 

  143. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:58

  144. msgid "Other services may be similarly affected. This list is not exhaustive."

  145. msgstr ""

  146. 

  147. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:60

  148. msgid "❌ **Encrypted appservices** do not work yet (related to [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190) and [PR 17705 for Synapse](https://github.com/element-hq/synapse/pull/17705)), so all bridges/bots that rely on encryption will fail to start (see [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3658) for Hookshot). You can use these bridges/bots only if you **keep end-to-bridge encryption disabled** (which is the default setting)."

  149. msgstr ""

  150. 

  151. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:62

  152. msgid "⚠️ **You will need to have email sending configured** (see [Adjusting email-sending settings](./configuring-playbook-email.md)), 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** going through the new SSO-based login flow. It's also possible to [work around email deliverability issues](#working-around-email-deliverability-issues) if your email configuration is not working."

  153. msgstr ""

  154. 

  155. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:64

  156. msgid "⚠️ [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) is **possible**, but requires **some playbook-assisted manual work**. Migration is **reversible with no or minor issues if done quickly enough**, but as users start logging in (creating new login sessions) via the new MAS setup, disabling MAS and reverting back to the Synapse user database will cause these new sessions to break."

  157. msgstr ""

  158. 

  159. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:66

  160. msgid "⚠️ [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) does not currently seem to preserve the \"admin\" flag for users (as found in the Synapse database). All users are imported as non-admin — see [element-hq/matrix-authentication-service#3440](https://github.com/element-hq/matrix-authentication-service/issues/3440). You may need update the Matrix Authentication Service's database manually and adjust the `can_request_admin` column in the `users` table to `true` for users that need to be administrators (e.g. `UPDATE users SET can_request_admin = true WHERE username = 'someone';`)"

  161. msgstr ""

  162. 

  163. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:68

  164. msgid "⚠️ Delegating user authentication to MAS causes **your Synapse server to be completely dependant on one more service** for its operations. MAS is quick & lightweight and should be stable enough already, but this is something to keep in mind when making the switch."

  165. msgstr ""

  166. 

  167. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:70

  168. msgid "⚠️ If you've got [OIDC configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on), you will need to migrate your OIDC configuration to MAS by adding an [Upstream OAuth2 configuration](#upstream-oauth2-configuration)."

  169. msgstr ""

  170. 

  171. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:72

  172. msgid "⚠️ A [compatibility layer](https://element-hq.github.io/matrix-authentication-service/setup/homeserver.html#set-up-the-compatibility-layer) is installed — all `/_matrix/client/*/login` (etc.) requests will be routed to MAS instead of going to the homeserver. This is done both publicly (e.g. `https://matrix.example.com/_matrix/client/*/login`) and on the internal Traefik entrypoint (e.g. `https://matrix-traefik:8008/_matrix/client/*/login`) which helps addon services reach the homeserver's Client-Server API. You typically don't need to do anything to make this work, but it's good to be aware of it, especially if you have a [custom webserver setup](./configuring-playbook-own-webserver.md)."

  173. msgstr ""

  174. 

  175. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:74

  176. msgid "✅ Your **existing login sessions will continue to work** (you won't get logged out). Migration will require a bit of manual work and minutes of downtime, but it's not too bad."

  177. msgstr ""

  178. 

  179. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:76

  180. msgid "✅ Various clients ([Cinny](./configuring-playbook-client-cinny.md), [Element Web](./configuring-playbook-client-element-web.md), Element X, FluffyChat) will be able to use the **new SSO-based login flow** provided by Matrix Authentication Service"

  181. msgstr ""

  182. 

  183. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:78

  184. msgid "✅ The **old login flow** (called `m.login.password`) **will still continue to work**, so clients (old Element Web, etc.) and bridges/bots that don't support the new OIDC-based login flow will still work. Going through the old login flow does not require users to have a verified email address, as [is the case](https://github.com/element-hq/matrix-authentication-service/issues/1505) for the new SSO-based login flow."

  185. msgstr ""

  186. 

  187. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:80

  188. msgid "✅ [Registering users](./registering-users.md) via **the playbook's `register-user` tag remains unchanged**. 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. Registering users via the command-line is no longer done via the `/matrix/synapse/bin/register` script, but via `/matrix/matrix-authentication-service/bin/register-user`."

  189. msgstr ""

  190. 

  191. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:82

  192. msgid "✅ 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."

  193. msgstr ""

  194. 

  195. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:84

  196. msgid "Installation flows"

  197. msgstr ""

  198. 

  199. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:86

  200. msgid "New homeserver"

  201. msgstr ""

  202. 

  203. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:88

  204. msgid "For new homeservers (which don't have any users in their Synapse database yet), follow the [Adjusting the playbook configuration](#adjusting-the-playbook-configuration) instructions and then proceed with [Installing](#installing)."

  205. msgstr ""

  206. 

  207. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:90

  208. msgid "Existing homeserver"

  209. msgstr ""

  210. 

  211. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:92

  212. msgid "Other homeserver implementations ([Dendrite](./configuring-playbook-dendrite.md), [Conduit](./configuring-playbook-conduit.md), etc.) do not support integrating wtih Matrix Authentication Service yet."

  213. msgstr ""

  214. 

  215. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:94

  216. msgid "For existing Synapse homeservers:"

  217. msgstr ""

  218. 

  219. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:96

  220. msgid "when following the [Adjusting the playbook configuration](#adjusting-the-playbook-configuration) instructions, make sure to **disable the integration between Synapse and MAS** by **uncommenting** the `matrix_authentication_service_migration_in_progress: true` line as described in the [Marking an existing homeserver for migration](#marking-an-existing-homeserver-for-migration) section below."

  221. msgstr ""

  222. 

  223. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:98

  224. msgid "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"

  225. msgstr ""

  226. 

  227. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:100

  228. msgid "Adjusting DNS records (optional)"

  229. msgstr ""

  230. 

  231. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:102

  232. msgid "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."

  233. msgstr ""

  234. 

  235. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:104

  236. msgid "If you wish to adjust it, see the section [below](#adjusting-the-matrix-authentication-service-url-optional) for details about DNS configuration."

  237. msgstr ""

  238. 

  239. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:106

  240. msgid "Adjusting the playbook configuration"

  241. msgstr ""

  242. 

  243. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:108

  244. msgid "To enable Matrix Authentication Service, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:"

  245. msgstr ""

  246. 

  247. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:122

  248. msgid "In the sub-sections that follow, we'll cover some additional configuration options that you may wish to adjust."

  249. msgstr ""

  250. 

  251. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:124

  252. msgid "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."

  253. msgstr ""

  254. 

  255. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:126

  256. msgid "Adjusting the Matrix Authentication Service URL (optional)"

  257. msgstr ""

  258. 

  259. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:128

  260. msgid "By tweaking the `matrix_authentication_service_hostname` and `matrix_authentication_service_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one."

  261. msgstr ""

  262. 

  263. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:130

  264. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:157

  265. msgid "Example additional configuration for your `vars.yml` file:"

  266. msgstr ""

  267. 

  268. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:138

  269. msgid "If you've changed the default hostname, you may need to create a CNAME record for the Matrix Authentication Service domain (`auth.example.com`), which targets `matrix.example.com`."

  270. msgstr ""

  271. 

  272. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:140

  273. msgid "When setting, replace `example.com` with your own."

  274. msgstr ""

  275. 

  276. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:142

  277. msgid "Marking an existing homeserver for migration"

  278. msgstr ""

  279. 

  280. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:144

  281. msgid "The [configuration above](#adjusting-the-playbook-configuration) instructs existing users wishing to migrate to add `matrix_authentication_service_migration_in_progress: true` to their configuration."

  282. msgstr ""

  283. 

  284. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:146

  285. msgid "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."

  286. msgstr ""

  287. 

  288. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:148

  289. msgid "Upstream OAuth2 configuration"

  290. msgstr ""

  291. 

  292. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:150

  293. msgid "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)."

  294. msgstr ""

  295. 

  296. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:152

  297. msgid "The playbook exposes a `matrix_authentication_service_config_upstream_oauth2_providers` variable for controlling this setting."

  298. msgstr ""

  299. 

  300. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:269

  301. msgid "💡 Refer to the [`upstream_oauth2.providers` setting](https://element-hq.github.io/matrix-authentication-service/reference/configuration.html#upstream_oauth2providers) for the most up-to-date schema and example for providers. The value shown above here may be out of date."

  302. msgstr ""

  303. 

  304. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:271

  305. msgid "⚠️ The syntax for existing [OIDC providers configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on) is slightly different, so you will need to adjust your configuration when switching from Synapse OIDC to MAS upstream OAuth2."

  306. msgstr ""

  307. 

  308. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:273

  309. msgid "⚠️ When [migrating an existing homeserver](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) which contains OIDC-sourced users, you will need to:"

  310. msgstr ""

  311. 

  312. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:275

  313. msgid "[Configure upstream OIDC provider mapping for syn2mas](#configuring-upstream-oidc-provider-mapping-for-syn2mas)"

  314. msgstr ""

  315. 

  316. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:276

  317. msgid "go through the [migrating an existing homeserver](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) process"

  318. msgstr ""

  319. 

  320. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:277

  321. msgid "remove all Synapse OIDC-related configuration (`matrix_synapse_oidc_*`) to prevent it being in conflict with the MAS OIDC configuration"

  322. msgstr ""

  323. 

  324. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:279

  325. msgid "Installing"

  326. msgstr ""

  327. 

  328. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:281

  329. msgid "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:"

  330. msgstr ""

  331. 

  332. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:288

  333. msgid "**Notes**:"

  334. msgstr ""

  335. 

  336. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:290

  337. msgid "The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`"

  338. msgstr ""

  339. 

  340. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:292

  341. msgid "`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."

  342. msgstr ""

  343. 

  344. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:294

  345. msgid "If you're in the process of migrating an existing Synapse homeserver to MAS, you should now follow the rest of the steps in the [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) guide."

  346. msgstr ""

  347. 

  348. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:296

  349. msgid "💡 After installation, you should [verify that Matrix Authentication Service is installed correctly](#verify-that-matrix-authentication-service-is-installed-correctly)."

  350. msgstr ""

  351. 

  352. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:298

  353. msgid "Migrating an existing Synapse homeserver to Matrix Authentication Service"

  354. msgstr ""

  355. 

  356. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:300

  357. msgid "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."

  358. msgstr ""

  359. 

  360. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:302

  361. msgid "Migration is done via a tool called `syn2mas`, which the playbook could run for you (in a container)."

  362. msgstr ""

  363. 

  364. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:304

  365. msgid "The installation + migration steps are like this:"

  366. msgstr ""

  367. 

  368. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:306

  369. msgid "[Adjust your configuration](#adjusting-the-playbook-configuration) to **disable the integration between the homeserver and MAS**. This is done by **uncommenting** the `matrix_authentication_service_migration_in_progress: true` line."

  370. msgstr ""

  371. 

  372. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:308

  373. msgid "Perform the initial [installation](#installing). At this point:"

  374. msgstr ""

  375. 

  376. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:310

  377. msgid "Matrix Authentication Service will be installed. Its database will be empty, so it cannot validate existing access tokens or authentication users yet."

  378. msgstr ""

  379. 

  380. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:312

  381. msgid "The homeserver will still continue to use its local database for validating existing access tokens."

  382. msgstr ""

  383. 

  384. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:314

  385. msgid "Various [compatibility layer URLs](https://element-hq.github.io/matrix-authentication-service/setup/homeserver.html#set-up-the-compatibility-layer) are not yet installed. New login sessions will still be forwarded to the homeserver, which is capable of completing them."

  386. msgstr ""

  387. 

  388. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:316

  389. msgid "The `matrix-user-creator` role would be suppressed, so that it doesn't automatically attempt to create users (for bots, etc.) in the MAS database. These user accounts likely already exist in Synapse's user database and could be migrated over (via syn2mas, as per the steps below), so creating them in the MAS database would have been unnecessary and potentially problematic (conflicts during the syn2mas migration)."

  390. msgstr ""

  391. 

  392. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:318

  393. msgid "Consider taking a full [backup of your Postgres database](./maintenance-postgres.md#backing-up-postgresql). This is done just in case. The **syn2mas migration tool does not delete any data**, so it should be possible to revert to your previous setup by merely disabling MAS and re-running the playbook (no need to restore a Postgres backup). However, do note that as users start logging in (creating new login sessions) via the new MAS setup, disabling MAS and reverting back to the Synapse user database will cause these new sessions to break."

  394. msgstr ""

  395. 

  396. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:320

  397. msgid "[Migrate your data from Synapse to Matrix Authentication Service using syn2mas](#migrate-your-data-from-synapse-to-matrix-authentication-service-using-syn2mas)"

  398. msgstr ""

  399. 

  400. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:322

  401. msgid "[Adjust your configuration](#adjusting-the-playbook-configuration) again, to:"

  402. msgstr ""

  403. 

  404. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:324

  405. msgid "remove the `matrix_authentication_service_migration_in_progress: false` line"

  406. msgstr ""

  407. 

  408. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:326

  409. msgid "if you had been using [OIDC providers configured in Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on), remove all Synapse OIDC-related configuration (`matrix_synapse_oidc_*`) to prevent it being in conflict with the MAS OIDC configuration"

  410. msgstr ""

  411. 

  412. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:328

  413. msgid "Perform the [installation](#installing) again. At this point:"

  414. msgstr ""

  415. 

  416. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:330

  417. msgid "The homeserver will start delegating authentication to MAS."

  418. msgstr ""

  419. 

  420. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:332

  421. msgid "The compatibility layer URLs will be installed. New login sessions will be completed by MAS."

  422. msgstr ""

  423. 

  424. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:334

  425. msgid "[Verify that Matrix Authentication Service is installed correctly](#verify-that-matrix-authentication-service-is-installed-correctly)"

  426. msgstr ""

  427. 

  428. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:336

  429. msgid "Migrate your data from Synapse to Matrix Authentication Service using syn2mas"

  430. msgstr ""

  431. 

  432. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:338

  433. msgid "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."

  434. msgstr ""

  435. 

  436. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:340

  437. msgid "You can invoke the `syn2mas` tool via the playbook by running the playbook's `matrix-authentication-service-mas-cli-syn2mas` tag. We recommend first doing a [dry-run](#performing-a-syn2mas-dry-run) and then a [real migration](#performing-a-real-syn2mas-migration)."

  438. msgstr ""

  439. 

  440. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:342

  441. msgid "Configuring syn2mas"

  442. msgstr ""

  443. 

  444. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:344

  445. msgid "If you're using [OIDC with Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on), you will need to [Configuring upstream OIDC provider mapping for syn2mas](#configuring-upstream-oidc-provider-mapping-for-syn2mas)."

  446. msgstr ""

  447. 

  448. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:346

  449. msgid "If you only have local (non-OIDC) users in your Synapse database, you can likely run `syn2mas` as-is (without doing additional configuration changes)."

  450. msgstr ""

  451. 

  452. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:348

  453. msgid "When you're done with potentially configuring `syn2mas`, proceed to doing a [dry-run](#performing-a-syn2mas-dry-run) and then a [real migration](#performing-a-real-syn2mas-migration)."

  454. msgstr ""

  455. 

  456. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:350

  457. msgid "Configuring upstream OIDC provider mapping for syn2mas"

  458. msgstr ""

  459. 

  460. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:352

  461. msgid "If you have existing OIDC users in your Synapse user database (which will be the case if when using [OIDC with Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on)), you may need to pass an additional `--upstreamProviderMapping` argument to the `syn2mas` tool to tell it which provider (on the Synapse side) maps to which other provider on the MAS side."

  462. msgstr ""

  463. 

  464. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:354

  465. msgid "If you don't do this, `syn2mas` would report errors like this one:"

  466. msgstr ""

  467. 

  468. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:356

  469. msgid "[FATAL] migrate - [Failed to import external id 4264b0f0-4f11-4ddd-aedb-b500e4d07c25 with oidc-keycloak for user @alice:example.com: Error: Unknown upstream provider oidc-keycloak]"

  470. msgstr ""

  471. 

  472. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:358

  473. msgid "Below is an example situation and a guide for how to solve it."

  474. msgstr ""

  475. 

  476. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:360

  477. msgid "If in `matrix_synapse_oidc_providers` your provider `idp_id` is (was) named `keycloak`, in the Synapse database users would be associated with the `oidc-keycloak` provider (note the `oidc-` prefix that was added automatically by Synapse to your `idp_id` value)."

  478. msgstr ""

  479. 

  480. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:362

  481. msgid "The same OIDC provider may have an `id` of `01HFVBY12TMNTYTBV8W921M5FA` on the MAS side, as defined in `matrix_authentication_service_config_upstream_oauth2_providers` (see the [Upstream OAuth2 configuration](#upstream-oauth2-configuration) section above)."

  482. msgstr ""

  483. 

  484. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:364

  485. msgid "To tell `syn2mas` how the Synapse-configured OIDC provider maps to the new MAS-configured OIDC provider, add this additional configuration to your `vars.yml` file:"

  486. msgstr ""

  487. 

  488. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:373

  489. msgid "Performing a syn2mas dry-run"

  490. msgstr ""

  491. 

  492. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:375

  493. msgid "Having [configured syn2mas](#configuring-syn2mas), we recommend doing a [dry-run](https://en.wikipedia.org/wiki/Dry_run_(testing)) first to verify that everything will work out as expected."

  494. msgstr ""

  495. 

  496. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:377

  497. msgid "A dry-run would not cause downtime, because it avoids stopping Synapse."

  498. msgstr ""

  499. 

  500. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:379

  501. msgid "To perform a dry-run, run:"

  502. msgstr ""

  503. 

  504. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:385

  505. msgid "Observe the command output (especially the last line of the the syn2mas output). If you are confident that the migration will work out as expected, you can proceed with a [real migration](#performing-a-real-syn2mas-migration)."

  506. msgstr ""

  507. 

  508. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:387

  509. msgid "Performing a real syn2mas migration"

  510. msgstr ""

  511. 

  512. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:389

  513. msgid "Before performing a real migration make sure:"

  514. msgstr ""

  515. 

  516. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:391

  517. msgid "you've familiarized yourself with the [expectations](#expectations)"

  518. msgstr ""

  519. 

  520. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:393

  521. msgid "you've performed a Postgres backup, just in case"

  522. msgstr ""

  523. 

  524. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:395

  525. msgid "you're aware of the irreversibility of the migration process without disruption after users have created new login sessions via the new MAS setup"

  526. msgstr ""

  527. 

  528. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:397

  529. msgid "you've [configured syn2mas](#configuring-syn2mas), especially if you've used [OIDC with Synapse](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on)"

  530. msgstr ""

  531. 

  532. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:399

  533. msgid "you've performed a [syn2mas dry-run](#performing-a-syn2mas-dry-run) and don't see any issues in its output"

  534. msgstr ""

  535. 

  536. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:401

  537. msgid "To perform a real migration, run the `matrix-authentication-service-mas-cli-syn2mas` tag **without** the `matrix_authentication_service_syn2mas_migrate_dry_run` variable:"

  538. msgstr ""

  539. 

  540. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:407

  541. msgid "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\")."

  542. msgstr ""

  543. 

  544. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:409

  545. msgid "Verify that Matrix Authentication Service is installed correctly"

  546. msgstr ""

  547. 

  548. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:411

  549. msgid "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."

  550. msgstr ""

  551. 

  552. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:413

  553. msgid "You can do it:"

  554. msgstr ""

  555. 

  556. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:415

  557. msgid "either via the Ansible playbook's `matrix-authentication-service-mas-cli-doctor` tag: `just run-tags matrix-authentication-service-mas-cli-doctor`"

  558. msgstr ""

  559. 

  560. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:417

  561. msgid "or by running the `mas-cli` script on the server (which invokes the `mas-cli` tool inside a container): `/matrix/matrix-authentication-service/bin/mas-cli doctor`"

  562. msgstr ""

  563. 

  564. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:419

  565. msgid "If successful, you should see some output that looks like this:"

  566. msgstr ""

  567. 

  568. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:431

  569. msgid "Management"

  570. msgstr ""

  571. 

  572. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:433

  573. msgid "You can use the [`mas-cli` command-line tool](https://element-hq.github.io/matrix-authentication-service/reference/cli/index.html) (exposed via the `/matrix/matrix-authentication-service/bin/mas-cli` script) to perform administrative tasks against MAS."

  574. msgstr ""

  575. 

  576. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:435

  577. msgid "This documentation page already mentions:"

  578. msgstr ""

  579. 

  580. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:437

  581. msgid "the `mas-cli doctor` sub-command in the [Verify that Matrix Authentication Service is installed correctly](#verify-that-matrix-authentication-service-is-installed-correctly) section, which you can run via the CLI and via the Ansible playbook's `matrix-authentication-service-mas-cli-doctor` tag"

  582. msgstr ""

  583. 

  584. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:439

  585. msgid "the `mas-cli manage register-user` sub-command in the [Registering users](./registering-users.md) documentation"

  586. msgstr ""

  587. 

  588. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:441

  589. msgid "There are other sub-commands available. Run `/matrix/matrix-authentication-service/bin/mas-cli` to get an overview."

  590. msgstr ""

  591. 

  592. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:443

  593. msgid "User registration"

  594. msgstr ""

  595. 

  596. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:445

  597. msgid "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))."

  598. msgstr ""

  599. 

  600. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:447

  601. msgid "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)."

  602. msgstr ""

  603. 

  604. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:449

  605. msgid "Working around email deliverability issues"

  606. msgstr ""

  607. 

  608. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:451

  609. msgid "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."

  610. msgstr ""

  611. 

  612. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:453

  613. msgid "Matrix Authentication Service attempts to verify email addresses by sending a verification email to the address specified by the user whenever they log in to an account without a verified email address."

  614. msgstr ""

  615. 

  616. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:455

  617. msgid "If email delivery is not working, **you can retrieve the email configuration code from the Matrix Authentication Service's logs** (`journalctl -fu matrix-authentication-service`)."

  618. msgstr ""

  619. 

  620. #: ../../../docs/configuring-playbook-matrix-authentication-service.md:457

  621. msgid "Alternatively, you can use the [`mas-cli` management tool](#management) to manually verify email addresses for users. Example: `/matrix/matrix-authentication-service/bin/mas-cli manage verify-email some.username email@example.com`"

  622. msgstr ""