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

mkdir ~/.element-onpremise-config/groupsync
cp config-sample/groupsync/gsync.yml ~/.element-onpremise-config/groupsync/

Configuring the source

LDAP Servers

cp config-sample/groupsync/ldap.yml ~/.element-onpremise-config/groupsync/

edit the following variables :

MS Graph (Azure AD)

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'

Revision #9
Created 18 April 2022 14:32:09 by Karl Abbott
Updated 22 September 2022 20:46:11 by James Reilly