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 Private key storage 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​

Installing Cloud Application Gateway involves five steps, which must be completed in order:

  1. Download
  2. Configure security and storage
  3. Register with Omada Identity Cloud
  4. Start worker services
  5. Register worker as an instance

Follow the steps in the presented order for successful installation and configuration of the Cloud Application Gateway.

Step 1: Download​

Important

For guidance on how to enable or migrate to the Cloud Application Gateway 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.

    CAG Zip Download

  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 Cloud Application Gateway 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.

The Cloud Application Gateway 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 Cloud Application Gateway.

Step 2: Configure security and storage​

Before you can register with Omada Identity Cloud, you must configure how and where the private key is stored. The key storage method and instance group assignment are permanently set during registration and cannot be changed afterward without re-registering.

Private key storage​

In the appsettings.Customer.json file, 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" }

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. The Cloud Application Gateway 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.

Instance group assignment​

Configure the InstanceGroupId in the appsettings.Customer.json file to assign the worker to a specific instance group. If you do not configure the InstanceGroupId setting, it defaults to Default.

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

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.

Step 3: Register with Omada Identity Cloud​

After configuring security and storage, register the Cloud Application Gateway with Omada Identity Cloud. This step creates the cryptographic key pair and authenticates the Cloud Application Gateway against the COPS API.

Important

You must complete Step 2: Configure security and storage before running the registration command. The registration uses the configured PrivateKeyLocation and InstanceGroupId settings.

Running the registration command​

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

Run the register command on one worker only (either Import or Provisioning), not on both. The key pair is shared across both services within the same instance group.

Ensure that "CloudApplicationGatewayConfiguration":"PrivateKeyLocation" is set to the same value for both import and provisioning workers.

Re-registration​

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.

Registering multiple Cloud Application Gateways​

  1. Perform the initial Cloud Application Gateway registration on a primary VM following the steps above.
  2. To register a Cloud Application Gateway on an additional VM, clone the Cloud Application Gateway 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 group assignment section.

Step 4: Start worker services​

After successful registration, start the 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.

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

Important

When you are starting a new worker instance that is based on a copy of an already registered worker, make sure that the CloudApplicationGatewayConfiguration.ServiceUId is removed from the new worker's appsettings.Customer.json file. This ensures that the new instance is registered with a unique serviceUId and prevents the registration process from failing.

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

Step 5: Register worker as an instance​

After the worker services are running, register each worker as an instance so it becomes visible in the Omada Identity Cloud administration page.

Important

The worker service must be running before you execute the register-instance command. This step cannot be performed before Step 4: Start worker services.

Use the following command in the PowerShell console:

.\Omada.Identity.[Import or Provisioning].WorkerService.exe register-instance <instanceGroupId> <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 serviceUID parameter is not defined, it is generated automatically.

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

Verifying instance registration​

After running register-instance, verify that the instance appears in Setup > Administration > Cloud Application Gateway > Instances.

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.

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 reference​

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 Step 1: Download 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 Cloud Application Gateway 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": 15,
      "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 monitoring needs.

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

Exporting and importing keys​

When using the EnvironmentVariable storage type, and migrating the Cloud Application Gateway 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.

Managing Cloud Application Gateway​

After completing the installation, you can manage your Cloud Application Gateway deployment through the Omada Identity Cloud administration page.

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 Cloud Application Gateway 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

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

CAG instance groups
  • You can add new group
    CAG instance groups new
  • You can edit existing group
    CAG instance groups edit

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.

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.

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