homeserver.yaml.j2 89.4 KB
Newer Older
1001
#    path: '/foo'
1002
#
1003
1004
#  # blacklist any URL with a literal IPv4 address
#  - netloc: '^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$'
1005
1006

# The largest allowed URL preview spidering size in bytes
1007
1008
#
#max_spider_size: 10M
1009

1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
# A list of values for the Accept-Language HTTP header used when
# downloading webpages during URL preview generation. This allows
# Synapse to specify the preferred languages that URL previews should
# be in when communicating with remote servers.
#
# Each value is a IETF language tag; a 2-3 letter identifier for a
# language, optionally followed by subtags separated by '-', specifying
# a country or region variant.
#
# Multiple values can be provided, and a weight can be added to each by
# using quality value syntax (;q=). '*' translates to any language.
#
# Defaults to "en".
#
# Example:
#
# url_preview_accept_language:
#   - en-UK
#   - en-US;q=0.9
#   - fr;q=0.8
#   - *;q=0.7
#
url_preview_accept_language:
#   - en

1035
1036

## Captcha ##
1037
# See docs/CAPTCHA_SETUP.md for full details of configuring this.
1038

1039
1040
# This homeserver's ReCAPTCHA public key. Must be specified if
# enable_registration_captcha is enabled.
1041
1042
#
#recaptcha_public_key: "YOUR_PUBLIC_KEY"
1043

1044
1045
# This homeserver's ReCAPTCHA private key. Must be specified if
# enable_registration_captcha is enabled.
1046
1047
#
#recaptcha_private_key: "YOUR_PRIVATE_KEY"
1048

1049
# Uncomment to enable ReCaptcha checks when registering, preventing signup
1050
# unless a captcha is answered. Requires a valid ReCaptcha
1051
# public/private key. Defaults to 'false'.
1052
#
1053
#enable_registration_captcha: true
1054
1055

# The API endpoint to use for verifying m.login.recaptcha responses.
1056
# Defaults to "https://www.recaptcha.net/recaptcha/api/siteverify".
1057
#
1058
#recaptcha_siteverify_api: "https://my.recaptcha.site"
1059
1060


1061
## TURN ##
1062
1063

# The public URIs of the TURN server to give to clients
1064
#
1065
1066
1067
1068
1069
turn_uris:
  - "turns:{{ matrix_domain }}?transport=udp"
  - "turns:{{ matrix_domain }}?transport=tcp"
  - "turn:{{ matrix_domain }}?transport=udp"
  - "turn:{{ matrix_domain }}?transport=tcp"
1070
1071

# The shared secret used to compute passwords for the TURN server
1072
#
1073
turn_shared_secret: "{{ vault_matrix_secrets[matrix_server_name].turn_shared_secret }}"
1074
1075
1076

# The Username and password if the TURN server needs them and
# does not use a token
1077
#
1078
1079
1080
1081
#turn_username: "TURNSERVER_USERNAME"
#turn_password: "TURNSERVER_PASSWORD"

# How long generated TURN credentials last
1082
1083
#
#turn_user_lifetime: 1h
1084

1085
1086
1087
1088
1089
# Whether guests should be allowed to use the TURN server.
# This defaults to True, otherwise VoIP will be unreliable for guests.
# However, it does introduce a slight security risk as it allows users to
# connect to arbitrary endpoints without having first signed up for a
# valid account (e.g. by passing a CAPTCHA).
1090
#
1091
#turn_allow_guests: true
1092

1093
1094

## Registration ##
1095
1096
1097
#
# Registration can be rate-limited using the parameters in the "Ratelimiting"
# section of this file.
1098
1099

# Enable registration for new users.
1100
1101
#
#enable_registration: false
1102

