Skip to content

Configuring Secure Border Gateway

See how to download example files from the helm chart here.

Configuration

For a quick setup using the default settings, see the minimal fragment example in charts/matrix-stack/ci/fragments/secure-border-getaway-minimal.yaml.

Secure Border Gateway CA

The Secure Border Gateway injects its own CA into Synapse. The CA is either automatically generated by helm, or you can inject your own CA through an existing secret.

secureBorderGateway:
  ownCA:
    # one of createViaHelm or existingSecret
    #
    # Generates a CA using genCA function of helm. Requires lookup to avoid rebuilding a new CA
    # on every helm upgrade. As such, this will not work with ArgoCD/Flux/....
    # createViaHelm: true
    #
    # An existing secret with the CA tls.crt and tls.key data.
    # existingSecret:

Secure Border Gateway policies

Private Federation

The Secure Border Gateway can be configured to enforce private federation in front of Synapse.

  • The fetchStore mode supports configuring the federation allow-list dynamically using the Synapse Pro API /_synapse/io.element/admin/v1/federation/whitelist. It also allows you to change the list of allowed servers without restarting SBG or Synapse.
  • The staticList mode allows you to configure the list of allowed servers with restarting only the SBG pods.
  checks:
    privateFederation:
    # one of fetchStore or staticList
    #
    # Makes SBG request Synapse to get the federation allow-list
    # it requires synapse module sbg_federation_allowlist_store.SBGFederationAllowlistStore
    # and Synapse Admin for the UI dynamic configuration
    # fetchStore: true
    #
    # Configures the list in SBG config file. Changing the list
    # involves a restart of SBG pods
    # staticList:
    # - example.com
    # - other-example.org

Required Client Headers

The Secure Border Gateway can be configured to require certain client headers to be present in the client requests. This is useful to prevent your users from connecting with third-party clients to your matrix server.

secureBorderGateway:
  checks:
    requiredClientHeaders:
    - headerName: user-agent
      headerValue: ^SomeUserAgent$
    - headerName: Other-Header-Name
      headerValue: ^[a-z]\.[0-9]*$

Additional configuration

Additional Secure Border Gateway configuration can be provided inline in the values as a string with

secureBorderGateway:
  additional:
    ## Either reference config to inject by:
    1-custom-config:
      config: |
        admin_contact: "mailto:admin@example.com"
    ## Either reference an existing `Secret` by:
    2-custom-config:
      configSecret: custom-sbg-config
      configSecretKey: shared.yaml