# SailPoint IQService Administrator's Guide > IQService Administrator's Guide # Documentation # Before/After Scripts for IQService > [!IMPORTANT] > > The ScriptExecutor service is disabled by default. Native before and after provisioning scripts do not run unless IQService uses TLS and you enable ScriptExecutor. > > To enable ScriptExecutor after upgrading from a previous version, refer to [Secure Communication Between VA and IQService](). > > Refer to [Option to Enable/Disable Services]() for other IQService services and service status. The IQService supports customization of the functions by allowing integrating before/after scripts implemented in languages like PowerShell and Batch. Scripts can be used to automate any required actions that cannot be automated using current source functionalities. Scripts called before processing the request are referred to as native before scripts and scripts called after processing the request are referred to as native after scripts. The following sources support Before/After Scripts for IQService: - Azure Active Directory - Active Directory - Lotus Domino - Microsoft SharePoint Online - Microsoft SharePoint Server SailPoint provides most of the provisioning functionality for many systems through its connectors. Some systems provide better integration interface from Windows platform compared to other platforms. Hence connectors for such systems require IQService deployed on a Windows system. The IQService implementation performs the provisioning functions (such as Add User, Connect User to a Group) that are supported by the respective System. The IQService functions are called by the SailPoint source implementation. In addition to the basic action, some organizations may require supplementary actions performed by each function from Windows system. The IQService supports customization of the functions by allowing integrating before/after scripts implemented in any language. Following are some features of the IQService Before/After script: - Centralized configurations (in SailPoint) for setting up Before/After scripts - Supports Object Oriented scripting - Script refers SailPoint library to get the request, result classes - Can be executed with specific context - Script can modify request/result > [!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. A script is a group of statements that perform one or more actions and manipulate request/result attributes. Scripts can be used to automate any required actions that are currently performed manually. Scripts called before processing the request are referred to as native before scripts and scripts called after processing the request are referred to as native after scripts. The scripts needs to be defined in a Rule and then configured for a source in SailPoint. Based on the rule type, the connector would send the scripts to IQService that needs to be executed before/after processing the request. The IQService supports executing before and after Rules for Create, Modify, and Delete request operations. ## Writing a Script IQService divides scripts in the following categories: - Scripts with Object Oriented support - Scripts without Object Oriented support ### Scripts with Object Oriented Support Scripting languages with Object Oriented capabilities (for example, PowerShell) are popular because of their simplistic nature and easy to use. These scripts can form objects of any type by referring any library/assembly implemented in any language and call its methods. Native scripts implemented in these languages have easier and more powerful access to request and result objects. IQService comes with a class library named `Utils.dll` which bundles all required classes to access the request and result objects. The inputs provided to the script would be in the form of process environment variables. The following table describes the environment variables created by IQService: | Name | Type | Before Script | After Script | | --- | --- | --- | --- | | Application | System.Collections.Hashtable | Read Only | Read Only | | Request | SailPoint.Utils.objects.AccountRequest | Read/Write | Read Only | | Result | SailPoint.Utils.objects.ServiceResult | Not Available | Read/Write | The data in the environment variables is in XML. The script creates respective objects using `Utils.dll`. Once the object is modified, the script should convert it to XML by calling the `toxml()` method of the object and write the xml to a file at the path that is passed as the only argument to the script. The script returns non-zero value in case of error and writes the error message in the file at the path that is passed as the argument to the script. This failure is communicated to SailPoint as part of result. #### Sample PowerShell Before Script The following is a sample PowerShell before script that modifies the value of an attribute and adds one new attribute to the request: ```powershell # Refer to SailPoint class library Requires PowerShell v2 installed on the system. Add-type -path utils.dll # Read the environment variables $sReader = New-Object System.IO.StringReader([System.String]$env:Request); # Form the xml reader object $xmlReader = [System.xml.XmlTextReader]([SailPoint.Utils.xml.XmlUtil]::getReader($sReader)); # Create SailPoint Request object $requestObject = New-Object SailPoint.Utils.objects.AccountRequest($xmlReader); # Loop through the attributes from the request for each ($attribute in $requestObject.AttributeRequests){ if($attribute.Name -eq "description"){ $attribute.value = "my description"; #change value of the attribute } } # Add a new attribute to request $attributeObject = New-Object SailPoint.Utils.objects.AttributeRequest; $attributeObject.Name = "otherMobile"; $otherMobileValues = New-Object System.Collections.ArrayList; $otherMobileValues.Add("222-292-2929"); $otherMobileValues.Add("333-292-2929"); $attributeObject.Value= $otherMobileValues; $attributeObject.Operation = "Set"; $requestObject.AttributeRequests.Add($attributeObject); # Write the request xml to file at the path passed as argument $requestObject.toxml()|out-file $args[0]; ``` #### Sample PowerShell After Script The following is a sample PowerShell after script that ensures that the request was processed successfully and creates a home directory at the path specified in the request: ```powershell # Refer to SailPoint class library. Requires PowerShell v2 installed on the system. Add-type -path E:\SVN\trunk\src\WinRPCGateway\IQService\bin\Debug\utils.dll # Read the environment variables $sReader = New-Object System.IO.StringReader([System.String]$env:Request); $sResult = New-Object System.IO.StringReader([System.String]$env:Result); # Form the xml reader objects $xmlReader = [ System.xml.XmlTextReader]([sailpoint.utils.xml.XmlUtil]::getReader($sReader)); $xmlReader_Result = [ System.xml.XmlTextReader]([sailpoint.utils.xml.XmlUtil]::getReader($sResult)); # Create SailPoint objects $requestObject = New-Object Sailpoint.Utils.objects.AccountRequest($xmlReader); $resultObject = New-Object Sailpoint.Utils.objects.ServiceResult($xmlReader_Result); #Check if the request was processed successfully if($resultObject.Errors.count -eq 0){ #Get Home directory path foreach ($attribute in $requestObject.AttributeRequests){ #Create Home directory if($attribute.Name -eq "TS_TerminalServicesHomeDirectory"){ new-item $attribute.Value -itemtype directory; } } } ``` Following after script displays how to access any application configuration attribute in the script. The following example reads application attributes with the names `Office365Username` and `password` and uses them to connect to Exchange Online and set mailbox properties: ```powershell # Refer to SailPoint class library. Add-type -path C:\Program files\IQService\bin\Debug\utils.dll # Read the environment variables $sReader = New-Object System.IO.StringReader([System.String]$env:Request); $sResult = New-Object System.IO.StringReader([System.String]$env:Result); # Form the xml reader objects $xmlReader = [ System.xml.XmlTextReader]([sailpoint.utils.xml.XmlUtil]::getReader($sReader)); $xmlReader_Result = [ System.xml.XmlTextReader]([sailpoint.utils.xml.XmlUtil]::getReader($sResult)); # Create SailPoint objects $requestObject = New-Object Sailpoint.Utils.objects.AccountRequest($xmlReader); $resultObject = New-Object Sailpoint.Utils.objects.ServiceResult($xmlReader_Result); # Retrive nativeIdentity from request object $nativeIdentity = $requestObject.NativeIdentity # Get xmlFactory object to retive application configuration $xmlFactory = [sailpoint.Utils.xml.XmlFactory]::Instance; # Read the environment variables $sReader1 = $env:Application # Retrive application configuration object $appObject = $xmlFactory.parseXml($sReader1) #Retrive application configuration entries named Office365username and password value from AzureAD application config $office365AdminUsername = $appObject.Office365username #Retrive password attribute value $o365Password = $appObject.password #create Credential object $secpasswd = ConvertTo-SecureString $o365Password -AsPlainText -Force $cred = New-Object System.Management.Automation.PSCredential ($office365AdminUsername, $secpasswd) #Connect to Office365 Import-Module msonline Connect-MsolService -Credential $cred #Connect Exchange-Online $msoExchangeURL = "https://ps.outlook.com/powershell/" $session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri $msoExchangeURL -Credential $cred -Authentication Basic -AllowRedirection Import-PSSession $session # Set mailbox properties Set-MailBox -identity $nativeIdentity -UseDatabaseQuotaDefaults $false -IssueWarningQuota "200MB" -ProhibitSendQuota "250MB" -ProhibitSendReceiveQuota "280MB" ``` ### Scripts Without Object Oriented Support Non Object Oriented scripts do not support referring to the class library or a way of parsing XML. To have easy access to each attribute along with their operation and values, IQService creates process environment variables for each of the application and request attribute with name in the form `SP__` for requests and `SP_APP_` for application. For native identity, the environment variable would be `SP_NativeIdentity`. These types of scripts have limited access to result and get only `SUCCESS` or `FAIL` in the `Result` environment variable. Hence the after scripts implemented using these scripting languages cannot modify any attribute/result. The before scripts can add, modify, or remove any attribute from the request. The script needs to write the newly added or modified attribute to the file at the path passed as an argument to the script in the form `SP__=`. For removing the attribute from the request, write `/~` to the file. Value for the multivalued attribute is delimited by `/#/`. Following is a sample batch after script which ensures that the request was processed successfully and creates home directory at the path specified in the request: ```text IF %Result% ==SUCCESS md %SP_Set_TS_TerminalServicesHomeDirectory% ``` ### Creating a Rule To add the script to a rule and use it, you need to create a rule. [Contact SailPoint Services]() for assistance on creating rule as per requirement. ### Configuring the Rules in Source Add the `nativeRules` attribute under Attributes map with list of names of the Rules that must be configured for a source using the REST API. > [!NOTE] > > For more information on SailPoint's REST APIs, refer to [Best Practices: REST API Authentication]() and [REST API - Update Source (Partial)]() in the SailPoint Developer Community. ## Specifying PowerShell Version for Before/After Scripts IQService now supports specifying the PowerShell version to provide provisioning of Before/After nativeRules scripts to run under any PowerShell version. > [!NOTE] > > PowerShell scripts requiring PowerShell version greater than 5.1 should have `pwsh.exe` installed in the IQService host. Refer to [Installing PowerShell on Windows]() for more information. Following are the ways to specify versioning for PowerShell script with PowerShell version above 5.1: - Add a Program attribute in the rule as shown below: ```xml ``` - Add a statement `#Requires -Version 7.3 (Or any version greater than 5)` in the script in the first line of source-code. Refer to [about\_Requires]() for more information. > [!NOTE] > > - For PowerShell version above 5.1, the script will be executed with `pwsh.exe` instead of `powershell.exe`. > - To run nativeRules scripts with PowerShell version 5.1 and before, the value of the Program attribute is by default `powershell.exe`. Ensure to mention the version you want in `#Requires -Version`. If you do not mention `#Requires -Version` in the script, the script will run under default PowerShell version of that IQService machine. > - Other functionality and access to XML object in `ObjectOrientedScript` will continue to work as before. # 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 | | --- | --- | | `-b` | Skips the installation of secondary IQService. This is recommended to use for IQService instances installed on a load balanced deployment. | | `-d` | Run in console mode | | `-i` | Install a service | | `-k` | Stop the service | | `-m` | Allows you to pick the best certificate for TLS communication (when there are multiple) from the IQService host personal folder.

