Configuring Authentication

See how to download example files from the helm chart here.

Overview

The chart components authentication is managed by the top-level key authentication.

The configuration is similar if you use standalone Synapse (legacy authentication) or if you enable Matrix Authentication Service.

You can find configurations examples in charts/matrix-stack/ci/fragments/authentication-secrets-externally.yaml and charts/matrix-stack/ci/fragments/authentication-secrets-in-helm.yaml.

Registration and Password Authentication

The charts come with:

registration disabled by default
password authentication enabled by default

To change this default behaviour, you will have to configure it through the synapse.additional or matrixAuthenticationService.additional key. See Synapse documentation or Matrix Authentication Service documentation for more details.

Restricting allowed clients

When using Matrix Authentication Service in ESS Pro 26.6.0 or later, the clients that can be used to login can be restricted.

matrixAuthenticationService:
  additional:
    restrict-clients.yaml:
      content: |
        policy:
          data:
            pro:
              # The empty list allows no clients
              # To allow all clients, omit entirely
              allowed_client_uris:
                # This includes the Element X & Element Desktop (Pro)
                - "https://element.io/*"
                - "https://<your Element Web domain>/"
                - "https://<your Element Admin domain>/"
              # If present and set to `true`, this denies all clients using compatibility logins
              deny_legacy_clients: true

By default, all clients are allowed.

When restricting logins to specific clients, it is advisable to disable QR code login.

synapse:
  additional:
    disable-qr-code-login.yaml:
      config: |
        experimental_features:
          msc4108_enabled: false

matrixAuthenticationService:
  additional:
    disable-qr-code-login.yaml:
      config: |
        oauth:
          device_code_grant_enabled: false

Configuring LDAP

You can configure a list of LDAP providers to use in the chart. Please refer to the description of the authentication.ldap key in the values file for details.

If LDAP is configured, and Advanced Identity Management is enabled, it will use the first LDAP provider configured in the list as the source of its users.

Configuring OIDC

You can configure a list of OIDC providers to use in the chart. Please refer to the description of the authentication.oidc key in the values file for details.

This section contains sample configurations for popular OIDC providers.

Apple

Sign-in with Apple uses special non-standard for authenticating clients, which requires a special configuration.

authentication:
  oidc:
  - idpId: 0000000000000000000001DCS0
    idpName: OIDC Provider 0
    issuer: <issuer>
    clientId: <clientid>
    clientAuthMethod: client_secret_basic
    clientSecret:
      value: <clientsecret>
    scopes:
    - openid
    - profile
    - email
    forwardLoginHint: false
    fetchUserInfo: false
    responseMode: query
    backchannelLogout: do_nothing
    endpointsDiscovery:
      skipVerification: false
      usePKCE: false

Authelia

These instructions assume that you have already enabled the OIDC provider support in Authelia.

Add a client for MAS to Authelia's configuration.yaml (see the Authelia OIDC documentation for full details):

identity_providers:
  oidc:
    clients:
      - client_id: "<client-id>" # TO BE FILLED
          client_name: Matrix
          client_secret: "<client-secret>" # TO BE FILLED
          public: false
          redirect_uris:
            - https://<mas-fqdn>/upstream/callback/<id>
          scopes:
            - openid
            - groups
            - profile
            - email
          grant_types:
            - 'refresh_token'
            - 'authorization_code'
          response_types:
            - code

Authentication service configuration:

authentication:
  oidc:
  - idpId: 0000000000000000000001DCS0
    idpName: OIDC Provider 0
    issuer: <issuer>
    clientId: <clientid>
    clientAuthMethod: client_secret_basic
    clientSecret:
      value: <clientsecret>
    scopes:
    - openid
    - profile
    - email
    forwardLoginHint: false
    fetchUserInfo: false
    responseMode: query
    backchannelLogout: do_nothing
    endpointsDiscovery:
      skipVerification: false
      usePKCE: false

Authentik

Authentik is an open-source IdP solution.

