Configuring TLS and Client Authentication for IQService

IQService, also referred to as the Integration Service, is a Windows service that enables Identity Security Cloud to participate in a Windows environment and access information only available through Windows APIs.

It is a lightweight service that must be installed on any supported Windows server that has connectivity to the target systems you want to manage in Identity Security Cloud. IQService can be installed on any Windows operating system that meets the requirements specified in Prerequisites of IQService.

Caution
If you have IdentityIQ and Identity Security Cloud in your environment, install a separate instance of IQService for each system.

  • TLS Communication – TLS Communication between IQService and the VA is supported and must be configured to secure this solution.

  • Client Authentication – IQService can authenticate a client while connecting to it. IQService-based sources support Client Authentication, a feature which authenticates every incoming request from Identity Security Cloud before executing them. To ensure the authentication works correctly, IQService expects the client to send the credentials of a registered user with every request. Before processing a request, IQService first confirms that the user is registered with it and then authenticates the credentials with Windows.

Note
Client Authentication is mandatory for operations that use IQService when TLS communication is enabled for IQService.

Prerequisites

Important
If you are updating your IQService instance to use a TLS port, ensure that you disable the existing non-TLS port. This is crucial to maintain secure communication and prevent potential security vulnerabilities arising from the simultaneous use of both TLS and non-TLS ports. For more information, refer to Disabling Non-TLS Communication for an Existing IQService Instance.

TLS Configuration between VA and IQService

  1. Download IQService from Identity Security Cloud via a source that requires it.

    1. Select Download IQService.

    2. Unzip the downloaded IQService.zip archive into the desired location. For example, C:\SailPoint\IQService\

  2. Install IQService to communicate with Identity Security Cloud on TLS port only.

    IQService.exe -i -o <TLS Port Number>

    This command installs IQService with the name IQService-Instance1 and the provided TLS port number.

  3. On the managed source configuration, in the Integration Service panel, enable the Use TLS for IQService.

TLS Configuration Check List

Configuration of IQService Client Authentication

  1. On the IQService host, run the following command:

    IQService.exe -a <Domain User/s>

    For example: IQService.exe -a "Corp\John.Doe"

    • The domain user must be in the msDS-PrincipalName format:

      <domain>\<user>

    • If you are using a local user, it must be in the following format:

      localuser

    • You must use the user name as an IQService User name in the same format.

  2. Configure the IQService User and IQService Password on the IQService-based source.

    Ensure that the IQService user value set here is the same that you registered on earlier on IQService.

Securing Communication between IQService and AD Domain Controller or Target system

Note
For IQService to connect using TLS and self-signed certificates, you must install the certificate in Trusted Root Certification Authorities on the IQService host. The configured IQService User must have all access/permissions to read all the installed Certificates.

  1. Export the server certificate and copy the exported .cer file to the IQService host.

  2. Double-click the .cer file and select Install Certificate.

  3. Select Next.

  4. Choose Place all certificates in the following store and select Browse...

  5. Select Show physical stores.

  6. Expand Trusted Root Certification Authorities and select Local Computer.

  7. Select OK.

  8. Select Next, then Finish.

Disabling Non-TLS Communication for an Existing IQService Instance

If you are enabling TLS communication for an existing IQService instance that previously used non-TLS communication, you must ensure that non-TLS communication is disabled for that same instance. You can achieve this using one of the following methods:

Method 1

  1. Set the existing non-TLS port to zero (0) or any negative number (such as -1, -2, -3 ) using the command line:

    IQService.exe -p <zero or negative port number>

    For example,

    IQService.exe -p 0

    IQService.exe -p -1

    Note
    Ensure to disable the non-TLS port for both the primary service and the secondary service (if configured).

  2. After setting the port, restart the IQService.

Method 2

Optionally, you can delete the non-TLS port entry from the IQService instance registry configuration.

Warning

Directly editing the registry can cause serious, potentially unrecoverable errors if done incorrectly. Only modify fields that are specifically intended for modification.

Following are the steps to delete non-TLS port entry from IQService instance: 

  1. Locate the registry configuration for your IQService instance.

    You can find the registry path for the primary service at:

    HKEY_LOCAL_MACHINE\SOFTWARE\SailPoint\IQService Instances\<IQService-Instance>

    You can find the registry path for the secondary service at:

    HKEY_LOCAL_MACHINE\SOFTWARE\SailPoint\IQService Instances\<IQService-Instance>\Secondary

    Replace <IQService-Instance> with the name of your IQService instance.

  2. Look for the port attribute.

  3. Delete the port attribute entry.

After completing one of these methods, the IQService will only communicate using TLS, ensuring secure communication between the IQService and other components. To verify that the non-TLS port has been successfully disabled for your IQService instance, run the following command:

IQService.exe -v

After running this command, the output should display only the Configured TLS Port information along with the corresponding TLS port number, such as Configured TLS Port : <TLS Port Number>

Troubleshooting

TLS Communication

Client Authentication

The following errors may be returned from IQService.