# SailPoint Disconnected Applications Connector Documentation > Disconnected Applications Connector Documentation # Documentation # Agent Installation The SailPoint Disconnected Application Agent is a Windows service that SailPoint uses to replay recorded operations. SailPoint sends a request to the agent. The agent opens a browser on the Windows host, runs the recorded steps, and returns the result. The browser stays on your network, and the managed system does not need to be reachable from the internet. The agent accepts TLS connections only. There is no plaintext port. The agent must run as a dedicated unprivileged service account. It does not run as SYSTEM. For more information, refer to [Configuring TLS and Client Authentication](). ## Prerequisites Before you install `SpDisconAppSvc.exe`, prepare a dedicated Windows Server virtual machine. The virtual machine must be able to reach the managed system, and the virtual appliance must be able to reach the virtual machine on the configured TLS port. ### 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 | Component | Recommended Hardware Requirement | Minimum Hardware Requirement | | --- | --- | --- | | CPU | 8-Core | 4-Core | | RAM | 16 GB | 8 GB | | Free Disk Space | 50 GB | 250 MB | - A dedicated service account used only by the SailPoint Disconnected Application Agent. The account must be a standard user whose only group membership is **Users**. Do not use an administrator account, a personal account, or SYSTEM. - Internet access on the host for the first runtime install, or pre-staged files for an offline install. - A TLS server certificate in **Local Computer \> Personal**, with a subject or SAN that matches the host name. The service account needs **Read** on the private key. If the certificate is self-signed, also place it in **Local Computer \> Trusted Root Certification Authorities**. - The Windows account that SailPoint uses to call the SailPoint Disconnected Application Agent. For more information, refer to [Configuring TLS and Client Authentication](). ## Service Account Permissions The service account requires the following permissions: | Permission | Location | Granted by | | --- | --- | --- | | Log on as a service | Local security policy | Administrator | | Full Control on the SailPoint Disconnected Application Agent registry key | Registry | Administrator | | Modify on the log folder | `%ProgramData%\SailPoint\` | Granted by `--service-account` | | Read on the TLS private key | Certificate store | Administrator | | Write on the account temp folder | Account temp folder | Usually already present | To print the required permissions for the installed instance, run the following command: ```text SpDisconAppSvc.exe --required-permissions ``` > [!CAUTION] > > `--service-account` records the account. It does not grant Log on as a service. Missing that right causes Windows error 1069. > [!CAUTION] > > Do not install the SailPoint Disconnected Application Agent under `C:\Users\\`. Use a system path such as `C:\SailPoint\SpDisconAppSvc`. Do not give the service account write access to the install folder. ## Downloading Agent > [!NOTE] > > You are only entitled to download components for which you have an active license with SailPoint. The availability of a component for download does not grant you a license to use a component or entitle you to use a component for which you do not have an active license. Contact your SailPoint Account Representative or Customer Success Manager (CSM) for more information. 1. Go to **Agent Settings** and select **Download Agent**. 2. Unzip the downloaded `SpDisconAppSvc-.zip` archive to a system location. For example, `C:\SailPoint\SpDisconAppSvc`. 3. Open the DLL properties and confirm that the files are trusted. Unblock the files if needed. ## Installing Agent Complete the following steps from an elevated Command Prompt. After you start the service, the SailPoint Disconnected Application Agent runs as the service account. The SailPoint Disconnected Application Agent does not include a browser. Before automation can run, install the browser runtime (Node.js, Playwright, and Chromium) on the host. You do not download these components by hand. One SailPoint Disconnected Application Agent command installs them. 1. Create the dedicated service account as a standard user whose only group membership is **Users**. 2. Install the browser runtime. This step requires internet access, or use `--offline ` for a host without internet access: ```text SpDisconAppSvc.exe --rpa-init ``` 3. Install the Windows service: ```text SpDisconAppSvc.exe -i ``` 4. Set the service account. You are prompted for the password: ```text SpDisconAppSvc.exe --service-account .\svc-rpa-agent ``` 5. Grant Log on as a service, registry Full Control, and Read on the certificate private key. 6. Register the SailPoint caller. At least one caller is required, or the service does not start: ```text SpDisconAppSvc.exe -a DOMAIN\user ``` 7. Verify the configuration, and then start the service: ```text SpDisconAppSvc.exe --show-config ``` ```text SpDisconAppSvc.exe -s ``` `--show-config` prints `Ready to start.` or lists what is still missing. Starting the service is the real test. Failures go to the trace file and the Windows event log. `--rpa-init` must complete before automation can run. Use `--rpa-update` later to switch only if the self-test passes. Use `--rollback` to return to the previous stack. ## Useful Commands | Command | Purpose | | --- | --- | | `SpDisconAppSvc.exe -i` / `-u` | Install or uninstall | | `SpDisconAppSvc.exe -s` / `-k` / `-t` | Start, stop, or restart | | `SpDisconAppSvc.exe -p ` | TLS listen port. A restart is required. | | `SpDisconAppSvc.exe -a DOMAIN\user` | Register a caller | | `SpDisconAppSvc.exe --rpa-init` | Install Node.js, Playwright, and Chromium | | `SpDisconAppSvc.exe --offline ` | Offline runtime install | | `SpDisconAppSvc.exe --show-config` | Configuration and readiness | | `SpDisconAppSvc.exe -h` | Help. Use this command if the available options differ. | ## Troubleshooting | Symptom | Resolution | | --- | --- | | Error 1069, logon failure | Grant Log on as a service, or correct the password. | | Access is denied. The trace file is empty. | Reinstall outside `C:\Users\`. | | Start times out after about 30 seconds. The trace file is empty. | The service account cannot write the registry key. Check Event Viewer. This is common after a reinstall. | | TLS error mentions the certificate | Grant Read on the private key. | | No certificate found, but it is in the store | Place the self-signed certificate in Trusted Root Certification Authorities. | | Provisioning or automation error | Run `--rpa-init` to completion. | | Name or port already in use on reinstall | Close Services and Event Viewer, and then retry. | # Installing the SailPoint Connectivity Browser Extension Install the SailPoint Connectivity Browser Extension in Google Chrome before you record operations. Chrome is the only supported browser. **To install the SailPoint Connectivity Browser Extension:** 1. Install Google Chrome on the system you use to record operations. 2. Install the SailPoint Connectivity Browser Extension in Chrome. For more information, refer to [SailPoint Connectivity Browser Extension](). # Connecting SailPoint and Disconnected Applications Use the following configuration options to set up the connection with the managed system. Configure the options in the order in which they are listed. Authentication, account aggregation, and single account aggregation must be configured before you record a provisioning operation. To connect SailPoint with Disconnected Applications, perform the following tasks: ## Adding the Source in SailPoint To connect to SailPoint, perform the following steps. Once the connection is made, you can configure it to meet your company's needs. > [!IMPORTANT] > > By default, the provisioning feature is **disabled**, and the connector only supports read-only operations. To support provisioning operations, you must manually enable the feature in the source configuration. **To configure a new source:** 1. Sign in to SailPoint. 2. Go to **Admin \> Connections \> Sources**. 3. Select **Create New**. 4. Search for the connector by entering the name in the search box, and then select **Configure**. 5. In the **Source Name** field, enter a unique and descriptive name for your source. Source names cannot exceed 128 characters. 6. In the **Description** field, provide additional details about the source to help distinguish it from similar sources. This field allows a maximum of 2,000 characters. 7. In the **Source Owner** field, begin typing the name of an owner. Matches appear after you type two or more letters. For more information, refer to [Assigning a Source Owner](). 8. Under **Connection Type**, select **Direct Connection** or **Flat File**. - **Direct Connection** - A direct connection fetches data from the **Virtual Appliance Cluster** you choose as the application connector for the source. A direct connection configuration allows for real-time updates. For more information about configuring and deploying virtual appliances, refer to the [Virtual Appliance Reference Guide](). - **Flat File** - Select the flat file if no connector is available, or if another system restricts the connection. This option allows only reading and aggregating data as a generic/delimited application. Provisioning activity is unsupported, and additional configuration pages like connection settings and aggregation settings are unavailable. 9. If you selected **Direct Connection**, in **Virtual Appliance Cluster**, select the virtual appliance cluster that will be used as the application connector for the source. 10. (Optional) Select a governance group to grant its members [source]() or [role]() sub-admin level oversight of the source and its access. For more information, refer to [Creating and Managing Governance Groups](). 11. If this source represents a primary system containing your organization's personnel records, select the **Authoritative Source** checkbox. For more information, refer to [Creating Identity Profiles](). 12. Select **Continue**. The source is created, and you are navigated to the **Source Setup \> Base Configuration** page. Continue to configure your connected source there. ## Base Configuration Provide the base configuration parameters. Information you entered in the Create New Source dialog is automatically entered into the fields in the Base Configuration page. You can edit this information if necessary. 1. Enter a unique name and description for the source. 2. In the **Source Owner** dropdown list, select the identity that owns this source. - To find a source owner, begin entering their name. 3. In the **Virtual Appliance Cluster** dropdown list, select the virtual appliance to use when communicating with your organization's systems. For more information, refer to [SailPoint Virtual Appliances](). 4. (Optional) If enabled for your organization, select the **Use a Credential Provider** checkbox to manage the source's authentication using a credential provider. > **Note** > > To add a credential provider, go to **Admin \> Connections \> Credential Providers**. For more information about credential providers, refer to [Credential Providers](). 5. Configure the authentication to allow SailPoint to connect to the source. Refer to [Connection Settings](<#connection-settings>) for more information. 6. (Optional) In the **Governance Group for Source Management** dropdown list, select a governance group to associate with this source. For more information about governance groups, refer to [Associating Governance Groups with a Source](). 7. (Optional) Choose whether to enable or disable provisioning for the source. Provisioning is disabled by default. - **Enable Provisioning** - Set the toggle to **Enabled** to allow the source to create, update, and deactivate accounts in the connected source system. - **Disable Provisioning** - Set the toggle to **Disabled** to disable provisioning for the source. Disabling provisioning will prevent the creation, updating, or deactivating of accounts on this source. 8. Select **Save**. ## Connection Settings Configure a connection to the managed system and specify how the system represents the status of an account. > [!NOTE] > > **Screenshot** > > [![Connection Settings]()]() 1. Enter the **Base URL** of the managed system. For example, `https://example.com`. > **Note** > > SailPoint recommends using HTTPS for a secured connection. 2. Enter the **Username** of the service account used to sign in to the managed system. 3. Enter the **Password** of the service account. 4. In **Browser Allowed Hosts**, enter any redirect hostnames visited during sign-in or password entry. To add a host, enter a single hostname and press **Enter**. - Host name example: `sso.example.com` - IP address example: `172.16.25.5` > **Note** > > The source automatically permits the Base URL hostname. 5. Select **Save**. ### Account Status Mapping SailPoint uses the status attribute of the managed system to report an account as enabled or disabled after an enable or disable operation runs. > [!IMPORTANT] > > The status attribute must be part of the account schema and must be aggregated. > [!NOTE] > > **Screenshot** > > [![Account Status Mapping]()]() 1. In **Account Enable Status Attribute**, enter the attribute and value that indicate an enabled account. For example, `status=Active`. 2. In **Account Disable Status Attribute**, enter the attribute and value that indicate a disabled account. For example, `status=Inactive`. 3. Select **Save**. ## Agent Settings The SailPoint Disconnected Application Agent replays the recorded operations of the source. Install and register the SailPoint Disconnected Application Agent before you configure the connection. For more information, refer to [Agent Installation](). ### Agent Connection Settings > [!NOTE] > > **Screenshot** > > [![Agent Connection Settings]()]() 1. In **Agent Host**, enter the host name or IP address of the system where the SailPoint Disconnected Application Agent is installed. For example, `172.16.25.5` or `node.domain.example`. 2. In **Agent Port**, enter the port number used to connect to the SailPoint Disconnected Application Agent. The default port is `5050`. 3. In **Client Authentication Username**, enter the user name used for client authentication. 4. In **Client Authentication Password**, enter the password used for client authentication. > **Note** > > SailPoint encrypts this data. 5. Select **Save**. ## Authentication Settings Record the sign-in to the managed system with the SailPoint Connectivity Browser Extension. SailPoint replays the recorded sign-in with the service account credentials entered in [Connection Settings](<#connection-settings>) before each aggregation and provisioning operation. > [!IMPORTANT] > > If you use a vanity URL, add the vanity URL and the URL of the managed system to the SailPoint Connectivity Browser Extension. 1. In **Authentication Settings**, select **Launch** for **SailPoint Connectivity Browser Extension**. 2. In the managed system, sign in as the service account, and then stop the recording. 3. Review the recorded steps, and then confirm the recording. 4. Select **Save**. > [!NOTE] > > The source supports form-based sign-in, including a sign-in that collects the user name and the password on separate screens. ## Account Aggregation Settings Configure how the source collects account data from the managed system. Account aggregation and single account aggregation are configured separately, and recording one of them again does not change the other. > [!IMPORTANT] > > If you use a vanity URL, add the vanity URL and the URL of the managed system to the SailPoint Connectivity Browser Extension. ### Account Aggregation Account aggregation collects the values displayed in the list of users. It does not open the details page of each account. Select one of the following configuration methods: - **SailPoint Connectivity Browser Extension** - Record the account aggregation workflow in the managed system. - **SFTP** - Import the account data from a CSV file on a remote server. > [!NOTE] > > SailPoint strongly recommends SFTP for account aggregation when the account volume is large, or when required attributes are not shown as columns on the grid. **To record account aggregation with the SailPoint Connectivity Browser Extension:** 1. In **Account Aggregation**, select **Launch** for **SailPoint Connectivity Browser Extension**. 2. In the managed system, go to the list of users, and then extract the account data. 3. Map the extracted data to the account schema attributes, and then confirm the recording. 4. Select **Save**. **To import account data with SFTP:** 1. In **Account Aggregation**, select **Select** for **SFTP**. 2. Enter the connection details of the remote server and the path of the CSV file that contains the account data. 3. Select **Save**. ### Single Account Aggregation Single account aggregation collects the data of one account. SailPoint uses this recording to refresh an account and to confirm the result of a provisioning operation. **To record single account aggregation with the SailPoint Connectivity Browser Extension:** 1. In **Single Account Aggregation**, select **Launch** for **SailPoint Connectivity Browser Extension**. 2. In the managed system, search for one account, and then open the details page of that account. 3. Extract the account data, and then confirm the recording. 4. Select **Save**. > [!NOTE] > > The search recorded for single account aggregation must return one account. ### Correlating Accounts Account correlation for the SailPoint Disconnected Application Connector is completed manually. After account aggregation, match each uncorrelated account to an identity. For more information, refer to [Manually Resolving Uncorrelated Accounts](). ## Entitlement Aggregation Settings Configure how the source collects entitlement data from the managed system. An entitlement must be aggregated before it can be requested, certified, or reported on. Select one of the following configuration methods: - **SailPoint Connectivity Browser Extension** - Record the entitlement aggregation workflow in the managed system. - **SFTP** - Import the entitlement data from a CSV file on a remote server. > [!IMPORTANT] > > If you use a vanity URL, add the vanity URL and the URL of the managed system to the SailPoint Connectivity Browser Extension. > [!NOTE] > > SailPoint strongly recommends SFTP for entitlement aggregation when the entitlement volume is large, or when required attributes are not shown as columns on the grid. **To record entitlement aggregation with the SailPoint Connectivity Browser Extension:** 1. In **Entitlement Aggregation**, select **Launch** for **SailPoint Connectivity Browser Extension**. 2. In the managed system, go to the list of groups or roles, and then extract the entitlement data. 3. Map the extracted data to the entitlement schema attributes, and then confirm the recording. 4. Select **Save**. **To import entitlement data with SFTP:** 1. In **Entitlement Aggregation**, select **Select** for **SFTP**. 2. Enter the connection details of the remote server and the path of the CSV file that contains the entitlement data. 3. Select **Save**. ## Create Account Settings Record the creation of an account with the SailPoint Connectivity Browser Extension. SailPoint replays the recorded steps when a create account request runs. If an operation has no recording, the source does not perform that operation. > [!IMPORTANT] > > If you use a vanity URL, add the vanity URL and the URL of the managed system to the SailPoint Connectivity Browser Extension. > [!NOTE] > > Configure [Authentication Settings](<#authentication-settings>) and [Account Aggregation Settings](<#account-aggregation-settings>) before you record this operation. 1. In **Create Account**, select **Launch** for **SailPoint Connectivity Browser Extension**. 2. In the managed system, create an account, and then stop the recording. 3. Map the recorded fields to the account schema attributes, and then confirm the recording. 4. Select **Save**. ## Update Account Settings Record each update operation you want to automate with the SailPoint Connectivity Browser Extension. SailPoint replays the recorded steps when the corresponding request runs. If an operation has no recording, the source does not perform that operation. > [!IMPORTANT] > > If you use a vanity URL, add the vanity URL and the URL of the managed system to the SailPoint Connectivity Browser Extension. > [!NOTE] > > Configure [Authentication Settings](<#authentication-settings>) and [Account Aggregation Settings](<#account-aggregation-settings>) before you record these operations. ### Update Account Attributes 1. In **Update Account Attributes**, select **Launch** for **SailPoint Connectivity Browser Extension**. 2. In the managed system, update the attributes of an account, and then stop the recording. 3. Map the recorded fields to the account schema attributes, and then confirm the recording. 4. Select **Save**. ### Enable Account 1. In **Enable Account**, select **Launch** for **SailPoint Connectivity Browser Extension**. 2. In the managed system, enable an account, and then stop the recording. 3. Review the recorded steps, and then confirm the recording. 4. Select **Save**. > [!NOTE] > > The status that the managed system sets during this operation must match the **Account Enable Status Attribute** value entered in [Connection Settings](<#connection-settings>). ### Disable Account 1. In **Disable Account**, select **Launch** for **SailPoint Connectivity Browser Extension**. 2. In the managed system, disable an account, and then stop the recording. 3. Review the recorded steps, and then confirm the recording. 4. Select **Save**. > [!NOTE] > > The status that the managed system sets during this operation must match the **Account Disable Status Attribute** value entered in [Connection Settings](<#connection-settings>). ### Add Entitlements Record assigning an entitlement to an account. For example, assign a group or a role. 1. In **Add Entitlements**, select **Launch** for **SailPoint Connectivity Browser Extension**. 2. In the managed system, assign a group or a role to an account, and then stop the recording. 3. Review the recorded steps, and then confirm the recording. 4. Select **Save**. ### Remove Entitlements Record removing an entitlement from an account. For example, unassign a group or a role. 1. In **Remove Entitlements**, select **Launch** for **SailPoint Connectivity Browser Extension**. 2. In the managed system, unassign a group or a role from an account, and then stop the recording. 3. Review the recorded steps, and then confirm the recording. 4. Select **Save**. ## Review and Test Perform a test to confirm the connection to SailPoint. 1. Go to **Review and Test**. 2. Confirm that the entries in each field are correct. If you note any mistakes, return to the section and make corrections. 3. Select **Test Connection**. ## SailPoint Application Onboarding SailPoint application onboarding enables you to easily onboard new applications and create sources following the successful onboarding of a discovery source. To use this feature, continue to **Discovered Applications** in the SailPoint user interface. For more information, refer to [Application Onboarding]() in the SailPoint SaaS documentation. # Integrating SailPoint with Disconnected Applications The SailPoint Disconnected Application Connector allows SailPoint to aggregate accounts and entitlements from, and provision accounts to, web applications that have no API and no supported SailPoint connector. This guide provides the requirements and field definitions needed to configure the SailPoint Disconnected Application Connector in SailPoint. > [!NOTE] > > To view the latest features, enhancements, and fixes for all SaaS connectors, refer to the [SaaS Release Notes]() page. ## Supported Features The SailPoint Disconnected Application Connector supports the following features: ### Account Management - Account aggregation - Single account aggregation - Create account - Update account attributes - Enable account - Disable account - Add entitlement - Remove entitlement ### Entitlement Management - Entitlement aggregation ## Prerequisites Before you configure the SailPoint Disconnected Application Connector, ensure that the following prerequisites are met: - Configure at least one virtual appliance cluster and successfully test the connection. For instructions, refer to the [Virtual Appliance Reference Guide](). - Install the SailPoint Disconnected Application Agent (`SpDisconAppSvc.exe`) on a Windows system that the virtual appliance can reach. For more information, refer to [Agent Installation](). - Install Google Chrome and the SailPoint Connectivity Browser Extension on the system you use to record operations. For more information, refer to [Installing the SailPoint Connectivity Browser Extension](). - Create a service account on the managed system. - Ensure that the managed system is reachable from the browser session you use to record operations, and from the virtual appliance and the system where the SailPoint Disconnected Application Agent is installed. - Ensure that the managed system uses a form-based sign-in with credentials that are local to the system. > [!IMPORTANT] > > The source does not support multi-factor authentication (MFA), CAPTCHA, single sign-on, or federated authentication. # Provisioning The create account provisioning policy supplies the values the source enters into the managed system when replaying a create account recording. For more information about recording create account, refer to [Create Account Settings](). - Each field you type during a recording acts as a placeholder. The source populates this field at run time using values from the provisioning plan. - Fields marked write-only during mapping appear in the create account policy but are excluded from the account schema. For more information, refer to [Schema Reference](). - Ensure all fields required by the managed system have a value in the policy; otherwise, the create operation fails when the system rejects the form. Go to the source's **Create Account Settings** to review the generated policy and add transforms or static values. # Schema Reference The account schema is built dynamically based on the attributes you select during mapping. There is no fixed schema. - The account aggregation recording that selects **Account ID** and **Account Name** sets them as the default required attributes. - Full aggregations populate the attributes you select during an account aggregation recording. - Single account aggregations populate attributes only when reading an individual account. If no grid column carries a matching attribute, the field remains empty after a full account aggregation runs. - The enable and disable status attributes configured in [Connection Settings]() must exist in the schema and be aggregated. - Map the entitlement type on the entitlement schema manually. The entitlement type is **group**. > [!WARNING] > > Do not rename a schema attribute after recording an operation. Recorded workflows reference attributes by name. Renaming an attribute breaks every associated recording, requiring you to record those operations again. The system does not automatically detect or migrate these changes. # Configuring TLS and Client Authentication TLS communication between the virtual appliance and the SailPoint Disconnected Application Agent is required. The agent does not accept requests on a non-TLS port. Client authentication is also required. The agent confirms that the user is registered, and then authenticates the credentials with Windows, before it runs a request from SailPoint. > [!NOTE] > > Client authentication is required for operations that use the SailPoint Disconnected Application Agent. ## Prerequisites ### TLS Communication - The agent host X.509 certificate, with Extended Key Usage (EKU) set to Server Authentication, is in the Personal certificate store of the local computer. The subject matches the fully qualified domain name of the agent host. For example, `spdisconappsvc.test.com`. - The matching private key is in the local computer certificate store and is associated with the certificate. - If the certificate is not available, create a certificate signing request on the agent host and submit it to a trusted internal or third-party certificate authority. - The certificate authority is a trusted root certificate authority on the agent host. ### Client Authentication - If the agent host is joined to a domain, use a domain user to authenticate the connection between SailPoint and the agent. - If the agent host is not joined to a domain, use a local Windows user on the agent host. > [!NOTE] > > No additional user permissions are required for client authentication. ## Configuring the Agent Host Certificate Confirm the following on the SailPoint Disconnected Application Agent host: - The X.509 certificate is in **Local Computer \> Personal**. - The certificate has a private key. In the certificate store, a certificate with a private key uses a different icon from a certificate without one. - Enhanced Key Usage includes Server Authentication (`1.3.6.1.5.5.7.3.1`). - The agent host fully qualified domain name is the common name (CN) in **Subject**, and a DNS entry in **Subject Alternative Name**. - The agent host trusts the certificate. Trust is established when the host trusts the root certificate authority that issued the certificate. ## Configuring the Virtual Appliance Certificate The virtual appliance must trust the SailPoint Disconnected Application Agent X.509 certificate. Trust is established when the virtual appliance trusts the root certificate authority that issued the certificate. > [!NOTE] > > Export the full certificate chain and convert it to a single PEM file. **To export the certificate chain and add it to the virtual appliance:** 1. In the Microsoft Management Console (MMC), export the certificate chain as a `.p7b` file in DER/Binary format. 2. Convert the `.p7b` file to a `.pem` file: ```text openssl pkcs7 -print_certs -in certchain.p7b -inform DER -out certificate.pem -outform PEM ``` 3. Copy `certificate.pem` to `/home/sailpoint/certificates` on the virtual appliance. 4. Restart the CCG service. The CCG service loads the certificates from that directory. ## Configuring Client Authentication **To register the user that SailPoint uses to call the agent:** 1. On the agent host, register the user. A domain user uses the `msDS-PrincipalName` format `domain\user`. A local user uses the local user name only. ```text SpDisconAppSvc.exe -a "Corp\John.Doe" ``` 2. In [Agent Settings](), enter that user in **Client Authentication Username** and the password in **Client Authentication Password**. Use the same format you used when you registered the user. ## Troubleshooting ### Failed to Connect. Check the TLS Configuration Confirm that the certificate file is in `/home/sailpoint/certificates` on the virtual appliance. ### No Subject Alternative Names Present Confirm that the certificate file is in `/home/sailpoint/certificates` on the virtual appliance. Confirm that the virtual appliance can reach the agent host. Confirm DNS. You can add a mapping for the agent host in `hosts.yaml` in `/home/sailpoint`. For more information, refer to [Configuring a Hosts.yaml File](). ### Connection Reset The host name of the agent server might not match the fully qualified domain name on the TLS certificate. Confirm that the host name matches the certificate fully qualified domain name, or that the Subject Alternative Name matches that name. If they do not match, set the certificate fully qualified domain name and restart the agent: ```text SpDisconAppSvc.exe -m hostname.example.com ``` ```text SpDisconAppSvc.exe -t ``` ### Connection Refused Confirm that the SailPoint Disconnected Application Agent service is running. ### No Such User Registered Register the user on the agent host with `SpDisconAppSvc.exe -a username`, and then confirm **Client Authentication Username** and **Client Authentication Password** in [Agent Settings](). ### The User's Password Must Be Changed Before Signing in The account is set to require a password change. Update the agent user's password. ### The User's Account Has Expired The agent user's password might have expired. Change the password. ### The Referenced Account Is Currently Locked Out Confirm that the agent user is not locked out. ### This Account Is Currently Disabled Confirm that the agent user is enabled. ### Your Account Has Time Restrictions The agent user might have logon hours set. Adjust the logon hours. # Enable Connector Logging This topic provides the steps needed to enable logging on SailPoint using REST APIs. > [!NOTE] > > This topic only applies to VA-based integrations. > [!NOTE] > > The examples provided might not match your configuration. Use the logging levels and logging classes reference at the bottom of the topic to configure your API responses to match your connector. This process is broken up into four steps: 1. Identify the Virtual Appliance (VA) cluster on which you want to enable logging. 2. Get the logging configuration for the existing VA cluster. 3. Update the VA cluster to enable logging levels. 4. Observe logging changes to the logging levels. ### Identify the Virtual Appliance Cluster Select the VA on which you need to enable logging using REST API. If you already know the VA application's `id`, proceed to [Get the Logging Configuration](<#get-the-logging-configuration>). 1. Make the following call to the REST API to return a list of available VA clusters: GET /v3/managed-clusters The REST API returns a response that looks similar to the following: ```json [ { "id": "2c9180866166b5b0016167c32ef31a66", "name": "Development Cluster", "description": "Development Cluster", "clientType": "CCG", "ccgVersion": "373_535_70.2.0", "pinnedConfig": true, "logConfiguration": null }, { "id": "2c9180846a93ce60016ab29f039944de", "name": "Cloud Cluster", "description": "Cloud Cluster", "clientType": "CCG", "ccgVersion": "373_535_70.2.0", "pinnedConfig": true, "logConfiguration": { "clientId": null, "durationMinutes": 60, "expiration": "2020-12-15T19:13:36.079Z", "rootLevel": "DEBUG", "logLevels": { "sailpoint.connector.ADLDAPConnector": "DEBUG" } } } ] ``` > **Note** > > The previous example code shows two VA clusters. One VA cluster has a log configuration and the other does not (refer to the `logConfiguration` value in each returned VA cluster). This is because one of the clusters already has logging enabled. This is just an example configuration, and your environment may not have logging enabled on a cluster. 2. Identify the VA cluster that you want to enable logging on by its name or description and record its `id` attribute. ### Get the Logging Configuration Get your selected VA's cluster logging configuration and identify the values you need to update. 1. Make the following call to the REST API to return the VA cluster's logging configuration. Replace `{id}` with the VA cluster's `id` attribute value recorded earlier. GET /v3/managed-clusters/{id}/log-config - If the VA doesn't have a logging configuration currently set, it returns `204 No Content` as a response. - If the VA has an existing logging configuration, it returns something similar to the following: ```json { "clientId": null, "durationMinutes": 60, "expiration": "2020-12-15T19:13:36.079Z", "rootLevel": "DEBUG", "logLevels": { "sailpoint.connector.ADLDAPConnector": "DEBUG" } } ``` You'll need to configure the following information in the response: - `durationMinutes` is the number of minutes logging should remain enabled. - `rootLevel` is the default level for all logs. For more information, refer to [Logging Levels](<#logging-levels>). - `logLevels` is a map object with logging classes as keys and logging levels as values. - For keys, refer to [Logging Classes](<#logging-classes>) for commonly used logging classes. - For a list of available values, refer to [Logging Levels](<#logging-levels>). ### Update Logging Configuration Update the VA cluster configuration returned by the REST API to update the logging settings as needed. 1. Make the following call to the REST API to update the VA cluster's logging configuration. Replace `{id}` with the VA cluster's `id` attribute value recorded earlier. PUT /v3/managed-clusters/{id}/log-config 2. Submit your configuration changes to the REST API in a JSON body. - If the VA cluster did not already have a logging configuration and you received a `204 No Content` response, you can create a new one. - If the VA returned a configuration, you can edit it to include the changes. The JSON body should be as follows: ```json { "durationMinutes": 60, "rootLevel": "DEBUG", "logLevels": { "sailpoint.connector.ADLDAPConnector": "DEBUG" } } ``` Consider the following as you edit the JSON: - `durationMinutes` is the number of minutes logging should remain enabled. - `rootLevel` is the default level for all logs. For more information, refer to [Logging Levels](<#logging-levels>). - `logLevels` is a map object with logging classes as keys and logging levels as values. - For keys, refer to [Logging Classes](<#logging-classes>) for commonly used logging classes. - For a list of available values, refer to [Logging Levels](<#logging-levels>). If the update was successful, the REST API should return a response similar to the following: ```json { "clientId": null, "durationMinutes": 60, "expiration": "2020-12-15T19:13:36.079Z", "rootLevel": "DEBUG", "logLevels": { "sailpoint.connector.ADLDAPConnector": "DEBUG" } } ``` ### Observe Logging Changes Approximately five minutes after you update the configuration, the VA cluster starts generating log files you can review. You can view the log files in **ccg.log**. ### References The tables in this reference section list information that can be helpful when creating the JSON body you'll use to configure the VA cluster's configuration file. #### Logging Levels | Logging Level | Description | | --- | --- | | ERROR | Designates error events that might still allow the connector to continue. | | WARN | Designates potentially harmful situations. | | INFO | Designates information messages that highlight process at a coarse-grain level. | | DEBUG | Very verbose. Fine grain logging levels used for development and debugging. | | TRACE | Most verbose. Finer grain logging levels than debugging. | #### Logging Classes | Connector | Logging Class | | --- | --- | | Active Directory | sailpoint.connector.ADLDAPConnector sailpoint.connector.LDAPConnector | | AIX | openconnector.connector.unix.AIXConnector openconnector.connector.unix.UnixConnector | | Amazon Web Services | logger.aws.name=openconnector.connector.aws logger.aws.level=trace logger.aws.additivity = false logger.aws.appenderRef.rolling.ref = STDOUT | | Atlassian Suite Cloud | sailpoint.connector.OpenConnectorAdapter openconnector.connector.atlassian.AtlassianConnector | | Atlassian Data Center | sailpoint.connector.OpenConnectorAdapter openconnector.connector.atlassian.AtlassianDataCenterConnector | | Microsoft Entra ID | sailpoint.connector.AzureADConnector | | Box | openconnector.connector.BoxNetConnector sailpoint.connector.OpenConnectorAdapter | | Cerner | openconnector.connector.CernerConnector sailpoint.connector.OpenConnectorAdapter | | Delimited File | logger.DelimitedFileConnector.name = sailpoint.connector.DelimitedFileConnector logger.DelimitedFileConnector.level = debug logger.DelimitedFileConnector.additivity = false logger.DelimitedFileConnector.appenderRef.rolling.ref = STDOUT | | Dropbox | openconnector.connector.DropBoxConnector sailpoint.connector.OpenConnectorAdapter | | Epic | openconnector.connector.EPICConnector sailpoint.connector.OpenConnectorAdapter | | GE Centricity | openconnector.connector.GECentricity sailpoint.connector.OpenConnectorAdapter | | Google Apps / G Suite | openconnector.connector.GoogleAppsDirect sailpoint.connector.OpenConnectorAdapter | | IBM i | openconnector.connector.IBMiConnector | | Lotus Domino | sailpoint.connector.LotusDomino | | JDBC | sailpoint.connector.JDBCConnector | | Sun One LDAP | sailpoint.connector.LDAPConnector | | Linux | openconnector.connector.unix.LinuxConnector sailpoint.connector.OpenConnectorAdapter sailpoint.connector.UnixConnector | | Microsoft Office365 | sailpoint.connector.Office365Connector | | Microsoft SQL Server | sailpoint.connector.mssql.serviceimpl.MSSQLServerConnectorV2 | | Okta | logger.openconnector.name = openconnector.connector.okta.OktaConnector logger.openconnector.level = debug logger.openconnector.additivity = false logger.openconnector.appenderRef.rolling.ref = STDOUT | | Oracle Database | sailpoint.connector.OracleDBConnector sailpoint.connector.JDBCConnector | | Oracle E-Business | sailpoint.connector.OracleEBSConnector sailpoint.connector.JDBCConnector | | Oracle Fusion HCM | openconnector.connector.oraclefusionhcm.OracleFusionHCMConnector sailpoint.connector.OpenConnectorAdapter | | Oracle HCM Cloud | sailpoint.connector.oraclehcmcloud.OracleHCMCloudConnector | | Oracle HRMS | sailpoint.connector.OracleAppsHRMSConnector sailpoint.connector.JDBCConnector | | Oracle Netsuite | openconnector.connector.netsuite.NetsuiteConnector | | PeopleSoft ERP | openconnector.connector.PeopleSoftConnector sailpoint.connector.OpenConnectorAdapter | | PeopleSoft HRMS | sailpoint.connector.PeopleSoftHRMSConnector | | RemedyForce | sailpoint.connector.ForceConnector | | RSA Authentication Manager | openconnector.connector.RSAConnector openconnector.connector.rsa.RSAHTTPClient sailpoint.connector.OpenConnectorAdapter | | Salesforce | sailpoint.connector.ForceConnector | | SAP Concur | openconnector.connector.sapconcur.SAPConcurConnector | | SAP - Direct | sailpoint.connector.SAPConnector sailpoint.connector.SAPInternalConnector | | SAP GRC | logger.SAPGRCConnector.name = sailpoint.connector.sapgrc logger.SAPGRCConnector.level = debug logger.SAPGRCConnector.additivity = false logger.SAPGRCConnector.appenderRef.rolling.ref = STDOUT | | SAP HR/HCM | sailpoint.connector.SAPHRInternalConnector | | SCIM 1.1 | openconnector.connector.SCIMConnector sailpoint.connector.OpenConnectorAdapter | | SCIM 2.0 | openconnector.connector.scim2.SCIM2Connector sailpoint.connector.OpenConnectorAdapter | | ServiceNow | openconnector.connector.servicenow.ServiceNowConnector openconnector.connector.servicenow.ServiceNowRestClient sailpoint.connector.OpenConnectorAdapter | | ServiceNow Service Desk Integration | openconnector.connector.servicedesk.ServiceNowServiceDeskConnector sailpoint.connector.OpenConnectorAdapter | | Siebel | openconnector.connector.SiebelConnector sailpoint.connector.OpenConnectorAdapter | | Snowflake | openconnector.connector.snowflake.SnowflakeConnector sailpoint.connector.OpenConnectorAdapter | | Solaris | openconnector.connector.unix.SolarisConnector openconnector.connector.unix.UnixConnector sailpoint.connector.OpenConnectorAdapter | | SuccessFactors | sailpoint.connector.SuccessFactorsConnector | | Sybase | sailpoint.connector.SybaseDirectConnector sailpoint.connector.JDBCConnector | | Webex | openconnector.connector.Webex sailpoint.connector.OpenConnectorAdapter | | Workday | openconnector.connector.WorkDay sailpoint.connector.OpenConnectorAdapter | | Workday Accounts | openconnector.connector.workdayaccounts openconnector.connector.workdayaccounts.WorkdayAccountsConnector sailpoint.connector.OpenConnectorAdapter | | Web Services | sailpoint.connector.WebServices | | XML | openconnector.connector.XMLConnector sailpoint.connector.OpenConnectorAdapter | | Yammer | openconnector.connector.YammerConnector sailpoint.connector.OpenConnectorAdapter | | Zoom | openconnector.connector.zoom.ZoomConnector sailpoint.connector.OpenConnectorAdapter | # 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]() ## Launch does nothing, or reports that no extension was found The SailPoint Connectivity Browser Extension is not installed or is an unsupported version. **Resolution**: Install or update the SailPoint Connectivity Browser Extension. For more information, refer to [Installing the SailPoint Connectivity Browser Extension](). ## Recorder panel does not appear on the managed system The origin of the managed system is not permitted, or the base URL does not match the managed system. **Resolution**: Confirm the base URL, and confirm the hosts entered in **Browser Allowed Hosts**. ## Recording is not saved after confirming The recording session expired, or the SailPoint tab was closed during recording. **Resolution**: Leave the SailPoint tab open and record again. ## Authentication fails Wrong credentials, a changed sign-in page, or a login that requires MFA or SSO. **Resolution**: Verify the credentials, record the login sequence again, and confirm the account is exempt from MFA and SSO. ## Aggregation returns no accounts The recorded list page no longer loads, or the service account cannot see the list. **Resolution**: Confirm the service account can open the list page, then record the aggregation again. ## Aggregation returns some columns empty Those attributes were selected from a single account recording and no list column carries them. **Resolution**: Select the attributes from an account aggregation recording, or accept that they populate only on a single account read. ## Aggregation returns fewer rows than the managed system shows The list page paginates differently than when it was recorded. **Resolution**: Record the aggregation again. ## Single account aggregation reports an ambiguous match The recorded search returns more than one row. **Resolution**: Record single account aggregation again with a search that resolves to exactly one account. ## Single account aggregation reports account not found The account does not exist, or the search field no longer matches on the account ID. **Resolution**: Confirm the account, then record single account aggregation again. ## Provisioning reports success but nothing changed The recording completed a form the managed system rejected silently. **Resolution**: Record the operation again and confirm the confirmation screen of the managed system is included. ## Provisioning reports a failure after the change was applied A step after form submission did not complete. **Resolution**: Review the run log. The change was applied. Record the operation again to include the confirmation step. ## Account still shows as enabled after a disable The Account Disable Status Attribute does not match the value the managed system sets. **Resolution**: Correct the value in [Connection Settings]() and aggregate again. ## Every operation fails after a managed system upgrade Recorded selectors no longer match. **Resolution**: Record the affected operations again. ## Provisioning is unavailable on the source Enable Provisioning is off. **Resolution**: Turn on Enable Provisioning in [Base Configuration](). # 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" } ] ```