1103
1104
1105
# Optional account validity configuration. This allows for accounts to be denied
# any request after a given period.
#
1106
1107
1108
1109
1110
1111
# Once this feature is enabled, Synapse will look for registered users without an
# expiration date at startup and will add one to every account it found using the
# current settings at that time.
# This means that, if a validity period is set, and Synapse is restarted (it will
# then derive an expiration date from the current validity period), and some time
# after that the validity period changes and Synapse is restarted, the users'
1112
1113
1114
# expiration dates won't be updated unless their account is manually renewed. This
# date will be randomly selected within a range [now + period - d ; now + period],
# where d is equal to 10% of the validity period.
1115
#
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
account_validity:
  # The account validity feature is disabled by default. Uncomment the
  # following line to enable it.
  #
  #enabled: true

  # The period after which an account is valid after its registration. When
  # renewing the account, its validity period will be extended by this amount
  # of time. This parameter is required when using the account validity
  # feature.
  #
  #period: 6w

  # The amount of time before an account's expiry date at which Synapse will
  # send an email to the account's email address with a renewal link. By
  # default, no such emails are sent.
  #
  # If you enable this setting, you will also need to fill out the 'email' and
  # 'public_baseurl' configuration sections.
  #
  #renew_at: 1w

  # The subject of the email sent out with the renewal link. '%(app)s' can be
  # used as a placeholder for the 'app_name' parameter from the 'email'
  # section.
  #
  # Note that the placeholder must be written '%(app)s', including the
  # trailing 's'.
  #
  # If this is not set, a default value is used.
  #
  #renew_email_subject: "Renew your %(app)s account"

  # Directory in which Synapse will try to find templates for the HTML files to
  # serve to the user when trying to renew an account. If not set, default
  # templates from within the Synapse package will be used.
  #
  #template_dir: "res/templates"

  # File within 'template_dir' giving the HTML to be displayed to the user after
  # they successfully renewed their account. If not set, default text is used.
  #
  #account_renewed_html_path: "account_renewed.html"

  # File within 'template_dir' giving the HTML to be displayed when the user
  # tries to renew an account with an invalid renewal token. If not set,
  # default text is used.
  #
  #invalid_token_html_path: "invalid_token.html"
1165

1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
# Time that a user's session remains valid for, after they log in.
#
# Note that this is not currently compatible with guest logins.
#
# Note also that this is calculated at login time: changes are not applied
# retrospectively to users who have already logged in.
#
# By default, this is infinite.
#
#session_lifetime: 24h

1177
1178
# The user must provide all of the below types of 3PID when registering.
#
1179
1180
1181
#registrations_require_3pid:
#  - email
#  - msisdn
1182

1183
1184
1185
# Explicitly disable asking for MSISDNs from the registration
# flow (overrides registrations_require_3pid if MSISDNs are set as required)
#
1186
#disable_msisdn_registration: true
1187

1188
1189
1190
# Mandate that users are only allowed to associate certain formats of
# 3PIDs with accounts on this server.
#
1191
1192
1193
1194
1195
1196
1197
#allowed_local_3pids:
#  - medium: email
#    pattern: '.*@matrix\.org'
#  - medium: email
#    pattern: '.*@vector\.im'
#  - medium: msisdn
#    pattern: '\+44'
1198

1199
1200
1201
1202
# Enable 3PIDs lookup requests to identity servers from this server.
#
#enable_3pid_lookup: true

1203
1204
1205
# If set, allows registration of standard or admin accounts by anyone who
# has the shared secret, even if registration is otherwise disabled.
#
1206
registration_shared_secret: "{{ vault_matrix_secrets[matrix_server_name].registration_shared_secret }}"
1207
1208
1209

# Set the number of bcrypt rounds used to generate password hash.
# Larger numbers increase the work factor needed to generate the hash.
1210
1211
1212
# The default number is 12 (which equates to 2^12 rounds).
# N.B. that increasing this will exponentially increase the time required
# to register or login - e.g. 24 => 2^24 rounds which will take >20 mins.
1213
1214
#
#bcrypt_rounds: 12
1215
1216
1217
1218

# Allows users to register as guests without a password/email/etc, and
# participate in rooms hosted on this server which have been made
# accessible to anonymous users.
1219
1220
#
#allow_guest_access: false
1221

1222
1223
1224
1225
1226
1227
1228
1229
# The identity server which we suggest that clients should use when users log
# in on this server.
#
# (By default, no suggestion is made, so it is left up to the client.
# This setting is ignored unless public_baseurl is also set.)
#
default_identity_server: https://matrix.org

1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
# Handle threepid (email/phone etc) registration and password resets through a set of
# *trusted* identity servers. Note that this allows the configured identity server to
# reset passwords for accounts!
#
# Be aware that if `email` is not set, and SMTP options have not been
# configured in the email config block, registration and user password resets via
# email will be globally disabled.
#
# Additionally, if `msisdn` is not set, registration and password resets via msisdn
# will be disabled regardless. This is due to Synapse currently not supporting any
# method of sending SMS messages on its own.
#
# To enable using an identity server for operations regarding a particular third-party
# identifier type, set the value to the URL of that identity server as shown in the
# examples below.
#
# Servers handling the these requests must answer the `/requestToken` endpoints defined
# by the Matrix Identity Service API specification:
# https://matrix.org/docs/spec/identity_service/latest
#
# If a delegate is specified, the config option public_baseurl must also be filled out.
#
account_threepid_delegates:
1253
    #email: https://example.com     # Delegate email sending to example.com
