config_documentation.md

---
Config option: `registration_requires_token`

Require users to submit a token during registration.
Tokens can be managed using the admin [API](../administration/admin_api/registration_tokens.md).
Note that `enable_registration` must be set to true.
Disabling this option will not delete any tokens previously generated.
Defaults to false. Set to true to enable.  

Example configuration:
```yaml
registration_requires_token: true
```
---
Config option: `registration_shared_secret`

If set, allows registration of standard or admin accounts by anyone who
has the shared secret, even if registration is otherwise disabled.

Example configuration:
```yaml
registration_shared_secret: <PRIVATE STRING>
```
---
Config option: `bcrypt_rounds`

Set the number of bcrypt rounds used to generate password hash.
Larger numbers increase the work factor needed to generate the hash.
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.
Example configuration:
```yaml
bcrypt_rounds: 14
```
---
Config option: `allow_guest_access`

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. Defaults to false.

Example configuration:
```yaml
allow_guest_access: true
```
---
Config option: `default_identity_server`

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 explicitly set.)

Example configuration:
```yaml
default_identity_server: https://matrix.org
```
---
Config option: `account_threepid_delegates`

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, and users will not be able to associate an msisdn
identifier to their account. 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).

Example configuration:
```yaml
account_threepid_delegates:
    email: https://example.com     # Delegate email sending to example.com
    msisdn: http://localhost:8090  # Delegate SMS sending to this local process
```
---
Config option: `enable_set_displayname`

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.

Example configuration:
```yaml
enable_set_displayname: false
```
---
Config option: `enable_set_avatar_url`

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.

Example configuration:
```yaml
enable_set_avatar_url: false
```
---
Config option: `enable_3pid_changes`

Whether users can change the third-party IDs associated with their accounts
(email address and msisdn).

Defaults to true.

Example configuration:
```yaml
enable_3pid_changes: false
```
---
Config option: `auto_join_rooms`

Users who register on this homeserver will automatically be joined
to the rooms listed under this option.

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. If the room already exists, make certain it is a publicly joinable
room, i.e. the join rule of the room must be set to 'public'. You can find more options
relating to auto-joining rooms below. 

Example configuration:
```yaml
auto_join_rooms:
  - "#exampleroom:example.com"
  - "#anotherexampleroom:example.com"
```
---
Config option: `autocreate_auto_join_rooms`

Where `auto_join_rooms` are specified, setting this flag ensures that
the rooms exist by creating them when the first user on the
homeserver registers.

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 to customise this behaviour.

Setting to false means that if the rooms are not manually created,
users cannot be auto-joined since they do not exist.

Defaults to true.

Example configuration:
```yaml
autocreate_auto_join_rooms: false
```
---
Config option: `autocreate_auto_join_rooms_federated`

Whether the rooms listen in `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.
Set to false to prevent users from other homeservers from
joining these rooms.

Example configuration:
```yaml
autocreate_auto_join_rooms_federated: false
```
---
Config option: `autocreate_auto_join_room_preset`

The room preset to use when auto-creating one of `auto_join_rooms`. Only has an
effect if `autocreate_auto_join_rooms` is true.

Possible values for this option are:
* "public_chat": the room is joinable by anyone, including
  federated servers if `autocreate_auto_join_rooms_federated` is true (the default).
* "private_chat": an invitation is required to join these rooms. 
* "trusted_private_chat": an invitation is required to join this room and the invitee is
  assigned a power level of 100 upon joining the room. 

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

Example configuration:
```yaml
autocreate_auto_join_room_preset: private_chat
```
---
Config option: `auto_join_mxid_localpart`

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.

Example configuration:
```yaml
auto_join_mxid_localpart: system
```
---
Config option: `auto_join_rooms_for_guests`
 
When `auto_join_rooms` is specified, setting this flag to false prevents
guest accounts from being automatically joined to the rooms.

Defaults to true.

Example configuration:
```yaml
auto_join_rooms_for_guests: false
```
---
Config option: `inhibit_user_in_use_error`
 
Whether to inhibit errors raised when registering a new account if the user ID
already exists. If turned on, requests to `/register/available` will always
show a user ID as available, and Synapse won't raise an error when starting
a registration with a user ID that already exists. However, Synapse will still
raise an error if the registration completes and the username conflicts.

Defaults to false.

Example configuration:
```yaml
inhibit_user_in_use_error: true
```
---
## Metrics ###
Config options related to metrics.

---
Config option: `enable_metrics`

Set to true to enable collection and rendering of performance metrics. 
Defaults to false.

Example configuration:
```yaml
enable_metrics: true
```
---
Config option: `sentry`

Use this option to enable sentry integration. Provide the DSN assigned to you by sentry
with the `dsn` setting. 

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 disseminate sensitive information
through insecure notification channels if so configured.

Example configuration:
```yaml
sentry:
    dsn: "..."
