Qlik Sense and changing the Active Directory Domain name

[Bastien_Laugiero]

In this article, we detail the 12 steps necessary to successfully configure Qlik Sense Enterprise on Windows after an Active Directory Domain name change or moving Qlik Sense to a new domain.

Depending on how you have configured your platform, not all the steps might be applicable. Before updating any hostname in Qlik Sense, make sure that the original value is using the old domain name. In some case, you may have configured “localhost” or the server name without any reference to the domain so there is no need in these cases to perform any update.

Scenario

In this scenario we are updating a three-node environment running Qlik Sense February 2021:

The domain has been changed from DOMAIN.local to DOMAIN2.local

The servers mentioned below are already part of the new domain name DOMAIN2.local and their Fully Qualified Domain Name (FQDN) is already updated as followed:

• QlikServer1.domain.local to QlikServer1.domain2.local: Central node
• QlikServer2.domain.local to QlikServer2.domain2.local: Rim node
• QlikServer3.domain.local to QlikServer3.domain2.local:  Dedicated Postgres and hosting the Qlik shared folder

All Qlik Sense services have been stopped on every node.

Step 1: Update the Postgres Configuration File

The first step is to update the postgres.conf file to listen on the correct hostname

1. Open the postgres.conf (make sure to make a copy) under
   • C:\ProgramData\Qlik\Sense\Repository\PostgreSQL\<version> (for an environment running the native Qlik Sense Repository Database)
   • C:\Program Files\PostgreSQL\<version>\data (for an environment running a dedicated PostgreSQL database)
2. Search for the parameter listen_addresses and update the hostname value if required
   
   
   
   
3. Save the file, close it and start the Qlik Sense Repository Database or PosgresSQL service depending if you are using the native PostgreSQL or a dedicated instance

Step 2: Backup your Qlik Sense site

Before doing any further changes, it is important to take a backup of your Qlik Sense Platform

• Backing up a Qlik Sense site

Step 3: Rename Server Node in QSR database

Now we update the node names in the database with the new Fully Qualified Domain Name.

1. Connect to the Qlik Sense Database using Installing and Configuring PGAdmin4 to access the PostgreSQL
2. Open the QSR Database and navigate through Schemas -> public ->Tables
3. Right-click on ServerNodeConfiguration -> View/Edit Data -> All Rows
4. Modify the hostname of each node if required
   
   
   
   
5. Save by clicking on the below icon available in the toolbar
   
   
   
   
6. Close PGAdmin

 

Step 4: Rename User Directory for existing users

1. Connect to the Qlik Sense Database using Installing and Configuring PGAdmin4 to access the PostgreSQL
2. Right-click on the QSR Database and select “Query Tool”
3. Run the following query
   

   UPDATE public."Users"
   SET "UserDirectory" = 'DOMAIN2'
   WHERE "UserDirectory" = 'DOMAIN';​

4. Validate the change by running the following query
   

   SELECT * FROM public."Users"​

   
   The User Directory should be updated to the new domain:
   
   
   
   
5. Close PGAdmin

Step 5: Update Service Cluster configuration

1. On the central node run the program C:\Program Files\Qlik\Sense\Repository\Util\QlikSenseUtil\QlikSenseUtil.exe and Connect to Database
   
   
   
   
2. Once connected, click on Service cluster and then OK
3. Update the FQDN with the new domain if required and press Save
   
   
   
   
4. Close QlikSenseUtil.exe

 

Step 6: Update the repository Connection Strings

1. On the central node run the program C:\Program Files\Qlik\Sense\Repository\Util\QlikSenseUtil\QlikSenseUtil.exe
2. Select Connection String Editor and click on Read
3. Update the FQDN with the new domain if required and press Save Value in config file encrypted
   
   
   
   
4. Close QlikSenseUtil.exe
5. Repeat the above steps on every rim node

Step 7: Update the dispatcher services connection strings

 

Verify if a hostname update is required

1. On the central node, open File Explorer and navigate to C:\Program Files\Qlik\Sense\Licenses and open the appsetting.json
2. Check if the parameter host contains the old domain name. If it does then you need to follow the below steps to update it otherwise you can jump to the next section

Update hostname on all Qlik Sense Dispatcher subservices

1. Search for the file called Configure-Service.ps1
   
   In Qlik Sense February, there are 8 of these files placed in different Qlik Sense Dispatcher sub-services. We need to run each of these files with a specific argument. In the previous or later version of Qlik Sense, the list presented below may need to be adapted.
   
   