1254
    msisdn: https://vector.im
1255

1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
# Whether users are allowed to change their displayname after it has
# been initially set. Useful when provisioning users based on the
# contents of a third-party directory.
#
# Does not apply to server administrators. Defaults to 'true'
#
#enable_set_displayname: false

# Whether users are allowed to change their avatar after it has been
# initially set. Useful when provisioning users based on the contents
# of a third-party directory.
#
# Does not apply to server administrators. Defaults to 'true'
#
#enable_set_avatar_url: false

# Whether users can change the 3PIDs associated with their accounts
# (email address and msisdn).
#
# Defaults to 'true'
#
#enable_3pid_changes: false

1279
# Users who register on this homeserver will automatically be joined
1280
1281
1282
1283
1284
# to these rooms.
#
# By default, any room aliases included in this list will be created
# as a publicly joinable room when the first user registers for the
# homeserver. This behaviour can be customised with the settings below.
1285
#
1286
1287
auto_join_rooms:
  - "#archlinux:archlinux.org"
1288
1289
1290
1291

# Where auto_join_rooms are specified, setting this flag ensures that the
# the rooms exist by creating them when the first user on the
# homeserver registers.
1292
1293
1294
1295
1296
#
# By default the auto-created rooms are publicly joinable from any federated
# server. Use the autocreate_auto_join_rooms_federated and
# autocreate_auto_join_room_preset settings below to customise this behaviour.
#
1297
1298
# Setting to false means that if the rooms are not manually created,
# users cannot be auto-joined since they do not exist.
1299
#
1300
1301
1302
# Defaults to true. Uncomment the following line to disable automatically
# creating auto-join rooms.
#
1303
autocreate_auto_join_rooms: false
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346

# Whether the auto_join_rooms that are auto-created are available via
# federation. Only has an effect if autocreate_auto_join_rooms is true.
#
# Note that whether a room is federated cannot be modified after
# creation.
#
# Defaults to true: the room will be joinable from other servers.
# Uncomment the following to prevent users from other homeservers from
# joining these rooms.
#
#autocreate_auto_join_rooms_federated: false

# The room preset to use when auto-creating one of auto_join_rooms. Only has an
# effect if autocreate_auto_join_rooms is true.
#
# This can be one of "public_chat", "private_chat", or "trusted_private_chat".
# If a value of "private_chat" or "trusted_private_chat" is used then
# auto_join_mxid_localpart must also be configured.
#
# Defaults to "public_chat", meaning that the room is joinable by anyone, including
# federated servers if autocreate_auto_join_rooms_federated is true (the default).
# Uncomment the following to require an invitation to join these rooms.
#
#autocreate_auto_join_room_preset: private_chat

# The local part of the user id which is used to create auto_join_rooms if
# autocreate_auto_join_rooms is true. If this is not provided then the
# initial user account that registers will be used to create the rooms.
#
# The user id is also used to invite new users to any auto-join rooms which
# are set to invite-only.
#
# It *must* be configured if autocreate_auto_join_room_preset is set to
# "private_chat" or "trusted_private_chat".
#
# Note that this must be specified in order for new users to be correctly
# invited to any auto-join rooms which have been set to invite-only (either
# at the time of creation or subsequently).
#
# Note that, if the room already exists, this user must be joined and
# have the appropriate permissions to invite new members.
#
1347
auto_join_mxid_localpart: heftig
1348

1349
1350
1351
1352
1353
# When auto_join_rooms is specified, setting this flag to false prevents
# guest accounts from being automatically joined to the rooms.
#
# Defaults to true.
#
1354
auto_join_rooms_for_guests: false
1355

1356
1357
1358
1359

## Metrics ###

# Enable collection and rendering of performance metrics
1360
#
1361
#enable_metrics: false
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372

# Enable sentry integration
# NOTE: While attempts are made to ensure that the logs don't contain
# any sensitive information, this cannot be guaranteed. By enabling
# this option the sentry server may therefore receive sensitive
# information, and it in turn may then diseminate sensitive information
# through insecure notification channels if so configured.
#
#sentry:
#    dsn: "..."

1373
1374
1375
1376
# Flags to enable Prometheus metrics which are not suitable to be
# enabled by default, either for performance reasons or limited use.
#
metrics_flags:
1377
    # Publish synapse_federation_known_servers, a gauge of the number of
1378
1379
1380
1381
1382
    # servers this homeserver knows about, including itself. May cause
    # performance problems on large homeservers.
    #
    #known_servers: true

