Skip to main content

Setting up Group Sync with the Installer

What is Group Sync?

Group Sync allows you to use the ACLs from your identity infrastructure in order to set up permissions on Spaces and Rooms in the Element Ecosystem. Please note that the initial version we are providing only supports a single node, non-federated configuration.

General settings

  • Create ~/.element-onpremise-config/groupsync
  • Copy sample file from config-sample/groupsync/gsync.yml in the installer directory to ~/.element-onpremise-config/groupsync 
mkdir ~/.element-onpremise-config/groupsync
cp config-sample/groupsync/gsync.yml ~/.element-onpremise-config/groupsync/
  • Edit the file with the following values :
    • group_power_levels : A list of groups that'll determine people's Matrix power levels. This affects only the space that the Group belongs to – doesn't leak up or down. For MSGraph source, groups should be identified by their ids. On LDAP, they should be identified by their names.
    • provisioner.dn_default_prefix: Display names starting with this prefix will get corrected according to the names we found for their users in LDAP. Optional. Useful if you're using an OIDC provider that doesn't give you users' display names.
    • provisioner.default_rooms : Optional. A list of rooms that'll get automatically created in in managed space. The ID is required to enable Group Sync to track whether they were already created or not. You can change it, but it'll cause new rooms to be generated.
    • provisioner.whitelisted_users : Optional. A list of userid patterns that will not get kicked from rooms even if they don't belong to them according to LDAP. This is useful for things like the auditbot. Patterns listed here will be wrapped in ^ and $ before matching.
    • verify_tls : Optional. If doing a POC with self-signed certs, set this to 0. The default value is 1.

Configuring the source

LDAP Servers

  • You should create a ldap account with read access to the OUs containing the users
  • This account should use password authentication
  • To use LDAP source, copy the file config-sample/groupsync/ldap.yml in the installer directory to ~/.element-onpremise-config/groupsync 
cp config-sample/groupsync/ldap.yml ~/.element-onpremise-config/groupsync/

edit the following variables :

  • ldap_check_interval_seconds: The interval check in seconds
  • ldap_uri: The LDAP Uri to connect to the ldap server
  • ldap_base: The LDAP base used to build the space hierarchy. This OU will become the root space. Every OU below this base will be a child-space.
  • ldap_bind_dn: The user bind dn to use to read the space hierarchy.
  • ldap_bind_password: The user password
  • ldap_attrs_uid: The attribute to use to map to users mxids
  • ldap_attrs_name: The attribute to use to map to spaces names
  • Restart the install script

MS Graph (Azure AD)

  • You need to create an App registration. You'll need the Tenant ID of the organization, the Application (client ID) and a secret generated from Certificates & secrets on the app.

  • For the bridge to be able to operate correctly, navigate to API permissions and ensure it has access to Group.Read.All, GroupMember.Read.All and User.Read.All. Ensure that these are Application permissions (rather than Delegated).

  • Remember to grant the admin consent for those.

  • To use MSGraph source, copy the file config-sample/groupsync/msgraph.yml in the installer directory to ~/.element-onpremise-config/groupsync and edit the following variables :

    • msgraph_tenant_id: This is the "Tenant ID" from your Azure Active Directory Overview
    • msgraph_client_id: Register your app in "App registrations". This will be its "Application (client) ID"
    • msgraph_client_secret : Go to "Certificates & secrets", and click on "New client secret". This will be the "Value" of the created secret (not the "Secret ID").

  • Restart the install script

Space Mapping

The space mapping mechanism allows us to configure additional spaces that Group Sync will maintain, beyond the ones that it creates by default. It is optional – the configuration can be skipped if no additional spaces are to be created.

This is especially useful when used with bridges other than LDAP, which would normally not create any spaces other than the company-wide one. When used with the LDAP backend, the spaces created from LDAP OrgUnits will be added to the list of subspaces of the toplevel space.

Space mapping also replaces the group power level configuration and group filtering, being a superset of their functionality. It is recommended to use space mapping in their stead, as they might eventually be deprecated and removed.

Note: transitioning to space mapping

If you're using Group Sync already and want to transition to space mapping, make sure to match the root space ID with the one that Group Sync has already created by default -- otherwise it will create a brand new space and forget about the old one.

For LDAP, the default ID is the DN (distinguished name) of your main OrgUnit.

For MS Graph, the ID should be your tenant ID.

For SCIM, use scim:<client-id>, where the client-id is what you have defined in client.id in your configuration.

You can verify what the ID of the existing space is by running Group Sync in dry-run mode (-n1 launch parameter).

Configuration

We define each space giving it a name (which will be displayed in Element), a unique ID (which allows Group Sync to track the Space even if it gets renamed), and a list of groups whose users will become the members of the Space. Users needs to be a member of any configured group, not all of them.

You can pick any ID you want (taking note of the section above), but if you change it later Group Sync will create a brand new space and abandon the old ones, likely confusing the users.

Each group may optionally include a powerLevel setting, allowing specific groups to have elevated permissions in the space.

A special group ID of '' (an empty string) indicates that all users from the server, regardless of their group membership, should become the members of the Space.

An optional list of subspaces may also be configured, each using the same configuration format and behaviour (recursively).

The default Group Sync behaviour is equivalent to the following Space Mapping:

spaces:
  id: root
  name: 'Company'
  groups:
    - externalId: '' # include all users, not limited to any group

In order to limit space membership to a specific Group, we include its Group ID. This is equivalent to the group_filter configuration option.

spaces:
  id: root
  name: 'Company'
  groups:
    - externalId: 'element-users'

With powerLevel option allows us to give users extra permissions. This is equivalent to the group_power_level setting[^note].

[^note]: In the LDAP bridge group_power_level is the only way to assign permissions to spaces automatically generated from LDAP OrgUnits. If you define both space mapping and group_power_level in your configuration, group_power_level will only be used for the automatically generated spaces, it will not be taken into account for the spaces defined manually in your space mapping config.

spaces:
  id: root
  name: 'Company'
  groups:
    # regular users
    - externalId: 'element-users'
    # moderators
    - externalId: 'element-moderators'
      powerLevel: 50

In case of Power Level conflicts, the highest power level will be used. With the following configuration:

spaces:
  id: root
  name: 'Company'
  groups:
    - externalId: 'moderators'
      powerLevel: 50
    - externalId: 'admins'
      powerLevel: 100

A user who's a member of both moderators and admins will end up with Power Level of 100.

Subspaces can be configured analogically:

spaces:
  id: shared
  name: "Element Corp"
  groups:
  - externalId: 'matrix-mods'
    powerLevel: 50
  - externalId: ''
  subspaces:
  - id: london
    name: "London Office"
    groups:
    - externalId: 'london-matrix-mods'
      powerLevel: 50
    - externalId: 'london-employees'
Back to top