2. Run the following command in PowerShell ISE as Administrator
   

   cd "C:\Program Files\Qlik\Sense\NLAppSearch\install"
   .\Configure-Service.ps1 QlikServer3.domain2.local 4432 qliksenserepository <qliksenserepository_password>
   
   cd "C:\Program Files\Qlik\Sense\AppDistributionService"
   .\Configure-Service.ps1 QlikServer3.domain2.local 4432 qliksenserepository <qliksenserepository_password>
   
   cd "C:\Program Files\Qlik\Sense\HybridDeploymentService"
   .\Configure-Service.ps1 QlikServer3.domain2.local 4432 qliksenserepository <qliksenserepository_password>
   
   cd "C:\Program Files\Qlik\Sense\Licenses"
   .\Configure-Service.ps1 QlikServer3.domain2.local 4432 qliksenserepository <qliksenserepository_password>
   
   cd "C:\Program Files\Qlik\Sense\NotifierService\install"
   .\Configure-Service.ps1 QlikServer3.domain2.local 4432 qliksenserepository <qliksenserepository_password>
   
   cd "C:\Program Files\Qlik\Sense\MobilityRegistrarService\install"
   .\Configure-Service.ps1 QlikServer3.domain2.local 4432 qliksenserepository <qliksenserepository_password>
   
   cd "C:\Program Files\Qlik\Sense\PrecedentsService\install"
   .\Configure-Service.ps1 QlikServer3.domain2.local 4432 qliksenserepository <qliksenserepository_password>
   
   cd "C:\Program Files\Qlik\Sense\DataPrepService\install"
   .\Configure-Service.ps1 QlikServer3.domain2.local 4432 qliksenserepository <qliksenserepository_password>

3. Repeat the above steps on every node (Including the verification)

Step 8: Update the Qlik Logging Service

If you are using the Qlik Logging Service;

1. Run the following command in Command Prompt:
   

   cd "C:\Program Files\Qlik\Sense\Logging"
   Qlik.Logging.Service.exe validate​

2. If you get something like:
   
   Failed to validate logging database. Database does not exist or is an invalid version.
   
   Then it probably means that the hostname needs to be updated
   
   
3. If so, run the following command in Command Prompt:
   

   cd "C:\Program Files\Qlik\Sense\Logging"
   Qlik.Logging.Service.exe update -h QlikServer3.domain2.local​

4. Once done, run the validate command again to verify that the connectivity is working
   
   
   
   
5. Repeat the above steps on every rim node

Step 9: Update the service account running the Qlik Sense services

1. On the central node, open the Windows Service Console an update each Qlik Sense services with the new domain (DO NOT START THE SERVICE AT THIS POINT)
   
   
   
   
2. Repeat the above step on every rim node
   
   

Step 10: Update the host.cfg and remove the certificate

1. On the central node login as the service account
2. Backup the Qlik Sense certificate following Backing up certificates
3. Remove the certificate you have previous backed up from the MMC
4. Make a copy of %ProgramData%\Qlik\Sense\Host.cfg and rename the copy to Host.cfg.old
   • Host.cfg contains the hostname encoded in base64. You can generate this string for the new hostname using a site such as https://www.base64encode.org/ (You may want to decode the original string to see if it contains the old domain name.
5. Open Host.cfg and replace the content with the new encoded hostname.
6. Run Windows Command Prompt as Administrator and execute the following command:
   

   "C:\Program Files\Qlik\Sense\Repository\Repository.exe" -bootstrap -iscentral -restorehostname​

7. In parallel start the Qlik Sense Dispatcher services
8. When the command has completed successfully you should see the following message in command prompt:
   
   Bootstrap mode has terminated. Press ENTER to exit..
   
   
9. Start every Qlik Sense services on the central node and try to access the QMC with https://localhost/qmc

Step 11: Distribute the certificate on the rim node(s)

1. On the rim node(s) login as the service account
2. Backup the Qlik Sense certificate following Backing up certificates
3. Remove the certificate you have previous backed up from the MMC
4. Start the Qlik Sense services
5. On the central node, open the QMC and go to Nodes
6. After a few minutes the rim node should have the status The certificates has not been installed
   
   
   
   
7. Click on Redistribute and follow the instructions to redistribute the certificates on the rim node(s)
8. After a few minutes, the services should be running
   
   

Step 12: Additional updates

User Directory Connector

If you are syncing your users with a User Directory Connector you will need to change the LDAP path to point to the new domain.