1383
# Whether or not to report anonymized homeserver usage statistics.
1384
#
1385
report_stats: true
1386

1387
1388
1389
1390
1391
# The endpoint to report the anonymized homeserver usage statistics to.
# Defaults to https://matrix.org/report-usage-stats/push
#
#report_stats_endpoint: https://example.com/report-usage-stats/push

1392
1393
1394
1395

## API Configuration ##

# A list of event types that will be included in the room_invite_state
1396
1397
1398
1399
1400
1401
1402
#
#room_invite_state_types:
#  - "m.room.join_rules"
#  - "m.room.canonical_alias"
#  - "m.room.avatar"
#  - "m.room.encryption"
#  - "m.room.name"
1403
1404


1405
1406
1407
# A list of application service config files to use
#
app_service_config_files:
1408
  - /etc/synapse/appservice-registration-irc.yaml
1409

1410
# Uncomment to enable tracking of application service IP addresses. Implicitly
1411
# enables MAU tracking for application service users.
1412
#
1413
#track_appservice_user_ips: true
1414

1415

1416
1417
1418
# a secret which is used to sign access tokens. If none is specified,
# the registration_shared_secret is used, if one is given; otherwise,
# a secret key is derived from the signing key.
1419
#
1420
macaroon_secret_key: "{{ vault_matrix_secrets[matrix_server_name].macaroon_secret_key }}"
1421

1422
# a secret which is used to calculate HMACs for form values, to stop
1423
1424
# falsification of values. Must be specified for the User Consent
# forms to work.
1425
#
1426
1427
form_secret: "{{ vault_matrix_secrets[matrix_server_name].form_secret }}"

1428
1429
1430
## Signing Keys ##

# Path to the signing key to sign messages with
1431
#
1432
signing_key_path: "/etc/synapse/{{ matrix_server_name }}.signing.key"
1433
1434

# The keys that the server used to sign messages with but won't use
1435
# to sign new messages.
1436
#
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
old_signing_keys:
  # For each key, `key` should be the base64-encoded public key, and
  # `expired_ts`should be the time (in milliseconds since the unix epoch) that
  # it was last used.
  #
  # It is possible to build an entry from an old signing.key file using the
  # `export_signing_key` script which is provided with synapse.
  #
  # For example:
  #
  #"ed25519:id": { key: "base64string", expired_ts: 123456789123 }
1448
1449
1450
1451
1452

# How long key response published by this server is valid for.
# Used to set the valid_until_ts in /key/v2 APIs.
# Determines how quickly servers will query to check which keys
# are still valid.
1453
1454
#
#key_refresh_interval: 1d
1455
1456

# The trusted servers to download signing keys from.
1457
#
1458
1459
1460
1461
1462
1463
1464
1465
1466
# When we need to fetch a signing key, each server is tried in parallel.
#
# Normally, the connection to the key server is validated via TLS certificates.
# Additional security can be provided by configuring a `verify key`, which
# will make synapse check that the response is signed by that key.
#
# This setting supercedes an older setting named `perspectives`. The old format
# is still supported for backwards-compatibility, but it is deprecated.
#
1467
1468
1469
1470
# 'trusted_key_servers' defaults to matrix.org, but using it will generate a
# warning on start-up. To suppress this warning, set
# 'suppress_key_server_warning' to true.
#
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
# Options for each entry in the list include:
#
#    server_name: the name of the server. required.
#
#    verify_keys: an optional map from key id to base64-encoded public key.
#       If specified, we will check that the response is signed by at least
#       one of the given keys.
#
#    accept_keys_insecurely: a boolean. Normally, if `verify_keys` is unset,
#       and federation_verify_certificates is not `true`, synapse will refuse
#       to start, because this would allow anyone who can spoof DNS responses
#       to masquerade as the trusted key server. If you know what you are doing
#       and are sure that your network environment provides a secure connection
#       to the key server, you can set this to `true` to override this
#       behaviour.
#
# An example configuration might look like:
#
#trusted_key_servers:
#  - server_name: "my_trusted_server.example.com"
#    verify_keys:
#      "ed25519:auto": "abcdefghijklmnopqrstuvwxyzabcdefghijklmopqr"
#  - server_name: "my_other_trusted_server.example.com"
#
1495
1496
1497
1498
1499
trusted_key_servers:
  - server_name: "matrix.org"

# Uncomment the following to disable the warning that is emitted when the
# trusted_key_servers include 'matrix.org'. See above.
1500
#
1501
1502
1503
1504
1505
1506
1507
1508
suppress_key_server_warning: true

