Setting up Qlik Data Gateway - Direct Access

This topic outlines the Qlik Data Gateway - Direct Access prerequisites, provides installation instructions, and describes the limitations and considerations you should be aware of when working with Qlik Data Gateway - Direct Access.

System prerequisites

This section describes the software, ports, and hardware requirements for using Qlik Data Gateway - Direct Access.

Software prerequisites

• The Direct Access gateway should be installed on a Windows Server machine behind your firewall. The server should be able to access your data source.

  Supported Windows Server editions:

  • 2016
  • 2019
  • 2022
  Tip noteFor optimal performance, install the Direct Access gateway on a server that is as close as possible to your data source.

• Two different .NET versions need to be installed. Install the following .NET versions only (later versions are not supported):

  • .NET 4.8: Required for the installation

  • .NET 6.x (latest patch): Required in order to run the Direct Access gateway application

  For instructions on how to verify the currently installed .NET version, see https://docs.microsoft.com/en-us/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed.

• Microsoft Visual C++ 2015-2022 Redistributable (x64). The Direct Access gateway setup will prompt you to install the redistributable if it detects that it is not currently installed.

Additional software prerequisites when using SAP data sources

• Install the SAP NetWeaver RFC SDK on the Qlik Data Gateway - Direct Access machine as described in Installing SAP NetWeaver RFC SDK for Qlik Data Gateway - Direct Access.
• Install Microsoft Visual C++ 2013 Redistributable (x64) on the Qlik Data Gateway - Direct Access machine.

Required ports and protocols

The following section lists the required ports.

Outbound ports

HTTPS/TCP-443 should be opened for outbound communication to <tenant-id>.<region>.qlikcloud.com.

Internal ports

Below is a list of ports used for communication by internal data gateway processes. If any of these ports is being used by another application, reconfigure the other application or uninstall it.

General ports

• 5050 (Connector Agent REST API)
• 9027 (DCAAS REST API)

ODBC ports

• 3005 (ODBC Connector REST API)
• 50060 (ODBC Connector gRPC)

SAP ports

• 3007 (SAP BW Connector REST API)
• 3008 (SAP SQL Connector REST API)
• 50070 (SAP BW Connector gRPC)
• 50080 (SAP SQL Connector gRPC)

WSS protocol

In addition to HTTPS, Direct Access gateway also uses WSS (WebSocket Secure) protocol. Therefore, make sure that your firewall and proxy server (if you intend to use one) are set up to allow outbound WSS connections.

Recommended minimum hardware

• 8 cores

• 32 GB memory

• 5 GB storage

System cryptography

Qlik Cloud Government supports using Qlik Data Gateway - Direct Access only when Windows is configured to run in a FIPS 140-2 approved mode of operation (FIPS mode). To turn on FIPS mode, enable the Windows policy: System cryptography: Use FIPS compliant algorithms for encryption, hashing, and signing. For more information, see step 3 of the procedure Using Windows in a FIPS 140-2 approved mode of operation.

Installing Qlik Data Gateway - Direct Access

Setting up the Direct Access gateway involves procedures that need to be performed both in the Management Console and on the Direct Access gateway server.

Stage one: Download Qlik Data Gateway - Direct Access

1. In the Management Console, select Data gateways.

   Any existing data gateways will be listed in a table showing basic information about each gateway.

2. Click the Deploy toolbar button.

   The Deploy data gateway dialog opens.

3. Select Data Gateway - Direct Access, accept the Qlik Customer Agreement, and click Download. The Direct Access gateway setup file (qlik-data-gateway-direct-access-<version>.x86_64.exe) will be downloaded to your machine.

Stage two: Install and set up the Direct Access gateway on a server behind the firewall protecting your data sources

This stage involves installing the Direct Access gateway, setting your Qlik Cloud tenant URL, optionally setting a proxy server, and generating a registration key. You will need to copy the key to the data gateway settings in the Management Console (in stage three below). The key is used to establish an authenticated connection between the Direct Access gateway and the Qlik Cloud tenant.

1. When the download is complete, copy the setup file to a Windows Server machine behind the firewall. Make sure the machine can communicate with your data sources.

2. Open the file to launch the Setup Wizard. Continue clicking Next until setup is complete.
   

   Information note

   • The Direct Access gateway requires Microsoft .NET 6.x. If setup detects that an earlier version is installed, you will be prompted to install the required version. When the .NET installation completes, you will need to restart the data gateway server and then run the Direct Access gateway setup again.

   • Setup will prompt you to install Microsoft Visual C++ 2015-2022 Redistributable (x64) if it detects that it is not currently installed.

   • During setup, you can optionally change the default installation path (C:\Program Files\Qlik\ConnectorAgent).

3. On the Direct Access gateway machine, open a Command Prompt as an administrator and change the working directory to the ConnectorAgent subfolder (C:\Program Files\Qlik\ConnectorAgent\ConnectorAgent with a default installation).

   Then, run the following commands:

   Setting the Qlik Cloud tenant

Set which Qlik Cloud tenant to connect to. To connect to the tenant via a proxy server, add the relevant parameters to the command as shown below.

Command for setting the Qlik Cloud tenant without a proxy server:

Syntax:

connectoragent qcs set_config --tenant_url your-qlik-cloud-tenant-url

Example:

connectoragent qcs set_config --tenant_url mytenant.us.qlikcloud.com

Command for setting the Qlik Cloud tenant with a proxy server:

Syntax:

connectoragent qcs set_config --tenant_url your-qlik-cloud-tenant-url --proxy_url http://host:port --proxy_username username --proxy_password password

Example:

