Enabling Mongo Authentication

MongoDB can be configured to require authentication for added security. However, this will restrict access to Square 9 software that needs to connect to MongoDB. The steps below detail how to to set this up.

These steps listed below should be performed by an IT specialist or technical user, as improperly following these steps may accidentally lock you out of GlobalSearch/GlobalCapture. Please read through the entire procedure before beginning. It is also recommended that all configuration files mentioned in this guide are backed up prior to being edited.

Requirements

The following requirements must be met prior to beginning this process:

1. GlobalSearch must be version 4.5.2.0 or later.

2. GlobalCapture must be version 2.1.0.116 or later.

3. MongoDB must be version 3.4.6 or 4.2

   • Mongo is updated to this version 3.4.6 upon upgrade to GlobalCapture 2.1

   • Mongo is not updated to version 4.2 upon upgrade to GlobalCapture 2.4. Only new installs of GlobalCapture 2.4 on servers that have never had an old install will install mongo 4.2. An uninstall re-install will not upgrade to 4.2.

   • You can verify your version of MongoDB by navigating to "C:\GetSmart\mongodb\bin", right-clicking "mongod.exe", selecting "Properties", and viewing the "Details" tab.

4. If using Robo 3T (formerly Robomongo), you must use version 0.9 or higher to connect after configuring Mongo authentication in this manner.

Configure GlobalSearch/GlobalCapture

To configure the Square 9 software, add the following entry to the "appSettings" section of the configuration files listed below.

XML Key

Configuration Files (please note that the exact file path may vary on a non-default setup):

1. C:\inetpub\wwwroot\Square9API\web.config

2. C:\inetpub\wwwroot\Square9CaptureAPI\web.config

3. C:\inetpub\wwwroot\Square9Rest\web.config

4. C:\GetSmart\Square9.GlobalAction.exe.config or C:\GetSmart\ActionServices\GlobalAction_1\Square9.GlobalAction.exe.config depending on GlobalAction version.
              You will need to edit this particular file for each GlobalAction engine installed across your network

5. C:\GetSmart\SSIMPORTERWS.exe.config

6. C:\GetSmart\BatchPortal\ssBatchPortal.exe.config

7. C:\GetSmart\CaptureServices\GlobalCapture_1\Square9.GlobalCapture.exe.config
              You will need to edit this particular file for each GlobalCapture engine installed across your network

Example: ssBatchPortal.exe.config

Open

Configure GlobalForms 10

GlobalForms 10 connects to MongoDB differently than GlobalSearch/GlobalCapture. To enable authentication, you must include the username/password in the MongoDB URL.

1. Pick a username/password. It can be any username and password. It does not need to be an existing Windows user.

2. Encode your username and password (separately) using a URL encoder

   1. The mongodb documentation lists the characters that need to be encoded: : / ? # [ ] @

3. Note the encoded username and password.

4. Navigate to the file "C:\GlobalForms\config\default.json". The exact file path may be different if you installed to a different directory.

5. Find the entry for "mongo". The URL entry should look something like "mongodb://<servername>:27017/GlobalForms".

6. Add the encoded username and password to the URL. You also need to specify the auth mechanism. This is done by adding "?authMechanism=DEFAULT" to the end of the URL.

Example

Using the username "globalforms10" and the password "globalforms10"

Add MongoDB Users

The next step is to configure the MongoDB users that we use to connect

Ensure the names of your databases

1. Connect to your MongoDB instance using a Mongo query utility, such as Robo 3T.

2. Note the names of your databases. You should have the following:

   1. WorkflowEngine

   2. ServiceEngine

   3. PortalSecurity

   4. CaptureWorkflow

      • This database may or may not be present. You are more likely to have this database if you upgraded from an earlier version.

   5. GlobalForms

      • This database will only be present if you are using this MongoDB instance for GlobalForms 10

3. If you do not have a PortalSecurity database, create one.

   • The simplest way to do this is to create a new Portal Connection and remove/secure a workflow to it. This creates the PortalSecurity database if it does not already exist. Review the following article for steps: https://square9softworks.atlassian.net/wiki/spaces/GC230/pages/246547298

   • You could also create the database using your querying utility. It is case-sensitive, so "portalsecurity" is not the same as "PortalSecurity".