1. In the QMC -> User Directory Connector
2. Edit your existing User Directory Connector, check the LDAP Path and update if necessary
   
   

Monitoring Application

You will need to update the monitoring apps and their associated data connection to use the new Fully Qualified Domain Name

• Configuring the Monitoring apps

Data Connections password

• Part of the steps followed earlier, the certificates had to be recreated. As a result, the passwords for the existing data connection needs to be re-typed and saved for all Data Connections and User Directory Connectors that include password information.

Security Rules and Licenses rules

It is possible that you have created rules based on the User Directory. As you have changed the domain name, the user directory has also changed in Qlik Sense so you will need to update those to reflect that.

Environment

• Qlik Sense Enterprise on Windows 

The information in this article is provided as-is and to be used at own discretion. Depending on tool(s) used, customization(s), and/or other factors ongoing support on the solution below may not be provided by Qlik Support.

[RaviGinqo]

Hey @Bastien_Laugiero , 

That's amazingly useful article and quite thorough. 

I was wondering what would be the approach when we need to  migrate  the user ID itself and not just Domain.

For example when user setup Qlik Sense Environment, they allowed user to login with Email (abc@domain.com) and now they want to leverage Unified Licensing So they want users to login with Domain\UserID (Domain\abc)

For starters they are able to get new attribute from IdP for Domain\UserID,  but all the old bookmarks, Apps and access , users all permissions are gone, as Qlik identifies the same user as new one now.  How should they be migrated now? Is there a way to do it?

Thanks

Ravi

[Bastien_Laugiero]

Hello Ravi,

Glad you have found this article useful! 

So regarding your scenario I believe this will require a two step approach.

1. As a first step you will need to create a SQL Script to run against the Database to update the existing users to reflect the new UserID and UserDirectory,... I would strongly recommend to involve a DB admin for that. 
2. If you are using a UDC, then you will potentially need to update the Attributes in the Advanced section to make sure you are loading the correct field from your Active Directory. 

Finally, before doing that in a live system, I would suggest to spin up a test environment and restore your production database in it so you can make sure the script is working as expected and the users are not getting duplicated.

Kind regards, 

Bastien Laugiero

[RaviGinqo]

Thank you @Bastien_Laugiero 

The points you mentioned are really crucial, I will work on this further and let you know if need advise.

Best Regards,

Ravi

[arosmari]

Hi Bastien,

thank you for this post, I'm trying to do the process but I have a problem in step 10.

when execute the command: "C:\Program Files\Qlik\Sense\Repository\Repository.exe" -bootstrap -iscentral -restorehostname​

in the CMD showme this:

"Waiting for initial configuration to be run by node installed on QlikServer3.domain1.local"

its still want to connect to old domain and I had no problems with the steps above.

Do you know why this happens or where the problem is?

thank you

[giociva]

@Bastien_Laugiero 

does the UserDirectoryConnectorName need to be changed as well?

Users in the different domain are not synchronized due to that field with OLDDOMAIN value in users table.

thanks.

[giociva]

@Bastien_Laugiero  @Sonja_Bauernfeind  little more of details:

I updated the UserDirectory with

UPDATE public."Users"
SET "UserDirectory" = 'DOMAIN2'
WHERE "UserDirectory" = 'DOMAIN';​

 the users now are shows in QMC with the DOMAIN2 UserDirectory but they are not being synchronized.

Looking at the INFO icon for those users I noticed that there is this value UserDirectoryConnectorName that is still referring the old DOMAIN name.

[Sonja_Bauernfeind]

Hello @giociva 

If you have followed all steps (including 12), the server setup is completed. We provide additional steps on how to convert users to a new user directory here: Qlik Sense moved to a new domain or server name changed: Convert Users To New User Directory  

If you need more help, I recommend posting about the challenge in our Qlik Sense Management forum. And if you are looking for a direct engagement from Qlik in this regard, we would need to recommend our Professional Services. 

All the best,
Sonja 

[giociva]

Thanks @Sonja_Bauernfeind , i will post on that forum.

[Sonja_Bauernfeind]

Hello @Mahamed_Qlik 

In your case, this can be left unedited. The line is commented out (the # in front of it means it is not being read), meaning it has never been configured previously. You can safely leave it as it is. The step you quote is only necessary if this line was previously edited.

All the best,
Sonja 

[Qlik_FZ]

Hi Sonja

We have followed all the 12 steps including your additional steps. We have successfully changed the domain.

But, we are getting user is not authenticated while accessing QMC with new user service account.
We also have provided 'rootadmin' for newly created service account user.