Introduction

Both ClearWay™ and AdvanceGuard® utilise the Mongo database for managing all system configuration and recording real-time data such as alarms and track data. By default the connection to the MongoDb server does not use authentication. Although network restrictions can be implemented to restrict any external connectivity to the database server, many customers will consider authentication a mandatory requirement. This document covers the steps required to configure both our software and the Mongo database to use authentication.

The authentication process used is called Salted Challenge Response Authentication Mechanism (SCRAM). More details can be found in the Mongo documentation here: SCRAM. The only supported SCRAM mechanism is SCRAM-SHA-256.

Contents

Prerequisites

In order to enable authentication you will need the following:

1. A version of ClearWay™ or AdvanceGuard® that supports database authentication:

   1. ClearWay™: V4.12.0.x or later.

   2. AdvanceGuard®: V4.12.0.x or later.

2. Local administrative access to the OS running the Mongo servers, Management Servers and Track Engines.

3. A working knowledge of Mongo replica sets (if your system uses one).

4. A working knowledge of the Witness Utility application.

5. A suitable text editor to ensure you edit configuration files. We recommend: https://notepad-plus-plus.org/.

Process Overview

The outline process is illustrated below. These are the key steps, however, some of these actions may be more involved depending on whether you are enabling authentication on a stand alone server or a replica set.

Open

Enabling Authentication

The detailed instructions cover both stand alone servers and replica setups, so please ensure you follow the relevant steps for your particular system configuration.

The process will create two default user accounts. Both accounts are created in the system admin database and are only allocated roles appropriate to their function. They are:

1. Administrator account with a username of admin. This account can be used to administer and access all databases on the server. This account should never be used for routine database access.

2. Application account with a username of tungsten. This is used by the software to access the application database. It is restricted to only the required roles required by the ClearWay™ and AdvanceGuard® software.

Enabling Authentication on a Standalone Server

To enable password authentication on a standalone server, complete the following steps:

Install / Upgrade the Application

1. Install or upgrade an existing system with a version of AdvanceGuard® or ClearWay™ that supports database authentication. Please refer to: Database Authentication | Prerequisites. Ensure all servers and clients are upgraded. Full instructions on installation can be found here: Installation Guide.

2. Once the software is installed or fully upgraded, then ensure all services are started, including the Mongo database server.

3. Verify that the dbsettings.json file has been created in the application data folder (%PROGRAMDATA%\Navtech) on the Management Server. If the file is not there, then either the version of software being installed does not support database authentication or something went wrong during the start-up of the Management Server. Please check the relevant logs for more information.

Create Database User Accounts

Two database users are required to complete this process. The first is the global database admin which will be able to perform system level database tasks once authentication is enabled. The second is the application account which is used by the software to access only the required data. We have enhanced the Witness Utility app to help create these accounts.

1. Establish suitable passphrases for your users (global admin and application user).

2. Use the https://navtechradar.atlassian.net/wiki/spaces/TUN/pages/2389803013 app with the database and createusers commands to create the user groups:

   1. Ensure you provide the correct database name, especially if enabling this on a database server which hosts multiple application data stores. The database name is provided during installation but defaults to ClearWay and AdvanceGuard for the respective applications, if left unchanged.

   2. Enter the passwords you created in step 1 for the options -a and -u.

      WitnessUtilities.exe database -d ClearWay -i 127.0.0.1 createusers -a globaladminpassword -u applicationuserpassword
      C:\Program Files\Navtech Radar\Witness\dotnet>WitnessUtilities.exe database -d ClearWay -i 127.0.0.1 createusers -a globaladminpassword -u applicationuserpassword Waiting 10s for the database server to become available Creating default user accounts ... Default users created successfully C:\Program Files\Navtech Radar\Witness\dotnet>

Edit the Mongo Configuration File

To enable password authentication we need to tell the Mongo server that we want to use authentication. To do this we need to make a simple change to the default configuration file that was created when the database server was installed.

To enable password authentication in the database configuration file:

1. Ensure the database server has a key file called database-security.key in the application data folder (%PROGRAMDATA%\Navtech).

2. On the database server, open the file database-configuration.yaml from the application data folder (%PROGRAMDATA%\Navtech) in a suitable text editor.

3. Find the security and keyfile entries:

   net: bindIp: 0.0.0.0 port: 27010 systemLog: destination: file path: "C:/Local/MongoDataTest/mongod.log" logAppend: true logRotate: reopen storage: dbPath: "C:/Local/MongoDataTest" #replication: # replSetName: "" #security: #keyfile: "C:/ProgramData/Navtech/database-security.key" ...