To pick the certificate with a matching subject name: `IQService.exe -m DNS:`

To pick the certificate with a matching serial number: `IQService.exe -m SN:`

To pick the certificate with a matching subject name and serial number: `IQService.exe -m DNS: -m SN:` | | `-p` | Update the port (requires restart)

**Important**
If you are updating your IQService instance to use a TLS port, disable the existing non-TLS port. For more information, refer to [Disabling Non-TLS Communication for an Existing IQService Instance]().

**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. | | `-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 ` | Trace Level 0-3; 0=off 1=error 2=info 3=debug | | `-f ` | Trace the file name. Defaults to system32 directory. Enter the full path with filename to log to a different path.

For example: `iqservice -l 3 -f "C:\Sailpoint\IQService\iqtrace.log"` | | `-a { \\| list}` | Registers a domain user for Client Authentication. Pass domain user name in msDS-PrincipalName (domain\\user) format. Multiple users can be registered in single command by separating users with semicolon ( ; ). This command appends the users to already registered users list if exist.

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 already registered users, run the command with "list" parameter. For example: `-a list` | | `-x { \\| list}` | De-registers a user from Client Authentication Users List. Pass domain user name in msDS-PrincipalName (domain\\user) format. Multiple users can be registered in single command by separating users with semicolon ( ; ).

For example: `-x "Acme\John.Smith; Acme\Joe.Phillips"`

To list already registered users, run the command with "list" parameter. For example: `-x list` | | `-o ` | TLS port for communication between IQService and SailPoint. This port accepts communication over TLS only.

**Important**
TLS is mandatory. Do not disable the TLS port. | | `-j ` | Enforce the specific TLS version for communication between IQService and SailPoint. Supported values are: TLS1.2, TLS1.1, TLS1.0. Default is TLS1.2. | | `-y ` | IQService update availability check interval. | | `-z tcp(s)://:` | Configures the UpdateService details that IQService communicates with. | | `-z enableClientAuth` | Enables the certificate-based client authentication between UpdateService and IQService. Configuring this will require an X.509 certificate be present in the personal certificate store of the IQService machine with EKU having Client Authentication. | | `-z disableClientAuth` | Disables the certificate-based client authentication. Configuring this will not provide a client certificate during the TLS handshake while communicating with UpdateService.

**Warning**
If UpdateService is configured to communicate with only trusted clients, then this configuration will break the communication channel. | | `-? \\| h:` | This is for help output.

Running `IQService.exe -?` or `IQService.exe -h` displays command line options.

**Caution**
To enhance security, it is mandatory to configure TLS for IQService. If you continue using a non-TLS configuration, before and after script execution is disabled to safeguard your environment.

Additionally, the following feature is also disabled in a non-TLS configuration: Using gMSA as a Service Account | | `-w` | Allow the IP addresses or FQDNs of additional client hosts configured for an instance. Separate multiple clients with semicolons. For example, `IQService.exe -w 10.10.20.30;LB.domain.com`.

To whitelist the IPs and FQDN, run the command with `IP/FQDN`. For example, `IQService.exe -w {}`

To list the whitelisted IPs and FQDN, run the command with the `list` parameter. For example, `IQService.exe -w list`

To delete the whitelisted IPs and FQDN, run the command with the `delete` parameter. For example, `IQService.exe -w delete` | | `-g` | View the enabled or disabled status of IQService services: `IQService.exe -g`

Enable a service: `IQService.exe -g --enable `

This applies to ScriptExecutor and GMSAPasswordData only.

Disable a service: `IQService.exe -g --disable `

This applies to ScriptExecutor and GMSAPasswordData only.