connectoragent qcs set_config --tenant_url mytenant.us.qlikcloud.com --proxy_url http://myproxy:1212 --proxy_username admin --proxy_password f56weqs@

Information noteFor information on proxy limitations, see Connecting to Qlik Cloud via a proxy server.

Setting the CA bundle

The CA bundle authenticates the identity of the Qlik Cloud tenant, thereby ensuring a trusted connection.

Who needs to set the CA bundle?

The CA bundle only needs to be set if you are:

• A Qlik Cloud Government customer
• A Qlik Cloud commercial customer using a security appliance that acts as a proxy and replaces the certificate information received from the Internet with its own CA root certificates

Which bundle should I use?

Customers should either use the Qlik CA bundle or bring their own CA bundle, as follows:

• Qlik provides the CA bundle: Should be used by Qlik Cloud Government customers with a standard environment. A standard environment is an environment that does not have a security appliance that acts as a proxy and replaces the certificate information received from the Internet with its own CA root certificates.

  In a default Direct Access gateway installation, the CA bundle file can be found in the following location: C:\Program Files\Qlik\ConnectorAgent\caBundle\qcg_ca_bundle.pem

  Information noteYou can rename the CA bundle file, but make sure that it has a .pem extension (for example, qlikcerts.pem). Then, run the command(s) described below.
• Customers bring their own CA bundle: Should be used if the customer's environment is using a security appliance that acts as a proxy and replaces the certificate information received from the Internet with its own CA root certificates. If those certificates are self-signed, then in addition to the command for setting the CA bundle, you also need to run the command for allowing the CA bundle. Both of these commands are described below. This applies to both Qlik Cloud Government customers and Qlik Cloud commercial customers alike.

Command for setting the CA bundle

Run the following command to set the CA certificate bundle:

Syntax:

connectoragent qcs set_config --ca_bundle_path path-to-ca-bundle-file

Example:

connectoragent qcs set_config --ca_bundle_path c:\ca\cacerts.pem

Command for allowing the CA bundle

Some environments use a security appliance that acts as a proxy and replaces the certificate information received from the Internet with its own CA root certificates. This command only needs to be run if the security appliance itself uses a self-signed certificate. In such a case, the CA bundle might not be trusted unless you run the following command:

connectoragent qcs set_config --ca_bundle_allow_invalid_certs

Information noteIf you are not sure whether your environment is using such a security appliance, please contact your IT administrator.

Generating and showing the registration key

The key is used to establish an authenticated connection between the Direct Access gateway and the Qlik Cloud tenant.

Command for generating the registration key

connectoragent qcs generate_keys

Command for showing the registration key

connectoragent qcs get_registration

The key is shown.



Copy the entire key as shown in the example above. You will need to paste it into the Management Console in the next stage.

Stage three: Return to the Management Console and register the data gateway

1. In the Management Console, select Data gateways.

   Any existing data gateways will be listed in a table showing basic information about each gateway.

2. Click the Create toolbar button.

   The Create data gateway dialog opens.

   

3. Specify a name for the data gateway.

4. Optionally, provide a description for the data gateway.

5. From the data gateway type drop-down list, select Direct Access.

6. Paste the registration key you generated earlier into the Key field.

7. From the Associated space drop-down list, select a space.

   When associating the Direct Access gateway with a space, you should be aware of the following:

   • Data gateways can be created in Shared or Managed spaces only
   • Only space members with the Can contribute role or higher will be able to create connections to access data through the data gateway.

   • To be able to create a data gateway, the user needs to be a space owner or have the Can manage role. In addition, the user needs Professional or Full User entitlement. Assign Professional entitlement manually or by turning on Enable dynamic assignment of professional users in the Management Console.

     For more information on user entitlements and dynamic assignment of professional access, see Assigning user entitlements

   • Data gateways can be associated with a single space only.

8. Click Create.

   The data gateway is added enabled to the Data gateways list.

Stage four: Start the Qlik Data Gateway - Direct Access service on the Direct Access gateway server

On the Direct Access gateway server, do one of the following to start the service:

• Open the Windows Services console and start the Qlik Data Gateway - Direct Access service.

• Open a Command Prompt as an administrator and change the working directory to the ConnectorAgentsubfolder (C:\Program Files\Qlik\ConnectorAgent\ConnectorAgent with a default installation). Then, run the following command:

  connectoragent service start

  A confirmation that the service started successfully will be shown.

See also: Running the service under a different account

Stage five: Add a connection to your data source

Locate your gateway in the Data gateways list and verify that its Status is “Connected” (you might need to refresh your browser to see the current status). You can then proceed to add a connection to your data source.

There are several ways you can load data from data sources: 

• Adding and managing data sources from spaces

• Loading and managing data with Data Manager

• Loading and transforming data with scripting

The list of available data sources will contain duplicate entries for those data sources that support gateway connectivity. Gateway-compliant data sources can be identified by the words "via Direct Access gateway”, which appear in parenthesis after the source type.

Supported data sources

• ODBC sources. For more information, see ODBC databases ‒ Qlik Cloud.

• SAP BW and SAP SQL sources. Requires Direct Access gateway 1.2.0 or later.

  For information on setting up connectivity to these sources, see SAP NetWeaver.

General limitations and considerations

When using Qlik Data Gateway - Direct Access, you should be aware of the following limitations and considerations:

• If, for any reason, the Direct Access gateway server is rebooted during a Qlik application reload, the reload will fail. Restart the Qlik application reload to refresh the data.
• The data gateway software should be installed on a dedicated Window Server as stipulated in the System Requirements below. Do not install it on the actual data source server or on a server that already has Qlik Sense Enterprise on Windows or Qlik DataTransfer installed.