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. The files can be unblocked by using the PowerShell command Unblock-File, similar to Get-ChildItem "C:\Path\To\Your\Folder" -Recurse | Unblock-File.

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.

Validating worker services​

You can validate if the services are running properly by using the validate PowerShell command. It initiates a service self-check and verifies connectivity to the Omada Identity Cloud.

To initiate use the following commands in the Worker Service folder:

  • For the Import Worker Service: .\Omada.Identity.Import.WorkerService.exe validate
  • For the Provisioning Worker Service: .\Omada.Identity.Provisioning.WorkerService.exe validate

Commands available for worker services​

You can access the list of available commands for both worker services in the command line interface by using the --help parameter, for example:

  • For the Import Worker Service: .\Omada.Identity.Import.WorkerService.exe --help
  • For the Provisioning Worker Service: .\Omada.Identity.Provisioning.WorkerService.exe --help

The following commands are available:

CommandDescription
register <fileName> <pfxPassword>Registers a private key. If a file path is provided, imports the key from the .pfx file and registers it. Otherwise, generates a new key pair and registers it.
import <fileName> <pfxPassword>Imports a private key into the local key repository from a specified file. Supports .pfx and .omadakey formats.
export <fileName> <pfxPassword>Exports the private key to a file. The key is encrypted using a passphrase before being saved.
validatePerforms Worker Service validation and checks if configuration is correct and connection to Omada Identity Cloud services could be properly established.
register-instance <instanceGroupId> <serviceUId>Registers this worker service as an instance for the specified Cloud Application Gateway Instance Group. If no instance group ID is provided, the instance will be registered to the one set in the configuration, which defaults to Default.

Installing Cloud Application Gateway on Docker or Kubernetes​

It is possible to deploy the Cloud Application Gateway using Docker containers or Kubernetes.

Before you start​

Deploying Cloud Application Gateway using Docker or Kubernetes requires retrieving the correct settings and configuration values from the Management Portal.

Download required files as described in the Downloading Cloud Application Gateway components section.

Private key storage configuration​

Omada highly recommends using the vault service for storing the private key when deploying Cloud Application Gateway on Docker or Kubernetes, as it is the intended storage method. You can find guidelines and detailed information on how to configure the vault service storage in the Vault service integration section.

Deployment configuration​

The Docker images for both Import Worker Service and Provisioning Worker Service are available in the Docker Hub under the following links:

Example of Docker Compose file configuration for Import Worker Service deployment
name: "omadaidentity-cag-workers"
services:
  import:
    image: omadaidentity/import-worker-cag:latest
    container_name: import-worker
    restart: unless-stopped
    environment:
      ### Variables taken from Management Portal ###
      CAG_CLIENTID: ""
      CAG_PASSWORD: ""
      COPSAPI_URL:  ""
      
      ### Variables for the Private Key Storage configuration ##
      CloudApplicationGatewayConfiguration__InstanceGroupId: "Default"
      CloudApplicationGatewayConfiguration__PrivateKeyLocation: "VaultService"
      CloudApplicationGatewayConfiguration__Vault__Service: "Azure"
      CloudApplicationGatewayConfiguration__Vault__SecretName: "default-cag-group-key"
      CloudApplicationGatewayConfiguration__Vault__Azure__AuthMethod: "ClientCredentials"
      CloudApplicationGatewayConfiguration__Vault__Azure__ApiVersion: "7.4"
      CloudApplicationGatewayConfiguration__Vault__Azure__KeyVaultUrl: "https://my-cag-kv.vault.azure.net/"
      CloudApplicationGatewayConfiguration__Vault__Azure__TenantId: ""
      CloudApplicationGatewayConfiguration__Vault__Azure__ClientId: ""
      CloudApplicationGatewayConfiguration__Vault__Azure__ClientSecret: ""

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.Customer.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

Instances and 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.

Instance groups diagram

In the Setup>Administration>Cloud Application Gateway section you can access the Instance Groups and Instances.

CAG setup showing navigation to Instance Groups and Instances

Instances​

In the Instances page, you can find following information:

  • The instance Group name that the instance is assigned to.
  • The instance type, either Import or Provisioning.
  • The Machine Name and Machine IP hosting the service.
  • The unique Service UID assigned for each instance.
  • The worker service Last Heartbeat Status and Last Heartbeat Time.
CAG-instance-groups-instances-tab showing table with columns: Group, Type, Machine Name, Machine IP, Service UID, Last Heartbeat Status, and Last Heartbeat Time. The table displays multiple worker instances assigned to different instance groups with their connection status and timing information.

You can register a worker service as an instance for a specified instance group by using the register-instance command in the PowerShell console, for example:

.\Omada.Identity.[Import or Provisioning].WorkerService.exe register-instance <instanceGroupsId> <service-uid>

Where instanceGroupId is the name of the instance group you want to assign the worker service to, and service-uid is the unique identifier of the worker service instance that you can find in the Instances page. If you do not specify the instanceGroupId parameter value, it is set to Default. If the instanceUID parameter is not defined, it is generated automatically.

Successful registration results in the serviceUId saved to the appsettings.Customer.json file.

Instance groups​

In the Instance Groups, you can find the list of existing instance groups and perform the following actions:

  • You can add new group
  • You can edit exisiting group

To assign a system to an instance group, configure the Cloud Application Gateway instance setting in the General settings of a system.

To assign a worker service, either Import or Provisioning, to an instance group, configure the InstanceGroupId value in the CloudApplicationGatewayConfiguration section in the appsettings.Customer.json file.

Restarting worker services​

If the worker is hosted as a service, you can restart it using the Restart option in the Cloud Application Gateway Instance Groups view.

  1. Go to Setup>Administration>Cloud Application Gateway and select the Instance Groups.
  2. Select the instance group from the list and expand the More menu.
  3. Select the Restart option to restart worker services.

When a restart event is initiated, the worker retrieves the service name from the appsettings.Customer.json file and restarts the service with the corresponding name, ensuring all worker processes are finialized before the restart.

Important

To effectively restart a worker service, the following configuration must be implemented within the customer environment:

  1. Go to Services in the Windows system.
  2. From the list, select appropriate worker services and select Properties. Windows Services properties window showing worker services.
  3. In the Recovery tab, set the failure options to Restart the Service for the first, second, and subsequent failures. Windows Services recovery options showing 'Restart the Service' selected for first, second, and subsequent failures.

This ensures that workers are restarted automatically and do not impede the overall functioning of the Cloud Application Gateway.

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.

Registering Cloud Application Gateway for a specified instance group​

You can register the Cloud Application Gateway for a specified instance group. This way, multiple instance groups can be hosted within a single environment with an autonomous and independent registration, authentication, and key management with separate public keys for each instance group. This separation provides an additional security layer when required, helping contain potential vulnerabilities within a specific instance group.

warning

Changing the Cloud Application Gateway group for an onboarded system with a configured password may cause import failures. This occurs because the password is encrypted with the key from the original group and cannot be decrypted with the key from the new group.

After changing the group, go to the system's configuration page, re-enter the password, and save the Connection details. To ensure the password is encrypted with the new key, run the Test connection action.

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 register

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

    .\Omada.Identity.Import.WorkerService.exe register "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 or -f option in the command, for example .\Omada.Identity.Import.WorkerService.exe register --force. 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 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 export "Cag_Key"

this generates a file named Cag_Key.omadaKey.

The parameter can be either:

  • A relative path to the current working directory, or

  • An absolute path to the .omadakey file.