4. These lines will be commented out using a prefix of #. Remove the # prefix from both lines as illustrated below.

5. Save and close the file.

Edit the Witness Settings File

To ensure the application uses the correct password to authenticate with the database we need to tell the application what password to use. This is done by putting it into the application database settings file on the Management Server.

To edit the settings file:

1. Open the file dbsettings.json from the application data folder (%PROGRAMDATA%\Navtech) in a suitable text editor on the Management Server.

2. Enter the password for the application user and change the UseAuth option to true:

3. Save and close the file.

Restart Services

Once all the settings are in place we can restart the necessary services to activate the authentication mechanism.

1. Restart the database service.

2. Restart the Management Server service.

Once the services are restarted you should be able to login to your application and everything will connect and operate as expected.

Edit the Log Rotate Script

When the database is installed, a Windows Scheduler Task is also created. This task will run a script, supplied by the installer, to force the rotation of the MongoDb server message log. By default this script does not try and authenticate with the database, therefore if you enable authentication on the server the script will fail to run. The script is self-managing, in that as well as rotating the logs on a schedule, it also supports options to manage itself. These steps take you through using the script to include authentication:

1. Find the script LogRotatePs.ps1 in %PROGRAMFILES%\Navtech Radar\Witness\Mongo on the database server.

2. Open a Windows PowerShell command prompt as an administrator. This script is designed for Windows PowerShell which is version 5.x not version 7.x. Windows PowerShell 5.x ships with Windows and therefore should already be installed.

3. Run the script install command and ensure you specify the admin password. Explanation for the options are listed below:

    

   Open

   

   LogRotatePs Script Execution

4. Note that the script will try and remove any previous versions of the script and if none are found then it will raise an error, this is normal. You should always see the summary with the TaskName and State and the State should show Ready.

Enabling Authentication on a Replica Set

The process for enabling authentication on a replica set is very similar, however there are a few extra steps. This process also assumes you are using redundant Management Servers with the database replica set which requires consideration to ensure both the primary and secondary servers can access the database.

To enable password authentication for a replica set complete the following steps:

Install / Upgrade the Application

1. Install or upgrade an existing system with a version of ClearWay™ or AdvanceGuard® that supports database authentication. Please refer to: Database Authentication | Prerequisites. Ensure all servers and clients are upgraded; full instructions on installation can be found here: Installation Guide.

2. Ensure you provide the relevant replica set settings during installation.

3. Once the software is installed or fully upgraded, then ensure all services are started, including all of the Mongo database servers.

4. Verify that the dbsettings.json file has been created in the application data folder (%PROGRAMDATA%\Navtech) on both Management Servers. If the file is not there, then either the version of software being installed does not support database authentication or something went wrong during the start-up of the Management Server. Please check the relevant logs for more information.

Create Database User Accounts

Two database users are required to complete this process. The first is the global database admin which will be able to perform system level database tasks once authentication is enabled. The second is the application account which is used by the software to access only the required data. We have enhanced the Witness Utility app to help create these accounts.

1. Establish suitable pass-phrases for your users (global admin and application user).

2. Use the https://navtechradar.atlassian.net/wiki/spaces/TUN/pages/2389803013 app with the database and createusers commands to create the user groups:

   1. Ensure you provide the correct database name, especially if enabling this on a replica set which hosts multiple application data stores. The database name is provided during installation but defaults to ClearWay and AdvanceGuard for the respective applications if left unchanged.

   2. Ensure you provide the IP address of the primary replica set member. This data will replicate to the other members of the set.

   3. Enter the passwords you created in step 1 for the options -a and -u.

Edit the Mongo Configuration File

To enable password authentication we need to tell all MongoDb servers that we want to use authentication. To do this we must make a simple change to the default configuration file that was created when the database server was installed.

To enable password authentication in the database configuration file:

1. Ensure the database server has a key file called database-security.key in the application data folder (%PROGRAMDATA%\Navtech).

2. The key file is created with a default security key. This is the only content within the file. Each database server will have a key file and the security key should be the same for all servers in the replica set.

3. On the database server, open the file database-configuration.yaml from the application data folder (%PROGRAMDATA%\Navtech) in a suitable text editor.

4. Find the security and keyfile entries:

5. These lines will be commented out using a prefix of #. Remove the # prefix from both lines as illustrated below.

6. Save and close the file.

7. Repeat this process for all the replica set members including arbiters.

Edit the Witness Settings File

To ensure the application uses the correct password to authenticate with the database we need to tell the application what password to use. This is done by putting it into the application database settings file on both Management Servers.

