Configure the MongoDB Agent for X.509 Authentication
On this page
- OAuth 2.0 authentication for programmatic access to Cloud Manager is available as a Preview feature.
- The feature and the corresponding documentation might change at any time during the Preview period. To use OAuth 2.0 authentication, create a service account to use in your requests to the Cloud Manager Public API.
Cloud Manager enables you to configure the Authentication Mechanisms that all clients, including the Cloud Manager Agents, use to connect to your MongoDB deployments. You can enable multiple authentication mechanisms for each of your projects, but you must choose only one mechanism for the Agents.
MongoDB supports X.509 certificate authentication for use with a secure TLS connection. X.509 client authentication allows clients to authenticate to servers with certificates rather than with a username and password.
Note
With Automation, Cloud Manager manages MongoDB Agent authentication for you. To learn more about authentication, see Enable x.509 Authentication for your Cloud Manager Project.
Considerations
A full description of Transport Layer Security, public key infrastructure, X.509 certificates, and Certificate Authorities exceeds the scope of this tutorial. This tutorial assumes prior knowledge of TLS and access to valid X.509 certificates.
Prerequisites
To enable X.509 Authentication for Cloud Manager, you must obtain valid TLS certificates that a single certificate authority (CA) generated and signed. To learn more about the certificate requirements, see Client x.509 Certificate in the MongoDB Manual.
X.509 Client Certificate Authentication requires you to enable and configure TLS for the deployment.
Procedures
This tutorial assumes that you have already configured your MongoDB deployment to use X.509 certificate authentication and TLS. If you have not done so, refer to the Use X.509 Certificates to Authenticate Clients and Configure mongod and mongos for TLS tutorials.
Create MongoDB User from the X.509 subject
When Automation is activated, Cloud Manager manages MongoDB Agent authentication.
To configure X.509 for MongoDB Agent authentication, see Enable x.509 Client Certificate Authentication for your Cloud Manager Project.
For the MongoDB Agent to connect to your MongoDB deployment, you must create a MongoDB user on your deployment that corresponds to the subject
value of your client certificate.
Where you create the MongoDB user depends upon whether or not you are using LDAP authorization.
Note
Starting with MongoDB 8.0, LDAP authentication and authorization is deprecated. The feature is available and will continue to operate without changes throughout the lifetime of MongoDB 8. LDAP will be removed in a future major release.
For details, see LDAP Deprecation.
If you are using LDAP authorization in your MongoDB deployment,
you must create an LDAP user and LDAP group for the
MongoDB Agent on the LDAP server. After creating the LDAP user
and group, map the LDAP group to a MongoDB role in your
deployment's admin
database.
Warning
When using LDAP Authorization, do not create any MongoDB
users in the $external
database. MongoDB 3.4 and later
does not start if a MongoDB user exists in the $external
database and LDAP authorization is enabled.
For the MongoDB user representing the MongoDB Agent:
Create a new LDAP user on your LDAP server named that uses the
subject
value of your client certificate as the username.Create an LDAP group whose name matches the MongoDB Agent's role.
Create the MongoDB Agent's role in your
admin
database with the appropriate permissions.Note
When Automation is activated, Automation automatically creates a role for for the MongoDB Agent user for LDAP authentication.
Assign the LDAP user to the LDAP group.
Tip
See also:
To learn how to: | See |
---|---|
Create an LDAP user | Documentation for your LDAP implementation. |
Create an LDAP group | Documentation for your LDAP implementation. |
Assign the appropriate roles for the MongoDB Agent | |
Map an LDAP group and MongoDB role | LDAP Roles section of the
LDAP authorization page in the MongoDB
manual. |
Configure LDAP authorization without Cloud Manager automation | LDAP Authorization page in the MongoDB
manual. |
If you are not using LDAP authorization, you must add the subject
value of your client certificate as the username
of the MongoDB Agent in the $external
database of your
MongoDB deployment. Without LDAP authorization, MongoDB uses
the $external
database to authenticate a user against
X.509.
Note
To discover the appropriate roles for the MongoDB Agent, see Required Access for MongoDB Agent.
Use the following commands to create the users from mongosh
:
db.getSiblingDB("$external").createUser( { user : "<x.509 subject>", roles : [ { role : "clusterAdmin", db : "admin" }, { role : "readWriteAnyDatabase", db : "admin" }, { role : "userAdminAnyDatabase", db : "admin" }, { role : "dbAdminAnyDatabase", db : "admin" }, { role : "backup", db : "admin" }, { role : "restore", db : "admin" } ] } )
To learn what access is required, see Required Access for MongoDB Agent.
Each MongoDB user must have its own X.509 certificate.
Edit MongoDB Agent Configuration File
To use X.509 authentication, you must configure the MongoDB Agent for TLS:
Specify the absolute file path to your trusted CA certificate in the MongoDB Agent config file.
If you enabled TLS for your Cloud Manager deployment, then you must configure the MongoDB Agent to use TLS. To configure the MongoDB Agent to use TLS, you must have the trusted Certificate Authority certificate that signed the MongoDB instance's certificate.
In the MongoDB Agent's install directory, edit the configuration
file to set httpsCAFile
field to the
path of a file containing one or more certificates in PEM format.
The location of the MongoDB Agent configuration file is
C:\MMSData\Automation\automation-agent.config
.
Note
The MongoDB Agent configuration file is named
automation-agent.config
as a way to enable easier upgrades
for those using legacy agents.
The location of the MongoDB Agent configuration file is
/etc/mongodb-mms/automation-agent.config
.
Note
The MongoDB Agent configuration file is named
automation-agent.config
as a way to enable easier upgrades
for those using legacy agents.
The location of the MongoDB Agent configuration file is
/etc/mongodb-mms/automation-agent.config
.
Note
The MongoDB Agent configuration file is named
automation-agent.config
as a way to enable easier upgrades
for those using legacy agents.
The location of the MongoDB Agent configuration file is
/path/to/install/local.config
.
Example
Use the following command to connect through mongosh
:
mongosh --tls --tlsCAFile /etc/ssl/ca.pem example.net:27017
Then, modify the configuration file and set the following key/value pair:
httpsCAFile=/etc/ssl/ca.pem
Save the configuration file.
To learn more about these settings, see Cloud Manager TLS Settings.
Configure MongoDB Agent to Use TLS provides more details about configuring the MongoDB Agent for TLS.
After you configure the MongoDB Agent, configure the X.509 Authentication mechanism in the Cloud Manager interface, as described in Enable x.509 Authentication for your Cloud Manager Project.