Skip to main content
Version: Cloud

Installing Cloud Application Gateway

This section provides detailed information on the prerequisites, installation, registration, and optional configuration of the CAG.

System requirements​

The following general and deployment-method-specific requirements need to be fulfilled to properly operate the CAG.

note

The Provisioning Worker Service and Import Worker Service each consume between 30 to 50 MB of memory when in the idle state. Each individual Provisioning Worker utilizes around 10 MB of memory when in idle state, with the demanded capacity increasing with running imports or performed provisioning tasks. It is especially impacted by large amounts of data imports with CustomRowFilter configured that might also contain nested URLs.

General conditions​

Before you initiate the deployment process, make sure that the following conditions are met:

  • Operating System - Windows Server 2022 is required, with all editions supported
  • .Net Framework - Version 4.8 is required for the legacy libraries and integrations
  • .NET Runtime - Version 8.0x is required

Deployment-specific conditions​

The following conditions must be met based on the chosen deployment variant.

  1. Fulfill the general conditions.
  2. Copy the application files and follow the deployment script or initiate the installer.
  3. Configure the Windows Firewall and, if it applies, the Internet Information Services (IIS).
Sizing input

Following measurements are basis for the deployment conditions.

CPU and memory utilization

ActivityCPU usage (%)Memory (MB)
Idle0.140
Light Load (20 rec/min)2–345–50
Nominal Load (80 rec/min)~7~60
High Load (160 rec/min)*~12–14~70

Per instance bandwidth summary

Load levelRecords/minTotal KB/s
Idle00.217
Light203.58
Medium8013.78
High16027.45
Heavy32054.58

Total bandwidth for 20 instances

Load levelTotal KB/sTotal Mbps
Idle0.217 × 20 = 4.34 KB/s~0.034 Mbps
Light3.58 × 20 = 71.6 KB/s~0.56 Mbps
Medium13.78 × 20 = 275.6 KB/s~2.15 Mbps
High27.45 × 20 = 549.0 KB/s~4.29 Mbps
Heavy54.58 × 20 = 1,091.6 KB/s~8.54 Mbps

System resources estimates for 20 instances

ModeTotal CPU usage (all cores)Total RAM usage
Idle~2% (20 × 0.1%)~800 MB (20 × 40 MB)
Active~140% (20 × 7%)~1.3 GB (20 × 60 MB)
Peak~240–280%~1.5 GB

Minimum required permissions for service accounts​

By default, the provided PowerShell script registers the Windows Service to run under the Local System context. You can optionally configure the service to run under a dedicated service account instead.

  1. Log On as a Service

    The service account must be granted “Log on as a service” user right to run Windows services.

  2. NTFS File System Permissions

    • Assign the following file permissions to the service account on relevant directories:

      • Read, Write, Modify, Delete

    • Apply to:

      • Service installation directories

      • Worker process directories

      • Connectivity package directories

      • Backup directory

    note

    Ensures operational access for read/write, configuration changes, and file management.

  3. Service Control Rights

    The service must be able to start and stop itself. Ensure necessary Start/Stop service permissions are granted.

  4. Private Key Access

    • Provide the service account with access to key material required for private key usage.

    • Refer to the Registration process documentation for exact file or store locations.

  5. Trusted Certificate Authority

    • The host system must trust the internal CA that signs service binaries and scripts.

    • Import the CA’s public certificate into trusted root certification authorities store.

Credentials for each source or target system are managed during system onboarding in Omada Identity Cloud.

For details on required permissions, go to the Connectors section.

Installing Cloud Application Gateway​

Installation and enabling the CAG solution consists of the following main steps:

  1. Download
  2. Registration
  3. Registration of Worker Services

Downloading Cloud Application Gateway components​

Important

For guidance on how to enable or migrate to the CAG solution, contact the Omada Support.

The solution is available for download from the Cloud Management Portal for Horizons-enabled instances.

  1. Go to the environment overview and from the extended view, download the .zip format file for the CAG.

  2. Unpack the .zip format file and run the installer following the instructions.

After downloading the package from the Cloud Management Portal, extract all files to the desired location.

Important

By default, the downloaded .dll format files are blocked by Microsoft to protect the users unit from malicious exposure. To allow the CAG solution to work correctly make sure that files in the Connectivity folder are unblocked.

CAG is organized into three subfolders:

  • Connectivity - contains the required libraries for all the Connectivity Packages provided by Omada
  • Import - contains the required files for the Import Worker Service
  • Provisioning - contains the required files for the Provisioning Worker Service
Important

Do not change the folder structure.

Refer to the prerequisites sections in the Connectors documentation for any drivers that might be required to be installed on the server where you have deployed the CAG.

Registration​