Create a provider in Authentik, with type OAuth2/OpenID.
The parameters are:
Client Type: Confidential
Redirect URIs: https://<auth-service-domain>/upstream/callback/<id>
Create an application for the authentication service in Authentik and link it to the provider.
Note the slug of your application, Client ID and Client Secret.

Authentication service configuration:

authentication:
  oidc:
  - idpId: 0000000000000000000001DCS0
    idpName: OIDC Provider 0
    issuer: <issuer>
    clientId: <clientid>
    clientAuthMethod: client_secret_basic
    clientSecret:
      value: <clientsecret>
    scopes:
    - openid
    - profile
    - email
    forwardLoginHint: false
    fetchUserInfo: false
    responseMode: query
    backchannelLogout: do_nothing
    endpointsDiscovery:
      skipVerification: false
      usePKCE: false

Facebook

You will need a Facebook developer account. You can register for one here.
On the apps page of the developer console, "Create App", and choose "Allow people to log in with their Facebook account".
Once the app is created, add "Facebook Login" and choose "Web". You don't need to go through the whole form here.
In the left-hand menu, open "Use cases" > "Authentication and account creation" > "Customize" > "Settings"
Add https://<auth-service-domain>/upstream/callback/<id> as an OAuth Redirect URL.
In the left-hand menu, open "App settings/Basic". Here you can copy the "App ID" and "App Secret" for use below.

Authentication service configuration:

authentication:
  oidc:
  - idpId: 0000000000000000000001DCS0
    idpName: OIDC Provider 0
    issuer: <issuer>
    clientId: <clientid>
    clientAuthMethod: client_secret_basic
    clientSecret:
      value: <clientsecret>
    scopes:
    - openid
    - profile
    - email
    forwardLoginHint: false
    fetchUserInfo: false
    responseMode: query
    backchannelLogout: do_nothing
    endpointsDiscovery:
      skipVerification: false
      usePKCE: false

GitLab

Create a new application.
Add the openid scope. Optionally add the profile and email scope if you want to import the user's name and email.
Add this Callback URL: https://<auth-service-domain>/upstream/callback/<id>

Authentication service configuration:

authentication:
  oidc:
  - idpId: 0000000000000000000001DCS0
    idpName: OIDC Provider 0
    issuer: <issuer>
    clientId: <clientid>
    clientAuthMethod: client_secret_basic
    clientSecret:
      value: <clientsecret>
    scopes:
    - openid
    - profile
    - email
    forwardLoginHint: false
    fetchUserInfo: false
    responseMode: query
    backchannelLogout: do_nothing
    endpointsDiscovery:
      skipVerification: false
      usePKCE: false

GitHub

GitHub doesn't support OpenID Connect, but it does support OAuth 2.0. It will use the fetch_userinfo option with a manual userinfo_endpoint to fetch the user's profile through the GitHub API.

Create a new application.
Fill in the form with an application name and homepage URL.
Use the following Authorization callback URL: https://<auth-service-domain>/upstream/callback/<id>
Retrieve the Client ID
Generate a Client Secret and copy it

Authentication service configuration:

authentication:
  oidc:
  - idpId: 0000000000000000000001DCS0
    idpName: OIDC Provider 0
    issuer: <issuer>
    clientId: <clientid>
    clientAuthMethod: client_secret_basic
    clientSecret:
      value: <clientsecret>
    scopes:
    - openid
    - profile
    - email
    forwardLoginHint: false
    fetchUserInfo: false
    responseMode: query
    backchannelLogout: do_nothing
    endpointsDiscovery:
      skipVerification: false
      usePKCE: false

Google

Set up a project in the Google API Console (see documentation)
Add an "OAuth Client ID" for a Web Application under "Credentials"
Add the following "Authorized redirect URI": https://<auth-service-domain>/upstream/callback/<id>

Authentication service configuration:

