Authentication configuration examples for LDAP, OpenID on Azure and SAML.
/_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.
