Skip to content

Managing Users

Overview

XMS (XoT Management System) does not manage users directly. Instead, it integrates with an identity source (such as Microsoft Entra ID or Keycloak) and synchronizes users and groups into its own database. Once synchronized, users can be assigned roles and issued client configurations that allow them to connect to the XoT network.

This means that user management in XMS involves three layers:

Identity Source

  • Where users and groups are created and maintained.
  • Can be Keycloak (internal identity provider), Microsoft Entra ID (Azure AD) or other LDAP source.

Directory Synchronization

  • The directory-sync service in XMS pulls users and groups from the identity source into the XMS database.
  • Only users that belong to a group whose ID has been added to XMS and enabled are synchronized.
  • Users must also belong to at least one group to be synchronized.

XMS Roles and Certificates

  • Once users appear in XMS, administrators assign them XMS roles (e.g., Superadmin, Admin).
  • Each user must also have a certificate common name (CN) that matches their email. This is required for client authentication.
  • Finally, a client configuration (certificate package or smart card profile) is generated and distributed to the user.

Identity Sources

Using Microsoft Entra ID

If your organization uses Microsoft Entra ID (Azure AD), then:

  • Users and groups are added to the Entra ID.
  • XMS synchronizes them via the directory-sync service.
  • Group membership in Entra ID determines which users are imported into XMS.

Adding users in Entra ID:

  1. Go to the Azure Portal Users page.
  2. Click New user.
  3. Choose Create new user for employees.
  4. Choose Invite external user for external collaborators.
  5. Provide at least an email, first name, and last name.

Adding groups in Entra ID:

  1. Go to the Azure Portal Groups page.
  2. Click New group.
  3. Group type: Security
  4. Membership type: Assigned
  5. Provide a group name.

Assigning users to groups:

  • Either add users directly to a group, or assign group membership from the user’s profile.

Using Keycloak

It is possible to avoid using any external identity provider if that is desired, by using the XMS authentication service, Keycloak, as an identity provider.

This is usually recommended for trial installations as it is easy to get started and create users as needed without affecting needing to connect to any Entra ID or LDAP source.

If your XMS uses Keycloak as the identity source:

  • Users and groups are created in the Keycloak admin console or via API/CLI.
  • XMS synchronizes them via the directory-sync service.
  • As with Entra ID, only users who belong to at least one group are synchronized.

Adding users in Keycloak:

  1. Log in to the Keycloak admin console.
  2. Select the xms realm.

Select realm

  1. Go to Manage → Users and click Add user.
  2. Set Username (mandatory, ASCII only).
  3. Set Email (mandatory).
  4. Optionally set first/last name.
  5. Toggle Email verified if you have SMTP configured.
  6. Assign the user to one or more groups.
  7. Click Create.
  8. To set a password, go to the Credentials tab and click Set password.

Adding groups in Keycloak:

  1. Go to Manage → Groups.
  2. Click Add group.

Adding group modal in Keycloak

  1. Enter a group name and click Create.

Synchronizing Users And Groups

  1. Log in to the XMS web interface as a Superadmin.
  2. Go to System settings → Group synchronization and make sure the groups you want to import present and enabled.
  3. If not all groups are available on this page, make sure that the relevant groups are not being excluded before being imported into XMS.
  4. Then go to Users → List in the main menu.
  5. If new users or groups are missing, click Sync.
  6. Wait a few minutes, then refresh the page. The new users and groups should appear.

Assigning Roles and Certificates in XMS

Once users are synchronized into XMS, they appear in the Users list provided at least one group they belong to is enabled in the web interface. You can now navigate to users by going to Users → List in the main menu. By default, an imported user will not have any permissions to either connect to protected assets or to log in and do administration in the XMS.

Accepted Certificate Common Name

By default, each user will be assigned a certificate common name that is the same as their email, though this value can be changed manually. Keep in mind that the common name in issued certificates must match their user's assigned CN or authentication will fail.

XMS Roles

A user can belong to zero or more roles. Assigned roles are shown in the Roles column of the table in the Users list.

A user not assigned to any XMS role cannot perform any management functions in XMS. They can however connect to any XoT-Lock protected assets they have been given access to through policies. They are also able to fetch client configuration from the XMS via its API, but if they attempt to login to XMS they will get an access denied message.

When a user is assigned at least one role, they will be able to login to XMS and their access rights are determined by the permissions associated with the roles the user hold. While roles and their permissions can be customized (as described in the next section), two high-privilege read-only XMS roles are always available:

Role Description
Superadmin Unrestricted system access
Admin Global administrative access

Both Superadmin and Admin have permissions to manage all resources on the XMS, including assets, policies, and XoTs, as well as system-wide settings such as asset locations and classifications, and firewall rules.

Superadmin has no restrictions.

Admin has all privileges of Superadmin, except for:

  • Uploading XoT firmware
  • Managing group synchronization

More restricted roles can be created in the role editor. Users assigned to these roles can modify only assets and policies, and only those explicitly permitted by the role’s configured permissions. All system-wide settings are read-only for these users.

Managing and Editing Roles

In the Roles page, user-defined roles can be created and managed. This page is located under System settings → Roles.

To create a new role click + Create Role in the top right corner, or select an existing role from the list to manage it.

In the editor, you can configure the role by assigning it a name and description and control which permissions it should have. Here you can also assign members to the role on the right hand side.

New roles start without any permissions. To add a permission, click the + Add permission button. Each permission has a permission type, which is explained in the next section.

Each permission type can be associated with a location (Where) and/or a classification (What). If these are not configured, then the permission is unscoped and applies to all assets or policies. Setting location or classification limits the scope of the permission to only the specified locations and classifications. When both are configured, the resource must match both the location and the classification for the permission to apply.

Permission types

The following permission types are available:

Asset manager

An asset manager is permitted to modify assets. What and Where must match the asset's classification and location.

If an asset is being connected to, is already connected to, or is being disconnected from an XoT-Lock, then the Where must also match that lock’s configured location. Otherwise, the asset manager cannot modify the asset.

Policy manager

A policy manager is permitted to modify policies. What and Where must match the what and where of the policy source and/or destination.

Policy activator

A policy activator is permitted only to toggle the active state of policies. What and Where must match the what and where of the policy source and/or destination.

Creating Client Configurations

Once a user has been imported into the XMS, an administrator can generate a client configuration for them, or are user can create their own configuration and download it themselves.

  1. When logged into XMS, go to Users → Create Client Configuration.
  2. Choose whether the user will use a soft token (certificate file) or a hard token (smart card, YubiKey, etc.).
  3. Set the Common Name to the user’s email.
  4. Set a password (the user will need this when configuring their XoT Client).
  5. Click Generate to create and download the configuration archive (encrypted .zip file).

Create client configuration.

Distributing Client Configurations

Client configuration files must be distributed to users through secure channels, in accordance with your organization’s infrastructure.

The overall security of the XoT Network relies on maintaining the confidentiality and integrity of user configurations.

Please consult your partner, or Xertified directly, if you have any questions.