authentication:
  oidc:
  - idpId: 0000000000000000000001DCS0
    idpName: OIDC Provider 0
    issuer: <issuer>
    clientId: <clientid>
    clientAuthMethod: client_secret_basic
    clientSecret:
      value: <clientsecret>
    scopes:
    - openid
    - profile
    - email
    forwardLoginHint: false
    fetchUserInfo: false
    responseMode: query
    backchannelLogout: do_nothing
    endpointsDiscovery:
      skipVerification: false
      usePKCE: false

Kanidm

Install and configure a Kanidm instance using the Official Docs

Create a OAuth2 Client following the OAuth2 Setup guide

⚠️ Important Ensure you configure the client to prefer short usernames. This means instead of user@domain.tld it will return just user as the preferred username You can configure this by running kanidm system oauth2 prefer-short-username <client_id>.

authentication:
  oidc:
  - idpId: 0000000000000000000001DCS0
    idpName: OIDC Provider 0
    issuer: <issuer>
    clientId: <clientid>
    clientAuthMethod: client_secret_basic
    clientSecret:
      value: <clientsecret>
    scopes:
    - openid
    - profile
    - email
    forwardLoginHint: false
    fetchUserInfo: false
    responseMode: query
    backchannelLogout: do_nothing
    endpointsDiscovery:
      skipVerification: false
      usePKCE: false

Keycloak

Follow the Getting Started Guide to install Keycloak and set up a realm.

Click Clients in the sidebar and click Create
Fill in the fields as below:

Field	Value
Client ID	`matrix-authentication-service`
Client Protocol	`openid-connect`

Click Save
Fill in the fields as below:

Field	Value
Client ID	`matrix-authentication-service`
Enabled	`On`
Client Protocol	`openid-connect`
Access Type	`confidential`
Valid Redirect URIs	`https://<auth-service-domain>/upstream/callback/<id>`
Front channel logout	`Off`
Backchannel logout URL	`https://<auth-service-domain>/upstream/backchannel-logout/<id>`
Backchannel logout session required	`On`

Click Save
On the Credentials tab, update the fields:

Field	Value
Client Authenticator	`Client ID and Secret`

Click Regenerate Secret
Copy Secret

authentication:
  oidc:
  - idpId: 0000000000000000000001DCS0
    idpName: OIDC Provider 0
    issuer: <issuer>
    clientId: <clientid>
    clientAuthMethod: client_secret_basic
    clientSecret:
      value: <clientsecret>
    scopes:
    - openid
    - profile
    - email
    forwardLoginHint: false
    fetchUserInfo: false
    responseMode: query
    backchannelLogout: do_nothing
    endpointsDiscovery:
      skipVerification: false
      usePKCE: false

Microsoft Azure Active Directory

Azure AD can act as an OpenID Connect Provider. Register a new application under App registrations in the Azure AD management console. The RedirectURI for your application should point to your authentication service instance: https://<auth-service-domain>/upstream/callback/<id> where <id> is the same as in the config file.

Go to Certificates & secrets and register a new client secret. Make note of your Directory (tenant) ID as it will be used in the Azure links.

Authentication service configuration:

authentication:
  oidc:
  - idpId: 0000000000000000000001DCS0
    idpName: OIDC Provider 0
    issuer: <issuer>
    clientId: <clientid>
    clientAuthMethod: client_secret_basic
    clientSecret:
      value: <clientsecret>
    scopes:
    - openid
    - profile
    - email
    forwardLoginHint: false
    fetchUserInfo: false
    responseMode: query
    backchannelLogout: do_nothing
    endpointsDiscovery:
      skipVerification: false
      usePKCE: false

Discord

Create a new application in the Discord Developer Portal (see documentation)
Add the following "Redirect URI" in the OAuth2 tab under settings: https://<auth-service-domain>/upstream/callback/<id>

Authentication service configuration:

