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
- Copy sample file from
config-sample/groupsync/gsync.yml
in the installer directory to~/.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
and 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 theTenant ID
of the organization, theApplication (client ID)
and a secret generated fromCertificates & 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
Define 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'