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

  • The IQService host's X.509 certificate with Extended Key Usage (EKU) used as Server Authentication must be available in the Personal Certificate Store of the host. The subject of the certificate should match the FQDN of the IQService host. An example subject is iqservice.test.com.

  • The matching private key must be present in the host's RSA key directory.

  • If the IQService host's X.509 certificate is not available, create a CSR (Certificate Signing Request) from the IQService host.

  • Submit the CSR to a trusted (internal or third party) certificate authority (CA) for signing. Ensure that the CA is on trusted root CA in the host.

  • The configuration of Client Authentication is mandatory when TLS communication is enabled for IQService.

  • To configure client authentication when the IQService host is added to any domain, you need to have a domain user whose credentials can be used to authenticate a connection between Identity Security Cloud and IQService.

  • If the IQService host is not added to any domain, the Windows local user from the IQService host can be used authenticate a connection between Identity Security Cloud and IQService instead of the domain user.

Note
No specific additional user permissions are required.

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

  • The X.509 certificate is located in the Local Computer's Personal certificate store.

  • A private key that matches the certificate is present in the Local Computer's store and is correctly associated with the certificate.

    For example, as displayed in the following screenshot, you can confirm if the certificate has a private key. A certificate with a private key (on the right, highlighted in green) has a different icon than a certificate without one (highlighted in red).

  • The Enhanced Key Usage extension includes the Server Authentication (1.3.6.1.5.5.7.3.1) object identifier.

  • The IQService host's fully qualified domain name (FQDN) must be in the common name (CN) in the Subject field in the X.509 certificate, and it must be a DNS entry in the Subject Alternative Name extension in the X.509 certificate.

    An example of IQService's FQDN is iqservice.test.com. Refer to the following examples:

  • The X.509 certificate must be trusted by the IQService host. Trust is established by configuring the IQService host to trust the root CA to which the issuing CA chains. Refer to the following examples:

The virtual appliance (VA) must trust the IQService X.509 certificate. Trust is established by configuring the VA to trust the root CA to which the issuing CA chains. To establish trust between the VA and the root CA:

  1. Add the root CA cert in the /home/sailpoint/certificates directory of the VA.

  2. Restart the CCG service.

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

Resolution:

  • Ensure that the certificate is placed at correct path in VA: /home/sailpoint/certificates

  • This error message might come if IQService is an older version or a non-TLS port is provided. Ensure your IQService is upgraded to latest IQService and TLS port is provided.

Resolution:

  • Ensure that the certificate is properly placed in VA: /home/sailpoint/certificates.

  • Check communication between IQService host and VA.

  • Ensure that the DNS settings are correct. Alternatively add the appropriate mapping entry for IQService host in hosts.yaml file in the /home/sailpoint directory.

    Note
    For information on creating a hosts.yaml file, refer to Configuring a Hosts.yaml File.

Resolution: Verify the following:

  • This could be because IQService TLS is disabled and you have provided TLS port. Ensure that the Use TLS for IQService checkbox is selected.

  • This could be because the hostname of the IQService server does not match the FQDN of the TLS certificate. Verify that the hostname matches the FQDN or the SubjectAlternateName DN is the same as the FQDN of the TLS certificate. If they are not the same, use the following commands to specify the certificate FQDN for IQService and then restart IQService:

    iqservice.exe -m hostname.example.com

    iqservice.exe -t

Resolution – Ensure your IQService service is running.

Resolution – This could be because the IQService version is older. Ensure your IQService service is upgraded to latest version. Deselect the Use TLS for IQService checkbox for non-TLS communication.

Resolution – If you want to use the IQService TLS functionality, use the latest CCG version and IQService version. If you are not using the latest CCG version and IQService version, ensure that the Use TLS for IQService checkbox is unchecked on source configuration.

Resolution – If you want to use the IQService TLS functionality, ensure that latest CCG version and IQService is deployed. If you are not using the latest CCG version and IQService version, ensure that the Use TLS for IQService checkbox is unchecked on source configuration.

Client Authentication

The following errors may be returned from IQService.

Resolution:

  • Ensure that you have registered and configured the IQService user and password on IQService host using the following command:

    IQService -a username

  • Ensure that you have provided the correct IQService user or password. Use the latest CCG version and IQService version.

Resolution – Check if the is checked. the IQService user's password could be expired. To resolve the issue, change the password for IQService user.

Resolution – Password could be expired for IQService user. To resolve the issue, change the password for IQService user.

Resolution – Ensure that the IQService user is not locked.

Resolution: Ensure that the IQService user is not locked.

Resolution – The reason could be IQService user has enabled logon hours and you are trying to perform an operation outside of their defined logon hours. Ensure that logon hours are correctly configured.

Resolution – This is the error that displays if you are trying to perform client authentication with an old CCG version but the latest IQService version. You need to remove the user details from IQService using the command: IQService -x username. Also remove IQService user and password from source config.