# The signing keys to use when acting as a trusted key server. If not specified
# defaults to the server signing key.
#
# Can contain multiple keys, one per line.
#
#key_server_signing_keys_path: "key_server_signing_keys.key"
1509
1510


1511
1512
## Single sign-on integration ##

1513
1514
# The following settings can be used to make Synapse use a single sign-on
# provider for authentication, instead of its internal password database.
1515
#
1516
# You will probably also want to set the following options to `false` to
1517
1518
1519
# disable the regular login/registration flows:
#   * enable_registration
#   * password_config.enabled
1520
#
1521
1522
# You will also want to investigate the settings under the "sso" configuration
# section below.
1523
1524
1525
1526
1527

# Enable SAML2 for registration and login. Uses pysaml2.
#
# At least one of `sp_config` or `config_path` must be set in this section to
# enable SAML login.
1528
#
1529
1530
1531
1532
1533
1534
# Once SAML support is enabled, a metadata file will be exposed at
# https://<server>:<port>/_matrix/saml2/metadata.xml, which you may be able to
# use to configure your SAML IdP with. Alternatively, you can manually configure
# the IdP to use an ACS location of
# https://<server>:<port>/_matrix/saml2/authn_response.
#
1535
1536
1537
1538
1539
1540
1541
1542
saml2_config:
  # `sp_config` is the configuration for the pysaml2 Service Provider.
  # See pysaml2 docs for format of config.
  #
  # Default values will be used for the 'entityid' and 'service' settings,
  # so it is not normally necessary to specify them unless you need to
  # override them.
  #
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
  sp_config:
    # Point this to the IdP's metadata. You must provide either a local
    # file via the `local` attribute or (preferably) a URL via the
    # `remote` attribute.
    #
    #metadata:
    #  local: ["saml2/idp.xml"]
    #  remote:
    #    - url: https://our_idp/metadata.xml

    # By default, the user has to go to our login page first. If you'd like
    # to allow IdP-initiated login, set 'allow_unsolicited: true' in a
    # 'service.sp' section:
    #
    #service:
    #  sp:
    #    allow_unsolicited: true

    # The examples below are just used to generate our metadata xml, and you
    # may well not need them, depending on your setup. Alternatively you
    # may need a whole lot more detail - see the pysaml2 docs!

    #description: ["My awesome SP", "en"]
    #name: ["Test SP", "en"]

    #ui_info:
    #  display_name:
    #    - lang: en
    #      text: "Display Name is the descriptive name of your service."
    #  description:
    #    - lang: en
    #      text: "Description should be a short paragraph explaining the purpose of the service."
    #  information_url:
    #    - lang: en
    #      text: "https://example.com/terms-of-service"
    #  privacy_statement_url:
    #    - lang: en
    #      text: "https://example.com/privacy-policy"
    #  keywords:
    #    - lang: en
    #      text: ["Matrix", "Element"]
    #  logo:
    #    - lang: en
    #      text: "https://example.com/logo.svg"
    #      width: "200"
    #      height: "80"

    #organization:
    #  name: Example com
    #  display_name:
    #    - ["Example co", "en"]
    #  url: "http://example.com"

    #contact_person:
    #  - given_name: Bob
    #    sur_name: "the Sysadmin"
    #    email_address": ["admin@example.com"]
    #    contact_type": technical
1601
1602
1603
1604
1605
1606

  # Instead of putting the config inline as above, you can specify a
  # separate pysaml2 configuration file:
  #
  #config_path: "CONFDIR/sp_conf.py"

1607
  # The lifetime of a SAML session. This defines how long a user has to
1608
  # complete the authentication process, if allow_unsolicited is unset.
1609
  # The default is 15 minutes.
1610
1611
1612
  #
  #saml_session_lifetime: 5m

1613
1614
  # An external module can be provided here as a custom solution to
  # mapping attributes returned from a saml provider onto a matrix user.
1615
  #
1616
1617
1618
1619
  user_mapping_provider:
    # The custom module's class. Uncomment to use a custom module.
    #
    #module: mapping_provider.SamlMappingProvider
1620

