---
path: faq/replica-set-authorization.mdx
title: Enabling and configuring authorization in a MongoDB replica set
slug: replica-set-authorization
description: >-
  Enabling authorization and inter-node authentication in a MongoDB replica set:
  creating a user, generating a keyfile, and configuring the Passwork
  config.env.
keywords:
  - Passwork
  - MongoDB
  - Replica Set
  - authorization
  - keyfile
  - authentication
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

## Overview

The example uses 3 MongoDB servers in a replica set:

- **example.mongo.01**
- **example.mongo.02**
- **example.mongo.03**

:::warning
Replica set configuration is described in [Configuring a MongoDB replica set](/faq/mongodb-replica-set). Configuring a replica set and authorization in Docker is described in [Migrating from standalone to a replica set](/faq/docker/fault-tolerance/migration-to-replica-set).
:::

## Connecting to MongoDB and creating a user

### Connecting to the shell

Connect to the MongoDB replica set:

<details>
  <summary>Linux</summary>

  <Tabs className="tabs-container">
    <TabItem className="tab-item-container" value="shell" label="shell">

  ```bash
  mongosh --host rs0/example.mongo.01:27017,example.mongo.02:27017,example.mongo.03:27017
  ```

    </TabItem>
  </Tabs>

</details>

<details>
  <summary>Windows Server</summary>

  If the command returns the error **mongosh : The term 'mongosh' is not recognized...**, the MongoDB utilities are not in `PATH`. Locate `mongosh.exe`:

  <Tabs className="tabs-container">
    <TabItem className="tab-item-container" value="shell" label="shell">

  ```powershell
  $mongoshPath = Get-ChildItem -Path "C:\" -Filter "mongosh.exe" -Recurse -ErrorAction SilentlyContinue | Select-Object -First 1; $mongoshDirectory = $mongoshPath.DirectoryName; cd $mongoshDirectory
  ```

    </TabItem>
  </Tabs>

  If MongoDB is installed on a non-default drive, change the path in the `-Path` parameter. Then connect:

  <Tabs className="tabs-container">
    <TabItem className="tab-item-container" value="shell" label="shell">

  ```powershell
  .\mongosh.exe --host rs0/example.mongo.01:27017,example.mongo.02:27017,example.mongo.03:27017
  ```

    </TabItem>
  </Tabs>

</details>


### Creating a user

Switch to the `admin` database:

<Tabs className="tabs-container">
  <TabItem className="tab-item-container" value="shell" label="shell">

```bash
use admin
```

  </TabItem>
</Tabs>

Create a user (replace the login and the password):

<Tabs className="tabs-container">
  <TabItem className="tab-item-container" value="shell" label="shell">

```bash
db.createUser({
  user: "adminuser",
  pwd: "password",
  roles: [
    { role: "root", db: "admin" }
  ],
  passwordDigestor: "server"
})
```

  </TabItem>
</Tabs>

:::warning
In MongoDB, do not use the following characters in the user name and password: `.` `@` `$` `:` `%` `"` `'` `/` `\` `|` — they can cause failures when the application connects to MongoDB.
:::

Grant the `clusterManager` role to the `adminuser` user for cluster management:

<Tabs className="tabs-container">
  <TabItem className="tab-item-container" value="shell" label="shell">

```bash
db.grantRolesToUser(
   "adminuser",
   [ "clusterManager" ]
)
```

  </TabItem>
</Tabs>

## Enabling authorization and configuring inter-node authentication

### Enabling authorization in MongoDB

Configuration file location:

- **Linux** — `/etc/mongod.conf`
- **Windows Server** — `C:\Program Files\MongoDB\Server\7.0\bin\mongod.cfg`

You can check the path from the MongoDB shell:

<Tabs className="tabs-container">
  <TabItem className="tab-item-container" value="shell" label="shell">

```bash
var cmdLineOpts = db.serverCmdLineOpts();
print("config: " + cmdLineOpts.parsed.config);
```

  </TabItem>
</Tabs>

Open the configuration file and change or add the parameters (on every node — `example.mongo.01`, `example.mongo.02`, `example.mongo.03`):

```yaml
security:
  authorization: enabled