```
---
Config option: `metrics_flags`

Flags to enable Prometheus metrics which are not suitable to be
enabled by default, either for performance reasons or limited use.
Currently the only option is `known_servers`, which publishes 
`synapse_federation_known_servers`, a gauge of the number of
servers this homeserver knows about, including itself. May cause
performance problems on large homeservers.

Example configuration:
```yaml
metrics_flags:
    known_servers: true
```
---
Config option: `report_stats`

Whether or not to report anonymized homeserver usage statistics. This is originally
set when generating the config. Set this option to true or false to change the current
behavior. 

Example configuration:
```yaml
report_stats: true
```
---
Config option: `report_stats_endpoint`

The endpoint to report the anonymized homeserver usage statistics to.
Defaults to https://matrix.org/report-usage-stats/push

Example configuration:
```yaml
report_stats_endpoint: https://example.com/report-usage-stats/push
```
---
## API Configuration ##
Config settings related to the client/server API

---
Config option: `room_prejoin_state:`

Controls for the state that is shared with users who receive an invite
to a room. By default, the following state event types are shared with users who 
receive invites to the room:
- m.room.join_rules
- m.room.canonical_alias
- m.room.avatar
- m.room.encryption
- m.room.name
- m.room.create
- m.room.topic

To change the default behavior, use the following sub-options:
* `disable_default_event_types`: set to true to disable the above defaults. If this 
   is enabled, only the event types listed in `additional_event_types` are shared.
   Defaults to false.
* `additional_event_types`: Additional state event types to share with users when they are invited
   to a room. By default, this list is empty (so only the default event types are shared).

Example configuration:
```yaml
room_prejoin_state:
   disable_default_event_types: true
   additional_event_types:
     - org.example.custom.event.type
     - m.room.join_rules
```
---
Config option: `track_puppeted_user_ips`

We record the IP address of clients used to access the API for various
reasons, including displaying it to the user in the "Where you're signed in"
dialog.

By default, when puppeting another user via the admin API, the client IP
address is recorded against the user who created the access token (ie, the
admin user), and *not* the puppeted user.

Set this option to true to also record the IP address against the puppeted
user. (This also means that the puppeted user will count as an "active" user
for the purpose of monthly active user tracking - see `limit_usage_by_mau` etc
above.)

Example configuration:
```yaml
track_puppeted_user_ips: true
```
---
Config option: `app_service_config_files`

A list of application service config files to use.

Example configuration:
```yaml
app_service_config_files:
  - app_service_1.yaml
  - app_service_2.yaml
```
---
Config option: `track_appservice_user_ips`

Defaults to false. Set to true to enable tracking of application service IP addresses.
Implicitly enables MAU tracking for application service users.

Example configuration:
```yaml
track_appservice_user_ips: true
```
---
Config option: `macaroon_secret_key`

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.

Example configuration:
```yaml
macaroon_secret_key: <PRIVATE STRING>
```
---
Config option: `form_secret`

A secret which is used to calculate HMACs for form values, to stop
falsification of values. Must be specified for the User Consent
forms to work.

Example configuration:
```yaml
form_secret: <PRIVATE STRING>
```
---
## Signing Keys ##
Config options relating to signing keys

---
Config option: `signing_key_path`

Path to the signing key to sign messages with.

Example configuration:
```yaml
signing_key_path: "CONFDIR/SERVERNAME.signing.key"
```
--- 
Config option: `old_signing_keys`

The keys that the server used to sign messages with but won't use
to sign new messages. 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.

Example configuration:
```yaml
old_signing_keys:
  "ed25519:id": { key: "base64string", expired_ts: 123456789123 }