1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
    # Custom configuration values for the module. Below options are
    # intended for the built-in provider, they should be changed if
    # using a custom module. This section will be passed as a Python
    # dictionary to the module's `parse_config` method.
    #
    config:
      # The SAML attribute (after mapping via the attribute maps) to use
      # to derive the Matrix ID from. 'uid' by default.
      #
      # Note: This used to be configured by the
      # saml2_config.mxid_source_attribute option. If that is still
      # defined, its value will be used instead.
      #
      #mxid_source_attribute: displayName

      # The mapping system to use for mapping the saml attribute onto a
      # matrix ID.
      #
      # Options include:
      #  * 'hexencode' (which maps unpermitted characters to '=xx')
      #  * 'dotreplace' (which replaces unpermitted characters with
      #     '.').
      # The default is 'hexencode'.
      #
      # Note: This used to be configured by the
      # saml2_config.mxid_mapping option. If that is still defined, its
      # value will be used instead.
      #
      #mxid_mapping: dotreplace

  # In previous versions of synapse, the mapping from SAML attribute to
  # MXID was always calculated dynamically rather than stored in a
  # table. For backwards- compatibility, we will look for user_ids
  # matching such a pattern before creating a new account.
1655
1656
  #
  # This setting controls the SAML attribute which will be used for this
1657
1658
  # backwards-compatibility lookup. Typically it should be 'uid', but if
  # the attribute maps are changed, it may be necessary to change it.
1659
1660
1661
1662
  #
  # The default is 'uid'.
  #
  #grandfathered_mxid_source_attribute: upn
1663

1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
  # It is possible to configure Synapse to only allow logins if SAML attributes
  # match particular values. The requirements can be listed under
  # `attribute_requirements` as shown below. All of the listed attributes must
  # match for the login to be permitted.
  #
  #attribute_requirements:
  #  - attribute: userGroup
  #    value: "staff"
  #  - attribute: department
  #    value: "sales"

1675

1676
# Enable OpenID Connect (OIDC) / OAuth 2.0 for registration and login.
1677
#
1678
1679
# See https://github.com/matrix-org/synapse/blob/master/docs/openid.md
# for some example configurations.
1680
1681
#
oidc_config:
1682
1683
1684
  # Uncomment the following to enable authorization against an OpenID Connect
  # server. Defaults to false.
  #
1685
  #enabled: true
1686

1687
1688
1689
1690
  # Uncomment the following to disable use of the OIDC discovery mechanism to
  # discover endpoints. Defaults to true.
  #
  #discover: false
1691

1692
1693
1694
1695
1696
  # the OIDC issuer. Used to validate tokens and (if discovery is enabled) to
  # discover the provider's endpoints.
  #
  # Required if 'enabled' is true.
  #
1697
  #issuer: "https://accounts.example.com/"
1698

1699
1700
1701
1702
  # oauth2 client id to use.
  #
  # Required if 'enabled' is true.
  #
1703
  #client_id: "provided-by-your-issuer"
1704

1705
1706
1707
1708
  # oauth2 client secret to use.
  #
  # Required if 'enabled' is true.
  #
1709
  #client_secret: "provided-by-your-issuer"
1710

1711
1712
1713
1714
1715
  # auth method to use when exchanging the token.
  # Valid values are 'client_secret_basic' (default), 'client_secret_post' and
  # 'none'.
  #
  #client_auth_method: client_secret_post
1716

1717
1718
1719
  # list of scopes to request. This should normally include the "openid" scope.
  # Defaults to ["openid"].
  #
1720
  #scopes: ["openid", "profile"]
1721

1722
1723
1724
  # the oauth2 authorization endpoint. Required if provider discovery is disabled.
  #
  #authorization_endpoint: "https://accounts.example.com/oauth2/auth"
1725

1726
1727
1728
  # the oauth2 token endpoint. Required if provider discovery is disabled.
  #
  #token_endpoint: "https://accounts.example.com/oauth2/token"
1729

1730
1731
1732
1733
  # the OIDC userinfo endpoint. Required if discovery is disabled and the
  # "openid" scope is not requested.
  #
  #userinfo_endpoint: "https://accounts.example.com/userinfo"
1734

1735
1736
1737
1738
  # URI where to fetch the JWKS. Required if discovery is disabled and the
  # "openid" scope is used.
  #
  #jwks_uri: "https://accounts.example.com/.well-known/jwks.json"
1739

1740
1741
1742
1743
1744
1745
1746
  # Uncomment to skip metadata verification. Defaults to false.
  #
  # Use this if you are connecting to a provider that is not OpenID Connect
  # compliant.
  # Avoid this in production.
  #
  #skip_verification: true
1747

1748
1749
1750
1751
1752
1753
1754
1755
  # Whether to fetch the user profile from the userinfo endpoint. Valid
  # values are: "auto" or "userinfo_endpoint".
  #
  # Defaults to "auto", which fetches the userinfo endpoint if "openid" is included
  # in `scopes`. Uncomment the following to always fetch the userinfo endpoint.
  #
  #user_profile_method: "userinfo_endpoint"

