Skip to main content

Authentication Section

A detailed look at Delegated Authentication options available and setup examples.

                 

                 

                 

Config:

This is a new section introduced in LTS 24.10 which replaces the previous Delegated Authentication options found within the Synapse section. Your previous configuration will be upgraded on first-run of the newer LTS.

In the Authentication section you will find options to configure settings specific to Authentication. Regardless of if you are using the Matrix Authentication Server, or have enabled Legacy Auth, the settings on this page will remain the same.

However please note, MAS does not support delegated authentication with SAML or GroupSync - if you wish to enable either of these you will need to return to the Host section and enable Legacy Auth.

All settings configured via the UI in this section will be saved to your deployment.yml, with the contents of secrets being saved to secrets.yml. You will find specific configuration examples in each section.

Config Example
  • deployment.yml 
    metadata:
annotations:
  ui.element.io/layer: |
    components:
      synapse:
spec:
  components:
    synapse:
      config:
        delegatedAuth:
  • secrets.yml 
    kind: Secret
metadata:
  name: synapse
  namespace: element-onprem
data:

By default, if you do not change any settings on this page, defaults will be added to your configuration file/s (see example below).

Config Example
  • deployment.yml 
    metadata:
  annotations:
    ui.element.io/layer: |
      components:

spec:
  synapse:
    config:
      delegatedAuth:
        localPasswordDatabase:
          enableRegistration: false # Note, if you deploy without any authentication methods enabled, the installer will default to Local Accounts.
  • secrets.yml 
    apiVersion: v1
kind: Secret
metadata:

data:
  ldapBindPassword: examplePassword

User Profiles

Config Example 
spec:
  components:
    synapse:
      config:
        delegatedAuth:
          userProfiles:
            allowAvatarChange: true # Not present if left as default
            allowDisplayNameChange: true # Not present if left as default
            allowEmailChange: true # Not present if left as default

Self-The User Profiles section provides some self-explanatory config options to adjust whetherwhat changes users are allowed to make changes to their User Profile

Profile,
such

Atas present,changing wetheir supportDisplay delegatingName. You may wish to restrict this if you'd prefer to delegate the authenticationsetting of usersthese values to the followingassociated Identity Provider.

OIDC

You can add and configure one, or multiple, OIDC providers - to do so you will need to click the Add OIDC / Add more OIDC button found after toggling on the ODIC section:

Once an OIDC provider interfaces:

is
    LDAP SAML OIDC

    When enabling Delegated Auth,added, you can stillremove allowany local users managedproviders by Elementclicking tothe connectrubbish bin icon found to the instance

    left

    Screenshot 2023-05-04 at 09.23.54.png

    When Allow Local Users Login is Enabled, you can both connect to your instance using your IDP andof the local database.

    Screenshot 2023-05-04 at 14.30.04.png

    Different options are offered by the installer and you can combine two or more options on the same instance like enabling SAML and OIDC delegated authentication.

    See the below relevant sections to your environment for specifics on getting configured.provider.

    LDAPConfig on Windows AD

    Example     
    spec:
    components: synapse: config: delegatedAuth: oidc: -

    IdP Name

    screenshot-2023-05-04-at-17-31-24.png

    Config Example 
    spec:
  components:
    synapse:
      config:
        delegatedAuth:
          oidc:
              idpName: example_name # Required

    IdP ID

    screencapture-3-76-146-148-8443-synapse-2023-05-04-17-33-17-copy.png

    Config Example 
      spec:
  components:
    Base.
      Thesynapse:
      distinguishedconfig:
        namedelegatedAuth:
          ofoidc:
              theidpId: root01JDS2WKNYTQS21GFAKM9AKD9R level# OrgRequired
