Skip to main content

Setting up Delegated Authentication with 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.

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.

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.
  • Additionally, this guide provides more details on how to create a certificate template.

Install AD FS

You need to 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

Screenshot 2023-06-22 at 15.55.57.png

  • Click Next

Screenshot 2023-06-22 at 15.57.41.png

  • Select the SSL Certificate and set a Federation Service Display Name

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

Screenshot 2023-06-22 at 16.04.13.png

  • Choose your database

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

Screenshot 2023-06-22 at 16.39.52.png

  • Enter https://<matrix domain>/_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)

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``

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

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

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/<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.
  • 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

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://<your-adfs.domain.com>/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.

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.