authentication-and-authorization

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!-- Tab options on this page. Append to the .md URL to filter: ?tabs=<id,...> select specific tabs (e.g. ?tabs=nodejs,shell) ?allTabs=true include every tab (no param) default: one tab per tabset

Available tabs: other tabs: scram, x509 -->

Configure Authentication and Authorization for mongot

Use this page to configure authentication and authorization for your mongot and MongoDB Community Edition deployments. For information on using mongot with MongoDB Controllers for Kubernetes Operator, see [MongoDB Search and Vector Search with Kubernetes.](https://www.mongodb.com/docs/kubernetes/current/fts-vs-deployment.md#std-label-k8s-deploy-search-resources

mongot communicates over two distinct channels, each of which requires its own security configuration:

  • Sync source (syncSource.replicaSet, syncSource.router): mongot's outbound connection to your MongoDB deployment for replication. You configure an authentication mechanism here so that mongot can authenticate to mongod or mongos.

  • gRPC server (server.grpc): The inbound channel over which mongod connects to mongot for search queries and index management commands. mongod and mongot authenticate to each other through mTLS.

Note:

The health check (healthCheck) and metrics (metrics) endpoints don't support TLS or authentication. Restrict access to these ports at the network layer.

Considerations

Before you configure authentication, review the following points:

  • You must configure exactly one authentication mechanism for the sync source: either SCRAM or X.509. The two mechanisms are mutually exclusive for each connection block.

  • For sharded clusters, you must specify both syncSource.replicaSet and syncSource.router in your mongot configuration file, and configure authentication on each connection independently. syncSource.router is not implied by syncSource.replicaSet, so you must configure it explicitly. Each shard requires its own dedicated mongot instance.

  • syncSource.replicaSet maps the mongot instance to its shard's replica set.

  • syncSource.router provides the mongos connection for cluster-wide coordination.

  • The searchCoordinator built-in role must exist on your MongoDB deployment before mongot can authenticate. This role is available in MongoDB 8.2 and later.

Before You Begin

Add the following setParameter options to your mongod configuration file, then restart mongod:

setParameter:
   mongotHost: <host>:<port>
   searchIndexManagementHostAndPort: <host>:<port>
   skipAuthenticationToSearchIndexManagementServer: false
   useGrpcForSearch: true

The setParameter option sets server parameters that tell the mongod server how to locate and communicate with mongot. You must set these parameters before mongot can connect to your deployment.

To learn more about the mongod configuration file, see [Self-Managed Configuration File Options.](https://www.mongodb.com/docs/manual/reference/configuration-options.md#std-label-configuration-options

Configure Sync Source Authentication

Configure one of the following authentication mechanisms on the sync source connection so that mongot can authenticate to your MongoDB deployment.

SCRAM

SCRAM (Salted Challenge Response Authentication Mechanism) authenticates mongot to your MongoDB deployment with a username and password.

To configure SCRAM for mongot, complete the following steps:

  1. Create the mongot user in the admin database.

Create the user on your MongoDB replica set with the searchCoordinator role.

Run the following command in [mongosh:](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh

javascript use admin db.createUser({ user: "mongotUser", pwd: "<password>", roles: [ { role: "searchCoordinator", db: "admin" } ] })

  1. Create a password file on the mongot host.

Replace <password> with your password, then run the command for your operating system to create the password file. The file must not contain a trailing newline.

For Linux or macOS:

bash echo -n "<password>" > /etc/mongot/secrets/passwordFile chmod 400 /etc/mongot/secrets/passwordFile

For Windows Command Prompt:

bat echo|set /p="<password>" > passwordFile

For Windows PowerShell:

```powershell

```

  1. Add the scramAuth block to your mongot configuration.

Add the scramAuth block under syncSource.replicaSet. For sharded clusters, also add the same block under syncSource.router. List multiple hosts in hostAndPort so mongot can still discover the replica set if one host is unavailable:

yaml syncSource: replicaSet: hostAndPort: - "<host1>:27017" - "<host2>:27017" scramAuth: username: mongotUser authSource: admin passwordFile: /etc/mongot/secrets/passwordFile tls: enabled: false

For sharded clusters, configure scramAuth under both syncSource.replicaSet and syncSource.router. syncSource.replicaSet authenticates mongot to the shard's replica set, and syncSource.router authenticates mongot to mongos for cluster-wide coordination. You can use the same credentials for both connections, or separate credentials if you administer them independently:

yaml syncSource: replicaSet: hostAndPort: - "<shard-host1>:27017" - "<shard-host2>:27017" scramAuth: username: mongotShardUser authSource: admin passwordFile: /etc/mongot/secrets/shard-passwordFile tls: enabled: false router: hostAndPort: - "<mongos1>:27017" - "<mongos2>:27017" scramAuth: username: mongotRouterUser authSource: admin passwordFile: /etc/mongot/secrets/router-passwordFile tls: enabled: false

For more information on the mongot configuration file, see [Configure mongot.](https://www.mongodb.com/docs/search/self-managed/current/configuration/reference.md#std-label-mongot-config-settings

  1. Enable TLS for the sync source connection if needed.

If your MongoDB deployment has TLS enabled, set tls.enabled to true and provide the following fields to your mongot configuration file as needed:

Field Description
caFile The PEM file that contains one or more X.509 CA certificates that verify mongod's server certificate. If you omit this field, mongot uses the JVM default trust store.
tlsCertificateKeyFile The PEM file that contains both the client's X.509 certificate and its private key. Required only if mongod verifies client certificates.
tlsCertificateKeyFilePasswordFile The password that decrypts the client certificate key. Required only if tlsCertificateKeyFile is password-protected.

Configure gRPC Server Transport Security

The gRPC server is the inbound channel over which mongod connects to mongot for search queries and index management commands. You secure this channel at the transport layer with TLS. To mutually authenticate mongod and mongot, use mTLS.

You configure the TLS mode with the server.grpc.tls.mode option on mongot and the searchTLSMode.

You can configure one of the following TLS modes in the mongot configuration file:

Disabled

No TLS. Use this mode only for deployments where mongod and mongot run on the same host:

server:
   grpc:
      address: "localhost:27028"
      tls:
         mode: "disabled"

TLS

mongot presents a server certificate, and mongod verifies it before establishing the connection. This mode requires certificateKeyFile:

server:
   grpc:
      address: "0.0.0.0:27028"
      tls:
         mode: "tls"
         certificateKeyFile: /etc/mongot/tls/mongot-server.pem
         # certificateKeyFilePasswordFile: /etc/mongot/secrets/server-key-password

Mutual TLS (mTLS)

Both mongot and mongod present and verify each other's certificates. This mode requires certificateKeyFile and caFile. When you use mtls, you must also configure mongod with the corresponding TLS settings for its connection to mongot:

server:
   grpc:
      address: "0.0.0.0:27028"
      tls:
         mode: "mtls"
         certificateKeyFile: /etc/mongot/tls/mongot-server.pem
         caFile: /etc/mongot/tls/ca.pem

Learn More

  • [Configure mongot](https://www.mongodb.com/docs/search/self-managed/current/configuration/reference.md#std-label-mongot-config-settings

  • [Known Limitations for Self-managed mongot](https://www.mongodb.com/docs/search/self-managed/current/limitations.md#std-label-mongot-limitations

  • [Monitor mongot Deployment](https://www.mongodb.com/docs/search/self-managed/current/deployment/monitoring.md#std-label-mongot-monitoring