Unit
      in
      your

      IdP LDAPBrand

      directory.

        Config distinguishedExampleThe name
        spec:
  cancomponents:
    besynapse:
      displayedconfig:
        bydelegatedAuth:
          selectingoidc:
              idpBrand: example_brand

        Issuer

        Config Example 
        Viewspec:
  components:
    synapse:
      config:
        delegatedAuth:
          oidc:
              issuer: https://issuer.example.com/ # Required
        /

        Client Auth Method

        Config Example 
        Advancedspec:
  Featurescomponents:
    insynapse:
      theconfig:
        ActivedelegatedAuth:
          Directoryoidc:
              consoleclientAuthMethod: andclient_secret_basic then,# right-clickingIf onno the`clientAuthMethod` object,defined, selectingwill Properties / Attributes Editor.
        Bind DN.
        The distinguished name of the LDAP account with read access. Filter.
        A LDAP filterdefault to filter`client_secret_basic` out# objectsclientAuthMethod: underclient_secret_post the# LDAPclientAuthMethod: Basenone DN. URI.
        The

        Client URIID

        of

        your
        Config serverExampleLDAP 
        ldap://dc.example.comspec:
  components:
    synapse:
      config:
        delegatedAuth:
          oidc:
              clientId: example_client_id
.
          This

          Client isSecret

          often

          your
          Config Controller, can also pass in ldaps:// for SSL connectivity.Domain
          The following are the typical ports for Windows AD LDAP servers:Example
          • ldap://ServerName:389deployment.yml 
            spec:
  components:
    synapse:
      config:
        delegatedAuth:
          oidc:
              clientSecretSecretKey: oidcClientSecret
          • ldaps://ServerName:636secrets.yml
          LDAP Bind Password.
          The password of the AD account with read access. LDAP Attributes.
            Mail.
            mail Name.
            cn UID.
            sAMAccountName

            OpenID on Microsoft Azure

            Before configuring within the installer, you have to configure Microsoft Azure Active Directory.

            Set up Microsoft Azure Active Directory

              You need to create an App registration. You have to select Redirect URI (optional) and set it to the following, where matrix is the subdomain of Synapse and example.com is your base domain as configured on the Domains section: 
              https://matrix.example.com/_synapse/client/oidc/callbackapiVersion: v1
kind: Secret
metadata:
  name: synapse
  namespace: element-onprem
data:
  oidcClientSecret: U2VjdXJlT0lEQ0NsaWVudFNlY3JldA==

              Allow Existing Users

              Screenshot 2023-05-03 at 16.30.06.png

              Config Example 
              spec:
  components:
    synapse:
      config:
        delegatedAuth:
          oidc:

              Scopes

              For the bridge to be able to operate correctly, navigate to API permissions, add Microsoft Graph APIs, choose Delegated Permissions and add:

                Config Example 
                spec:
  components:
    synapse:
      config:
        delegatedAuth:
          oidc:
              scopes:
                - openid
                - profile
                - email
                profile email

                Remember to grant the admin consent for those.

                To setup the installer, you'll need:

                  The Application (client) ID The Directory (tenant) ID A secret generated from Certificates & Secrets on the app.

                  Configure the installer

                  image-1715183635194.png image-1715183663530.png image-1715183677555.png
                    IdP Name.
                    A user-facing name for this identity provider, which is used to offer the user a choice of login mechanisms in the Element UI. IdP ID.
                    A string identifying your identity provider in your configuration, this will be auto-generated for you (but can be changed). IdP Brand.
                    An optional brand for this identity provider, allowing clients to style the login flow according to the identity provider in question. Issuer.
                    The OIDC issuer. Used to validate tokens and (if discovery is enabled) to discover the provider's endpoints. Use https://login.microsoftonline.com/DIRECTORY_TENNANT_ID/v2.0 replacing DIRECTORY_TENNANT_ID. Client Auth Method.
                    Auth method to use when exchanging the token. Set it to Client Secret Post or any method supported by your IdP. Client ID.
                    Set this to your Application (client) ID. Client Secret.
                    Set this to the secret value defined under "Certificates and secrets". Scopes.
                    By default openid, profile and email are added, you shouldn't need to modify these. User Mapping Provider.
                    Configuration for
                    Config attributesExamplehow returned
                    spec:
  fromcomponents:
    asynapse:
      OIDCconfig:
        providerdelegatedAuth:
          areoidc:
              mappeduserMappingProvider:
