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 Identity Security Cloud deployment. If you have IdentityIQ and Identity Security Cloud 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

  • 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.

  • 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:

    IQService -z "tcps://<host-name>:<port-number>

  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:

      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:

      UpdateService -a <trusted-certificate-subject>

      For example, UpdateService.exe -a iqservice1.test.com

    3. You can add multiple entries by separating the certificate subject names with a semi-colon (;).