Where to update Connection Strings when AppServer certificate changes (4373076)

Where to update Connection Strings when AppServer certificate changes

Identity Manager and Identity Manager On Demand use certificates for secure communication.  The certificate is hosted on the Application Server and will be changed on a regular cadence.  For Identity Manager On Premise installations, this cadence is set by the Administrators.  For Identity Manager On Demand and Identity Manager On Demand Starling Edition this is done on a yearly basis as part of our standard maintenance by the One Identity Operations team.

When configuring connections to the Application Server, there is an option for Administrators to enter the certificate for enhanced security (pinning a certificate).  If so, the connection strings for the connection need to be updated each time the certificate is changed.  If the Administrator chooses not to enter a certificate and leave the certificate field blank, the connections strings do not need to be updated when the certificate is changed.

Should the Administrator choose to enter a certificate in their Application Server Connection settings (pin a certificate), please update the connection strings in the below locations when the certificate is updated.

Note: To avoid updating certificates yearly for Identity Manager On Demand and Identity Manager On Demand Starling Edition administrators may leave the certificate field blank when updating the Application Server connection in the various locations below.

Should an Administrator choose to pin a certificate, the following error message will appear if the Application Server Certificate is changed:
 
The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel.
 
The remote certificate is invalid according to the validation procedure.

Note: This document will be updated as required. 

There are several possible locations where the Connection String may need to be updated:

- Front End Applications, e.g. Manager or Designer
- Designer Connection Data
- Synchronization Projects
- Job Service (On-Premise)
- Web-Designer Web Portal (On-Premise)
- API-Server Web Portal (On-Premise)

If a certificate is selected when creating a new connection to the Application server, e.g.:
 

Then the certificate public key will be pinned:
 

This can be viewed by selecting Options | Advanced options:
 

However, if no certificate is selected, then there will be no entry for PinnedPublicKey.

Front End Applications

To update the Connection String used by Front End applications:

 

• Open any front-end application – For example, Manager.
  • Click the drop-down under Select a database connection.
  • The existing connection will be highlighted blue.
  • Use the Delete key on the keyboard.
  • When prompted, click Yes to confirm the deletion. 
  • Click Add new connection.
  • Select Application server and click the Next button.
  • Enter the Application Server URL when prompted.
  • A certificate can be selected but it is not necessary, the field can be left blank.
  • Click the Finish button.

Designer Connection Data

To update the Connection String set in Designer under “Connection Data”:

• Open Designer
  • Click on Base Data in the left navigation bar.
  • Expand Security Settings
  • Click on Connection data
  • Click on the applicable entry in the list (if it exists).
  • Click the triple dots […] next to the Connection parameter field.
  • Enter the Application Server URL when prompted.
  • A certificate can be selected but it is not necessary, the field can be left blank.
  • Click the OK button.
  • Click Commit to database to save the change.
• Follow the above steps for each Connection data entry if multiple are present using the old certificate. 

Synchronization Projects

To update the Connection String used by Synchronization Projects:

• Open the Synchronization Editor
  • Load an applicable Synchronization Project
  • In the Configuration section in the left navigation pane click on One Identity Manager Connection
  • If prompted, enter the Synchronization user password.
  • Click on Edit connection...
  • Follow the Wizard and when prompted to select a Certificate, one can be set but it is not necessary, the field can be left blank.
  • Finish the Wizard and click OK when prompted.
  • Click Commit to database to save the change.
• Follow the above steps for each synchronization project. 

Job Service (On-Premise)

To update the Connection String used by any On-Premise Job Servers:

• Browse to the Installation directory of Identity Manager and launch JobServiceConfigurator.exe
  • Under Process Collection click on AppServerJobProvider
  • Click on Connection String <hidden value>
  • Click Edit
  • Enter the Application Server URL
  • A certificate can be selected but it is not necessary, the field can be left blank.
  • Click OK
  • From the top menu bar, select File | Save.
  • Restart the One Identity Manager service.
• Follow the above steps for each On-Premise job server. 

Web-Designer Web Portal (On-Premise)

To update the Connection String used by any On-Premise Web-Designer Web Portal:

Option 1: Web Designer Configuration Editor

• Browse to the Installation directory of the Web-Designer Web Portal and launch WebDesigner.ConfigFileEditor.exe
  • Under Connection click on Enter new connection
  • Select either SQL Server or Application Server
  • If using the Application Server 
    • Enter the Application Server URL
    • A certificate can be selected but it is not necessary, the field can be left blank.
    • Click Finish
  • If using the SQL Server 
    • Enter the Server 
    • Provide a Username and Password or select the Windows Authentication checkbox.
    • Select the Database dropdown and choose the correct database.
    • If the Options | Test Connection is successful, click Finish.
  • From the top menu bar, select File | Save.
  • Restart the One Identity Manager service.
• Follow the above steps for each On-Premise Web-Designer server. 

Option 2: Decrypt and Re-Encrypt the connection string manually.

• Open a Command Prompt as Administrator
  • Run the following command:

    • CD C:\Windows\Microsoft.NET\Framework\V4.0.30319

  • Decrypt the Web.Config connection string with the following command:

    • Aspnet_regiis.exe -pdf “connectionStrings” C:\inetpub\wwwroot\IdentityManager

  • Update the connectionStrings settings as needed.
  • Encrypt the Web.Config connection string with the following command:    

    • Aspnet_regiis.exe -pef “connectionStrings” C:\inetpub\wwwroot\IdentityManager

• Follow the above steps for each On-Premise Web-Designer server. 

API-Server (On-Premise)

To update the Connection String used by any On-Premise API-Server Web Portal:

• Open a Command Prompt as Administrator
  • Run the following command:

    • CD C:\Windows\Microsoft.NET\Framework\V4.0.30319

  • Decrypt the Web.Config connection string with the following command:

    • Aspnet_regiis.exe -pdf “connectionStrings” C:\inetpub\wwwroot\APIServer

  • Update the connectionStrings settings as needed.
  • Encrypt the Web.Config connection string with the following command:    

    • Aspnet_regiis.exe -pef “connectionStrings” C:\inetpub\wwwroot\APIServer

• Follow the above steps for each On-Premise API-Server.