1756
1757
1758
1759
1760
  # Uncomment to allow a user logging in via OIDC to match a pre-existing account instead
  # of failing. This could be used if switching from password logins to OIDC. Defaults to false.
  #
  allow_existing_users: true

1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
  # An external module can be provided here as a custom solution to mapping
  # attributes returned from a OIDC provider onto a matrix user.
  #
  user_mapping_provider:
    # The custom module's class. Uncomment to use a custom module.
    # Default is 'synapse.handlers.oidc_handler.JinjaOidcMappingProvider'.
    #
    # See https://github.com/matrix-org/synapse/blob/master/docs/sso_mapping_providers.md#openid-mapping-providers
    # for information on implementing a custom mapping provider.
    #
    #module: mapping_provider.OidcMappingProvider
1772

1773
1774
1775
1776
1777
1778
    # Custom configuration values for the module. This section will be passed as
    # a Python dictionary to the user mapping provider module's `parse_config`
    # method.
    #
    # The examples below are intended for the default provider: they should be
    # changed if using a custom provider.
1779
    #
1780
1781
1782
    config:
      # name of the claim containing a unique identifier for the user.
      # Defaults to `sub`, which OpenID Connect compliant providers should provide.
1783
      #
1784
      #subject_claim: "sub"
1785

1786
      # Jinja2 template for the localpart of the MXID.
1787
      #
1788
1789
1790
      # When rendering, this template is given the following variables:
      #   * user: The claims returned by the UserInfo Endpoint and/or in the ID
      #     Token
1791
      #
1792
1793
1794
      # This must be configured if using the default mapping provider.
      #
      localpart_template: "{{ '{{ user.preferred_username }}' }}"
1795

1796
1797
1798
1799
      # Jinja2 template for the display name to set on first login.
      #
      # If unset, no displayname will be set.
      #
1800
      #display_name_template: "{{ '{{ user.given_name }} {{ user.last_name }}' }}"
1801

1802
1803
1804
1805
1806
1807
      # Jinja2 templates for extra attributes to send back to the client during
      # login.
      #
      # Note that these are non-standard and clients will ignore them without modifications.
      #
      #extra_attributes:
1808
        #birthdate: "{{ '{{ user.birthdate }}' }}"
1809

1810

1811

1812
# Enable Central Authentication Service (CAS) for registration and login.
1813
#
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
cas_config:
  # Uncomment the following to enable authorization against a CAS server.
  # Defaults to false.
  #
  #enabled: true

  # The URL of the CAS authorization endpoint.
  #
  #server_url: "https://cas-server.com"

  # The public URL of the homeserver.
  #
  #service_url: "https://homeserver.domain.com:8448"

  # The attribute of the CAS response to use as the display name.
  #
  # If unset, no displayname will be set.
  #
  #displayname_attribute: name

  # It is possible to configure Synapse to only allow logins if CAS attributes
  # match particular values. All of the keys in the mapping below must exist
  # and the values must match the given value. Alternately if the given value
  # is None then any value is allowed (the attribute just must exist).
  # All of the listed attributes must match for the login to be permitted.
  #
  #required_attributes:
  #  userGroup: "staff"
  #  department: None
1843
1844


1845
1846
# Additional settings to use with single-sign on systems such as OpenID Connect,
# SAML2 and CAS.
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
#
sso:
    # A list of client URLs which are whitelisted so that the user does not
    # have to confirm giving access to their account to the URL. Any client
    # whose URL starts with an entry in the following list will not be subject
    # to an additional confirmation step after the SSO login is completed.
    #
    # WARNING: An entry such as "https://my.client" is insecure, because it
    # will also match "https://my.client.evil.site", exposing your users to
    # phishing attacks from evil.site. To avoid this, include a slash after the
    # hostname: "https://my.client/".
    #