```
---
Config option: `key_refresh_interval`

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. Defaults to 1d.

Example configuration:
```yaml
key_refresh_interval: 2d
```
---
Config option: `trusted_key_servers:`

The trusted servers to download signing keys from.

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.

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

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.

Example configuration #1:
```yaml
trusted_key_servers:
  - server_name: "my_trusted_server.example.com"
    verify_keys:
      "ed25519:auto": "abcdefghijklmnopqrstuvwxyzabcdefghijklmopqr"
  - server_name: "my_other_trusted_server.example.com"
```
Example configuration #2:
```yaml
trusted_key_servers:
  - server_name: "matrix.org"
```
---
Config option: `suppress_key_server_warning`

Set the following to true to disable the warning that is emitted when the
`trusted_key_servers` include 'matrix.org'. See above.

Example configuration:
```yaml
suppress_key_server_warning: true
```
---
Config option: `key_server_signing_keys_path`

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.

Example configuration:
```yaml
key_server_signing_keys_path: "key_server_signing_keys.key"
```
---
## Single sign-on integration ##

The following settings can be used to make Synapse use a single sign-on
provider for authentication, instead of its internal password database.

You will probably also want to set the following options to false to
disable the regular login/registration flows:
   * `enable_registration`
   * `password_config.enabled`

You will also want to investigate the settings under the "sso" configuration
section below.

---
Config option: `saml2_config`

Enable SAML2 for registration and login. Uses pysaml2. To learn more about pysaml and
to find a full list options for configuring pysaml, read the docs [here](https://pysaml2.readthedocs.io/en/latest/).

At least one of `sp_config` or `config_path` must be set in this section to
enable SAML login. You can either put your entire pysaml config inline using the `sp_config`
option, or you can specify a path to a psyaml config file with the sub-option `config_path`.
This setting has the following sub-options:

* `sp_config`: 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. Here are a few useful sub-options for configuring pysaml:
   * `metadata`: 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.
   * `accepted_time_diff: 3`: Allowed clock difference in seconds between the homeserver and IdP.
      Defaults to 0.
   * `service`: By default, the user has to go to our login page first. If you'd like
     to allow IdP-initiated login, set `allow_unsolicited` to true under `sp` in the `service`
     section.
* `config_path`: specify a separate pysaml2 configuration file thusly: 
  `config_path: "CONFDIR/sp_conf.py"`
* `saml_session_lifetime`: The lifetime of a SAML session. This defines how long a user has to
   complete the authentication process, if `allow_unsolicited` is unset. The default is 15 minutes.
* `user_mapping_provider`: Using this option, an external module can be provided as a 
   custom solution to mapping attributes returned from a saml provider onto a matrix user. The 
   `user_mapping_provider` has the following attributes:
  * `module`: The custom module's class. 
  * `config`: Custom configuration values for the module. Use the values provided in the 
     example if you are using the built-in user_mapping_provider, or provide your own
     config values for a custom class if you are using one. This section will be passed as a Python
     dictionary to the module's `parse_config` method. The built-in provider takes the following two
     options:
      * `mxid_source_attribute`: The SAML attribute (after mapping via the attribute maps) to use
          to derive the Matrix ID from. It is '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_mapping`: The mapping system to use for mapping the saml attribute onto a
         matrix ID. Options include: `hexencode` (which maps unpermitted characters to '=xx')
         and `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.
* `grandfathered_mxid_source_attribute`: 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. This setting controls the SAML attribute which will be used for this
   backwards-compatibility lookup. Typically it should be 'uid', but if the attribute maps are changed, it may be necessary to change it.
   The default is 'uid'. 
* `attribute_requirements`: 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 in the example. All of the listed attributes must
    match for the login to be permitted.
* `idp_entityid`: If the metadata XML contains multiple IdP entities then the `idp_entityid`
   option must be set to the entity to redirect users to.
   Most deployments only have a single IdP entity and so should omit this option.
  

Once SAML support is enabled, a metadata file will be exposed at
`https://<server>:<port>/_synapse/client/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>/_synapse/client/saml2/authn_response`.

