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.
- Create ~/.element-onpremise-config/groupsync
- Copy sample file from
config-sample/groupsync/gsync.ymlin the installer directory to
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
- 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.ymlin the installer directory to
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 IDof the organization, the
Application (client ID)and a secret generated from
Certificates & secretson 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.ymlin the installer directory to
~/.element-onpremise-config/groupsyncand 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
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).
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'
powerLevel option allows us to give users extra permissions. This is equivalent to the
[^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
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'