# How to Implement Keyfile Authentication for a Secure MongoDB Sharded Cluster

> Secure your MongoDB cluster with keyfile authentication. Learn to generate a keyfile, create a custom Docker image, and configure your nodes for robust internal authentication.

- Repository: [Jin/mongodb-cluster-docker-compose](https://github.com/minhhungit/mongodb-cluster-docker-compose)
- Tags: how-to-guide
- Published: 2026-03-07

---

**Generate a 756-byte base64 keyfile, bake it into a custom MongoDB 6.0.2 Docker image with restrictive permissions, and launch every node with the `--keyFile` flag to enable internal cluster authentication and admin user access.**

This guide walks you through implementing **keyfile authentication** in a containerized MongoDB sharded cluster using the `minhhungit/mongodb-cluster-docker-compose` repository. Keyfile authentication secures intra-cluster communication by requiring each `mongod` and `mongos` instance to authenticate using a shared secret before joining replica sets, creating the foundation for client authentication and production-ready security.

## What Is Keyfile Authentication in MongoDB?

**Keyfile authentication** is MongoDB's built-in method for enabling internal authentication between cluster members. Each node presents a shared keyfile—containing a base64-encoded secret—to prove its identity when joining a replica set or sharded cluster. Once internal authentication is active, you can create user credentials for client applications, effectively securing both server-to-server and client-to-server communication.

## Prerequisites and File Structure

Before implementing keyfile authentication, ensure you have Docker, Docker Compose, and OpenSSL installed. Clone the `minhhungit/mongodb-cluster-docker-compose` repository and navigate to the `with-keyfile-auth/` directory, which contains the secure configuration files:

- `with-keyfile-auth/mongodb-build/Dockerfile` – Custom image definition that embeds the keyfile
- [`with-keyfile-auth/docker-compose.yml`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/with-keyfile-auth/docker-compose.yml) – Service orchestration with `--keyFile` flags for all nodes
- [`with-keyfile-auth/scripts/auth.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/with-keyfile-auth/scripts/auth.js) – Admin user creation script executed against replica set members

## Step-by-Step Implementation

### Generate the Keyfile

Create a 756-byte base64-encoded keyfile using OpenSSL. This size meets MongoDB's minimum requirement for keyfile authentication.

```bash
openssl rand -base64 756 > mongodb-keyfile
chmod 400 mongodb-keyfile

```

Move the generated file to `with-keyfile-auth/mongodb-build/auth/mongodb-keyfile`. The restrictive `chmod 400` permissions ensure only the file owner can read the key, satisfying MongoDB's security requirements documented in the repository's README.

### Build the Custom Docker Image

The `with-keyfile-auth/mongodb-build/Dockerfile` embeds the keyfile into the MongoDB 6.0.2 image with the correct ownership and permissions.

```dockerfile

# with-keyfile-auth/mongodb-build/Dockerfile

FROM mongo:6.0.2
COPY /auth/mongodb-keyfile /data
RUN chmod 400 /data/mongodb-keyfile
RUN chown 999:999 /data/mongodb-keyfile

```

The `chown 999:999` command sets ownership to the `mongo` user (UID 999) inside the official Docker image, preventing permission denied errors when the server attempts to read the keyfile at startup.

### Configure the Docker Compose Services

Every service in [`with-keyfile-auth/docker-compose.yml`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/with-keyfile-auth/docker-compose.yml) must include the `--keyFile` parameter in its command. This applies to config servers, shard replicas, and `mongos` routers.

```yaml

# with-keyfile-auth/docker-compose.yml (router01 excerpt)

router01:
  build:
    context: mongodb-build
  image: jin-mongo:6.0.2
  container_name: router-01
  command: mongos --port 27017 \
          --configdb rs-config-server/configsvr01:27017,configsvr02:27017,configsvr03:27017 \
          --bind_ip_all --keyFile /data/mongodb-keyfile
  ports:
    - 27117:27017

```

The `--keyFile /data/mongodb-keyfile` flag forces MongoDB to use the shared secret for internal authentication. Without this flag, nodes cannot join the replica sets, and the cluster will fail to initialize.

### Initialize Replica Sets and Create Admin User

Start the cluster and initialize the config server replica set and shard replica sets using the provided scripts. Then create the admin user by executing [`auth.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/auth.js) against each member.

```bash

# Initialize config servers

docker-compose exec configsvr01 bash "/scripts/init-configserver.js"

# Initialize shards

docker-compose exec shard01-a bash "/scripts/init-shard01.js"
docker-compose exec shard02-a bash "/scripts/init-shard02.js"
docker-compose exec shard03-a bash "/scripts/init-shard03.js"

# Create admin user on each member

docker-compose exec configsvr01 bash "/scripts/auth.js"
docker-compose exec shard01-a bash "/scripts/auth.js"

# Repeat for shard02-a, shard03-a, and other members

```

The [`auth.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/auth.js) script located at [`with-keyfile-auth/scripts/auth.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/with-keyfile-auth/scripts/auth.js) executes `db.createUser()` with the `root` role on the `admin` database, granting full administrative privileges.

### Connect with Authentication

Once the admin user exists, connect through the `mongos` router using the authentication database.

```bash
docker-compose exec router01 mongosh --port 27017 \
   -u "your_admin" -p "your_password" --authenticationDatabase admin

```

All subsequent client connections must provide these credentials. The keyfile itself is used only for internal server-to-server authentication and should never be used for client connections or exposed to application layers.

## Security Best Practices for Keyfile Authentication

When implementing keyfile authentication in production environments, adhere to these guidelines:

- **Restrict keyfile permissions**: Always set `chmod 400` and ensure the file is owned by the MongoDB user (UID 999 in official Docker images). Never commit a production keyfile to source control.
- **Use strong base64 encoding**: Generate keys with `openssl rand -base64 756` to meet MongoDB's length requirements and ensure cryptographic randomness.
- **Automate user creation**: Execute [`auth.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/auth.js) against every replica set member immediately after initialization to prevent unsecured windows where the cluster accepts connections without authentication.
- **Rotate keys periodically**: While MongoDB does not support online keyfile rotation, plan maintenance windows to update the shared secret across all nodes.

## Summary

Implementing **keyfile authentication** in a MongoDB sharded cluster requires generating a secure shared secret, embedding it into a custom Docker image with strict permissions, and configuring every node to use the `--keyFile` parameter. The `minhhungit/mongodb-cluster-docker-compose` repository demonstrates this pattern by:

- Generating a 756-byte base64 keyfile with `openssl rand -base64 756`
- Building a custom MongoDB 6.0.2 image that copies the keyfile to `/data/mongodb-keyfile` with `chmod 400` and ownership `999:999`
- Launching config servers, shards, and `mongos` routers with the `--keyFile /data/mongodb-keyfile` flag
- Creating a root admin user via [`with-keyfile-auth/scripts/auth.js`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/with-keyfile-auth/scripts/auth.js) executed against each replica set member

## Frequently Asked Questions

### What is the minimum keyfile size for MongoDB authentication?

MongoDB requires keyfiles to contain **at least 756 bytes of base64-encoded content** (approximately 1024 characters when encoded). The `openssl rand -base64 756` command generates exactly this amount, satisfying the minimum length requirement while ensuring cryptographic randomness suitable for production environments.

### Why does MongoDB require specific file permissions on the keyfile?

MongoDB enforces strict **file permission checks** for security reasons. The keyfile must be readable only by the user running the `mongod` or `mongos` process (typically UID 999 in official Docker images). Setting `chmod 400` and `chown 999:999` prevents unauthorized users from reading the shared secret, which would compromise the entire cluster's authentication mechanism and allow unauthorized nodes to join the replica set.

### Can I add keyfile authentication to an existing running MongoDB cluster?

**No**, you cannot enable keyfile authentication on a running cluster without downtime. MongoDB requires the `--keyFile` parameter at startup to initialize internal authentication. To secure an existing cluster, you must generate the keyfile, update your Docker images or volume mounts to include it, restart all nodes with the `--keyFile` flag, and re-initialize replica sets. Plan a maintenance window for this operation, as the cluster will be unavailable during the transition.

### How do I connect to a MongoDB cluster that uses keyfile authentication?

Once keyfile authentication is enabled and an admin user is created, clients must authenticate using valid credentials against the `admin` database. Use the `mongosh` command with the `-u`, `-p`, and `--authenticationDatabase` flags:

```bash
mongosh --host router01 --port 27017 \
  -u "your_admin" -p "your_password" --authenticationDatabase admin

```

All client connections, including application drivers, must provide these credentials. The keyfile itself is used only for internal server-to-server authentication and should never be used for client connections or exposed to application layers.