```

:::warning
Indentation in the configuration file matters for the syntax. The **security** parameter controls authorization, authentication, and other security settings.
:::

:::info
Authorization cannot be verified at this stage yet — authentication between the replica set members has not been configured.
:::

### Configuring authentication between replica set members

Create a base64 `keyfile` on **example.mongo.01**:

<details>
  <summary>Linux</summary>

  <Tabs className="tabs-container">
    <TabItem className="tab-item-container" value="shell" label="shell">

  ```bash
  openssl rand -base64 756 > /var/lib/mongodb/keyfile
  ```

    </TabItem>
  </Tabs>

</details>

<details>
  <summary>Windows Server</summary>

  Open PowerShell as an administrator:

  - Right-click the "Start" icon in the bottom-left corner of the screen;
  - Select "Windows PowerShell (Admin)" from the context menu.

  Commands to create the file:

  <Tabs className="tabs-container">
    <TabItem className="tab-item-container" value="shell" label="shell">

  ```powershell
  # Generating random bytes
  $randomBytes = New-Object byte[] 756
  [System.Security.Cryptography.RNGCryptoServiceProvider]::Create().GetBytes($randomBytes)

  # Encoding to base64
  $base64String = [Convert]::ToBase64String($randomBytes)

  # Writing to the file
  $base64String | Out-File -FilePath "C:\Program Files\MongoDB\Server\7.0\data\keyfile" -Encoding ASCII
  ```

    </TabItem>
  </Tabs>

</details>

Set the permissions on the `keyfile` and assign the `mongodb` owner:

<details>
  <summary>Linux</summary>

  <Tabs className="tabs-container">
    <TabItem className="tab-item-container" value="shell" label="shell">

  ```bash
  chmod 400 /var/lib/mongodb/keyfile
  chown mongodb:mongodb /var/lib/mongodb/keyfile
  ```

    </TabItem>
  </Tabs>

</details>

<details>
  <summary>Windows Server</summary>

  No additional commands are required — the security policies of the `.\data` directory apply to the file.

</details>

Copy the keyfile to the remaining nodes (example.mongo.02, example.mongo.03):

<details>
  <summary>Linux</summary>

  <Tabs className="tabs-container">
    <TabItem className="tab-item-container" value="shell" label="shell">

  ```bash
  scp /var/lib/mongodb/keyfile root@example.mongo.02:/var/lib/mongodb/
  scp /var/lib/mongodb/keyfile root@example.mongo.03:/var/lib/mongodb/
  ```

    </TabItem>
  </Tabs>

</details>

<details>
  <summary>Windows Server</summary>

  Transfer the keyfile manually to the remaining nodes into the directory:

  <Tabs className="tabs-container">
    <TabItem className="tab-item-container" value="shell" label="shell">

  ```text
  C:\Program Files\MongoDB\Server\7.0\data\
  ```

    </TabItem>
  </Tabs>

</details>

:::warning
The `keyfile` must be **identical** on all nodes — it is used for authentication between the nodes.
:::

On the example.mongo.02 and example.mongo.03 nodes, set the same permissions and owner:

<details>
  <summary>Linux</summary>

  <Tabs className="tabs-container">
    <TabItem className="tab-item-container" value="shell" label="shell">

  ```bash
  chmod 400 /var/lib/mongodb/keyfile
  chown mongodb:mongodb /var/lib/mongodb/keyfile
  ```

    </TabItem>
  </Tabs>

</details>

<details>
  <summary>Windows Server</summary>

  <Tabs className="tabs-container">
    <TabItem className="tab-item-container" value="shell" label="shell">

  ```powershell
  icacls "C:\Program Files\MongoDB\Server\7.0\data\keyfile" /reset
  ```

    </TabItem>
  </Tabs>

</details>

Open the configuration file on **every** node and add the `keyFile` parameter:

```yaml
security:
  authorization: enabled
  keyFile: /var/lib/mongodb/keyfile or C:\Program Files\MongoDB\Server\7.0\data\keyfile
```

After making the changes, restart the MongoDB service:

<details>
  <summary>Linux</summary>

  <Tabs className="tabs-container">
    <TabItem className="tab-item-container" value="shell" label="shell">

  ```bash
  systemctl restart mongod.service
  ```

    </TabItem>
  </Tabs>

</details>

<details>
  <summary>Windows Server</summary>

  <Tabs className="tabs-container">
    <TabItem className="tab-item-container" value="shell" label="shell">

  ```powershell
  net stop MongoDB
  net start MongoDB
  ```

    </TabItem>
  </Tabs>

</details>

Verify the connection to the replica set with authorization:

<Tabs className="tabs-container">
  <TabItem className="tab-item-container" value="shell" label="shell">

```bash
mongosh --host rs0/example.mongo.01:27017,example.mongo.02:27017,example.mongo.03:27017 -u adminuser -p password --authenticationDatabase admin
```

  </TabItem>
</Tabs>

## Configuring Passwork to connect to the replica set

Edit the Passwork configuration file — `config.env`:

<Tabs className="tabs-container">
  <TabItem className="tab-item-container" value="shell" label="shell">

```bash
MONGODB_URL=mongodb://example.mongo.01:27017,example.mongo.02:27017,example.mongo.03:27017/?replicaSet=rs0
MONGODB_DB=pw
MONGODB_USERNAME=adminuser
MONGODB_PASSWORD=password
```

  </TabItem>
</Tabs>

File location:

- **Linux** — `/var/www/init/config.env`
- **Windows Server** — `C:\inetpub\wwwroot\passwork\init\config.env`

Save the changes and reload the Passwork web interface page to verify the authorized connection to MongoDB.