Skip to main content
Version: v4.13

Connect to MongoDB

The sections below explain how to connect to MongoDB, via Cyral, using CLI tools (like mongosh) and GUI-based tools like Compass or Studio3T

For both of the above Cyral supports native, SSO based, and AWS-IAM based authentication.

Connect to MongoDB via CLI

The main CLI tool to connect to MongoDB is mongosh.

Native authentication with CLI

Connect using the sidecar's host and port instead of the Mongo server's endpoint:

$ mongosh "mongodb://{YOUR_USER}@{SIDECAR_HOST}:{SIDECAR_PORT}/{OPTIONS}"

Multiple {SIDECAR_HOST} and {SIDECAR_PORT} pairs can be supplied separated by commas.

SSO authentication with CLI

The easiest way to do this is to connect to your Cyral Control Plane and extract the pre-populated connection string from there. Instructions on how to do that can be found here.

If you prefer using the command line directly, you can get an access token using the Cyral CLI. Once you have an access token then you can build your own connection string using the following format:

mongosh "mongodb://{SIDECAR}:{SIDECAR_PORT}/{OPTIONS}" --authenticationDatabase {AUTH_DATABASE_NAME} --username {SSO_USER} --authenticationMechanism PLAIN --password {ACCESS_TOKEN}

Note: if multiple access rules apply to your user, use {SSO_USER}:{DATABASE_ACCOUNT} as the DB user to specify which [database account] you'll use to log in:

mongosh "mongodb://{SIDECAR}:{SIDECAR_PORT}/{OPTIONS}" --authenticationDatabase {AUTH_DATABASE_NAME} --username {SSO_USER}:{DATABASE_ACCOUNT} --authenticationMechanism PLAIN --password {ACCESS_TOKEN}

Example with a DATABASE_ACCOUNT value:

mongo "mongodb://sidecar.example.com:3306/feed_survey" --authenticationDatabase admin --username "bwilliams@barnfeed.com:dataScienceUser" --authenticationMechanism PLAIN --password 9PhbSJJkRJbn2PMX

As it's usual with MongoDB, you can specify multiple sidecar hosts and ports in your connection string by separating them with commas.

AWS IAM authentication with CLI

The first step is to assume an AWS IAM role. Please contact your database administrator to know the ARN of the role to assume. As part of the command to assume a role, you will need to supply your identity (usually the username in your company identity provider or your email address) in the "role session name". Finally, if there are access rules that grant you permission to access more than one database account in the same MongoDB repository, then you will also need to add that to the "role session name". Here is an example of using the AWS CLI to assume the role:

aws sts assume-role --role-arn {ARN} --role-session-name frank.hardy@hhiu.us,engineering

In the above example, frank.hardy@hhiu.us is the user's email address, and the engineering part means that this user wants to connect to the engineering account in the Cyral repository.

Now, the output from the assume-role command will be some credentials which you will use in the connection string:

mongosh "mongodb://{SIDECAR}:{SIDECAR_PORT}/{DATABASE}?authSource=%24external&authMechanism=MONGODB-AWS?[OTHER_OPTIONS]" --username <AWS access key> --password <AWS secret key> --awsIamSessionToken <session token (for AWS IAM Roles)>

Note that exporting the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN as environment variables is also supported: in that case, there's no need to pass them as part of the connection string.

As it's usual with MongoDB, you can specify multiple sidecar hosts and ports in your connection string by separating them with commas.

Connect to MongoDB via GUI

Native and SSO authentication with GUI

In order to connect using native credentials, simply use the connection string from the Native and SSO authentication with CLI section.

For SSO, use the connection string from the SSO authentication with CLI section.

AWS IAM authentication with GUI

GUI-based tools such as Compass or Studio3T have an Authentication tab, typically within an Advanced or similar tab. In order to authenticate to the Cyral sidecar using AWS IAM roles all you have to do is populate the three requested parameters with the appropriate values. These are commonly labeled Access Key ID, Secret Access Key, and Session Token (sometimes prefixed with AWS).