**Note**
For service descriptions and security changes, refer to [Option to Disable Services](). | ## tlsVersion Configuration IQService supports the tlsVersion configuration `default`. To enable it, run 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 common supported version from the predefined list of TLS versions. # IQService Fallback Implementation IQService allows you to install a secondary instance (fallback instance) of primary service running on a IQService host machine. This secondary IQService instance will take over only when a primary IQService instance is down and not serving the requests coming from SailPoint. In SailPoint, any request from user gets routed through VA (Cloud Connector Gateway). VA takes care of sending request to the appropriate request handler. Here if primary IQService instance is down, then the request processing will be redirected to secondary IQService instance by the VA. > [!NOTE] > > Once the primary IQService is restored or working as expected, VA will automatically start redirecting requests to the primary IQService. [![IQService fallback flow between the primary and secondary instances.]()]() > [!CAUTION] > > Do not consider the secondary service a load balancer or high availability service. The secondary service works only as a fallback when the primary IQService fails. > [!NOTE] > > Secondary IQService details are updated in source xml file only after first Test connection call. ## Installing the Secondary IQService Instance The secondary IQService is automatically installed on the same host but with different port (installer will use another available port) as the primary IQService. After installation, you can [configure]() a different port and TLS port. 1. `IQService.exe -i` : This command installs two instances of IQService. During installation it creates "IQService-Instance1-Secondary" directory inside installation directory of IQService. It copies all files present inside installation directory to that directory. It is installation directory for IQService-Instance1-Secondary service. 2. `IQService.exe -i -b` : This command allows customer to install only one instance of IQService. This command is recommended for only for the customers having load balancer configured to take care of failures in running service. 3. `IQService.exe -s` : If secondary service is installed this command will start both the instances of IQService. 4. `IQService.exe -k` : If secondary service is installed this command will stop both the instances of IQService. 5. `IQService.exe -t` : If secondary service is installed this command will restart both the instances. > [!NOTE] > > When Primary service is started, stopped, or restarted either from command or through services console the operation will be performed on both the instances. ## Configuring the Secondary IQService Instance The following commands are for Secondary IQService and must be executed from the installation directory of Secondary IQService (For example, `C:\IQService\-Secondary`): 1. `IQService.exe -v`: Print version information 2. `IQService.exe -p `: Update the port number of secondary service 3. `IQService.exe -o `: Update the TLS port number of secondary service 4. `IQService.exe -t`: Restart the secondary service For TLS, secondary service will use all the configuration defined in primary service (except the TLS port). The secondary service will use the log level defined in the primary service. The filename will be same as that of primary service. The only change is that the file would be present in the installation directory of the secondary service. > [!NOTE] > > It is recommended that customer should not stop secondary service. > [!NOTE] > > If log on user is changed for primary service then same log on user should be configured for secondary service, as well. # Frequently Asked Questions This Frequently Asked Questions (FAQs) section provides answers to the most commonly asked questions for IQService and its associated services. ## IQService - Auto Update ### What Does Auto-Update Mean? Auto-update means that the service updates automatically and does not require any manual intervention to upgrade to the new IQService version. It is like any other connector-bundle release on your VA. ### Does the UpdateService Require Internet Connectivity to Be Enabled from the IQService Box to Be Able to Download the Updates? Internet access is not required for IQService auto update as long as your VA is getting other bundles updated in your environment. Updates are downloaded at your VA and then the required updates are applied to all the IQService hosts using the UpdateService. ### How Do I Enable the Auto-Update? Auto update should already be enabled on your IQService instance. Other than that, you only need to ensure that IQService and the UpdateService are healthy and running. If auto update is not enabled on your system, refer to [Updating IQService]() for configuration instructions. ### Are IQService Auto Updates Safe/Recommended? Yes, enabling auto updates is safe and recommended by SailPoint. The auto updates ensure that your environment is always up to date with fixes and security patches. ### Are There Post Update Verification Steps That I Am Required to Follow? There are no required post update verification steps. If you want, you can check the UpdateService logs to confirm that you have the latest version and to verify the current update status. For more information on setting the trace log level, refer to [Updating IQService](). ### If I Choose to Not Enable Auto Update on IQService, How Will I Be Notified When It Is Time to Perform the Update Manually? SailPoint does not recommend that you manually update IQService. If you are still using the manual process, IQService releases are announced on the [SaaS Release Notes]() page. ### If an Auto Update Fails, Does IQService Roll Back to the Prior Version, or Does the Failed Update Cause the Service to Go Down? The auto update process includes an auto rollback process. A backup of the existing IQService version is made before starting the auto-update process, and if something goes wrong during the update process the backup is used to restore and restart the required services to restore functionality. If you run into a case where the update is successful and some functionality is not working, reach out to your SailPoint Customer Success Manager (CSM). ### How Long Does the Auto-Update Process Take? The process is quick and can last anywhere from a few milliseconds to 30 seconds. ### What Happens to Any in Progress IQService Tasks or Rules That Are in Execution When the Update Runs? Do They Get Interrupted and Is There an Automatic Recovery or Retry for Interrupted Processes? The auto-update process waits until there are no ongoing IQService transactions before starting the update. If there is an ongoing process the UpdateService will retry the update until there is a break in the transactions. ### How Do I Configure the IQService Auto Update When IQService Is Behind a Load Balancer? Refer to the Load Balancer Deployment column in the table on [Updating IQService](). ### I Have Two IQService Servers (behind a Load Balancer) - Does the Update Occur on One and Then the Other Sequentially? In load-balanced deployments, the UpdateService is shared amongst multiple IQService hosts. IQService instances are updated one at a time. This sequential update process ensures, there is no downtime during updates and at least one IQService instance is always available to process requests. This approach maintains system availability while applying updates to your IQService servers. For more information on configuring the UpdateService in an environment with a load balancer, refer to the Load Balancer Deployment column in the table on [Updating IQService](). ### To Configure UpdateService with TLS What Commands Are Required to Be Executed, or Is It Necessary to Go Through the Entire IQService Installation Process from the Beginning? You do not need to go through the entire IQService installation to configure TLS. Run the following command on the UpdateService and on the remote IQService server: ```text IQService.exe -z "tcps://:" ``` ### What Is the Process for Testing and Verifying the Functionality After Configuring UpdateService with TLS? If you have configured TLS and the UpdateService is running after installation, then that's it. You can run the IQService `-v` command to list the current statuses for all the services including the UpdateService. If the UpdateService is running, then your environment is good to go. ### Can IQService Be Behind the Load Balancer As Required for Redundancy or Load Sharing? IQService can be behind the load balancer as required for redundancy or load sharing. > [!NOTE] > > SailPoint does not certify any specific load balancer, work with your networking/IT team to resolve any configuration issue. For Configuring IQService with Load Balancer, perform the following: 1. For TLS communication, perform the following: 1. Create a certificate on load balancer. 2. For IQService hosts, export the certificate with **Private Key** and copy the certificates to personal and trusted folders. 3. Import the certificate in keystore and restart the web server. 4. Configure IQService with -m command `(-m )` as follows: ```text iqservice.exe -m "FQDNNameOFLoadBalancer" ``` 5. Restart the IQService. 2. For an unknown hosts error, provide the DNS mapping of Load balancer in IdentityIQ hosts files in the following format: ```text IPAddress FQDN 172.18.40.23 FQDNofLoadBalancer ``` File locations: - (For windows) `C:\Windows\System32\drivers\etc\hosts` - (For Linux) `/etc/hosts` 3. For key exchange, the key exchange task request would be triggered for one of the IQService hosts. Now copy the keys on other IQService machines. 4. To avoid Load Balancer creating unnecessary logging in IQService, set the IQService log level to 0. 5. In case of any fail over, the Load Balancer mechanism would redirect the requests to appropriate running IQService hosts. 6. TLS and Non-TLS ports of IQService are allowed through firewall for incoming and outgoing request through Load Balancer. ## IQService - Security ### Is It Possible to Change the TLS Cipher Suites on the IQService Side? Yes, you can change the TLS version and cipher suites on the Windows side. Microsoft provides a list of the default prioritized cipher suites that come as part of Windows OS, and on that list the AEAD ciphers (for example, AES-GCM) are usually on top. By default, IQService uses the top AEAD cipher suite unless the peer is configured to use less secure cipher suites. You have the option to configure TLS versions and cipher suites on Windows, that way if a client tries to negotiate with less secure ciphers, they are disabled on the OS level. The following lists the cipher suites supported on Windows, you can configure these based on your requirements: [Cipher Suites in TLS/SSL](). The following provides information on TLS configurations: [Enable TLS 1.1 and TLS 1.2 onwards support in Office Online Server](). You can enable TLS on the server side. For more information, refer to [Enable TLS 1.1 and TLS 1.2](). # Using gMSA as a Service Account > [!IMPORTANT] > > Ensure that the "PowerShell module for Active Directory" is installed on the IQService machine. To configure IQService to use a Group Managed Service Account (gMSA), follow these steps: 1. Create a gMSA account: 1. Open PowerShell as an administrator on the domain controller. 2. Run the following command to create a gMSA user, if not already existing: ```text New-ADServiceAccount MSAuserName -DNSHostName domainFQDNName -PrincipalsAllowedToRetrieveManagedPassword "Domain Controllers","Read-only Domain Controllers" ``` For example, ```text New-ADServiceAccount myMSAAccount -DNSHostName Monday.weekday.lab -PrincipalsAllowedToRetrieveManagedPassword "Domain Controllers","Read-only Domain Controllers" ``` This command creates the gMSA and allows the domain controllers and read only domain controllers to retrieve the password. This is only useful if the IQService is installed on a domain controller. 2. Restart the domain controller or run `klist purge -li 0x3e7` to refresh your credentials. 3. Install the gMSA account in the Active Directory environment by running the following command: ```text Install-ADServiceAccount -identity 'CN=myMSAAccount,CN=Managed Service Accounts,DC=Weekday,DC=lab' ``` 4. Add the User Principal Name (UPN) to the gMSA account if not already present, for example: ```text myMSAAccount@weekday.lab ``` 5. Configure IQService to run under the gMSA account: 1. Open **Services.msc** and locate the IQService Instance. 2. Right-click on the service and select **Properties**. 3. Go to the **Log On** tab and provide the **Account Name** as `myMSaAccount$`. 4. Remove any values in the Password fields. 5. Select **Apply** and then **OK**. 6. Restart the IQService for the changes to take effect. 6. Grant the service account the capability to retrieve the password by running the following command: ```text Set-ADServiceAccount -Identity -PrincipalsAllowedToRetrieveManagedPassword "" ``` For example, ```text Set-ADServiceAccount -Identity myMSAAccount$ -PrincipalsAllowedToRetrieveManagedPassword IQserviceuser1 ``` The gMSA service account can also be used as the IQService LogOn User (Windows Service LogOn User). In this case, ensure that the gMSA service account has full access to the IQService Instance folder on the registry. The gMSA account itself and the IQService server computer account are granted permission to retrieve the gMSA password, eliminating the need to set permissions for the IQService LogOn User. > **Note** > > You cannot use this gMSA as an IQService User during [IQService Settings]() configuration, which is required for client authentication. You still need either a domain or local user with a password to achieve the same purpose. 7. Configure Active Directory in SailPoint: 1. Ensure that you have added the necessary TLS certificate to the Virtual Appliance (VA) before creating the Active Directory connector. > **Important** > > SailPoint recommends adding the necessary TLS certificate to the Virtual Appliance (VA) before creating the Active Directory connector to ensure a smooth configuration process. 2. Go to the **Domain Settings** in the Active Directory configuration. 3. Set the **Authentication Type** to strong for Strong (SASL) authentication. 4. Provide the necessary domain details, such as **Forest Name**, **Domain DN**, **Servers**, and the gMSA account UPN. Here's an example of the configuration: ```json { "entry": { "value": { "List": { "Map": { "entry": [ { "key": "authorizationType", "value": "strong" }, { "key": "forestName", "value": "weekday.lab" }, { "key": "domainDN", "value": "DC=Weekday,DC=lab" }, { "key": "password" }, { "key": "port", "value": "389" }, { "value": { "Boolean": "true" }, "key": "enablePasswordLessAuthenticationForDomain" }, { "value": { "List": { "String": "myDC.weekday.lab" } }, "key": "servers" }, { "value": { "Boolean": "" }, "key": "useSSL" }, { "key": "user", "value": "myMSAAccount@weekday.lab" } ] } } }, "key": "domainSettings" } } ``` > [!IMPORTANT] > > The GMSAPasswordData service is disabled by default. The gMSA password retrieval does not work unless IQService uses TLS and you enable GMSAPasswordData. > > To enable GMSAPasswordData after upgrading from a previous version, refer to [Configuring TLS and Client Authentication for IQService](). > > For other IQService service and service status, refer to [Option to Enable/Disable Services](). ## Opening Port 88 for gMSA Communication When you use a gMSA account, open port 88 on the firewall for communication between the Virtual Appliance (VA), the IQService server, and Active Directory. If this port is not open, the test connection fails with a timeout error. ## Using Non-TLS LDAP Ports with Strong (SASL) Authentication For domain and forest settings, use a non-TLS LDAP port. TLS is not supported for Strong (SASL) authentication with gMSA, so you cannot use gMSA with simple bind, with or without Transport Layer Security (TLS). > [!NOTE] > > This restriction applies only to the LDAP connection between SailPoint and Active Directory. IQService can still use TLS for its own communication. ## Configuring Forest Settings for gMSA After IQService runs under the gMSA account, configure the Active Directory source forest settings the same way as the domain settings: provide the gMSA account UPN, set the authentication type to Strong (SASL), and use a non-TLS port. For field-level guidance, refer to [Forest Settings]() and [Domain Settings](). # Introduction to 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. > [!NOTE] > > The latest version of IQService is IQService-May-2025. The following figure shows the communication flow of IQService with various end systems. A single IQService instance can serve multiple sources of the same or different source types. For enhanced performance, SailPoint recommends setting up separate instances for each of the sources. IQService supports setting up multiple instances on the same system, though these instances share the same system resources and it might degrade performance. [![Communication flow of IQService with various end systems.]()]() Securing all communications coming in and going out from IQService is very crucial to ensure overall security of the solution and data integrity. For more information, refer to [IQService Security Considerations](). IQService executable and libraries are digitally signed to ensure integrity of the files. ## Supported Sources ### Active Directory - Provisioning operations - Managing Exchange - Managing Skype - Managing (Read\\Write) terminal service attributes - Before and After script - Shared Mailbox Management ### Azure Active Directory - Before and After script - Exchange Online management ### HCL Domino (IBM Lotus Domino) - Password management - ID Vault operations - Delta aggregation - Before and After script ### Microsoft SharePoint Online - Before and After script ### Microsoft SharePoint Server - Test Connection - Account Aggregation - Entitlement Aggregation - Provisioning operations - Before and After script ### Windows Local Source - Test Connection - Account Aggregation - Entitlement Aggregation - Provisioning operations - Before and After script # Installing and Registering IQService > [!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. You can download IQService from the configuration page of a source that requires it. - **Alternative Names:** Look for "**IQService**," "**Integration Service**," or "**Server Host**". - **Network Protocol:** IQService is compatible with both IPv4 and IPv6. ## Download the Integration Service Install this service only if you use one of the following sources: - Azure Active Directory - Active Directory - HCL Domino (IBM Lotus Domino) - Microsoft SharePoint Online - Microsoft SharePoint Server - Windows Local > [!NOTE] > > No need to install IQService if you do not already have one of these sources configured. **To download the service:** 1. Go to **Connections \> Sources**. 2. Select one of the sources that needs IQService. 3. On the source configuration page, find the panel labeled **IQService** or **Integration Service**. [![Integration Service panel on the source configuration page.]()]() 4. Select **Download**. ## Installation and Service Start-Up 1. **Prepare the Installation Files** Before you start, use the downloaded components in compliance with the active SailPoint license. Use the files only for their intended purpose and do not share or redistribute them. If you have questions about usage rights, contact your Account Representative or CSM. 1. **Unzip the archive** - Extract the downloaded `IQService.zip` archive into your desired location. For example: ```text C:\SailPoint\IQService\ ``` 2. **Verify DLLs** - After extracting, right-click the DLL files and check the properties to confirm they are from a trusted source. 2. **Install the Windows Service** To improve security, the IQService installation enforces a TLS configuration by default. Complete the necessary TLS prerequisites before running the installation command. For detailed requirements and setup procedures, refer to [Configuring TLS and Client Authentication for IQService](). When you are ready, open a command prompt and run one of the following commands: **Option A - Default installation:** This command installs the service as `IQService-Instance1` on the default port 5050, if available. ```text IQService.exe -i ``` **Option B - TLS-only installation:** This command installs the service as `IQService-Instance1` on the TLS port number that you provide. ```text IQService.exe -i -o ``` ### Security Notice During a Fresh Install When you run a fresh install of IQService, the installer displays a security notice in the command prompt. The notice states that selected services are disabled by default and must be explicitly enabled after TLS is configured. The notice is similar to the following: ```text ╔══════════════════════════════════════════════════════════════════════════════╗ ║ SECURITY NOTICE - Services Disabled by Default ║ ╠══════════════════════════════════════════════════════════════════════════════╣ ║ Starting this release, the following services are DISABLED ║ ║ by default and must be explicitly enabled before use: ║ ║ ║ ║ GMSAPassword - Using gMSA as a Service Account ║ ║ ScriptExecutor - Script execution (before and after script) ║ ║ ║ ║ To enable a service, run (TLS must be configured first): ║ ║ IQService.exe -g --enable ║ ║ ║ ║ Example: IQService.exe -g --enable GMSAPassword ║ ╚══════════════════════════════════════════════════════════════════════════════╝ ``` > **Note** > > Use the exact service name shown by `IQService.exe -g` when you run `--enable`. The gMSA service is called `GMSAPasswordData`. Confirm the name in your build before you enable the service. Refer to [Option to Enable/Disable Services](). ### Service and Port Details - **Service name:** The service is installed with the name `IQService-Instance1`. In the Windows Services console, its display name begins with `SailPoint`. - **Default port:** By default, IQService uses port 5050 for the primary instance and 5051 for the secondary instance. ### For Existing Installations (If Updating) Disable the old non-TLS port if you are updating an existing IQService instance to use a TLS port. This is crucial to close security gaps and maintain a secure connection. - For detailed instructions, refer to [Disabling Non-TLS Communication for an Existing IQService Instance](). - For complete details on the requirements and procedures for a secure setup, refer to the [Configuring TLS and Client Authentication for IQService]() guide. ### Start the Service Select one of the following methods to start the service: 1. **From the Windows Services console** - Open the **Services** console, locate the service name beginning with `SailPoint`, and select **Start**. 2. **From the command line** - Run the following command: ```text IQService.exe -s ``` ### Grant Service Account Access to the Certificate Private Key > **Note** > > If you run IQService under a service account context, that service account must be granted access to the private key of the valid certificate on your VA machine. **To grant access to the certificate private key:** 1. Go to Certificate Manager on your VA. [![Certificate Manager showing Personal Certificates store on the local computer.]()]() 2. Right-click the valid certificate and select **All tasks \> Manage private keys**. [![Certificate context menu with All tasks and Manage private keys selected.]()]() 3. Add the service account user that is used when configuring IQService. [![Permissions dialog for certificate private keys with Add selected.]()]() 4. Select **Apply**. 5. Restart IQService. # Option to Enable/Disable Services IQService has a configuration option to disable unwanted services from an IQService installation. IQService provides multiple services to communicate to different windows-based end systems. It is possible that for a given deployment, not all services are required. Services which are not required in your deployment can be disabled. | Service Name | Description | | --- | --- | | AD | This service is used to communicate with Active Directory. | | Lotus Domino | This service is used when Delta aggregation/change password is to be performed for a Lotus Domino source. | | ScriptExecutor | This service is used to run native before and after provisioning scripts. | | SharePointServer | This service is used if a SharePoint server source is configured. | | AzureAD | This service is used when native before and after provisioning scripts need to be executed or when Exchange Online mailbox management is to be performed. | | WinLocal | This service is used if a Windows Local source is configured. | | GMSAPasswordData | This service allows IQService to retrieve clear-text passwords for Group Managed Service Accounts (gMSA) from Active Directory using Windows PowerShell. | ## Viewing the Current Status of Services To view the enabled or disabled status of services, run `IQService.exe -g`. To toggle the state, run the following command: ```text IQService.exe -g IQService.exe -g AD ``` Multiple services must be separated by semicolon: ```text IQService.exe -g AD;LotusDomino ``` > [!NOTE] > > Restart IQService when service status is updated. ## Services Enabled by Default The following IQService services are enabled by default: - AD - LotusDomino - SharePointServer ## Services Disabled by Default The following IQService services are disabled by default: - **ScriptExecutor** - native before and after provisioning scripts (including when the `nativeRules` feature is configured on an Active Directory source). - **GMSAPasswordData** - gMSA password retrieval from Active Directory. The ScriptExecutor and GMSAPasswordData services are disabled by default. Related functionality does not work unless IQService is configured to communicate over TLS and an administrator explicitly enables the required service. **To configure TLS and enable services after upgrading from a previous version:** 1. Configure IQService to communicate over TLS, for example: ```text IQService.exe -o ``` Refer to [Secure Communication Between VA and IQService]() for TLS configuration instructions. 2. Enable each service your deployment requires, for example: ```text IQService.exe -g --enable ScriptExecutor IQService.exe -g --enable GMSAPasswordData ``` 3. Restart IQService after you update service status. To disable a service explicitly, run `IQService.exe -g --disable `. Refer to [Before/After Scripts for IQService]() for native before and after provisioning scripts. Refer to [Using gMSA as a Service Account]() for gMSA configuration. # Prerequisites The following lists the software, hardware, and service account requirements. ## Software Requirements ### Operating Systems - Microsoft Windows Server 2025 - Microsoft Windows Server 2022 - Microsoft Windows Server 2019 - Microsoft Windows Server 2016 ### .NET Framework - .NET Framework version 4.8 and later ## Hardware Requirements The hardware requirements are specified as: | Component | Recommended Hardware Requirement | Minimum Hardware Requirement | | --- | --- | --- | | CPU | 8-Core | 4-Core | | RAM | 16 GB | 8 GB | | Free Disk Space | 50 GB | 250 MB | > [!IMPORTANT] > > This is minimum hardware requirement for basic working 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 caters to. ## Service Account The service account defined in the SailPoint source that connects to IQService, is used for provisioning operations, aggregation (for Active Directory, terminal services and Skype attributes), and server-less binding for respective target system. > [!NOTE] > > IQService User registered with IQService is used for Client Authentication. However, the account defined for the IQService Log On as account in Windows, is used for the before/after scripts where Powershell is being used and if the source's service account is not used then the Powershell session is opened under the service account credentials of IQService. To use gMSA as a service account for Active Directory sources, refer to [Configuring IQService to Use gMSA as a Service Account for Active Directory](<#configuring-iqservice-to-use-gmsa-as-a-service-account-for-active-directory>) for more information. ## Source-Specific Additional Prerequisites The following lists the sources that require IQService and the respective additional prerequisites: ### Active Directory - The user must be a Local Administrator and an Account Operator or Domain Administrator in Active Directory. > **Note** > > The Account Operator user can manage passwords of the normal users. However, if any of the users are at a higher level than Account Operator (such as a Domain Admin), then the Service Account needs to be at the same level or higher and the Service Account must have appropriate rights on the Active Directory. - Windows PowerShell 3.0 - The Domain Controller must be accessible from IQService host computer. - For Microsoft Skype for Business Server user management: - IQService host must have Skype Server Administrative Tools installed - IQService must be installed in the same domain as the Skype server - The user must be a member of RTCUniversalServerAdmins and CSAdministrator domain groups. The user must also be a member of local Administrator group where IQService is installed. > **Note** > > Skype Server Administrative Tools cannot be installed on a Domain Controller. If the IQService is currently running on a Domain Controller, you must move it to any other machine where tools can be installed, before provisioning to Skype. - For Microsoft Exchange provisioning: - To manage Microsoft Exchange Server 2010 and above, the user and the user running IQService must be a member of the Recipient Management group. - Windows PowerShell 3.0 is required if you want to manage Exchange using the Active Directory source and IQService is installed on servers with operating systems older than Microsoft Windows 2012. > **Note** > > For Microsoft Exchange Server 2007 and Skype for Business Server, rename the app.config file present in the IQService directory to IQService.exe.config. > **Note** > > The IQService has the multi-forest support for the Active Directory source. - The Active Directory source supports Serverless configuration. To get the closest Active Directory Server (DomainController) for a particular domain, the source calls the IQService. - If the Active Directory source is configured in Serverless mode (no explicit Active Directory Server defined), the following are the prerequisites: 1. Windows PowerShell 3.0 or above. 2. Active Directory Module for Windows PowerShell must be installed. ### HCL Domino - A HCL Notes Client that has the same version as the HCL Domino Server. - Microsoft Visual Studio C++ 2015-2022 Redistributable 14.0 onwards. > **Note** > > Ensure that the PATH environment variable must contain the Notes data folder. For example, `C:\Program Files\HCL\Notes` - If you are running a 32-bit version of HCL Notes (that is, a version prior to HCL Domino Client 14.0), IQService must be running as a 32-bit process to interact with 32-bit HCL Notes. If IQService must be installed on a 64-bit Windows system, perform the following before installing the IQService: 1. Download Microsoft Windows SDK or .NET Framework SDK. 2. Extract the IQService zip file into a temporary folder. For example, `C:\temp` 3. Run the following command from the command prompt: ```text \CorFlags.exe C:\temp\IQService.exe /32BIT+ ``` For example, ```text C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\x64>CorFlags.exe C:\temp\IQService.exe /32BIT+ ``` This command converts the IQService.exe to a 32-bit application. 4. Copy all the files from `C:\temp` to the `C:\Program Files (x86)\HCL\Notes` path. 5. Install and start the IQService. For more information on IQService installation steps, refer to [Installing and Configuring IQService](). - If you are running a 64-bit version of HCL Notes (that is, HCL Domino Client 14.0 and onwards), IQService must be running as a 64-bit process in order to interact with the 64-bit HCL Domino Client. 1. Extract IQService zip file into a temporary folder. For example, `C:\temp` 2. From path `C:\temp\IQService\SPLotusNotes-x64\`, copy the `SPLotusNotesWrapper.dll` file and replace it with the destination `C:\temp\IQService\` 3. Copy all the files from `C:\temp` to the `C:\Program Files\HCL\Notes` path. 4. Install and start the IQService. For more information on IQService installation steps, refer to [Installing and Configuring IQService](). ### Azure Active Directory - Location: Remote or Local - Other Libraries: .NET Framework version 4.5.x onwards - PowerShell version 5.1.x onwards (with the exception of PowerShell v7, which is not supported). ### Ports Used with Active Directory Integrations The IQService provisioning agent calls functions exposed by Microsoft's .net packages that are a "black box" that communicate to Active Directory indirectly. SailPoint does not control what port numbers these APIs leverage to interact with Active Directory. Microsoft publishes a list of ports that the .net API and ADSI interfaces use to communicate with an Active Directory server. Were a firewall to be placed between IQService and the Active Directory domain controllers it would need to be exceedingly permissive by opening a large number of dynamic ports. The complete list of ports is published by Microsoft here: [Active Directory and Active Directory Domain Services Port Requirements](). The IQService agent uses a sub-set of these ports documented by Microsoft. For communication between IQService and a domain controller SailPoint recommends at least the following ports must be opened: - LDAP Ports 389 and 636 - Kerberos port 88 - Active Directory Web Services 9389 - Active Directory port 3268 - Active Directory port 3269 - Active Directory DNS port 53 - Active Directory Replication, Login services port 445 - Kerberos Passwords, port 464 - Authentication port UDP 137 - Authentication port TCP 139 For more information, refer to [IQService Architecture - Network Ports and Firewalls](). ## Required Permissions The IQService supports configuration of the minimum permissions. The sources supporting IQService minimum permissions are: - Active Directory - Microsoft SharePoint Server ### Prerequisites - The IQService must have been installed with the admin permission. - A domain user or local user can be used to run the IQService with minimum required permission. > [!NOTE] > > If the IQService host machine is not added to any domain, instead of the domain user, you must use the Windows local user. > [!NOTE] > > The IQService can run under user context of minimum permission user or gMSA user. Ensure the user have proper minimum permission. ### Steps for Running Service with Minimum Permission User 1. Install the IQService with admin permission. 2. In registry, assign full permissions to the domain user or Local user or GMSA user created previously (as mentioned in [Prerequisites](<#prerequisites_1>)) to the IQService instance that is installed and needs to be run. > **Note** > > The default location for the registry is `Computer\HKEY_LOCAL_MACHINE\SOFTWARE\SailPoint\IQService Instances\IQService-InstanceName` ### Steps to Assign Full Permissions to the User That Is Required to Manage the IQService Instance 1. Assume a new IQService instance is installed on machine (`IQService-InstanceName`). 2. Navigate to registry and search for SailPoint registry hive. `Computer\HKEY_LOCAL_MACHINE\SOFTWARE\SailPoint\IQService Instances\IQService-InstanceName` Right-click on the Instance and select permission. 3. Add the required user and assign full Control Permission. Save the changes. 4. Use the same user for "log on as service" from Services tab for the IQService instance. 5. Restart the IQService to work with the user defined above. Log file must also have the required permission to user for writing files. The IQService Instance folder must also have the required permissions. For enabling TLS for IQService settings, a normal user or gMSA user must have full permission to access the IQService certificate that is required for communication between secure TLS communication between SailPoint and IQService. Perform the following: 1. On IQService host, navigate to Personal Folder (on Local System) where the certificate exists. 2. Add full control access on Certificate to the user 1. Right click on IQService Certificate \> All tasks \> Manage Private keys \> Add user \> Full control \> Ok 2. Add the user and provide full permission that is used for managing the IQService. > [!NOTE] > > For managing Skype for Active Directory Connector, IQService must be running in Admin mode only. > [!NOTE] > > Also, for managing Before/After scripts, user must have required permission to execute cmdlets in the script. ### Configuring IQService to Use gMSA As a Service Account for Active Directory For all the gMSA(s) that will be used during Active Directory source configuration, `PrincipalsAllowedToRetrieveManagedPassword` permission is required to be added to the IQSerivce Log On User. Add the following permission to the Log-On User of the IQService using the Active Directory PowerShell module: ```text Set-ADServiceAccount -Identity -PrincipalsAllowedToRetrieveManagedPassword "" ``` For example, ```text Set-ADServiceAccount -Identity Aug13u1$ -PrincipalsAllowedToRetrieveManagedPassword IQserviceuser1 ``` Refer to [Using gMSA as a Service Account]() for more information. When gMSA password retrieval is required, configure TLS on IQService and run `IQService.exe -g --enable GMSAPasswordData`, then restart IQService. Refer to [Option to Enable/Disable Services]() and [Using gMSA as a Service Account]() for upgrade steps and related security changes. # Recent Updates ## UpdateService With the latest release, IQService is packaged with UpdateService which needs to be configured alongside IQService to enable the auto update functionality. Once the UpdateService is configured, no manual intervention is required for further releases. To ensure secure communication between the services, SailPoint recommends that you use TLS and Client Authentication for IQService configuration, which in turn is used by the UpdateService for communication. ## Configuration of Timeout IQService supports configuring a maximum waiting time before terminating the inactive connection while reading requests. By default, the timeout value is 15 seconds. For example, you can use the `IQService.exe -q 20` command to set up the time for 20 seconds. ## .NET Framework Prerequisite for IQService SailPoint recommends .NET Framework 4.8. IQService is compatible with .NET Framework 4.5.2 or later. ## Correct Display of Logs The IQService `IQService.exe -v` command now displays the trace level logs. Additionally, the IQService log level values: - 0=off - 1=error - 2=info - 3=debug By default, it is 1 = error level logs. ## Improved TLS Connection IQService now successfully connects with TLS from SailPoint when certificate SAN (subject name) is in a foreign language. ## 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 - Setting the Port 1. Set the existing non-TLS port to zero (0) or any negative number (such as -1, -2, -3) using the command line: ```text IQService.exe -p ``` For example, ```text 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 - Deleting the Registry Entry 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: ```text HKEY_LOCAL_MACHINE\SOFTWARE\SailPoint\IQService Instances\ ``` You can find the registry path for the secondary service at: ```text HKEY_LOCAL_MACHINE\SOFTWARE\SailPoint\IQService Instances\\Secondary ``` Replace `` 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: ```text 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 : ` ## Install and Command Line Notices A fresh IQService install displays a security notice banner in the command prompt. The `IQService.exe -?` help output includes an additional TLS security warning and lists features disabled when TLS is not configured. Refer to [Installing and Registering IQService]() and [IQService Commands](). ## IQService Security Updates The ScriptExecutor and GMSAPasswordData services are disabled by default. If you are upgrading from a previous version, you must configure TLS and explicitly enable each required service to avoid interruption. Configure TLS with `IQService.exe -o `. For instructions, refer to [Secure Communication Between VA and IQService](). Enable services with `IQService.exe -g --enable `, then restart IQService. Refer to [Option to Enable/Disable Services]() for service names and usage details. ### ScriptExecutor Used for native before and after provisioning scripts, including when the `nativeRules` feature is configured on an Active Directory source. Refer to [Before/After Scripts for IQService](). ### GMSAPasswordData Used to retrieve clear-text gMSA passwords from Active Directory. Refer to [Using gMSA as a Service Account](). # Secure Communication Between IQService and UpdateService TLS Communication and Client Authentication between IQService and UpdateService must be configured to completely secure this solution. - TLS Communication between IQService and UpdateService is supported and must be configured to secure this communication channel. > **Note** > > Certificate based client authentication is not mandatory for TLS communication. - For Client Authentication, UpdateService supports authenticating a client connecting to it. This authenticates every incoming request from IQService before executing those requests. To ensure the authentication works correctly, UpdateService expects the client (IQService here) to send, with every request, a client certificate of the trusted client that is already registered with UpdateService. > **Note** > > To enable certificate based client authentication between IQService and UpdateService, it needs to be explicitly configured. For more information on configuration, refer to [Configuring TLS and Certificate-Based Client Authentication for UpdateService](). # IQService Security Considerations > [!WARNING] > > SailPoint recommends that you must configure sources to use Transport Layer Security (TLS) along with client authentication to secure the communication channels involving IQService. > > In the absence of TLS configuration, an unauthenticated attacker could potentially execute arbitrary commands on the system. For communication between the SailPoint VA and IQService, every incoming request from SailPoint is authenticated before executing it on the target system. To ensure the authentication works correctly, IQService expects the client (SailPoint here) to send, with every request, the credentials of a user that is already registered with IQService. Before processing every request the IQService first confirms that the passed user is registered with it and then authenticates the credentials with the Windows system it is running on. Client Authentication is mandatory when the TLS communication is enabled for IQService. To secure the communication between IQService (Client) and UpdateService (Server), TLS communication can be configured. It is not mandatory to have Client Authentication for this communication channel. To further secure the communication channel, Certificate based Client Authentication can be configured. # Secure Communication Between VA and IQService TLS Communication and Client Authentication between IQService and VA must be configured to completely secure this solution. > [!CAUTION] > > If you have IdentityIQ and SailPoint Human Fabric 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 SailPoint 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 the IQService when the TLS communication is enabled for IQService. > > SailPoint recommends using a privileged access user as the registered user for client authentication. You can also use the IQService Service Log On user for this purpose. ## Prerequisites > [!NOTE] > > **For TLS Communication between the VA and IQService** > > - 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. > [!NOTE] > > **For Client Authentication** > > - 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 SailPoint 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 SailPoint 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](<#disabling-non-tls-communication-for-an-existing-iqservice-instance>). ## TLS Configuration Between VA and IQService 1. Download IQService from SailPoint 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 SailPoint on the TLS port only. ```text IQService.exe -i -o ``` 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 **Enable Transport Layer Security (TLS)** checkbox. ## TLS Configuration Check List ### IQService Host - 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). [![TLS certificate with and without private key]()]() - 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. > [!NOTE] > > **Common Name (CN) in the Subject field in X.509 certificate** > > [![Common Name in X.509 certificate Subject field]()]() > [!NOTE] > > **DNS entry in the Subject Alternative Name extension in the X.509 certificate** > > [![DNS entry in X.509 certificate Subject Alternative Name extension]()]() - 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: > [!NOTE] > > **X.509 certificate (Non trusted)** > > [![Non-trusted X.509 certificate]()]() > [!NOTE] > > **X.509 certificate (Trusted)** > > [![Trusted X.509 certificate]()]() ### Virtual Appliance Configuration 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. [![TLS virtual appliance configuration]()]() > [!NOTE] > > Ensure to export the full certificate chain and convert it into a single PEM / Base64 formatted file. > [!NOTE] > > **Steps to Export and Convert the Certificate Chain** > > 1. Using the Microsoft Management Console (MMC), export the certificate chain as a `.p7b` file in DER/Binary format. > 2. Use the following OpenSSL command to convert the `.p7b` file to a `.pem` file: > > ```text > openssl pkcs7 -print_certs -in certchain.p7b -inform DER -out certificate.pem -outform PEM > ``` > 3. Place the output `.pem` file onto the VA. The CCG will then load the certificates from this file. > > ##### Handling Multiple Certificate Chains > > If you have multiple certificate chains (For example, one for VA to IQService communication and another for VA to AD communication), each chain must be placed in a separate PEM file. ## Configuration of IQService Client Authentication 1. On the IQService host, run the following command: ```text IQService.exe -a ``` For example: `IQService.exe -a "Corp\John.Doe"` - The domain user must be in the `msDS-PrincipalName` format: ```text \ ``` - If you are using a local user, it must be in the following format: ```text 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: ```text IQService.exe -p ``` For example, ```text IQService.exe -p 0 ``` ```text 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: ```text HKEY_LOCAL_MACHINE\SOFTWARE\SailPoint\IQService Instances\ ``` You can find the registry path for the secondary service at: ```text HKEY_LOCAL_MACHINE\SOFTWARE\SailPoint\IQService Instances\\Secondary ``` Replace `` 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: ```text 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 : ` ## Troubleshooting ### TLS Communication > [!NOTE] > > **Failed to connect to IQService. Please check TLS configuration for IQService.** > > **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. > [!NOTE] > > **java.security.cert.CertificateException: No subject alternative names present** > > **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](). > [!NOTE] > > **Connection Reset** > > **Resolution**: Verify the following: > > - This could be because IQService TLS is disabled and you have provided TLS port. Ensure that the **Enable Transport Layer Security (TLS)** 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: > > ```text > iqservice.exe -m hostname.example.com > iqservice.exe -t > ``` > [!NOTE] > > **Connection refused** > > **Resolution** - Ensure your IQService service is running. > [!NOTE] > > **Failed to connect to IQService. Please check TLS configuration for IQService.** > > **Resolution** - This could be because the IQService version is older. Ensure your IQService service is upgraded to latest version. Deselect the **Enable Transport Layer Security (TLS)** checkbox for non-TLS communication. > [!NOTE] > > **Line: 1 Column:1: Content is not allowed in prolog.** > > **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 **Enable Transport Layer Security (TLS)** checkbox is unchecked on source configuration. > [!NOTE] > > **Unrecognized SSL message, plaintext connection?** > > **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 **Enable Transport Layer Security (TLS)** checkbox is unchecked on source configuration. ### Client Authentication The following errors may be returned from IQService. > [!NOTE] > > **No such user registered with IQService.** > > **Resolution**: > > - Ensure that you have registered and configured the IQService user and password on IQService host using the following command: > > ```text > IQService -a username > ``` > - Ensure that you have provided the correct IQService user or password. Use the latest CCG version and IQService version. > [!NOTE] > > **Client authentication failed with error - The user's password must be changed before signing in** > > **Resolution** - The IQService user's password could be expired. To resolve the issue, change the password for the IQService user. > [!NOTE] > > **Client authentication failed with error - The user's account has expired** > > **Resolution** - Password could be expired for IQService user. To resolve the issue, change the password for IQService user. > [!NOTE] > > **Client authentication failed with error - The referenced account is currently locked out and may not be logged on to.** > > **Resolution** - Ensure that the IQService user is not locked. > [!NOTE] > > **Client authentication failed with error - This user can't sign in because this account is currently disabled** > > **Resolution**: Ensure that the IQService user is not disabled. > [!NOTE] > > **Client authentication failed with error - Your account has time restrictions that keep you from signing in right now** > > **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. > [!NOTE] > > **The input is not a valid Base-64 string as it contains a non-base 64 character, more than two padding characters, or an illegal character among the padding characters.** > > **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. # Configuring TLS and Certificate-Based Client Authentication for UpdateService UpdateService is a service that is responsible to update itself and all the corresponding IQServices that communicate with it. SailPoint highly recommends configuring the UpdateService for receiving smooth updates, feature releases and bug fixes. UpdateService removes the requirement to manually update the IQService whenever a new version is released. > [!NOTE] > > UpdateService is only packaged for SailPoint deployment. If you have IdentityIQ and SailPoint in your environment, install a separate instance of IQService for each system. SailPoint highly recommends configuring the UpdateService along with the IQService instances. - **TLS Communication**: TLS Communication between IQService and UpdateService is supported and must be configured to secure this communication channel. - **Client Authentication**: The UpdateService supports Client Authentication that authenticates every incoming request from any client before executing those requests. To ensure the authentication works correctly, UpdateService expects the client to send, with every request, a client certificate whose subject is already registered with it. Before processing the request, UpdateService validates the client certificate during TLS handshake and also verifies whether its subject is registered with it or not. It only proceeds with the request if it finds the subject is registered with UpdateService. > [!NOTE] > > - While registering certificate subject names of trusted clients with UpdateService, providing Subject Alternative Name of the certificate is also supported. > - If TLS is configured between the VA and IQService, then IQService and UpdateService will both use the same certificate for Server Authentication. This is because UpdateService uses the same logic to search for the server certificate as its corresponding IQService. > - The IQService that is local to UpdateService will use the same certificate for Client Authentication. This is because the logic to search for certificates for different EKUs is the same. This requires the certificate to have both of the following EKUs: > > - Server Authentication > - Client Authentication ## Prerequisites ### For TLS Communication Between IQService and UpdateService - All UpdateService machines must have an X.509 certificate with Extended Key Usage (EKU) as Server Authentication must be available in the personal certificate store of the machine. The subject of certificate should match the FQDN of the UpdateService machine for example, `updateservice.test.com`. - The matching private key must be present in the machines RSA key directory. - If the certificate mentioned above is not available, create a CSR (Certificate Signing Request) from the UpdateService machine. - Submit the CSR to a trusted (internal or third party) CA for signing. Ensure that the CA is on trusted root CA list of the machine. - This certificate must be trusted by all the IQService client machines to validate the server authenticity. ### For Certificate-Based Client Authentication - In this case IQService is the client. All the IQService machines must have an X.509 certificate with Extended Key Usage (EKU) as Client Authentication in the personal certificate store of the machine. - The subject of the client certificate must be added as a trusted client with UpdateService. This should be done for all the IQService instances that will be communicating with UpdateService. ## TLS Configuration Between UpdateService and IQService To enforce TLS communication between UpdateService and its corresponding IQService(s), complete the following steps: 1. UpdateService is always configured and installed alongside one of the IQService instances. UpdateService installation is not standalone. 2. While installing UpdateService along with its corresponding IQService, TLS must be configured using the following command: ```text IQService -z "tcps://: ``` 3. UpdateService uses this configuration to enforce TLS communication between its clients. ## Configuration of Certificate-Based Client Authentication for UpdateService To configure client authentication, the following steps need to be performed on both UpdateService side and IQService(s) side. > [!IMPORTANT] > > Certificate-Based Client Authentication will only be initiated by UpdateService if it is configured with the list of trusted certificate names. If that is not done, UpdateService will skip the validation of incoming client requests whether or not the client provide any certificates during the TLS handshake. - IQService Configuration: 1. IQService machines must have the respective X.509 certificate with matching FQDN with EKU as Client Authentication. 2. IQService must configure itself to use Client Authentication using the following command: ```text IQService.exe -z "enableClientAuth" ``` 3. Restart IQService after this configuration. 4. Only when this configuration is added will IQService (client) search for its Client Authentication certificate to provide to the UpdateService. - UpdateService Configuration 1. UpdateService must be configured with the subjects of trusted client certificates. 2. This can be done using the following command: ```text UpdateService -a ``` For example, `UpdateService.exe -a iqservice1.test.com` 3. You can add multiple entries by separating the certificate subject names with a semi-colon (;). # TLS Configuration on Virtual Appliances Enabling a source to communicate with a virtual appliance using a TLS connection encrypts all data sent between the source and the VA. ## Sources That Support TLS The following sources can be configured to communicate over a TLS connection: - [Active Directory]() - [ACF2]() - [Top Secret]() - [IBM i]() - [OpenLDAP]() - [Oracle Internet Directory]() - [RSA]() - [RACF]() ## Manually Uploading a Certificate to a Virtual Appliance ### Import a Certificate and Keychain to the Virtual Appliance > [!IMPORTANT] > > When adding a certificate to the virtual appliance (VA), ensure that the certificate you copy is in Privacy-Enhanced Mail (PEM) format. - Before manually adding a new certificate for the source to your virtual appliance's truststore, ensure the following: - The virtual appliance (VA) is not connected to the source. - Connection testing between the source and VA is suspended. - Scheduled aggregations are temporarily paused, if necessary. - The source server has been configured for TLS. - The `va-config-.yaml` file has been configured for your virtual appliance. - You must complete the following steps for every virtual appliance on the virtual appliance cluster connected to the source: 1. Copy the PEM-encoded certificates to the `/home/sailpoint/certificates` directory. This directory might not be empty because it's where the VA adds any certificates it gets from the source. 2. Restart the CCG using the following command: `sudo systemctl restart ccg` 3. Watch the `/home/sailpoint/log/ccg-start.log` file. If successful, the import should log messages from the form: ```text {"@timestamp":"2017-04-21 06:57:12 +0000","level":"INFO","type":"ccg","message":"Checking CCG Sources certificates"} {"@timestamp":"2017-04-21 06:57:12 +0000","level":"INFO","type":"ccg","message":"Cert files found: [\"/home/sailpoint/certificates/411818.pem\"]"} 06:57:12 +0000","level":"INFO","type":"ccg","message":"Importing cert /home/sailpoint/certificates/411818.pem"} ``` > **Note** > > If you see an error instead of the log messages above, this is an indication that your certificate is in an invalid format. Verify you're using a PEM format for your certificate and then try again. - Sometimes the export of a certificate may not work properly with the VA. Using the openSSL command to get the certificate is a good way to get the latest certificate. 1. Use the openSSL command to get the latest certificate: 1. Run the following command in openSSL: `openssl s_client -connect server.example.com:636 > output < /dev/null` 2. From the command output file, copy the certificate content between `--BEGIN CERTIFICATE--` and `--END CERTIFICATE--`. 3. Create a new file called `cert.pem` in the `/home/sailpoint/certificates` folder. 4. Save the copied certificate contents in the new `cert.pem` file. 2. Restart the CCG using the following command: `sudo systemctl restart ccg` ## Using an External Certificate Authority (CA) ### Add the Certificate to the Virtual Appliance If you're using an external certificate authority, you only have to connect to the VA from the source to import the certificate. **Prerequisites:** - The ability to use TLS 1.0 - 1.2 - You have created at least one virtual appliance cluster - CA root and intermediate certificates are in the Java CAcerts keystore - The certificate is on the source **Complete the following steps:** 1. In the source, ensure that the following are true: - The **Hostname** for the source matches the hostname in the virtual appliance's configuration. - The source is connected to the virtual appliance you configured to use TLS. > **Note** > > If you are using Active Directory with IQService enabled, the Hostname cannot be an IP Address. 2. Change the **Port** to **636**. > **Screenshot** > > [![Change the port to 636]()]() 3. If available, select the **Advanced Options** checkbox. 4. In the **Use TLS** field, select the **Enable** checkbox. > **Screenshot** > > [![Enable Use TLS]()]() 5. Test the connection. > **Note** > > The source's certificate is auto-imported to the VA. ### Replace an Expired Certificate Issued by an External Certificate Authority When your certificate has expired, replace it on the source and then reboot your VA. **Prerequisites** - Complete the process described in [Add the Certificate to the Virtual Appliance](<#add-the-certificate-to-the-virtual-appliance>). **Complete the following steps:** 1. Add the new certificate on the source with a new name. 2. Restart the CCG using the following command: `sudo systemctl restart ccg` > [!NOTE] > > The source's certificate is auto-imported to the VA. ## Using an Internal Certificate Authority ### Add the Certificate to the Virtual Appliance If you're using your own certificate authority, you will need to add the root and intermediate certificates to the VA. > [!NOTE] > > This process might also be required if your source is not automatically uploading the certificate from the VA. **Prerequisites:** - You have created at least one virtual appliance cluster - The certificate is on the source **Complete the following steps:** 1. Import the certificate and the entire key chain (Root and Intermediate Certificates) to the VA as described in [Import a Certificate and Keychain to the Virtual Appliance](<#import-a-certificate-and-keychain-to-the-virtual-appliance>). 2. Restart the CCG using the following command: `sudo systemctl restart ccg` 3. In the source, ensure that the following are true: - The **Hostname** for the source matches the hostname in the virtual appliance's configuration. - The source is connected to the virtual appliance you configured to use TLS. > **Note** > > If you are using Active Directory with IQService enabled, the Hostname cannot be an IP Address. 4. Change the **Port** to **636**. > **Screenshot** > > [![Change the port to 636]()]() 5. If available, select the **Advanced Options** checkbox. 6. In the **Use TLS** field, select the **Enable** checkbox. > **Screenshot** > > [![Enable Use TLS]()]() 7. Test the connection. > [!NOTE] > > The source's certificate is auto-imported to the VA. ### Replace an Expired Certificate Issued by an Internal Certificate Authority If you're using an internal CA, you need to add the new certificate on both the source and the VA with a new name. **Prerequisites:** - Complete the process described in [Add the Certificate to the Virtual Appliance](<#add-the-certificate-to-the-virtual-appliance_1>) **Complete the following steps:** 1. Add the new certificate on the source with a new name. 2. Import certificate and entire key chain (Root and Intermediate Certificates) to VA as described in [Import a Certificate and Keychain to the Virtual Appliance](<#import-a-certificate-and-keychain-to-the-virtual-appliance>). 3. Restart the CCG using the following command: `sudo systemctl restart ccg` 4. Test the connection. # Troubleshooting If you encounter any of the following issues or errors, SailPoint recommends that you follow the guidance provided below to resolve the error before contacting SailPoint Support. For issues or errors that are not addressed in this connector guide, refer to the following resources for troubleshooting information: - [SailPoint Identity Services Documentation]() - [SailPoint Support Knowledge Base]() - [SailPoint Developer Community]() ## This Service Is Disabled The following error appears when a service is not explicitly enabled and IQService receives a request for that handler: ```text This service is disabled. Service: To continue, enable the service on the IQService server. ``` **Resolution**: Enable the service on the IQService server. Configure TLS first, then run the following command: ```text IQService.exe -g --enable ``` Replace `` with the service name from the error message (for example, `ScriptExecutor` or `GMSAPasswordData`). Restart IQService after you update service status. Refer to [Configuring TLS and Client Authentication for IQService]() and [Option to Disable Services]() for TLS prerequisites and handler descriptions. ## SocketException (0x80004005) Port Conflict The following error message appears when you are attempting to run IQService: ```text System.Net.Sockets.SocketException (0x80004005): Only one usage of each socket address (protocol/network address/port) is normally permitted. ``` This error occurs because IQService uses port 5050 by default for debugging. If IQService is already running on port 5050, a conflict occurs when you attempt to use IQServie in debug mode for troubleshooting purpose. **Resolution**: To run IQService in debug mode, you must register it on a different TLS port to free up port 5050. Ensure the IQService is not running as a background service. 1. Open a command prompt as an administrator and go to the IQService directory. 2. Register IQService on a different port (for example, 5053) by running the following command: ```text IQService.exe -o 5053 ``` 3. Run IQService in debug mode using the -d flag: ```text IQService.exe -d ``` > [!NOTE] > > The port 5050 is fixed for debugging and cannot be changed. ## "Utils.dll not found" Error for IQService **Resolution**: Complete the following steps: 1. Copy the IQService.zip file to folder to extract it. 2. Right click the zip file and check properties. 3. Select **Unblock/Trust this zip file**. 4. Extract the zip file. [![Zip file properties dialog showing the Unblock option.]()]() 5. Verify the DLLs are trusted by checking the properties of the DLL files. ## Enable Log Files To enable debug logs, complete the following: 1. Open command prompt and navigate to IQService path. 2. Enable IQService logging: `iqservice -l 3 -f "C:\Sailpoint\IQService\iqtrace.log"` (replace path with your local IQService path). 3. Restart IQService: `iqservice -t` > [!NOTE] > > The IQService trace logging correctly rolls the logs when performing bulk operations, using the `maxFileSize` attribute. ## After Provisioning Rule Task Error The following are possible causes of the error and their respective resolutions: - The After Provisioning Rule task does not work while upgrading to a new version of IQService. **Resolution**: Ensure that the properties of the following files of IQService are unblocked: - IQService.zip file - .dlls file - .exe file - The After Provisioning rule is executed even if the provisioning operation failed. **Resolution**: The IQService always executes the After Provisioning rule, irrespective of provisioning operation result. ## The Given Path's Format Is Not Supported Error The following error message is displayed while performing IQService operations: ```text The given path's format is not supported ``` **Resolution**: Ensure that the `tracefile` registry key of IQService does not contain an extra double quote at the beginning or end of the key string. ## Configuration Error After upgrading when a load balancer if configured, the following error is displayed: ```text Please check TLS configuration for IQService: java.security.cert.CertificateException: No subject alternative DNS name matching found ``` **Resolution**: Execute the following command: `IQservice -m ` ## The System Cannot Find the File When Running a Script The IQService machine displays the following error: ```text Exception occurred in executing the script : The system cannot find the file specified ``` The following issues can cause this error to be displayed: - The absolute path of the powershell.exe is not set as an environment variable on the IQService machine. - The absolute path is provided but the file itself is missing. - A dependent file that is used in the script is missing. **Resolution**: Complete the following, moving down the list until you have resolved your issue: - Check if the powershell.exe path is set in the environment variable on the IQService host machine. - Try the operation by providing powershell.exe absolute path in the current rule. - Verify you have all of the files associated with the script in place. ## Service Startup Fails with 1075 Error Code If service startup fails with a 1075 error and an entry is visible in the event logs stating that UpdateService is not installed on your system, then you have not configured the UpdateService or explicitly opted out of using UpdateService. UpdateService configuration is mandatory. You must either configure it with IQService or explicitly opt out of using it. **Resolution**: Configure UpdateService or opt out of using UpdateService. Refer to [IQService Commands]() for more information on configuring or opting out of using UpdateService. ## No Matching Certificate Found Error The following error is displayed: ```text No matching certificate found ``` **Resolution**: Verify the subject name you provided using the `-m` command while installing or updating IQService is correct. ## An Exception Occurred While Accepting a New Client Request The following exception occurred while accepting a new client request: ```text :System.Security.Authentication.AuthenticationException: The remote certificate is invalid according to the validation procedure. ``` **Resolution**: Verify you have enabled UpdateService and the `EnableClientAuth` parameter. If they are already configured, verify they are configured correctly. ## Authentication Failed Because User Is Not Registered with IQService Authentication failed because no such user was registered with IQService. **Resolution**: Verify while configuring or updating IQService that the user is registered with IQService for client authentication and that the correct user is registered. ## Test Connections Fails with IQService Installation on the New Development Server IQService configured port and IP should be allowed between the IIQ Server/VA and IQService host. **Resolution**: IQService port (either Non-TLS or TLS) should be allowed via the firewall from the IdentityIQ Server or Virtual Appliance (VA) to the IQService to avoid the connection error with an IQService. ## Authentication Fails Because the Remote Party Has Closed the Transport Stream The following error occurred in IQTrace logs from Load Balancer: ```text ERROR : "An Exception occurred while accepting new client request from :10.XX.XXX.XXX:XXXXX. Error : An Exception occurred while accepting new client request :System.IO.IOException: Authentication failed because the remote party has closed the transport stream. at sailpoint.rpcserver.RpcHandler.AuthenticateServer(X509Certificate2 serverCertificate, SslProtocols sslprotocol, Boolean initialCall) at sailpoint.rpcserver.RpcHandler..ctor(Hashtable services, Hashtable registry, TcpClient client, String port, Boolean useTLS, String subject, String tlsVersion, String registeredClients) ``` This error usually occurs when TLS for IQService is load balanced via Load Balancer. **Resolution**: Run the following command as an Administrator from command prompt: `IQService.exe -w 10.XX.XXX.XXX` and restart the service using the command `IQService.exe -t`. ## When Testing Connection with IQService Configuration Using Non-TLS Configuration an Error Is Displayed The following error is displayed when testing the connection: ```text Client authentication failed with error - The filename or extension is too long. ``` **Resolution**: 1. Retrieve the current XML configuration: - Use GET API to get the current XML configuration: [Get Source by ID]() - This will return the XML configuration for the Active Directory connector. 2. Update the XML configuration: - Copy the retrieved XML to a text editor. - Locate the line containing: `"templateApplication": "Active Directory Template",` - Immediately after this line, add the following new line: `"encrypted": "forestAdminPassword,IQServicePassword",` 3. Perform a PUT request: - Copy the entire edited XML to the body of a new API request. - Send PUT request to update the connector: [Update Source]() 4. Verify the connection: - After updating the configuration, test the Active Directory connection again. - You should no longer see the error message: `Client authentication failed with error - The filename or extension is too long.` > **Note** > > For more information on SailPoint's REST APIs, refer to [Best Practices: REST API Authentication]() and [REST API - Update Source (Partial)]() in the SailPoint Developer Community. ## IQService Upgrade Not Happening **Resolution**: Check if the Secondary IQService is up and running. Ensure that the Secondary IQService is operational and properly configured to allow the upgrade process to proceed successfully. ## TLS Communication ### Before/After Scripts or Native Rules Fail to Execute When Using the TLS Port for IQService Configuration **Resolution**: Remove the non-TLS configuration for IQService, and restart the IQService. This ensures proper execution of scripts and rules with the TLS-configured IQService. ### Failed to Connect to IQService. Check TLS Configuration for IQService. **Resolution**: Ensure that: - The certificate is imported in the keystore which is getting referenced by IdentityIQ. - The communication has been established between IQService computer and IdentityIQ and verify that the DNS settings are correct. - The data for **IQService Port** field is added only when you select **Use TLS** for IQService checkbox. - (For Windows Operating System) TLS 1.2 is enabled under registry editor (regedit) on the server where IQService is installed. ### With TLS or Non TLS Configuration, IQService Fails with an Error Message. During aggregation, IQService fails with the following error message: ```text Attempted to read or write protected memory. ``` **Resolution**: Perform the following: 1. Rename the `app.config` file in the IQService installation directory to `IQService.exe.config` and add the following content in the file: ```xml ``` 2. Save the `IQService.exe.config` file and restart IQService. ## Client Authentication ### No Such User Registered with IQService. **Resolution**: Perform the following based on the following respective scenarios: - If the IQService User is not registered, then ensure that you have registered IQService User on IQService computer using the following command: IQService -a username - If the IQService User is registered, then ensure that the user has provided correct IQService User or Password and the Username registered in IQService and Application UI are in the same format. ### The User's Password Must Be Changed Before Signing In. The possibility could be that the password has expired for IQService User. **Resolution**: Change the password for IQService User at next logon. ### The User's Account Has Expired. **Resolution**: Change the password for IQService User. ### The Referenced Account Is Currently Locked Out and May Not Be Logged On To. **Resolution**: Ensure that IQService user is not locked. ### This User Can't Sign In Because This Account Is Currently Disabled. **Resolution**: Ensure that IQService User is not locked. ### Your Account Has Time Restrictions That Keep You from Signing In Right Now. This error message appears when IQService user has enabled logon hours and the user is trying to perform operation beyond the defined logon hours. **Resolution**: Ensure that the logon hours are correctly configured. ### While Accepting New Client Request, Authentication Failed Because the Remote Party Has Closed the Transport Stream The following error appears while accepting new client requests in a load-balanced IQService environment: ```text An Exception occurred while accepting new client requestSystem.IO.IOException: Authentication failed because the remote party has closed the transport stream. ``` **Resolution**: To resolve this issue, set the IQService log level to '2' (info). # Timeout Errors and Settings Timeout errors might occur when SailPoint is waiting for a response from the Virtual Appliance (VA). These errors are applicable to all connectors and tend to occur during the setup of sources or when sources are down. This document is designed to give specific information that can be used to resolve these errors. Each timeout attribute has a default time value that is listed in seconds or minutes. Increasing the time value may resolve the error as it will allow for longer communication time between the two systems, thus avoiding the timeout error. > [!IMPORTANT] > > Add the necessary attributes or values before performing the "replace" operation, as missing attributes will cause the operation to fail. To increase the communication time, increase the value of the appropriate timeout attribute. Then submit the change to the VA using the SailPoint REST API. > [!NOTE] > > For more information on SailPoint's REST APIs, refer to [Best Practices: REST API Authentication]() and [REST API - Update Source (Partial)]() in the SailPoint Developer Community. ### aggregateTimeout **Description:** This parameter is set for the aggregation timeout, measured in seconds. **Resolution:** Increase the `aggregateTimeout` value gradually to optimize aggregation. Start with 180, then increase to 600, 900, and finally 1800. The maximum value is 3600 seconds. For example: If your current time value is 180 seconds, update the `aggregateTimeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/aggregateTimeout", "value": 600 } ] ``` ### healthCheckTimeout **Description:** This parameter is set for the test connection and health check timeout. **Resolution:** The default value is 30 seconds. If the timeout error continues, increase the value in 15 second increments and try again. For example: If your current time value is 30 seconds, update the `healthCheckTimeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/healthCheckTimeout", "value": 45 } ] ``` ### provisioningTimeout **Description:** This parameter is set for provisioning timeout. **Resolution:** Increase the `provisioningTimeout` value gradually to optimize provisioning. Start with 180, then increase to 360, and finally 600. The maximum value is 600 seconds. For example: If your current time value is 180 seconds, update the `provisioningTimeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/provisioningTimeout", "value": 360 } ] ``` ### timeout **Description:** This parameter is set for pass-through authentication timeout. **Resolution:** The default value is 15 seconds. If the timeout error continues, increase this value in 15 second increments and try again. For example: If your current time value is 15 seconds, update the `timeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/timeout", "value": 30 } ] ``` ### apiTimeout **Description:** This parameter is set for API time tracking; customers can check it using an external tool. **Resolution:** The default value is 60 seconds. If the error continues, increase the value by 15 second increments and try again. For example: If your current time value is 60 seconds, update the `apiTimeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/apiTimeout", "value": "75" } ] ``` ### timeoutInSeconds **Description:** This parameter helps prevent the VA from waiting indefinitely for an API response, ensuring efficient handling of API requests. For example: If your current time value is 30 seconds, update the `timeoutInSeconds` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/timeoutInSeconds", "value": "15" } ] ``` # Updating IQService IQService has the built-in capability to auto update (this is the default) using the service, UpdateService. UpdateService needs to be configured alongside the IQService installation. > [!NOTE] > > - Auto update for 32-bit IQServices is not currently supported. Updates to 32-bit IQService deployments, such as with Lotus Domino sources, require manual updates. > - To upgrade, you must uninstall the previous version and then install the new version in its place. For more information, refer to [Installing and Registering IQService](). > - SailPoint recommends that you back up your current installation before starting the update process. If you have issues with the new update, the backup can help with troubleshooting. ## Manually Upgrade IQService to Latest Version To upgrade IQService to the latest version: 1. Create a backup of your existing IQService Installation folder where you have configured your IQService. 2. Stop the current IQService service using either from the Services applet or from the command line by running: `IQService.exe -k` 3. Extract the latest IQService in the installation directory. 4. If UpdateService is not already installed, then install UpdateService using the `IQService.exe -i -z "tcp://:"` command. You can check for assigned/unassigned ports by checking your registry. Use an available port in your registry (that is open and available). If you specify a port that is already in use, UpdateService adds a counter and uses an available port. 5. Start the IQService from the Services applet or from the command line by using the `IQService.exe -s` command. ## Auto Update IQService to Latest Version SailPoint requires you to install and configure UpdateService to update IQService without manual intervention. UpdateService ensures that you always have the latest released versions of IQService and itself deployed in your environment. Running the latest software version ensures that you always have the latest features and bug fixes. > [!NOTE] > > No internet connection is required for IQService auto update if your Virtual Appliance (VA) is getting other bundles updated in its environment. Updates are downloaded on your VA and then necessary updates will be applied to all the IQService hosts using the UpdateService. Following are the steps that explain how Auto UpdateService works for the new updated IQService package: 1. Once the IQService update is available, VA downloads the new IQService package (IQService-xyz). 2. VA sends the new IQService package (IQService-xyz) to the IQService configured over the IQService port. 3. IQService and Upgrade Service confirm the new version of IQService package (IQService-xyz) is different from the existing version. 4. IQService sends a new upgrade version to UpgradeService over the Upgrade Service port. 5. UpdateService performs an upgrade on IQService over the IQService port. ### Configuring IQService Auto Update | Configuration Details | Standalone Deployment | Load Balancer Deployment | | --- | --- | --- | | Deployment architecture details | UpdateService manages the update for a single IQService instance and its corresponding secondary IQService. UpdateService is deployed locally alongside IQService. | Multiple IQService instances are deployed on multiple nodes that cater to incoming requests depending on the load balancing strategy. | | UpdateService installation location | Local to the IQService location | One instance of IQService has local UpdateService.
All other IQService instances refer to the configured local instance of UpdateService. | | Installation command | `IQService.exe -z "tcp://localhost:"`
`IQService.exe -z "tcps://localhost:"` | UpdateService node:
\- `IQService.exe -z "tcp://localhost:"`
\- `IQService.exe -z "tcps://localhost:"`

