Skip to content

Microsoft Entra ID Integration for XMS

Use this guide when XMS should authenticate users and/or synchronize users and groups from Microsoft Entra ID (Azure AD).

If you selected Microsoft Entra ID as user source during XMS setup, XMS already prepares the directory-sync template for Azure. You can also run scripts/entra-id-sync-setup.sh on the XMS host to configure sync interactively.

1. Authentication Setup (OIDC)

1.1 Create an App Registration

In Azure Portal:

  1. Go to App registrations and select New registration.
  2. Name it (for example xms-auth).
  3. For supported account types, choose Accounts in this organizational directory only (single tenant).
  4. Set Redirect URI platform to Web.

1.2 Note the Application (Client) ID

Save the Application (client) ID. You will use it when configuring the identity provider in Keycloak.

1.3 Add Redirect URI

Configure this redirect URI in the app registration:

https://<XMS-FQDN>/idp/realms/xms/broker/oidc/endpoint

1.4 Create Client Secret

In Certificates & secrets, create a new client secret and save its value immediately. You cannot retrieve this value later.

2. User Synchronization Setup (Microsoft Graph)

2.1 Create a Separate App Registration

Create another app registration (for example xms-user-sync):

  1. Go to Microsoft Entra ID -> App registrations -> New registration.
  2. Choose Accounts in this organizational directory only (recommended).
  3. Leave Redirect URI empty.

2.2 Set API Permissions

In the new app registration:

  1. Go to API permissions.
  2. Select Add a permission -> Microsoft Graph -> Application permissions.
  3. Add:
  4. User.Read.All
  5. Group.Read.All
  6. Select Grant admin consent for .

3. Configure Directory Sync on XMS

Edit:

/etc/xms/config/directory-sync/application.yaml

In config.repository.graph.authentication:

  • Set public-client-id to the Application (client) ID from the user-sync app registration.
  • Set authority to https://login.microsoftonline.com/<tenant-id>, replacing <tenant-id> with your Microsoft Entra tenant ID.

4. Certificate-Based Authentication for Sync

Generate a certificate and key for directory-sync:

sudo openssl req -x509 -days 3650 -newkey rsa:2048 \
  -keyout /etc/xms/secrets/directory-sync/private-key-with-pass.pem \
  -out /etc/xms/secrets/directory-sync/public-certificate.pem

Convert the private key to PKCS#8 without password:

openssl pkcs8 -topk8 -nocrypt \
  -in /etc/xms/secrets/directory-sync/private-key-with-pass.pem \
  -out /etc/xms/secrets/directory-sync/private-key.pem

Move private-key-with-pass.pem to secure storage after conversion.

4.1 Upload Public Certificate to Azure

Upload /etc/xms/secrets/directory-sync/public-certificate.pem to the user-sync app registration:

App registrations -> <your app> -> Certificates & secrets -> Certificates -> Upload certificate

5. Configure Which Groups to Synchronize

Only users in configured Entra groups are synchronized.

  1. In Azure Portal, open each target group and copy its Object ID.
  2. Update group configuration in /etc/xms/config/directory-sync/application.yaml according to your template structure.
  3. Restart directory-sync:
cd /usr/share/xms
docker compose restart directory-sync

After synchronization completes, users and groups should appear in XMS. Verify by checking the Users section in the XMS dashboard.

If users do not appear, check the directory-sync logs:

cd /usr/share/xms
docker compose logs directory-sync

Common issues include incorrect Application (client) ID, missing admin consent on API permissions, or the certificate not matching between the XMS host and the Azure app registration.