Example configuration:
```yaml
saml2_config:
  sp_config:
    metadata:
      local: ["saml2/idp.xml"]
      remote:
        - url: https://our_idp/metadata.xml
    accepted_time_diff: 3

    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
        
  saml_session_lifetime: 5m
  
  user_mapping_provider:
    # Below options are intended for the built-in provider, they should be 
    # changed if using a custom module. 
    config:
      mxid_source_attribute: displayName
      mxid_mapping: dotreplace
  
  grandfathered_mxid_source_attribute: upn

  attribute_requirements:
    - attribute: userGroup
      value: "staff"
    - attribute: department
      value: "sales"

  idp_entityid: 'https://our_idp/entityid'
```
---
Config option: `oidc_providers`

List of OpenID Connect (OIDC) / OAuth 2.0 identity providers, for registration
and login. See [here](../../openid.md)
for information on how to configure these options.

For backwards compatibility, it is also possible to configure a single OIDC
provider via an `oidc_config` setting. This is now deprecated and admins are
advised to migrate to the `oidc_providers` format. (When doing that migration,
use `oidc` for the `idp_id` to ensure that existing users continue to be
recognised.)

Options for each entry include:
* `idp_id`: a unique identifier for this identity provider. Used internally
   by Synapse; should be a single word such as 'github'.
   Note that, if this is changed, users authenticating via that provider
   will no longer be recognised as the same user!
   (Use "oidc" here if you are migrating from an old `oidc_config` configuration.)

* `idp_name`: A user-facing name for this identity provider, which is used to
   offer the user a choice of login mechanisms.

* `idp_icon`: An optional icon for this identity provider, which is presented
   by clients and Synapse's own IdP picker page. If given, must be an
   MXC URI of the format mxc://<server-name>/<media-id>. (An easy way to
   obtain such an MXC URI is to upload an image to an (unencrypted) room
   and then copy the "url" from the source of the event.)