1859
1860
1861
1862
    # If public_baseurl is set, then the login fallback page (used by clients
    # that don't natively support the required login flows) is whitelisted in
    # addition to any URLs in this list.
    #
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
    # By default, this list is empty.
    #
    #client_whitelist:
    #  - https://riot.im/develop
    #  - https://my.custom.client/

    # Directory in which Synapse will try to find the template files below.
    # If not set, default templates from within the Synapse package will be used.
    #
    # DO NOT UNCOMMENT THIS SETTING unless you want to customise the templates.
    # If you *do* uncomment it, you will need to make sure that all the templates
    # below are in the directory.
    #
    # Synapse will look for the following templates in this directory:
    #
    # * HTML page for a confirmation step before redirecting back to the client
    #   with the login token: 'sso_redirect_confirm.html'.
    #
    #   When rendering, this template is given three variables:
    #     * redirect_url: the URL the user is about to be redirected to. Needs
    #                     manual escaping (see
    #                     https://jinja.palletsprojects.com/en/2.11.x/templates/#html-escaping).
    #
    #     * display_url: the same as `redirect_url`, but with the query
    #                    parameters stripped. The intention is to have a
    #                    human-readable URL to show to users, not to use it as
    #                    the final address to redirect to. Needs manual escaping
    #                    (see https://jinja.palletsprojects.com/en/2.11.x/templates/#html-escaping).
    #
    #     * server_name: the homeserver's name.
    #
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
    # * HTML page which notifies the user that they are authenticating to confirm
    #   an operation on their account during the user interactive authentication
    #   process: 'sso_auth_confirm.html'.
    #
    #   When rendering, this template is given the following variables:
    #     * redirect_url: the URL the user is about to be redirected to. Needs
    #                     manual escaping (see
    #                     https://jinja.palletsprojects.com/en/2.11.x/templates/#html-escaping).
    #
    #     * description: the operation which the user is being asked to confirm
    #
    # * HTML page shown after a successful user interactive authentication session:
    #   'sso_auth_success.html'.
    #
    #   Note that this page must include the JavaScript which notifies of a successful authentication
    #   (see https://matrix.org/docs/spec/client_server/r0.6.0#fallback).
    #
    #   This template has no additional variables.
    #
    # * HTML page shown during single sign-on if a deactivated user (according to Synapse's database)
    #   attempts to login: 'sso_account_deactivated.html'.
    #
    #   This template has no additional variables.
    #
    # * HTML page to display to users if something goes wrong during the
    #   OpenID Connect authentication process: 'sso_error.html'.
    #
    #   When rendering, this template is given two variables:
    #     * error: the technical name of the error
    #     * error_description: a human-readable message for the error
    #
1925
1926
1927
1928
1929
1930
    # You can see the default templates at:
    # https://github.com/matrix-org/synapse/tree/master/synapse/res/templates
    #
    #template_dir: "res/templates"


1931
1932
1933
1934
1935
1936
1937
# JSON web token integration. The following settings can be used to make
# Synapse JSON web tokens for authentication, instead of its internal
# password database.
#
# Each JSON Web Token needs to contain a "sub" (subject) claim, which is
# used as the localpart of the mxid.
#
1938
1939
1940
# Additionally, the expiration time ("exp"), not before time ("nbf"),
# and issued at ("iat") claims are validated if present.
#
1941
# Note that this is a non-standard login type and client support is
1942
# expected to be non-existent.
1943
1944
#
# See https://github.com/matrix-org/synapse/blob/master/docs/jwt.md.
1945
#
1946
#jwt_config:
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
    # Uncomment the following to enable authorization using JSON web
    # tokens. Defaults to false.
    #
    #enabled: true

    # This is either the private shared secret or the public key used to
    # decode the contents of the JSON web token.
    #
    # Required if 'enabled' is true.
    #
    #secret: "provided-by-your-issuer"

    # The algorithm used to sign the JSON web token.
    #
    # Supported algorithms are listed at
    # https://pyjwt.readthedocs.io/en/latest/algorithms.html
    #
    # Required if 'enabled' is true.
    #
    #algorithm: "provided-by-your-issuer"
1967

1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
    # The issuer to validate the "iss" claim against.
    #
    # Optional, if provided the "iss" claim will be required and
    # validated for all JSON web tokens.
    #
    #issuer: "provided-by-your-issuer"

    # A list of audiences to validate the "aud" claim against.
    #
    # Optional, if provided the "aud" claim will be required and
    # validated for all JSON web tokens.
    #
    # Note that if the "aud" claim is included in a JSON web token then
    # validation will fail without configuring audiences.
    #
    #audiences:
    #    - "provided-by-your-issuer"

1986
1987

password_config:
1988
1989
1990
1991
   # Uncomment to disable password login
   #
   #enabled: false

1992
1993
1994
1995
1996
1997
   # Uncomment to disable authentication against the local password
   # database. This is ignored if `enabled` is false, and is only useful
   # if you have other password_providers.
   #
   #localdb_enabled: false

1998
1999
   # Uncomment and change to a secret random string for extra security.
   # DO NOT CHANGE THIS AFTER INITIAL SETUP!
2000
   #
For faster browsing, not all history is shown. View entire blame