authentication:
  oidc:
  - idpId: 0000000000000000000001DCS0
    idpName: OIDC Provider 0
    issuer: <issuer>
    clientId: <clientid>
    clientAuthMethod: client_secret_basic
    clientSecret:
      value: <clientsecret>
    scopes:
    - openid
    - profile
    - email
    forwardLoginHint: false
    fetchUserInfo: false
    responseMode: query
    backchannelLogout: do_nothing
    endpointsDiscovery:
      skipVerification: false
      usePKCE: false

Rauthy

Click Clients in the Rauthy Admin sidebar and click Add new Client
Fill in the fields as below:

Field	Value
Client ID	`matrix-authentication-service`
Client Name	`matrix-authentication-service`
Redirect URI	`https://<auth-service-domain>/upstream/callback/<id>`

Set the client to be Confidential.
Click Save
Select the client you just created from the clients list.
Enable the authorization_code, and refresh_token grant types.
Set the allowed scopes to openid, profile, and email.
Set both Access Algorithm and ID Algorithm to RS256.
Set PKCE challenge method to S256.
Click Save
Copy the Client ID from the Config tab and the Client Secret from the Secret tab.

Authentication service configuration:

authentication:
  oidc:
  - idpId: 0000000000000000000001DCS0
    idpName: OIDC Provider 0
    issuer: <issuer>
    clientId: <clientid>
    clientAuthMethod: client_secret_basic
    clientSecret:
      value: <clientsecret>
    scopes:
    - openid
    - profile
    - email
    forwardLoginHint: false
    fetchUserInfo: false
    responseMode: query
    backchannelLogout: do_nothing
    endpointsDiscovery:
      skipVerification: false
      usePKCE: false

To use a Rauthy-supported Ephemeral Client, use this JSON document:

{
  "client_id": "https://path.to.this.json",
  "redirect_uris": [
    "https://your-app.com/callback"
  ],
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "access_token_signed_response_alg": "RS256",
  "id_token_signed_response_alg": "RS256"
}

Shibboleth

Shibboleth is an open-source identity management system commonly used by universities and research institutions. It is primarily based on SAML but also supports OIDC via the OIDC OP Plugin.

These instructions assume you have a running Shibboleth instance with the OIDC plugin configured.

Register MAS as a relying party in Shibboleth:

Add a metadata file (e.g. mas-metadata.xml) to %{idp.home}/metadata/ with the following content:

   <?xml version="1.0" encoding="UTF-8"?>
   <EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
                     xmlns:oidcmd="urn:mace:shibboleth:metadata:oidc:1.0"
                     entityID="<client-id>">
       <Extensions>
           <oidcmd:ClientInformation>
               <oidcmd:ClientSecret><client-secret></oidcmd:ClientSecret>
           </oidcmd:ClientInformation>
       </Extensions>
       <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
           <Extensions>
               <oidcmd:OIDCClientInformation scopes="openid profile email"
                                             token_endpoint_auth_method="client_secret_basic">
                   <oidcmd:GrantType>authorization_code</oidcmd:GrantType>
                   <oidcmd:ResponseType>code</oidcmd:ResponseType>
               </oidcmd:OIDCClientInformation>
           </Extensions>
           <AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                                     Location="https://<auth-service-domain>/upstream/callback/<id>"
                                     index="1"/>
       </SPSSODescriptor>
   </EntityDescriptor>

Replace <client-id>, <client-secret>, <auth-service-domain>, and <id> with your values.

Reference the metadata file in %{idp.home}/conf/metadata-providers.xml and reload services.

Authentication service configuration:

authentication:
  oidc:
  - idpId: 0000000000000000000001DCS0
    idpName: OIDC Provider 0
    issuer: <issuer>
    clientId: <clientid>
    clientAuthMethod: client_secret_basic
    clientSecret:
      value: <clientsecret>
    scopes:
    - openid
    - profile
    - email
    forwardLoginHint: false
    fetchUserInfo: false
    responseMode: query
    backchannelLogout: do_nothing
    endpointsDiscovery:
      skipVerification: false
      usePKCE: false