Space mapping

This mechanism allows us to configure spaces that Advanced Identity and Access Management will maintain.

Configuration

We define each space giving it a name (which will be displayed in Element), a unique ID (which allows Advanced Identity and Access Management 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, but if you change it later Advanced Identity and Access Management will create a brand new space and abandon the old ones, likely confusing the users.

In order to limit space membership to a specific Group, we include its Group ID.

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.

In addition to regular groups, you may also make a space federated by specifying federatedGroups and a remote Advanced Identity and Access Management server. See Federation for more details.

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

If a space has subspaces configured, its members list will be composed of the members of the space itself and any of its subspaces, recursively — so a subspace's member list is always a subset of its parent space's member list. This may change in the future, so it's advised not to rely on this when configuring your spaces.

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

The powerLevel option allows enabling different permissions for each group. The default is 0 if the group doesn't define a power level.

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'

Preserving elevated power levels

Note, this feature will be available starting from ESS Pro version 26.10.0.

If wanted, Advanced IAM can be configured to preserve elevated power levels for users who it thinks have a too high power level. This can be done for the whole space hierarchy, or just a part of the space tree. Child spaces and rooms automatically inherit this setting from their parents, where if a room has several space parents, a space enabling preserving power levels wins.

This feature allows users who create new rooms into the space tree to keep their admin permissions, and allows manually promoting users to a higher level than they would otherwise receive from the group mappings.

Note, if the group power level is decreased, and preserving power levels is enabled, Advanced IAM will not apply the new group power level in spaces if it is configured to preserve elevated power levels.

Preserving elevated power levels is disabled by default.

Example config to preserve elevated power levels in the whole space tree:

spaces:
  id: root
  name: 'Company'
  preserveElevatedPLs: true
  groups:
    - externalId: ''

Example config to preserve elevated power levels in a child space:

spaces:
  id: root
  name: 'Company'
  groups:
    - externalId: ''
  subspaces:
  - id: london
    name: "London Office"
    preserveElevatedPLs: true
    groups:
    - externalId: 'london-employees'

It is also possible to configure the whole space tree to preserve elevated power levels, but configure one particular child space branch to not do so:

spaces:
  id: root
  name: 'Company'
  preserveElevatedPLs: true
  groups:
    - externalId: ''
  subspaces:
  - id: london
    name: "London Office"
    preserveElevatedPLs: false
    groups:
    - externalId: 'london-employees'
  - id: berlin
    name: "Berlin Office"
    # Doesn't need `preserveElevatedPLs: true`, as it is inherited
    groups:
    - externalId: 'berlin-employees'