To edit the settings file:

1. Open the file dbsettings.json from the application data folder (%PROGRAMDATA%\Navtech) in a suitable text editor on the Management Server.

2. Enter the password for the application user and change the UseAuth option to true:

3. Save and close the file.

4. Repeat this process for both Management Servers.

Restart Services

Once all the settings are in place we can restart the necessary services to activate the authentication mechanism.

1. Restart the database services for all replica set member servers.

2. Restart all the Management Server services.

Once the services are restarted you should be able to login to your application and everything will connect and operate as expected.

Edit the Log Rotate Script

When the database is installed, a Windows Scheduler Task is also created. This task will run a script, supplied by the installer, to force the rotation of the MongoDb server message log. By default this script does not try and authenticate with the database, therefore if you enable authentication on the server the script will fail to run. The script is self-managing, in that as well as rotating the logs on a schedule, it also supports options to manage itself. These steps take you through using the script to include authentication:

1. Find the script LogRotatePs.ps1 in %PROGRAMFILES%\Navtech Radar\Witness\Mongo on the database server.

2. Open a Windows PowerShell command prompt as an administrator. This script is designed for Windows PowerShell which is version 5.x not version 7.x. Windows PowerShell 5.x ships with Windows and therefore should already be installed.

3. Run the script install command and ensure you specify the admin password. Explanation for the options are listed below:

    

4. Note that the script will try and remove any previous versions of the script and if none are found then it will raise an error, this is normal. You should always see the summary with the TaskName and State and the State should show Ready.

5. Repeat this for all the database servers in the replica set.

Disabling Authentication

The process for disabling authentication is fairly straightforward and by reversing this approach you can easily re-enable authentication as required.

Edit the Mongo Configuration File

We need to edit the database configuration to disable authentication on the database servers.

To disable password authentication in the database configuration file:

1. On the database server, open the file database-configuration.yaml from the application data folder (%PROGRAMDATA%\Navtech) in a suitable text editor.

2. Find the security and keyfile entries:

3. Comment out these lines by adding a # at the beginning of each line:

4. Save and close the file.

5. If your using a replica set then repeat this process on each member server.

Edit the Witness Settings File

To ensure the application does not try to authenticate with database servers that have authentication disabled we must change the application database settings.

To edit the settings file:

1. Open the file dbsettings.json from the application data folder (%PROGRAMDATA%\Navtech) in a suitable text editor on the Management Server.

2. Change the UseAuth option to false:

3. There is no need to remove the password; this can be kept to make it easier to re-enable authentication at a later date.

4. Save and close the file.

5. If using a resilient setup then repeat this process for all Management Servers.

Restart Services

Once all the settings are in place we can restart the necessary services to deactivate the authentication mechanism.

1. Restart the database services for all database servers.

2. Restart all the Management Server services.

Once the services are restarted you should be able to login to your application and everything will connect and operate as expected.

Edit the Log Rotate Script

Assuming the log rotate script was updated to use authentication, this process will show you how to remove the script and re-install it without a password:

1. Open the Windows Task Scheduler.

2. Find the WitnessMongoLogRotate task in the root folder and delete it:
   
   

3. Find the script LogRotatePs.ps1 in %PROGRAMFILES%\Navtech Radar\Witness\Mongo on the database server.

4. Open a Windows PowerShell command prompt as an administrator. This script is designed for Windows PowerShell which is version 5.x not version 7.x. Windows PowerShell 5.x ships with Windows and therefore should already be installed.

5. Run the script install command and ensure you leave the password out. Explanation for the options are listed below:

6. Note that the script will try and remove any previous versions of the script and if none are found then it will raise an error, this is normal. You should always see the summary with the TaskName and State and the State should show Ready.

7. Repeat this for all the database servers in the replica set.

Updating Passwords

You can change passwords, once the initial accounts have been created, by using the https://navtechradar.atlassian.net/wiki/spaces/TUN/pages/2389803013. A password can be changed before or after authentication has been enabled on the database server using the updatepassword command. Once authentication is enabled, updatepassword uses the admin account created when using the createusers command to access the database. Please refer to the utility documentation for more details.

If you change the password for the application user account then you must update the password file used by Witness. To update the file:

1. Open the file dbsettings.json from the application data folder (%PROGRAMDATA%\Navtech) in a suitable text editor on the Management Server.

2. Update the password for the application user and ensure the UseAuth option is true:

3. Save and close the file.

4. Repeat this process for both Management Servers if you are using a resilient setup.

5. Restart all the Management Server services.

Related Information