Create MongoDB admin user

1. Open a Mongo shell by running the following commands from an Administrative Command prompt:

   cd C:\GetSmart\mongodb\bin mongo --port 27017

2. Run the following commands in the Mongo shell. The user created in the second command is your Mongo admin user, simply replace "MyAdminUser" and "MyAdminPassword". This does not need to be your service account, but you will need this username and password to access MongoDB via querying utilities, such as Robo 3T.

   use admin db.createUser({user: "MyAdminUser", pwd: "MyAdminPassword", roles: [{role:"root",db:"admin"}] })

Create MongoDB database users for GlobalSearch/GlobalCapture databases

1. While you still have the Mongo shell open, run the following commands. This user must be your Square 9 service account. This user is SSAdministrator by default. This is also case-sensitive. "WorkflowEngine" is not the same as "workflowengine".

2. Repeat the previous step for the ServiceEngine, PortalSecurity, and CaptureWorkflow databases. To do this, replace "use WorkflowEngine" with "use ServiceEngine", etc.

3. Repeat the commands for the GlobalForms database. Make sure you use the username and password picked out when editing the default.config file (see "Configure GlobalForms 10" above).

Configure MongoDB to Enforce Authentication

The following steps are what actually forces MongoDB to require authentication. You can switch MongoDB back to normal by reversing these steps.

1. Stop the MongoDB service (if the ssBatchPortal, GlobalCapture_1, S9GlobalAction, or GlobalForms services are running, you will be prompted to stop them too).

2. Navigate to "C:\GetSmart" and open the file "mongod.cfg" in a plain text editor, such as notepad, notepad++, or vim.

3. Depending on whether you are running Standalone GlobalCapture or GlobalSearch and GlobalCapture on the same machine, your configuration file will need to be modified to reflect the example for your environment.

   1. GlobalSearch and GlobalCapture

      1. Traditional Configuration file

          

      2. YAML Configuration file
         
         

   2. GlobalCapture Only
      See also: https://square9softworks.atlassian.net/wiki/spaces/S9SKB/pages/973472014

4. Save the file and restart the MongoDB service. Also restart the ssBatchPortal, GlobalCapture_1, S9GlobalAction (or GlobalAction_1 for version 2.2.0.0 and higher), and GlobalForms services.

Test Connecting to MongoDB using Robo 3T

The last step is to ensure that Mongo is actually enforcing authentication. The easiest way to check this is to use Robo 3T, version 0.9 or newer.

1. Close and Restart Robo 3T if it is already open.

2. Try to connect using an existing connection (one without authentication). You should receive the following error message:
   
   
   

   
   
   This is a good error message. It means that your MongoDB instance is denying your ability to see the list of databases.
   
   
   

3. Create a new connection.

4. In the "Authentication" tab, check off "Perform authentication". Specify "admin" as your database.

5. Enter the "User Name" and "Password" of the Mongo admin user you created (see "Create MongoDB admin user" above).

6. Specify "SCRAM-SHA-a" as your "auth mechanism".

7. Test your connection. If it succeeds, then you confirmed that your MongoDB connection is now enforcing authentication.

Resetting the SSAdministrator Password

In the event that you need to reset your SSAdministrator password, you will need to update the Mongo database users. You should first make sure that you have updated your SSAdministrator password using the instructions in the following article: https://square9softworks.atlassian.net/wiki/spaces/GS61/pages/1448938034

Then, take the following steps:

1. Open an authenticated Mongo shell by running the following commands using an administrative command prompt. Replace "MyAdminUser" and "MyAdminPassword" with the Mongo admin username and password you created (see "Create MongoDB admin user" above).

   
   
   

2. In the Mongo shell, run the following commands. Replace "SSAdministrator" and "MySSAdministratorPassword" with the username and password (respectively) for your Square 9 service account.

   
   
   

3. Repeat the previous step for the ServiceEngine, PortalSecurity, and CaptureWorkflow databases. To do this, replace "use WorkflowEngine" with "use ServiceEngine", etc.

4. Restart the ssBatchPortal, S9GlobalAction, and GlobalCapture_1 services.

Related articles