Remote IQService instance:
\- `IQService.exe -z "tcp://:"`
\- `IQService.exe -z "tcps://:"` | | Installation details | UpdateService can be configured during installation or at a later point of time. It requires an IQService restart. While configuring UpdateService for the first time, if the hostname in the URL for UpdateService maps to the hostname of the local machine (localhost/IP/FQDN) then the UpdateService is installed on the machine.

You can start UpdateService using the following:
\- Starting IQService automatically starts UpdateService
\- Start UpdateService through the command line option `-t`
\- Once installed, start UpdateService through services.msc | UpdateService can be configured during installation or at a later point of time. It requires an IQService restart. If the hostname for UpdateService is remote, then IQService communicates directly with the remote UpdateService and does not install the UpdateService locally. | | Update UpdateService details | To update or reconfigure any configuration parameters associated with UpdateService, SailPoint recommends:
1\. You stop all IQService instances and UpdateService.
2\. You update the configuration using the command line options.
3\. You start the respective service instances. | To update or reconfigure any configuration parameters associated with UpdateService, SailPoint recommends:
1\. You stop all IQService instances and UpdateService.
2\. You update the configuration using the command line options.
3\. You start the respective service instances. | | Services installed in the deployment | \- Primary IQService
\- Secondary IQService
\- UpdateService | \- IQService node with UpdateService
\- Other IQService nodes without UpdateService local installation

