SOTI Cloud Link Integration

Before you begin

This document describes the integration of SOTI Connect with SOTI Cloud Link and discusses the relevant parts, including the SOTI Cloud Link Broker, the SOTI Cloud Link Agent, and the SOTI Cloud Link Agent Admin Utility Tool.

Note: Support for SOTI Cloud Link in SOTI Connect 2024.1 requires SOTI Cloud Link Agent Admin Utility Tool 2024.1.

Setting up SOTI Cloud Link Broker

Procedure

  1. From the SOTI Connect web console, select Global Settings > Services > Cloud Link.
    Download Certificate
  2. Select the Download Certificate button in the Broker tab of the SOTI Cloud Link page and download the Token Signature certificate file (connect-token-validation-cert.pem).
  3. Move the Token Signature certificate file to C:\IOT\certs.
    Important: For the Azure environment, set GRPC_DNS_RESOLVER to native in the System Environment.
    Tip: If SOTI Connect and broker is being installed on an Azure VM, change Idle timeout to 30 mins (the default is 4 minutes).
  4. Open Manage Computer Certificates and navigate to Personal -> Certificates store. Ensure there is at least one certificate issued to the Fully Qualified Domain Name (FQDN) of the VM or issued to the wildcard domain otherwise Broker can select the wrong certificate.
    • This certificate is used as the SSL certificate of SOTI Cloud Link Broker and must be trusted on the SOTI Cloud Link Agent and SOTI Connect VMs (if they are not on the same VM).
    • Certificates issued by GoDaddy are already trusted on other VMs.
  5. Download the Soti.CloudLink.Broker installer file (in *.nupkg format) from: https://www.soti.net/soticloudlinkagent/help/v2024.0/en/broker/enable_installer.html.
  6. Extract the *.nupkg file to a folder, rename the file extension to *.zip and extract.
  7. Open PowerShell as an administrator and navigate to the extracted folder.
  8. Run the command: Import-Module '.\Soti.CloudLink.Broker.Installer.psm1'

    This script checks for required dependencies. Install any dependencies that are missing on your VM.

    Note: If a 'File is not digitally signed' error occurs, run the following command and try again: Set-ExecutionPolicy -ExecutionPolicy bypass -Scope process.
  9. Run Install-IdentityCloudLinkBroker and follow the prompts.
    1. If this is an initial installation on the VM, enter no to set up from the start.
      Note: For subsequent installs, enter yes to reuse the previous configuration.
    2. The Broker Hostname is the FQDN of the VM.
    3. For the Discovery Service, enter 0.
    4. For the Authority URL, enter https://+:5596.
    5. For the Audience, leave blank (press Enter).
    6. For the Token Signature certificate, enter C:\IOT\certs\connect-token-validation-cert.pem.
    7. For the Token Signature certificate password, enter 123 (this is a required password for the installer but is not used elsewhere).
    8. For Kestrel Endpoint Certificate subject, this depends on the certificate you obtained in Step 2.
    • If the certificate is issued to the wildcard domain, then use it. This is likely if the VM is on cloud (for example, *.soticonnect.cloud).
    • If the certificate is issued to the VM's FQDN, then enter the FQDN.
    Running the Install-IdentityCloudLinkBroker installer
  10. The installer may display error messages as the installation proceeds. The installation is successful if 'Cloud Link Broker successfully installed and running.' is the final message.
  11. The install script is for SOTI Identity. For the script to work with SOTI Connect, run this command in PowerShell:
    For Non-Azure environment:

    Import-Module ".\Binaries\Soti.CloudLink.Broker.Administration\Soti.CloudLink.Broker.Administration.dll" && Set-CloudLinkConfiguration "C:\Program Files\SOTI\Soti.CloudLink.Broker\appsettings.json" 'DiscoveryServiceConfiguration:Enabled' $false && Set-CloudLinkConfiguration "C:\Program Files\SOTI\Soti.CloudLink.Broker\appsettings.json" && Restart-Service -Name "SOTI Cloud Link Broker"

    For Azure environment:

    Import-Module ".\Binaries\Soti.CloudLink.Broker.Administration\Soti.CloudLink.Broker.Administration.dll" && Set-CloudLinkConfiguration "C:\Program Files\SOTI\Soti.CloudLink.Broker\appsettings.json" 'DiscoveryServiceConfiguration:Enabled' $false && Set-CloudLinkConfiguration "C:\Program Files\SOTI\Soti.CloudLink.Broker\appsettings.json" 'ProxyConfiguration:ConnectionBlockingDisabled' $true && Restart-Service -Name "SOTI Cloud Link Broker"

  12. From the SOTI Connect web console, set the SOTI Cloud Link Broker URL using the Add button on the Broker tab of SOTI Cloud Link page.
    Enter the address to connect a SOTI Cloud Link Broker

