Skip to main content

Synapse Section: Delegated Auth

Specific Examples

LDAP on Windows AD

In the installer, set the following fields:

  • Base: the distinguished name of the root level Org Unit in your LDAP directory. The distinguished name can be displayed by selecting View/Advanced Features in the Active Directory console and then, right-clicking on the object, selecting Properties/Attributes Editor.
    Screenshot 2023-05-04 at 17.31.24.png
  • Bind Dn: the distinguished name of the LDAP account with read access.
  • Filter: an LDAP filter to filter out objects under the LDAP Base DN.
  • Uri: the URI of your LDAP server. (often your Domain Controller) can pass in ldaps:// for SSL connectivity. The following are the typical ports for Windows AD LDAP servers:
    • ldap://ServerName:389
    • ldaps://ServerName:636
  • LDAP Bind Password: the password of the AD account with read access.

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

OpenID on Microsoft Azure

Before setting up 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 https://matrix.your-domain.com/_synapse/client/oidc/callback

Screenshot 2023-05-03 at 16.30.06.png

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

  • openid
  • profile

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

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

  • Allow Existing Users: 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. This property has to bet set to https://your-domain/_synapse/client/oidc/backchannel_logoutin your identity provider

    Screenshot 2023-05-02 at 15.39.56.png

  • 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: your Application (client) ID

  • 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://login.microsoftonline.com/<Directory (tenant) ID>/v2.0
  • Token Endpoint: the oauth2 authorization endpoint. Required if provider discovery is disabled.
  • Client Secret: your secret value defined under "Certificates and secrets"

Screenshot 2023-05-03 at 15.20.20.png

  • 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. Screenshot 2023-05-11 at 11.06.39.png

    • Localpart Template: Jinja2 template for the localpart of the MXID. Set it to {{ user.preferred_username.split('@')[0] }} for Azure AD
    • Display Name Template: Jinja2 template for the display name to set on first login. If unset, no displayname will be set. Set it to {{ user.name }}for Azure AD

    Other configurations are documented here.

OpenID on Microsoft AD FS

SAML on Microsoft Azure

Back to top