* `idp_brand`: An optional brand for this identity provider, allowing clients
   to style the login flow according to the identity provider in question.
   See the [spec](https://spec.matrix.org/latest/) for possible options here.

* `discover`: set to false to disable the use of the OIDC discovery mechanism
  to discover endpoints. Defaults to true.

* `issuer`: Required. The OIDC issuer. Used to validate tokens and (if discovery
   is enabled) to discover the provider's endpoints.

* `client_id`: Required. oauth2 client id to use.

* `client_secret`: oauth2 client secret to use. May be omitted if
  `client_secret_jwt_key` is given, or if `client_auth_method` is 'none'.

* `client_secret_jwt_key`: Alternative to client_secret: details of a key used
   to create a JSON Web Token to be used as an OAuth2 client secret. If
   given, must be a dictionary with the following properties:

  * `key`: a pem-encoded signing key. Must be a suitable key for the
    algorithm specified. Required unless `key_file` is given.

  * `key_file`: the path to file containing a pem-encoded signing key file.
     Required unless `key` is given.

  * `jwt_header`: a dictionary giving properties to include in the JWT
     header. Must include the key `alg`, giving the algorithm used to
     sign the JWT, such as "ES256", using the JWA identifiers in
     RFC7518.

  * `jwt_payload`: an optional dictionary giving properties to include in
    the JWT payload. Normally this should include an `iss` key.

* `client_auth_method`: auth method to use when exchanging the token. Valid
   values are `client_secret_basic` (default), `client_secret_post` and
   `none`.

* `scopes`: list of scopes to request. This should normally include the "openid"
   scope. Defaults to ["openid"].

* `authorization_endpoint`: the oauth2 authorization endpoint. Required if
   provider discovery is disabled.

* `token_endpoint`: the oauth2 token endpoint. Required if provider discovery is
   disabled.

* `userinfo_endpoint`: the OIDC userinfo endpoint. Required if discovery is
   disabled and the 'openid' scope is not requested.

* `jwks_uri`: URI where to fetch the JWKS. Required if discovery is disabled and
   the 'openid' scope is used.

* `skip_verification`: set to 'true' to skip metadata verification. Use this if
   you are connecting to a provider that is not OpenID Connect compliant.
   Defaults to false. Avoid this in production.

* `user_profile_method`: Whether to fetch the user profile from the userinfo
   endpoint, or to rely on the data returned in the id_token from the `token_endpoint`.
   Valid values are: `auto` or `userinfo_endpoint`.
   Defaults to `auto`, which uses the userinfo endpoint if `openid` is
   not included in `scopes`. Set to `userinfo_endpoint` to always use the
   userinfo endpoint.

* `allow_existing_users`: set to true 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.

* `user_mapping_provider`: Configuration for how attributes returned from a OIDC
   provider are mapped onto a matrix user. This setting has the following
   sub-properties:

     * `module`: The class name of a custom mapping module. Default is
       `synapse.handlers.oidc.JinjaOidcMappingProvider`.
        See https://matrix-org.github.io/synapse/latest/sso_mapping_providers.html#openid-mapping-providers
        for information on implementing a custom mapping provider.

     * `config`: Configuration for the mapping provider module. This section will
        be passed as a Python dictionary to the user mapping provider
        module's `parse_config` method.

        For the default provider, the following settings are available:

       * subject_claim: name of the claim containing a unique identifier
         for the user. Defaults to 'sub', which OpenID Connect
         compliant providers should provide.

       * `localpart_template`: Jinja2 template for the localpart of the MXID.
          If this is not set, the user will be prompted to choose their
          own username (see the documentation for the `sso_auth_account_details.html` 
          template). This template can use the `localpart_from_email` filter.

       * `confirm_localpart`: Whether to prompt the user to validate (or
          change) the generated localpart (see the documentation for the
          'sso_auth_account_details.html' template), instead of
          registering the account right away.

       * `display_name_template`: Jinja2 template for the display name to set
          on first login. If unset, no displayname will be set.

       * `email_template`: Jinja2 template for the email address of the user.
          If unset, no email address will be added to the account.
                 
       * `extra_attributes`: a map of 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.

     When rendering, the Jinja2 templates are given a 'user' variable,
     which is set to the claims returned by the UserInfo Endpoint and/or
     in the ID Token.


It is possible to configure Synapse to only allow logins if certain attributes 
match particular values in the OIDC userinfo. The requirements can be listed under
`attribute_requirements` as shown here:
```yaml
attribute_requirements:
     - attribute: family_name
       value: "Stephensson"
     - attribute: groups
       value: "admin"
```
All of the listed attributes must match for the login to be permitted. Additional attributes can be added to
userinfo by expanding the `scopes` section of the OIDC config to retrieve
additional information from the OIDC provider.

If the OIDC claim is a list, then the attribute must match any value in the list.
Otherwise, it must exactly match the value of the claim. Using the example 
above, the `family_name` claim MUST be "Stephensson", but the `groups`
claim MUST contain "admin".

Example configuration:
```yaml
oidc_providers:
  # Generic example
  #
  - idp_id: my_idp
    idp_name: "My OpenID provider"
    idp_icon: "mxc://example.com/mediaid"
    discover: false
    issuer: "https://accounts.example.com/"
    client_id: "provided-by-your-issuer"
    client_secret: "provided-by-your-issuer"
    client_auth_method: client_secret_post
    scopes: ["openid", "profile"]
    authorization_endpoint: "https://accounts.example.com/oauth2/auth"
    token_endpoint: "https://accounts.example.com/oauth2/token"
    userinfo_endpoint: "https://accounts.example.com/userinfo"
    jwks_uri: "https://accounts.example.com/.well-known/jwks.json"
    skip_verification: true
    user_mapping_provider:
      config:
        subject_claim: "id"
        localpart_template: "{{ user.login }}"
        display_name_template: "{{ user.name }}"
        email_template: "{{ user.email }}"
    attribute_requirements:
      - attribute: userGroup
        value: "synapseUsers"
```
---
Config option: `cas_config`

Enable Central Authentication Service (CAS) for registration and login.
Has the following sub-options:
* `enabled`: Set this to true to enable authorization against a CAS server.
   Defaults to false.
* `server_url`: The URL of the CAS authorization endpoint.
* `displayname_attribute`: The attribute of the CAS response to use as the display name.
   If no name is given here, no displayname will be set.
* `required_attributes`:  It is possible to configure Synapse to only allow logins if CAS attributes
   match particular values. All of the keys given 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.

Example configuration:
```yaml
cas_config:
  enabled: true
  server_url: "https://cas-server.com"
  displayname_attribute: name
  required_attributes:
    userGroup: "staff"
    department: None
```
---
Config option: `sso`

Additional settings to use with single-sign on systems such as OpenID Connect,
SAML2 and CAS.

Server admins can configure custom templates for pages related to SSO. See 
[here](../../templates.md) for more information.

Options include:
* `client_whitelist`: 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/".
   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.
   By default, this list contains only the login fallback page.
* `update_profile_information`: Use this setting to keep a user's profile fields in sync with information from
   the identity provider. Currently only syncing the displayname is supported. Fields 
   are checked on every SSO login, and are updated if necessary.
   Note that enabling this option will override user profile information,
   regardless of whether users have opted-out of syncing that
   information when first signing in. Defaults to false.


Example configuration:
```yaml
sso:
    client_whitelist:
      - https://riot.im/develop
      - https://my.custom.client/
    update_profile_information: true
```
---
Config option: `jwt_config`

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.

Additionally, the expiration time ("exp"), not before time ("nbf"),
and issued at ("iat") claims are validated if present.

Note that this is a non-standard login type and client support is
expected to be non-existent.

See [here](../../jwt.md) for more.

Additional sub-options for this setting include:
* `enabled`: Set to true to enable authorization using JSON web
   tokens. Defaults to false.
* `secret`: 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 set to true.
* `algorithm`: The algorithm used to sign (or HMAC) the JSON web token.
   Supported algorithms are listed
   [here (section JWS)](https://docs.authlib.org/en/latest/specs/rfc7518.html).
   Required if `enabled` is set to true.
* `subject_claim`: Name of the claim containing a unique identifier for the user.
   Optional, defaults to `sub`.
* `issuer`: The issuer to validate the "iss" claim against. Optional. If provided the 
   "iss" claim will be required and validated for all JSON web tokens.
* `audiences`: 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.

Example configuration:
```yaml
jwt_config:
    enabled: true 
    secret: "provided-by-your-issuer"
    algorithm: "provided-by-your-issuer"
    subject_claim: "name_of_claim"
    issuer: "provided-by-your-issuer"
    audiences:
        - "provided-by-your-issuer"
```
---
Config option: `password_config`

Use this setting to enable password-based logins. 

This setting has the following sub-options:
* `enabled`: Defaults to true.
   Set to false to disable password authentication.
   Set to `only_for_reauth` to allow users with existing passwords to use them
   to log in and reauthenticate, whilst preventing new users from setting passwords.
* `localdb_enabled`: Set to false 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`. Defaults to true. 
* `pepper`: Set the value here to a secret random string for extra security. # Uncomment and change to a secret random string for extra security.
   DO NOT CHANGE THIS AFTER INITIAL SETUP!
* `policy`: Define and enforce a password policy, such as minimum lengths for passwords, etc. 
   Each parameter is optional. This is an implementation of MSC2000. Parameters are as follows:
   * `enabled`: Defaults to false. Set to true to enable.
   * `minimum_length`: Minimum accepted length for a password. Defaults to 0.
   * `require_digit`: Whether a password must contain at least one digit.
      Defaults to false.
   * `require_symbol`: Whether a password must contain at least one symbol.
      A symbol is any character that's not a number or a letter. Defaults to false.
   * `require_lowercase`: Whether a password must contain at least one lowercase letter.
      Defaults to false.
   * `require_uppercase`: Whether a password must contain at least one uppercase letter.
      Defaults to false.