Setting up SOTI Cloud Link Agent with SOTI Connect

Procedure

  1. Download the SOTI Cloud Link Agent installer to the VM from the following URL:
    https://www.soti.net/soticloudlinkagent/help/v4.1/en/setup/inbound/setup_inbound_sid.html
  2. Run the installer and follow the prompts to set up the SOTI Cloud Link Agent.
  3. In the SOTI Connect web console, select Global Settings -> Services -> Cloud Link.
  4. Select the Add icon to add a new SOTI Cloud Link Agent to SOTI Connect.
    Add a SOTI Cloud Link Agent to SOTI Connect
  5. Copy the SOTI Cloud Link Agent configuration details to the clipboard by selecting the Copy Configuration button.
    Copy the SOTI Cloud Link Agent configuration details to the clipboard
  6. Open the SOTI Cloud Link Agent Admin Utility Tool.
  7. Select Add to paste the SOTI Cloud Link Agent configuration details.
    Paste the SOTI Cloud Link Agent configuration details
    Note: For Azure environment, modify C:\Program Files\SOTI\CloudLink\Soti.CloudLink.GrpcServer.exe.config. Search and modify KeepAliveTimeInMs to 1600000 then restart SOTI Cloud Link Agent using the Admin Utility.
  8. The SOTI Cloud Link Agent appears in the SOTI Connect Agent table.
    Newly added broker displays in the Agents table
    Any errors that occur appear in the error logs of the SOTI Cloud Link Agent in C:\ProgramData\SOTI\CloudLinkAgent.
    Errors are likely to be SSL certificate issues.
    Note: You may need to trust the SOTI Connect root certificate in the SOTI Cloud Link Agent VM.
    Note: You may need to trust the SOTI Cloud Link Broker SSL certificate in the SOTI Cloud Link Agent VM, if the certificate is not issued by GoDaddy.

Updating SOTI Connect or the System Certificate

About this task

Important: During a SOTI Connect update, changes to the root certificate also affect the token certificate. Manually updating the token certificate on the SOTI Cloud Link Broker is essential for LDAP users’ uninterrupted access. To acquire the new certificate, you must sign in with local Administrator privileges and navigate to Global Settings > Services > Cloud Link > Broker to download it.

Procedure

  1. When updating SOTI Connect or updating the System Certificate, you must get a new Token Signature certificate (see Step 2. in Setting up SOTI Cloud Link Broker)
  2. Move the Token Signature certificate file to C:\IOT\certs.
  3. Restart the SOTI Cloud Link Broker.

Uninstalling SOTI Cloud Link Broker

Procedure

  1. Open PowerShell as an administrator and navigate to the SOTI Cloud Link Broker installer folder.
  2. Run the command: Import-Module '.\Soti.CloudLink.Broker.Installer.psm1'
  3. Run the command: Remove-IdentityCloudLinkBrokerInstallation and follow the prompts.

Using SOTI Cloud Link Agent in a Certificate Authority Template

About this task

When setting up a CA Template of type ADCS, you can specify a SOTI Cloud Link Agent.

Procedure

  1. Under Authority type select ADCS.
  2. The last option lets you select a SOTI Cloud Link Agent.
    Selecting a SOTI Cloud Link Agent
    Note: You cannot delete a SOTI Cloud Link Agent associated with a CA template.

Cloud Link Agents in the Security Access Table

About this task

When adding a new SOTI Cloud Link Agent to the SOTI Cloud Link Agent table, it is also automatically added to the Security Access table.

Procedure

You can identify an automatically added SOTI Cloud Link Agent by the Access Source column (red box below).
  • SOTI Connect indicates the SOTI Cloud Link Agent was automatically added and is controlled by SOTI Connect.
  • User indicates the SOTI Cloud Link Agent was added by the user and is controlled by the user.
Identifying SOTI Cloud Link Agent types in the Security Access table
Note: Entries with SOTI Connect in the Access Source column are not controllable by the user. You cannot toggle the Active status, and the menu icon only enables editing of the Description. Entries with User in the Access Source column are controllable by the user. You can delete user entries and edit the agent Client ID and Client Secret.
Editing the Description of a SOTI Cloud Link Agent that was automatically added by SOTI Connect

Troubleshooting

About this task

The SOTI Cloud Link Agent stays inactive and there are error logs on the management server.

Procedure

  1. Verify that there are error logs on the management server similar to:
    Failed to ping CLA: Status(StatusCode="Unauthenticated", Detail="Received http2 header with status: 401" ...
  2. The error logs indicate the SOTI Cloud Link Broker is not using the correct Token Signature certificate. To resolve this issue, download the Token Signature certificate again (see Step 2 in the SOTI Cloud Link Broker Setup section above).