Authentication Section

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

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.

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

User Profiles

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

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:

• 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

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

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.

spec:
  components:synapse:


    

      
config:
        delegatedAuth:
          oidc:
            - 


IdP Name



Config Example

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


IdP ID


Config 

ldap://dc.example.comspec:
  components:
    synapse:
      config:
        delegatedAuth:
          oidc:
              clientId: example_client_id
.

Allow Existing Users

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

• 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
  how

  Config attributesExample

  returned

  spec:
    fromcomponents:
      asynapse:
        OIDCconfig:
          providerdelegatedAuth:
            areoidc:
                mappeduserMappingProvider:
  onto

  a
  matrix user.
  • Localpart

    Subject Template.
    Jinja2

    template

    

    for
    the

    Config localpartExample

    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
    the

    Config displayExample

    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.

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 }}'