Skip to main content
Skip table of contents

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
XML 
<add key="MongoAuthentication" value="true"/>

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 (*not used in GC3.0+)

  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

Configure GlobalForms 10

The way that GlobalCapture 3.0 configures MongoDB Authentication is that there is one user in the admin database that has access to all databases. To communicate this to GlobalForms you have to tell it which database to authenticate against, for a GlobalCapture 3.0 configured MongoAuthentication configuration you can do this by appending ?authSource=admin to the end of the Connection string. mongodb://globalforms10:globalforms10@localhost:27017/GlobalForms?authMechanism=DEFAULT&authSource=admin",

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"

Original URL

"mongodb://localhost:27017/GlobalForms"


New URL

"mongodb://globalforms10:globalforms10@localhost:27017/GlobalForms"

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: Portal Management

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

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

    JS 
    use admin
db.createUser({user: "MyAdminUser", pwd: "MyAdminPassword", roles: [{role:"root",db:"admin"},{ role: "userAdminAnyDatabase", db: "admin" },{ role: "readWriteAnyDatabase", 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".

    JS 
    use 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.

Note that there are two different formats for MongoDB configuration files. “Traditional” (uses = ) and “YAML” (uses : ), newer versions of MongoDB will use the YAML style by default.

  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

        JS 
        auth=true

      2. YAML Configuration file

        CODE 
        security:
  authorization: enabled

    2. GlobalCapture Only
      See also: How To Restrict Mongo To Only Accept Local Connections

      JS 
      security:
    authorization: enabled

  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: Change the SSAdministrator Password

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

    POWERSHELL 
    cd C:\GetSmart\mongodb\bin
mongo.exe --port 27017 -u MyAdminUser -p MyAdminPassword --authenticationDatabase "admin"


  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.

    JS 
    use WorkflowEngine
db.updateUser("SSAdministrator",{pwd:"MySSAdministratorPassword"})


  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.


At this point, your MongoDB instance is now enforcing authentication. You should confirm there are no issues with connecting to Mongo by performing a basic health checkup. Can you view batch history? Are you able to create and edit workflows? Are your GlobalAction and GlobalCapture engines processing your existing workflows?


If at any point you want to reconfigure MongoDB back to the way it was, simply remove the "auth=true" from C:\GetSmart\mongod.cfg and restart the MongoDB service (as well as any dependent services). You can remove the Mongo database users using the command db.dropUser("SSAdministrator") from a Mongo shell


For complete documentation regarding Mongo authentication, please reference the following link: http://mongodb.github.io/node-mongodb-native/3.0/tutorials/connect/authenticating/


If you add all of the correct keys and still cannot get the Batch Portals to connect, make sure this key exists in the batchportal.exe.config file:  <add key="Mongo" value="mongodb://localhost/?safe=true"></add>




JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close