Installing and Configuring IQService

IQService, also referred to as the Integration Service, is a native Windows service that enables SailPoint 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 SailPoint.

Prerequisites

Software Requirements

Operating Systems	.NET Framework
Microsoft Windows Server 2019; Microsoft Windows Server 2016	.NET Framework version 4.8 Minimum; .NET Framework version required 4.5.2 Supports; .NET Framework version 4.7.1

Note

IQService is compatible with lower versions of .NET Framework (4.5.2 onwards). SailPoint recommends using the latest version of .NET Framework 4.8 to align your environment with future releases of this service.

Hardware Requirements

This is the minimum hardware requirement for a basic working instance of IQService with an average processing load when used with one application. The requirement proportionately increases with an increase in the request processing load and number of applications it serves.

Component	Recommended Hardware Requirement	Minimum Hardware Requirement
CPU	8-Core	4-Core
RAM	16 GB	8 GB
Free Disk Space	50 GB	250 MB

Service Account

The service account defined in the SailPoint source that connects to IQService is used for provisioning operations, aggregation (terminal services attributes and Skype attributes), and server-less binding for respective target system.

However, the account defined for the IQService Log On as an account in Windows is used for the before/after scripts where PowerShell is being used. If the source's service account is not used, then the PowerShell session is opened under the service account credentials of IQService.

Installing IQService

Download the Integration Service from a source that requires it in Admin.

Screenshot
Run the following commands to install a Windows service named IQService.
- To install IQService so it communicates with SailPoint on a non-TLS port:
```
IQService.exe -i
```
  This command installs an instance of IQService named IQService-Instance1 and on port 5050 (if available).
- To install IQService so it communicates with SailPoint on a TLS port:
```
IQService.exe -i -o <TLS Port Number>
```
  This command installs an instance of IQService named IQService-Instance1 and on the given TLS port number.
  
  Note
  
  For more details on the requirements and procedure to set up TLS Communication and Client Authentication, refer to Configuring TLS and Client Authentication for IQService.
- To install IQService so it communicates with SailPoint on both TLS and Non-TLS ports:
```
IQService -i -p <Non-TLS Port> -o <TLS port>
```
  This command installs an instance IQService named IQService-Instance1 and on the given TLS and Non-TLS ports.
  
  Warning
  
  To enhance security, it is mandatory to configure the TLS for IQService. If you continue using non-TLS configuration, any before and after script execution will be disabled to safeguard your environment. Remove non-TLS configuration for IQService to execute any rules and scripts.
Unzip the downloaded IQService.zip archive into the created or desired location. For example, C:\SailPoint\IQService\

Note

Verify the DLLs are trusted by checking the properties of the DLL files.
Start the service either from the Services Applet or from the command line by running the following command:
```
IQService.exe -s
```

IQService Commands

In addition to the commands -i to install and -s to start, other command line options with IQService include:

Command Line Options	Description
`-d`	Run in console mode
`-i`	Install a service. Refer to Registering IQService for more information.
`-k`	Stop the service
`-p`	Update the port (requires a service restart)
`-r`	Remove the service
`-u`	Uninstall the service. Removes the service components and clears the registry entries.
`-s`	Start the service
`-t`	Restart (stop/start) the service
`-v`	Print version information
`-l <level>`	Trace Level 0-3; 0=off 1=error 2=info 3=debug
`-f <filename>`	Trace the file name. Defaults to the system32 directory. Enter the full path with a filename to log to a different path. For example: `iqservice -l 3 -f "C:\Sailpoint\IQService\iqtrace.log"`
`-a {<Domain User/s> \| list}`	Registers a domain user for Client Authentication. Pass the domain user name in msDS-PrincipalName (domain\user) format. Multiple users can be registered in a single command by separating them with a semicolon ( ; ). This command appends users to existing registered users. For example: `-a "Acme\John.Smith; Acme\Joe.Phillips"`. Ensure that the exact same user name is configured on the source for this feature to work. To list existing registered users, run the command with the list parameter. For example: `-a list`
`-x {<Domain User/s> \| list}`	Unregisters a user from the Client Authentication Users List. Pass the domain user name in msDS-PrincipalName (domain\user) format. Multiple users can be registered in single command by separating them with a semicolon ( ; ). For example: `-x "Acme\John.Smith; Acme\Joe.Phillips"`. To list existing registered users, run the command with the list parameter. For example: `-x list`
`-o <Port Number>`	TLS port for communication between IQService and SailPoint. This port accepts communication over TLS only.
`-j <TLS Version>`	Enforce the specific TLS version for communication between IQService and SailPoint. Supported values are: `TLS1.2` (Default), `TLS1.1`, `TLS1.0`
`-m <Subject CN>`	"Issued To" (CN of Subject) of the X.509 certificate. It is applicable to communication between IQService and SailPoint. This overrides the default lookup text for IQService to search for the X.509 certificate on the machine. By default, IQService looks for the X.509 certificate issued to FQDN of current machine. For example: `-m example.com`
`-? \| h:`	This is for help output

Configuring Default TLS Version

IQService supports the default configuration for tlsVersion. To enable this configuration, execute the IQService.exe -j default command.

With this configuration, the operating system selects the best available protocol. This configuration requires that SystemDefaultTlsVersions is enabled on the IQService machine. If it is not enabled, then IQService falls back to the highest commonly supported version from the predefined list of TLS versions.

Registering IQService

The IQService.exe -i command installs and registers the service with the new registry path HKEY_LOCAL_MACHINE\SOFTWARE\SailPoint\IQService Instances\IQService-Instance1 with the following keys:

Keys	Description
port	Port to listen
tracefile	Path to the tracefile
tracelevel	0 (off) 3 (verbose)
maxTraceFiles	Maximum number of Trace log files that must get created before overwriting the older files
traceFileSize	Maximum file size of a trace file in bytes. A new file is created when the current file exceeds this limit
clientAuthUsers	If you configure IQService with client authentication, the IQService user is displayed with this key.
tlsPort	If you configure the TLS port, the IQService is set up for the communication over TLS.

The IQService accesses only the IQService-related keys in the registry editor, and installs or uninstalls successfully.

Upgrading IQService

To upgrade, you must uninstall the previous version and then install the new version.

SailPoint also recommends backing up the current installation before uninstalling to aid with troubleshooting the new version, should issues arise.

To determine the existing (old) version, run the following command:
```
IQService.exe -v
```
To uninstall the existing (old) version, run the following command:
```
IQService.exe -u
```
Run the following command to install a new version:
```
IQService.exe -i
```

Upgrading IQService to the Latest Version

Take the backup of the existing IQService installation.
Stop the service either from the Services Applet or from the command line by running the following command:
```
IQService.exe -k
```
Uninstall IQService using the IQService -u command.
Extract the latest IQService in the installation directory.
Install the new IQService using the IQService -i command.
Start the IQService.

Note

If you have executed the IQService Public Key Exchange task for the existing IQService then SailPoint recommends that you follow the instructions mentioned to install and register a new IQService.

Documentation Feedback

Feedback is provided as an informational resource only and does not form part of SailPoint’s official product documentation. SailPoint does not warrant or make any guarantees about the feedback (including without limitation as to its accuracy, relevance, or reliability). All feedback is subject to the terms set forth at https://developer.sailpoint.com/discuss/tos.