# Authentication Configuration Examples
Authentication configuration examples for LDAP, OpenID on Azure and SAML.
Provided below are some configuration examples covering how you can set up various types of Delegated Authentication. For a more detailed look at what each configuration option does, please refer to the [Authentication Section](https://ems-docs.element.io/books/element-server-suite-documentation-lts-2410/page/authentication-section) detailed document.
### LDAP on Windows AD
- **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`.
- **Bind DN****.**
The distinguished name of the LDAP account with read access.
- **Filter****.**
A [LDAP filter](https://ldap.com/ldap-filters/) to filter out objects under the LDAP Base DN.
- **URI****.**
The URI of your LDAP server `ldap://dc.example.com`.
- This is often your Domain Controller, can also 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.
- **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/callback
```
[](https://ems-docs.element.io/uploads/images/gallery/2023-05/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`
- `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 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.preferred_username.split('@')[0] }}`.
- **Display Name Template****.**
Jinja2 template for the display name to set on first login.
If unset, no display name will be set. Set it to `{{ user.name }}`.
- **Discover****.**
Enable / Disable the use of the OIDC discovery mechanism to discover endpoints.
- **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_logout`in 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
Before starting the installation, make sure:
- your Windows computer 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 find a checklist [here](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/deployment/checklist--setting-up-a-federation-server).
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](https://learn.microsoft.com/en-us/windows-server/networking/core-network-guide/cncg/server-certs/install-the-certification-authority).
##### 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](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/dn781428(v=ws.11)).
- Additionally, this [guide](https://learn.microsoft.com/en-us/windows-server/networking/core-network-guide/cncg/server-certs/configure-the-server-certificate-template) 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](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/deployment/install-the-ad-fs-role-service).
##### 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
[](https://ems-docs.element.io/uploads/images/gallery/2023-06/screenshot-2023-06-22-at-15-55-57.png)
- Click `Next`
[](https://ems-docs.element.io/uploads/images/gallery/2023-06/screenshot-2023-06-22-at-15-57-41.png)
- Select the SSL Certificate and set a Federation Service Display Name
[](https://ems-docs.element.io/uploads/images/gallery/2023-06/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
[](https://ems-docs.element.io/uploads/images/gallery/2023-06/screenshot-2023-06-22-at-16-04-13.png)
- Choose your database
[](https://ems-docs.element.io/uploads/images/gallery/2023-06/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`
[](https://ems-docs.element.io/uploads/images/gallery/2023-06/screenshot-2023-06-22-at-16-39-52.png)
- Enter `https:///_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)
[](https://ems-docs.element.io/uploads/images/gallery/2023-06/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``
[](https://ems-docs.element.io/uploads/images/gallery/2023-06/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`
[](https://ems-docs.element.io/uploads/images/gallery/2023-06/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`
[](https://ems-docs.element.io/uploads/images/gallery/2023-06/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`: 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//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`
[](https://ems-docs.element.io/uploads/images/gallery/2023-05/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:///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.
[](https://ems-docs.element.io/uploads/images/gallery/2023-05/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](https://element-hq.github.io/synapse/v1.41/openid.html).
### SAML on Microsoft Azure
Before setting up the installer, you have to configure Microsoft Entra ID.
#### Set up Microsoft Entra ID
With an account with enough rights, go to : `Enterprise Applications`
1. Click on `New Application`
2. Click on `Create your own application` on the top left corner
3. Choose a name for it, and select `Integrate any other application you don't find in the
gallery`
4. Click on "Create"
5. Select `Set up single sign on`
6. Select `SAML`
7. `Edit` on `Basic SAML Configuration`
8. In `Identifier` , add the following URL : `https://synapse_fqdn/_synapse/client/saml2/metadata.xml`
9. Remove the default URL
10. In `Reply URL` , add the following URL : `https://synapse_fqdn/_synapse/client/saml2/authn_response`
11. Click on `Save`
[](https://ems-docs.element.io/uploads/images/gallery/2023-11/image-1701176026243.png)
12. Make a note of the `App Federation Metadata Url` under `SAML Certificates` as this will be required in a later step.
13. `Edit` on `Attributes & Claims`
14. Remove all defaults for additional claims
15. 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`
16. Click on `Save`
[](https://ems-docs.element.io/uploads/images/gallery/2023-11/image-1701172980662.png)
17. 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.
### Troubleshooting
#### 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.