Skip to end of metadata
Go to start of metadata

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 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 all steps 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
    • Mongo is updated to this version upon upgrade to GlobalCapture 2.1
    • You can verify your version of Mongo 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
<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
  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

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, such as this one: https://www.url-encode-decode.com/
  3. Note down 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?authMechanism=DEFAULT"

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: http://knowledge.square-9.com/display/GCV202/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:

    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. If you are using a different. This is also case-sensitive. "WorkflowEngine" is not the same as "workflowengine".

    use WorkflowEngine
    db.createUser({user: "SSAdministrator", pwd: "MySSAdministratorPassword", roles: ["readWrite","dbAdmin"]})

  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. Add the following line to the bottom of the file:

    auth=true


    Your mongod.cfg file should look something like this:

  4. Save the file and restart the MongoDB service. Also restart the ssBatchPortal, GlobalCapture_1, S9GlobalAction, 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: http://knowledge.square-9.com/display/GSW45/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).

    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.

    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/




Write a comment…