**Note**
You must install IQService by applying the -b option that skips the installation of the secondary IQService, which is not required for a load balanced deployment. | | Security and client authentication | Prerequisite: To use `TLS/Client Authentication` for UpdateService, you must configure IQService to use TLS communication with the corresponding client authentication details.

`tcps` can be configured to use TLS for inter-service communication.

No special steps need to be performed for a standalone deployment. If IQService is configured to use TLS, UpdateService uses the IQService certificate and user for client authentication. | Prerequisite: To use `TLS/Client Authentication` for UpdateService, you must configure IQService to use TLS communication with the corresponding client authentication details.

`tcps` can be configured to use TLS for inter-service communication.

To ensure smooth TLS communication:
\- Add the certificate issuer in the Trusted Root Certification Authorities
\- The nodes should be in the same domain to use the same IQService user for client authentication | | Integrity | IQService and UpdateService validate the signature of the `dll` files of the IQService zip before proceeding with any operation. | IQService and UpdateService validate the signature of the `dll` files of the IQService zip before proceeding with any operation. | | Extra open ports | As the IQService and the respective UpdateService are present on the same local machine, no extra ports need to be exposed for communication. | For remote IQService instances to be able to communicate with UpdateService, the port that the UpdateService is listening on needs to be open for external communication with remote IQService instances. | ### UpdateService Configuration Parameters For more information on securing communication between IQService and UpdateService, refer to [Secure Communication Between IQService and UpdateService](). > [!IMPORTANT] > > Any IQService or UpdateService configuration changes require a restart of the corresponding service. | Option | Parameters | Details | | --- | --- | --- | | `-a` | Trusted client certificate trusted names or Subject Alternative Name | Provide a list of semi-colon (;) separated trusted client certificate subject names or Subject Alternative Name (SAN) of the IQService machines that will be communicating with the UpdateService.

For example:
\- `UpdateService.exe -a iqservice.test.com`
\- `UpdateService.exe -a iqservice.test.com;iqservice1.test.com` | | `-a list` | N/A | Displays the list of trusted certificate subject names configured with UpdateService. | | `-h \\| ?` | N/A | Prints the help for the UpdateService. | | `-t` | N/A | Restarts the UpdateService. | | `-l` | 0 - 3 | Trace level 0 - 3
\- 0 - Off
\- 1 - Error
\- 2 - Information
\- 3 - Debug

Changing trace level requires a restart of UpdateService. | | `-f` | fileName | Trace file name. | | `-p` | Port | Update the UpdateService port.

Updating the port requires a restart of UpdateService. | | `-u` | true/false | True to enable TLS and false to disable TLS.

Enabling or disabling TLS requires a restart of UpdateService. | | `-q` | Timeout in seconds | Connection read timeout for UpdateService. | | `-x` | N/A | Deletes the list of trusted certificate subject names.

**Note**
If configured, UpdateService will not validate the certificate-based client authentication during the TLS handshake. |