# 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](<https://documentation.sailpoint.com/connectors/disconnected_application/va/help/connecting.html#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](<https://documentation.sailpoint.com/saas/help/va/config_va.html#configuring-a-hostsyaml-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](<https://documentation.sailpoint.com/connectors/disconnected_application/va/help/connecting.html#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.