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
note
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 MDE4BQFZNh9T0BhTXkvc2zJdx5bLLLT-
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
note
This requires that an AWS IAM integration has been configured and access rules have been configured for the repository you wish to access.
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
note
SSO authentication requires that an IdP integration has been configured and access rules have been configured for the repository you wish to access.
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
note
This requires that an AWS IAM integration has been configured and access rules have been configured for the repository you wish to access.
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).