Before the initial startup, the CAG requires registration to the Omada Identity Cloud.

For guidelines on the registration process, go to the Security documentation.

Registering Multiple CAGs
  1. Perform the initial CAG registration on a primary VM, following the guidelines in the Security documentation.
  2. To register a CAG on an additional VM, clone the CAG setup from the primary VM:
    1. Export the private key from the primary VM.
    2. Import the private key into the additional VM.
  3. If the additional VM needs to connect to a different target system, update the InstanceGroupId setting in the appsettings.Customer.json file. No further re-registration is required.

For more details on instance groups, see the Instance groups section.

Registering Worker Services​

The Cloud Application Gateway consists of two main components: the Import Worker Service and the Provisioning Worker Service. Both services can be operated in two ways:

  • As a command-line application (useful for troubleshooting)
  • As an installed Windows service (recommended deployment)

Each service has to be initiated individually.

note

When registering or starting the Worker or the Provisioning Service as a console application, running it from a standard Command Prompt or PowerShell session is a recommended practice. Avoid using tools such as PowerShell ISE, as they can interfere with console output. Proper console output is required for specific operations, for example when registering a private key using a certificate file.

  • Console mode - the service is started from the Import\Worker Service\Omada.Identity.Import.WorkerService.exe file.
  • Windows service - to add it as a Windows service execute the Import\WorkerSetup.ps1 script with administrative rights.
Important

Omada recommends saving and closing all configuration files before initiating the Import and the Provisioning Worker Services. Leaving the files open may prevent the files replacement during the auto-update process.

Uninstalling Cloud Application Gateway​

To uninstall Cloud Application Gateway, you need to remove related Windows Services and delete folders created during the installation process.

info

You can remove Windows Services with the SC DELETE <servicename> console command.

Additional configuration​

Here you can find configuration guidelines for some of the CAG features.

Over-the-air upgrade​

When an upgrade is available, the update process is conducted automatically on any local CAG instance.

You can configure the time interval for services to check for available updates in the following places:

  • For the Provisioning worker: appsettings.Customer.json

    Example value
    {
      "AutoUpdate" : {
        "IntervalSeconds" : "15",
        "ReleaseChannel": "stable"
      }
    }

  • For the Import worker: appsettings.Customer.json

    Example value
    {
      "AutoUpdate": {
      "IntervalSeconds": 0,
      "ReleaseChannel": "stable"
      }
    }

For both examples the auto-update check is configured to happen every 15 seconds.

Important

Setting the value to 0 results in disabling the auto-update feature. It can result in the Cloud Application Gateway not working properly if the last updated version is no longer supported.

It includes the creation of a backup of the currently installed version of the Worker Service. You can define where the backup is stored by configuring the History.Path in the appsettings.Customer.json file.

 "History": {
    "Path": "../OmadaProvisioningWorkerHistory"
 }

Proxy support​

You can configure proxy connection in the appsettings.json, for importing, to connect with the target system. It is not used when communicating with the Horizons Cloud Services.

Proxy configuration example
{
   "Proxy" : { 
     "Address": "http://proxy.example.com:8080", // Proxy server address 
     "Username": "user", // Username for proxy authentication 
     "Password": "password", // Password for proxy authentication 
     "BypassOnLocal": false, // Determines if proxy should be skipped on local request 
     "BypassHosts": [] // Hosts to bypass, can be an array of strings or regex patterns 
   } 
}

Heartbeat mechanism​

Heartbeat is applied to both the Import Worker and Provisioning Worker.

Default interval is set to 5 minutes and can be configured in the appsettings.json file.

parametervalue
Fileappsettings.json
Sectionserviceconfiguration
KeyHeartbeatIntervalMinutes
"serviceconfiguration": {
  "HeartbeatIntervalMinutes": 5
}
Important

To apply changes to the appsettings.json file, restart the service.

You can adjust both intervals to accommodate performance or monitorin needs.

Heartbeat widget in the Operations dashboard​

To enable the Heartbeat widget in the Operations Dashboard, go to Setup -> Dashboards and edit the configuration by adding the below section to the xml.

{
  name: 'SystemHeartbeats',
  refreshRate: 3600,
  title: S_OperationsDashboard_Text_SystemHeartbeatsWidget_Name,
  infoText: S_OperationsDashboard_Text_SystemHeartbeatsWidget_Info,
  hideTitle: false,
  height: 440,
  params: { },
  isHiddenEvaluator: function() { return !appPageVars.useCAG; }
}

Logging​

Logs for worker process, import and provisioning Worker Services are stored in log targets. You can set them in the XML-based LogConfiguration of the appsetting.Customer.json file, where you specify the targets.

You can find more information on how to set the LogConfiguration in the Event logging section.

Logs structure example

Message: Import Worker Service is available