onto
                    a
                    matrix user.
                      Localpart
                      Subject Template
                      .
                      Jinja2 template

                      for
                      Config localpartExamplethe of
                      spec:
  thecomponents:
    MXID.
                      Setsynapse:
      itconfig:
        todelegatedAuth:
          oidc:
              userMappingProvider:
                subjectTemplate: '{{ user.preferred_username.split('@')[0]subject }}'
.
                      Localpart Template

                      Config Example 
                      spec:
  components:
    synapse:
      config:
        delegatedAuth:
          oidc:
              userMappingProvider:
                localpartTemplate: '{{ user.preferred_username }}'
                      Display Name Template
                      .
                      Jinja2 template

                      for
                      Config displayExamplethe name
                      spec:
  tocomponents:
    setsynapse:
      onconfig:
        firstdelegatedAuth:
          login.
                      Ifoidc:
              unset,userMappingProvider:
                nodisplayNameTemplate: display name will be set. Set it to '{{ user.name }}'
.
                      Email
                      Template Discover.
                      Enable

                      Config Example 
                      spec:
  components:
    synapse:
      config:
        delegatedAuth:
          oidc:
              userMappingProvider:
                emailTemplate: '{{ user.email }}'

                      Endpoints Discovery

                      Auto Discovery

                      Config Example 
                      spec:
  components:
    synapse:
      config:
        delegatedAuth:
          oidc:
            - clientId: synapsekieranml
              clientSecretSecretKey: oidcClientSecret
              endpointsDiscovery:
                skipVerification: false
              idpId: 01JDS2WKNYTQS21GFAKM9AKD9R
              idpName: Keycloak
              issuer: https://keycloak.ems-support.element.dev/realms/matrix
              Disablescopes:
                the- useopenid
                of- theprofile
                OIDC- discoveryemail
              mechanismuserMappingProvider:
                todisplayNameTemplate: discover'{{ endpoints.
                      user.name }}' emailTemplate: '{{ user.email }}'
                      Skip Verification
                      Config Example 
                      spec:
  components:
    synapse:
      config:
        delegatedAuth:
          oidc:
            - clientId: synapsekieranml
              clientSecretSecretKey: oidcClientSecret
              endpointsDiscovery:
                skipVerification: false
              idpId: 01JDS2WKNYTQS21GFAKM9AKD9R
              idpName: Keycloak
              issuer: https://keycloak.ems-support.element.dev/realms/matrix
              scopes:
                - openid
                - profile
                - email
              userMappingProvider:
                displayNameTemplate: '{{ user.name }}'
                emailTemplate: '{{ user.email }}'

                      Backchannel Logout Enabled

                      .
                      Synapse supports receiving OpenID Connect Back-Channel Logout notifications. This lets the OpenID Connect Provider notify Synapse when a user logs out, so that Synapse can end that user session. This property has to bet set to https://matrix.example.com/_synapse/client/oidc/backchannel_logoutin your identity provider, where matrix is the subdomain of Synapse and example.com is your base domain as configured on the Domains section.

                      OpenID on Microsoft AD FS

                      Install Microsoft AD FS

                      BeforeThe startingMatrix theAuthentication installation,Service makedoes sure:

                      not
                        support yourconfiguring WindowsBackchannel computerLogout. name is correct since you won't be able to change it after having installed AD FS you configured your server with a static IP address your server joined a domain and your domain is defined under Server Manager > Local server you can resolve your server FQDN like computername.my-domain.com

                        You can findonly aconfigure checklistBackchannel here.

                        Steps to follow:

                          Install AD CS (Certificate Server) to issue valid certificates for AD FS. AD CS provides a platform for issuing and managing public key infrastructure [PKI] certificates. Install AD FS (Federation Server)
                          Install AD CS

                          You need to install the AD CS Server Role.

                            Follow this guide.
                            Obtain and Configure an SSL Certificate for AD FS

                            Before installing AD FS, you are required to generate a certificate for your federation service. The SSL certificate is used for securing communications between federation servers and clients.

                              Follow this guide. Additionally, this guide provides more details on how to create a certificate template.
                              Install AD FS

                              You need to install the AD FS Role Service.

                                Follow this guide.
                                Configure the federation service

                                AD FS is installed but not configured.

                                  Click on Configure the federation service on this server under Post-deployment configuration in the Server Manager. Ensure Create the first federation server in a federation server farm and is selected

                                  Screenshot 2023-06-22 at 15.55.57.png

                                    Click Next

                                    Screenshot 2023-06-22 at 15.57.41.png

                                      Select the SSL Certificate and set a Federation Service Display Name

                                      Screenshot 2023-06-22 at 15.59.27.png

                                        On the Specify Service Account page, you can either Create a Group Managed Service Account (gMSA) or Specify an existing Service or gMSA Account

                                        Screenshot 2023-06-22 at 16.04.13.png

                                          Choose your database

                                          Screenshot 2023-06-22 at 16.05.50.png

                                            Review Options , check prerequisites are completed and click on Configure Restart the server
                                            Add AD FS as an OpenID Connect identity provider

                                            To enable sign-in for users with an AD FS account, create an Application Group in your AD FS.
                                            To create an Application Group, follow theses steps:

                                              In Server Manager, select Tools, and then select AD FS Management In AD FS Management, right-click on Application Groups and select Add Application Group On the Application Group Wizard Welcome screen
                                                Enter the Name of your application Under Standalone applications section, select Server application and click Next

                                                Screenshot 2023-06-22 at 16.39.52.png

                                                  Enter https://<matrix domain>/_synapse/client/oidc/callback in Redirect URI: field, click Add, save the Client Identifier somewhere, you will need it when setting up Element and click Next (e.g. https://matrix.domain.com/_synapse/client/oidc/callback)

                                                  Screenshot 2023-06-22 at 16.45.44.png

                                                    Select Generate a shared secret checkbox and make a note of the generated Secret and press Next (Secret needs to be added in the Element Installer GUI in a later step) Right click on the created Application Group and select `Properties``

                                                    Screenshot 2023-06-22 at 16.56.40.png

                                                      Select Add application... button. Select Web API In the Identifier field, type in the client_id you saved before and click Next

                                                      Screenshot 2023-06-23 at 09.48.07.png

                                                        Select Permit everyone and click Next Under Permitted scopes: select openid and profile and click Next

                                                        Screenshot 2023-06-23 at 09.51.06.png

                                                          On Summary page, click `Next`` Click Close and then OK
                                                          Export Domain Trusted Root Certificate
                                                            Run mmc.exe Add the Certificates snap-in
                                                              File/Add snap-in for Certificates, Computer account Under Trusted Root Certification Authorities/Certificates, select your DC cert Right click and select All Tasks/Export... and export as Base-64 encoded X 509 (.CER) Copy file to local machine

                                                              Configure the installer

                                                              Add an OIDC provider in the 'Synapse' configuration after enabling Delegated Auth and set the following fields in the installer:

                                                                Allow Existing Users:logout if checked, it allows 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. Authorization Endpoint: the oauth2 authorization endpoint. Required if provider discovery is disabled.

                                                                https://login.microsoftonline.com/<Directory (tenant) ID>/oauth2/v2.0/authorize

                                                                Backchannel Logout Enabled: Synapse supports receiving OpenID Connect Back-Channel Logout notifications. This lets the OpenID Connect Provider notify Synapse when a user logs out, so that Synapse can end that user session. Client Auth Method: auth method to use when exchanging the token. Set it to Client Secret Basic or any method supported by your Idp Client ID: the Client ID you saved before Discover: enable/disable the use of the OIDC discovery mechanism to discover endpoints Idp Brand: an optional brand for this identity provider, allowing clients to style the login flow according to the identity provider in question Idp ID: a string identifying your identity provider in your configuration Idp Name: A user-facing name for this identity provider, which is used to offer the user a choice of login mechanisms in the Element UI. In the screenshot bellow, Idp Name is set to Azure AD

                                                                Screenshot 2023-05-04 at 10.45.23.png

                                                                  Issuer: the OIDC issuer. Used to validate tokens and (if discovery is enabled) to discover the provider's endpoints https://<your-adfs.domain.com>/adfs/ Token Endpoint: the oauth2 authorization endpoint. Required if provider discovery is disabled. Client Secret: your client secret you saved before. Scopes: add every scope on a different line
                                                                    The openid scope is required which translates to the Sign you in permission in the consent UI You might also include other scopes in this request for requesting consent.

                                                                    Screenshot 2023-05-03 at 17.27.00.png

                                                                      User Mapping Provider: Configuration for how attributes returned from a OIDC provider are mapped onto a matrix user.
                                                                        Localpart Template: Jinja2 template for the localpart of the MXID. Set it to {{ user.upn.split('@')[0] }} for AD FS

                                                                        Other configurations are documented here.

                                                                        SAML on Microsoft Azure

                                                                        Before setting up the installer, you have toenabled configureLegacy MicrosoftAuth Entrafrom ID.the Host Section.

                                                                        Set

                                                                        up
                                                                        Config EntraExampleMicrosoft ID
                                                                        spec:
  components:
    synapse:
      config:
        delegatedAuth:
          oidc:
            - clientId: synapsekieranml
              clientSecretSecretKey: oidcClientSecret
              endpointsDiscovery:
                skipVerification: false
              idpId: 01JDS2WKNYTQS21GFAKM9AKD9R
              idpName: Keycloak
              issuer: https://keycloak.ems-support.element.dev/realms/matrix
              scopes:
                - openid
                - profile
                - email
              userMappingProvider:
                displayNameTemplate: '{{ user.name }}'
                emailTemplate: '{{ user.email }}'

                                                                        SAML

                                                                        WithThe anMatrix accountAuthentication withService enoughdoes rights,not gosupport SAML and it is recommended to :switch to OIDC. You can only enable SAML authentication if you have enabled EnterpriseLegacy ApplicationsAuth

                                                                          Click on New Application Click on Create your own application onfrom the topHost left corner Choose a name for it, and select Integrate any other application you don't find in the gallery Click on "Create" Select Set up single sign on Select SAML Edit on Basic SAML Configuration In Identifier , add the following URL : https://synapse_fqdn/_synapse/client/saml2/metadata.xml Remove the default URL In Reply URL , add the following URL : https://synapse_fqdn/_synapse/client/saml2/authn_response Click on Save

                                                                          Section.

                                                                            Make a note of the App Federation Metadata Url under SAML Certificates as this will be required in a later step. Edit on Attributes & Claims Remove all defaults for additional claims Click on Add new claim to add the following (suggested) claims (the UID will be used as the MXID):
                                                                              Name: uid , Transformation : ExtractMailPrefix , Parameter 1 : user.userprincipalname Name: email , Source attribute : user.mail Name: displayName , Source attribute : user.displayname Click on Save

                                                                                In the application overview screen select Users and Groups and add groups and users which may have access to element

                                                                                Configure the installer

                                                                                Add a SAML provider in the 'Synapse' configuration after enabling Delegated Auth and set the following (suggested) fields in the installer:

                                                                                  Allow Unknown Attributes.
                                                                                  Checked Attribute Map.
                                                                                  Select URN:Oasis:Names:TC:SAML:2.0:Attrname Format:Basic as the Identifier Mapping.
                                                                                  Set the following mappings:
                                                                                    From: Primary Email To: email From: First Name To: firstname From: Last Name To: lastname Entity.
                                                                                      Description.
                                                                                      Entity ID. (From Azure) Name.
                                                                                      User Mapping Provider.
                                                                                      Set the following:
                                                                                        MXID Mapping: Dotreplace MXID Source Attribute: uid Metadata URL.
                                                                                        Add the App Federation Metadata URL from Azure.

                                                                                        LDAP

                                                                                        TroubleshootingLocal Accounts

                                                                                        Redirection loop on SSO

                                                                                        Synapse needs to have the X-Forwarded-For and X-Forwarded-Proto headers set by the reverse proxy doing the TLS termination. If you are using a Kubernetes installation with your own reverse proxy terminating TLS, please make sure that the appropriate headers are set.

                                                                                        Back to top