Sync Azure Entra ID Groups with CloudSoda Roles

The identity-bridge service can be used to perform a full sync one time, periodically, or in response to a webhook. The sync can be run in the foreground or background (as a daemon).

Prerequisites

MS Entra ID (Azure AD) Setup

Before running identity-bridge, you must configure an application in MS Entra ID with the appropriate permissions.

1. Register an Application

1. Go to Azure Portal > Microsoft Entra ID > App registrations
2. Click New registration
3. Configure the application:
   • Name: CloudSoda Identity Bridge (or similar)
   • Supported account types: Accounts in this organizational directory only
   • Redirect URI: Leave blank (not needed for daemon apps)
4. Click Register
5. Note down:
   • Application (client) ID - this is azure-client-id
   • Directory (tenant) ID - this is azure-tenant-id

2. Create a Client Secret

1. In your app registration, go to Certificates & secrets
2. Click New client secret
3. Add a description and select an expiration period
4. Click Add
5. Copy the secret value immediately (you won't see it again) - this is azure-client-secret

3. Grant API Permissions

The tool requires Microsoft Graph API permissions to read users and groups.

1. In your app registration, go to API permissions
2. Click Add a permission > Microsoft Graph > Application permissions
3. Add the following permissions:

4. Click Grant admin consent for [your tenant] (requires Global Administrator or Privileged Role Administrator)

MS Entra Group Configuration

Identity-bridge matches MS Entra groups to CloudSoda roles by exact name. For synchronization to work:

1. Create Security Groups or Microsoft 365 Groups in MS Entra with names that exactly match your CloudSoda role names
2. Add users to the appropriate groups

Important:

• Group names are case-sensitive and must match exactly
• Only Security Groups (securityEnabled = true) and Microsoft 365 Groups are supported
• Users are matched between systems by their email address

CloudSoda Setup

You also need OAuth credentials from CloudSoda:

1. Create an OAuth client in CloudSoda with appropriate permissions to manage users and roles. This client must be a Member and Manger of all the roles you want to sync.
2. Note down:
   • Client ID - soda-client-id in the yaml config
   • Client Secret - soda-client-secret in the yaml config
   • Account ID - the UUID of the CloudSoda account to sync - soda-account-id in the yaml config

General Structure

identity-bridge [--debug] 

Commands and their meaning are:

• help – display general usage and exit
• run – perform the sync between CloudSoda and MS-Entra ID, see below the different modes
• status – tell if the program is running in daemon mode
• stop – in case the program is running in daemon mode, it will stop it

General Execution Environment

n order to perform the synchronization between CloudSoda and MS-Entra (i.e. the run command), the service needs the following information to be set in a configuration file passed to the -c/--config flag. This information is required for all execution modes (one time or periodically):

Notes

• (1) --debug flag must be set before commands
• (2) --period values are specified as a number and time measurement suffix, valid values are s (seconds), m (minutes), h (hours), d (days). Several values can be combined, e.g. 1h30m, 5m20s, 1d30m. The minimum value is 1m.

Sync One Time

In this mode, the program performs the sync one time and then exits.

General command structure:

identity-bridge [--debug] run -c config.yaml --once [--dry-run] 

To activate this mode, the --once flag must be set. If not set, it syncs periodically (see below).

Optional Flags

• --dry-run – the program will not execute any action. It will just log the changes it would have performed if the flag were not set. In combination with --debug, it will output detailed information on users and roles in tables. Note --dry-run only can be set if --once is also set.

Sync Periodically (Foreground)

In this mode, the program synchronizes the data every 30 minutes; this interval is configurable.

General command structure:

identity-bridge [--debug] run -c config.yaml

Daemon

In this mode, the program launches a background process that runs indefinitely until it is stopped (via stop) or the system is restarted. Both periodic sync and webhook behaviors can be set in daemon mode, so required flags apply. Daemon cannot accept --once nor --dry-run flags.

General command structure:

identity-bridge [--debug] run --daemon [flags (see above)]

To activate daemon mode, the --daemon flag must be set.

When the program is launched in daemon mode, it creates two files: one for logs and second for the OS process identifier (PID). The files are different, depending on platform, as described below:

Notes

• (3) If user is root
• (4) If user is not root
• (5) %PROGRAMDATA% is usually C:\ProgramData
• (6) %SYSTEMDRIVE% is usually C:
• (7) %USERPROFILE% is usually C:\Users\ where is the current user.
• (8) If user is not root, the is the OS user id
• (9) Windows temp directory is any of these variables %TMP%, %TEMP%, %USERPROFILE% in this order

Status

This command indicates if the service is running as daemon or not.

To see daemon status, run:

identity-bridge [--debug] status

Stop

This command stops the daemon.

To stop daemon, run:

identity-bridge [--debug] stop

Validating Your Setup

Before running a live sync, use dry-run mode to verify your configuration:

identity-bridge --debug run --once --dry-run \
  --azure-client-id "your-azure-client-id" \
  --azure-client-secret "your-azure-client-secret" \
  --azure-tenant-id "your-azure-tenant-id" \
  --azure-subscription-id "your-azure-subscription-id" \
  --soda-client-id "your-soda-client-id" \
  --soda-client-secret "your-soda-client-secret" \
  --soda-account-id "your-soda-account-id" \
  --interfacer-url "https://api.your-instance.cloudsoda.io"

This will:

1. Connect to both MS Entra and CloudSoda
2. Fetch users, groups, and roles from both systems
3. Calculate what role assignments would be created or removed
4. Display the results without making any changes

Review the output to ensure:

• Users are being matched correctly by email
• Groups are being matched to roles by name
• The proposed assign/unassign operations are expected