Metadata:

  • ipAddress
  • machineName
  • serviceName
  • timestamp
  • uptime
  • version

Instance groups​

Instance groups allow you to organize your systems based on shared characteristics such as infrastructure, for example Azure-hosted systems. All newly onboarded systems are automatically assigned to the Default instance group. Creating additional instance groups enables more efficient resource allocation and improves overall CAG performance.

  1. To access instance groups, go to Setup>Connectivity configuration>Cloud Application Gateway Instance Groups.
  1. There you can see a list of existing instance groups.
  • You can add new group
  • You can edit exisiting group
  1. To assign a system to an instance group, configure the Cloud Application Gateway instance setting in the General setting of a system.

  1. To assign a Provisioning Worker Service to an instance group, configure the InstanceGroupId value in the CloudApplicationGatewayConfiguration section in the file appsettings.Customer.json.

  2. To assign an Import Worker Service to an instance group, configure the InstanceGroupId value in the CloudApplicationGatewayConfiguration section in the file appsettings.Customer.json.

InstanceGroupId setting​

You can access the InstanceGroupId setting in the appsettings.Customer.json configuration file. By configuring the setting to a specific group ID you can assign the Worker service, either Import or Provisioning, to a specific Instance Group. If you do not configure the InstanceGroupId setting, it has the Default value.

"CloudApplicationGatewayConfiguration": {
...
"InstanceGroupId": "Default"
}
note

Only systems assigned to the instance group configured in the InstanceGroupId setting undergo the staging step and are processed in the import process.

Configuring security​

Registration process​

In the appsettings.Customer.json file you can choose the storage method of the private key. The following options are available:

  1. As an environment variable
"CloudApplicationGatewayConfiguration" : { ... , "PrivateKeyLocation" : "EnvironmentVariable" }

The private key is encrypted with ASP.NET Core Data Protection. The DataProtectionKeyLocation defines the storage of the protection keys within the machine. This allows multiple users on the machine to access the private keys and register or run CAG services.

Learn more about the ASP .NET Core Data Protection

Important

The HKEY_LOCAL_MACHINE registry location requires administrator permissions during the CAG registration process.

  1. Stored using vault service
"CloudApplicationGatewayConfiguration" : { ... , "PrivateKeyLocation" : "VaultService" }

  • Registration command (applies to both methods) Use the following command in PowerShell to register the worker:

    .\Omada.Identity.Import.WorkerService.exe --Operation=register

    If you prefer to use keys from a certificate, use:

    .\Omada.Identity.Import.WorkerService.exe --Operation=register --FileName="C:\Certs\MyAppCert.pfx"
    Important

    You can use the command for either Import or Provisioning Worker, but not for both. Ensure that "CloudApplicationGatewayConfiguration":"PrivateKeyLocation" is set to the same value for both import and provisioning workers.

It is required that the "CloudApplicationGatewayConfiguration":"PrivateKeyLocation" for import and provisioning worker is set to the same value.

Vault service integration​

Vault service integration allows you to securely store and retrieve the private key as a secret in a vault service. CAG workers support the following vault services, each offering multiple authentication methods:

  • Managed Identity - applies if the worker is deployed on Azure platform.
    • Requires only key vault url address.
    • Does not require credentials.
    • Is suited for Azure-hosted environments.
  • Client credentials - utilizes app registration with clientId and clientSecret.
    • Requires tenant id, client id, and a client secret.
    • Requires client secret to be stored in configuration file.
  • TLS certificates - a mTLS authentication with the certificate attached to the request to access vault.
    • Requires tenant id, client id, and either certificate path and password (the certificate is taken from the PFX file) or certificate thumbprint with storage location.

For more information, go to the Vault Service section.

note

To replace the existing private key, include the --Force=true component in the command, for example .\Omada.Identity.Import.WorkerService.exe --Operation=register --Force=true. Beforehand, unregister the public key with the assistance of the Omada support and make sure that you have a confirmation that it was successful. Otherwise, the attempt to replace private key results in an error.

The --Force=true option only works if the public key is unregistered and you have expired private key stored.

After the change the worker is not initiated automatically. To do so, run it without any parameters.

Key Export and Import for EnvironmentVariable Storage Type​

When using the EnvironmentVariable storage type, and migrating Cloud Application Gateway (CAG) workers to a different machine, you need to manually export and import the private key.

note

This step is not required when using the VaultService storage type, as vaults are accessible across multiple machines.

Use the following command to export the key:

.\Omada.Identity.Import.WorkerService.exe --Operation=export --FileName="Cag_Key"

this generates a file named Cag_Key.omadaKey.

The --FileName parameter can be either:

  • A relative path to the current working directory, or

  • An absolute path to the .omadakey file.