Synapse Section: Delegated Auth
Specific
LDAP on Windows AD
In
the
installer,
set
the
following
fields:
-
Base
: the.
The distinguished name of the root level Org Unit in your LDAP directory.
-
Bind Dn
: theDN.
The distinguished name of the LDAP account with read access.
-
Filter
: an.
A LDAP filter to filter out objects under the LDAP Base DN.
-
Uri
: theURI.
The URI of your LDAP server.server (ldap://dc.example.com
.
- This is often your Domain
Controller)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.
The password of the AD account with read access.
-
LDAP Attributes.
-
Mail.
mail
-
Name.
cn
-
UID.
sAMAccountName
OpenID on Microsoft Azure
Before settingconfiguring upwithin 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.your-domain.example.com/_synapse/client/oidc/callback
For the bridge to be able to operate correctly, navigate to API permissions, add Microsoft Graph APIs, choose Delegated Permissions and addadd:
-
openid
-
profile
-
email
Remember to grant the admin consent for those.
To setup the installer, you'll needneed:
the
The Application (client) ID
the
The Directory (tenant) ID
a
A secret generated from Certificates & secretsSecrets
on the app.
Configure the installer
Add
an
OIDC
-
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 theyour 'Synapse'configuration, configurationthis 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 couldwill be usedauto-generated iffor switchingyou from(but passwordcan loginsbe to OIDC.
changed).
-
AuthorizationIdP Endpoint
:Brand.
An optional brand for this identity provider, allowing clients to style the oauth2login authorizationflow endpoint.according Requiredto ifthe identity provider in question.
-
Issuer.
The OIDC issuer. Used to validate tokens and (if discovery is disabled.enabled) to discover the provider's endpoints. Use https://login.microsoftonline.com/<DirectoryDIRECTORY_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 (tenant)client) ID>/oauth2/v2.0/authorize
.
-
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 displayname 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://your-domain/matrix.example.com/_synapse/client/oidc/backchannel_logout
in your identity providerprovider, 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
Contents
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
- Click on
New Application
- Click on
Create your own application
on the top 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
-
ClientEdit
Authon MethodBasic SAML Configuration
- In
Identifier
, add the following URL : authhttps://synapse_fqdn/_synapse/client/saml2/metadata.xml
method
- Remove the default URL
- In
Reply URL
, add the following URL : https://synapse_fqdn/_synapse/client/saml2/authn_response
- Click on
Save
- 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 use when exchangingadd the token.following Set(suggested) itclaims (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 ClientDelegated Secret PostAuth
orand anyset methodthe supportedfollowing by(suggested) yourfields Idpin the installer:
-
Allow Unknown Attributes.
Checked
-
Attribute Map.
Select URN:Oasis:Names:TC:SAML:2.0:Attrname Format:Basic
as the Identifier
-
ClientMapping.
Set ID
:the yourfollowing mappings:
- From:
ApplicationPrimary (client)Email
IDTo: email
- From:
DiscoverFirst Name
: enable/disableTo: the use of the OIDC discovery mechanism to discover endpoints
firstname
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,From: IdpLast Name
is set toTo: Azure ADlastname
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"
Scopes: add every scope on a different line
-
Entity.
-
Description.
-
Entity ID. (From Azure)
-
Name.
-
User Mapping
Provider:Provider.
Set Configurationthe for how attributes returned from a OIDC provider are mapped onto a matrix user.
following:
-
LocalpartMXID TemplateMapping
: Jinja2 template for the localpart of the MXID. Set it to {{ user.preferred_username.split('@')[0] }}Dotreplace
for Azure AD
-
DisplayMXID NameSource TemplateAttribute
: Jinja2 template for the display name to set on first login. If unset, no displayname will be set. Set it to {{ user.name }}uid
for Azure AD
Other configurations are documented here.
OpenID
on-
MicrosoftMetadata ADURL.
Add FSthe SAMLApp onFederation MicrosoftMetadata Azure
URL from Azure.
LDAP on Windows AD
In
-
Base
: the.
The distinguished name of the root level Org Unit in your LDAP directory. -
Bind
Dn: theDN.
The distinguished name of the LDAP account with read access. -
Filter
: an.
A LDAP filter to filter out objects under the LDAP Base DN. -
Uri: theURI.
The URI of your LDAPserver.server(ldap://dc.example.com
.- This is often your Domain
Controller)Controller, can also pass inldaps://
for SSL connectivity. - The following are the typical ports for Windows AD LDAP servers:
-
ldap://ServerName:389
-
ldaps://ServerName:636
-
- This is often your Domain
-
LDAP Bind Password
: the.
The password of the AD account with read access. -
LDAP Attributes.
-
Mail.
mail
-
Name.
cn
-
UID.
sAMAccountName
-
Mail.
OpenID on Microsoft Azure
Before settingconfiguring upwithin 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, wherematrix
is the subdomain of Synapse andexample.com
is your base domain as configured on the Domains section:https://matrix.
your-domain.example.com/_synapse/client/oidc/callback
For the bridge to be able to operate correctly, navigate to API permissions, add Microsoft Graph APIs, choose Delegated Permissions and addadd:
-
openid
-
profile
-
email
Remember to grant the admin consent for those.
To setup the installer, you'll needneed:
theThe
Application (client) ID
theThe
Directory (tenant) ID
aA secret generated from
Certificates &
on the app.secretsSecrets
Configure the installer
Add
an
-
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 intheyour'Synapse'configuration,configurationthisafter enablingDelegated Authand 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 couldwill beusedauto-generatedifforswitchingyoufrom(butpasswordcanloginsbeto OIDC.-
AuthorizationIdPEndpoint:Brand.
An optional brand for this identity provider, allowing clients to style theoauth2loginauthorizationflowendpoint.accordingRequiredtoifthe identity provider in question. -
Issuer.
The OIDC issuer. Used to validate tokens and (if discovery isdisabled.enabled) to discover the provider's endpoints. Usehttps://login.microsoftonline.com/
replacing<DirectoryDIRECTORY_TENNANT_ID/v2.0DIRECTORY_TENNANT_ID
. -
Client Auth Method.
Auth method to use when exchanging the token. Set it toClient Secret Post
or any method supported by your IdP. -
Client ID.
Set this to yourApplication (
.tenant)client) ID>/oauth2/v2.0/authorize -
Client Secret.
Set this to the secret value defined under "Certificates and secrets". -
Scopes.
By defaultopenid
,profile
andemail
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 displayname will be set. Set it to{{ user.name }}
.
-
Localpart Template.
-
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 tohttps://
in your identityyour-domain/matrix.example.com/_synapse/client/oidc/backchannel_logoutproviderprovider, wherematrix
is the subdomain of Synapse andexample.com
is your base domain as configured on the Domains section.
OpenID on Microsoft AD FS
Contents
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
- Click on
New Application
- Click on
Create your own application
on the top 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
-
ClientEditAuthonMethodBasic SAML Configuration
- In
Identifier
, add the following URL :authhttps://synapse_fqdn/_synapse/client/saml2/metadata.xml
method - Remove the default URL
- In
Reply URL
, add the following URL :https://synapse_fqdn/_synapse/client/saml2/authn_response
- Click on
Save
- Make a note of the
App Federation Metadata Url
underSAML Certificates
as this will be required in a later step. -
Edit
onAttributes & Claims
- Remove all defaults for additional claims
- Click on
Add new claim
touse when exchangingadd thetoken.followingSet(suggested)itclaims (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
- Name:
- 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 ClientDelegated Secret PostAuthorand anyset methodthe supportedfollowing by(suggested) yourfields Idpin the installer:
-
Allow Unknown Attributes.
Checked -
Attribute Map.
SelectURN:Oasis:Names:TC:SAML:2.0:Attrname Format:Basic
as theIdentifier
-
ClientMapping.
SetID:theyourfollowing mappings:- From:
ApplicationPrimary(client)EmailIDTo:email
- From:
DiscoverFirst Name:enable/disableTo:the use of the OIDC discovery mechanism to discover endpointsfirstname
Idp Brand: an optional brand for this identity provider, allowing clients to style the login flow according to the identity provider in questionIdp ID: a string identifying your identity provider in your configurationIdp 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,From:IdpLast Nameis set toTo:Azure ADlastname
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.0Token Endpoint: the oauth2 authorization endpoint. Required if provider discovery is disabled.Client Secret: your secret value defined under "Certificates and secrets"
Scopes: add every scope on a different line-
Entity.
-
Description.
- Entity ID. (From Azure)
-
Name.
-
Description.
-
User Mapping
Provider:Provider.
SetConfigurationthefor how attributes returned from a OIDC provider are mapped onto a matrix user.following:-
:LocalpartMXIDTemplateMappingJinja2 template for the localpart of the MXID. Set it to{{ user.preferred_username.split('@')[0] }}Dotreplacefor Azure AD -
:DisplayMXIDNameSourceTemplateAttributeJinja2 template for the display name to set on first login. If unset, no displayname will be set. Set it to{{ user.name }}uidfor Azure AD
Other configurations are documentedhere. -
OpenID - From:
-
MicrosoftMetadataADURL.
AddFSthe
URL from Azure.SAMLApp
onFederationMicrosoftMetadataAzure