Securely access Amazon DocumentDB (with MongoDB compatibility) locally using AWS Client VPN

Amazon DocumentDB (with MongoDB compatibility) is a scalable, highly durable, and fully managed database service for operating mission-critical MongoDB workloads. When interfacing with a document database such as Amazon DocumentDB, developers need an environment to test and debug their applications. In this post, we cover how to connect to your Amazon DocumentDB resources from outside the cluster’s VPC by utilizing AWS Certificate Manager (ACM) and AWS Client VPN.

Amazon DocumentDB clusters are deployed within a VPC. The following are options you have for connecting to Amazon DocumentDB resources from your local machine:

• AWS Direct Connect – This allows you to create virtual interfaces directly to the Amazon DocumentDB VPC
• VPN connection – You can establish a connection to an AWS-managed virtual private gateway, which is the VPN device on the AWS side of the VPN connection
• SSH tunneling – If you need to access your Amazon DocumentDB resources from outside the cluster’s VPC, you can use this method (also known as port forwarding)

For developers that are starting their cloud journey, utilizing their local development machine with all its libraries, tools, and custom configurations is the preferred way to connect with AWS services. This allows developers that have custom scripts, resources, and tools kept locally on their machine to call on those scripts without uploading to another environment.

In this post, we create an architecture similar to the following diagram that allows you to connect your local machine to Amazon DocumentDB.

Prerequisites

The following is required to run this solution:

• OpenVPN EasyRSA
• VPN client (for this demo, we use OpenVPN Connect)

For this post, you use EasyRSA to create your own certificate authority (CA) locally before exporting to ACM to manage your self-generated keys and certificates. The VPN Client is used to securely connect your local machine to your Amazon DocumentDB resources.

The steps we follow in this post and the architecture deployed via the AWS CloudFormation template are meant for testing purposes only. You can use your own CA for creating certificates if available. AWS takes cloud security seriously, and any deployment to your account should incorporate security reviews and controls appropriate with the environment and data being used. Note that it’s best practice to incorporate appropriate logging and detection capability for any VPN connection to your AWS resources. You can contact your security team for guidance and for more information, refer to Security best practices for AWS Client VPN.

You should also have the following prerequisites:

• A VPC with at least one public and one private subnet. This architecture allows you to have a private subnet routing to a NAT gateway and a public subnet routing to an internet gateway.
• An Amazon DocumentDB cluster. If you don’t have an Amazon DocumentDB cluster set up, refer to Create an Amazon DocumentDB cluster.
• An Amazon Simple Storage Service (Amazon S3) bucket.

If you associate more than one subnet with a Client VPN endpoint, each subnet must be in a different Availability Zone. Your public subnet and private subnets must also be in different Availability Zones.

Provision resources with AWS CloudFormation

You can download a CloudFormation template from GitHub that deploys much of this solution for you:

• The Client VPN endpoint that you use to connect to the Amazon DocumentDB cluster residing in a private subnet in your VPC from your on-premises workstation.
• The necessary resources to make this client VPN work. It creates the security group, client VPN routes, subnet associations, and authorization rule.
• A custom resource with an AWS Lambda function, which gives you the OVPN configuration file in an S3 bucket that’s downloadable and ready to use as soon as the CloudFormation stack launches successfully.

To use this template, you first complete the following section to generate the server and client certificates. Refer to the readme from the GitHub repo to see a complete walkthrough of how to launch this CloudFormation stack.

Generate the server and client certificates

The Client VPN endpoint in this post uses mutual authentication. With mutual authentication, Client VPN uses certificates to perform authentication between clients and the Client VPN endpoint. You need to have a server certificate and key, and at least one client certificate and key. You use EasyRSA to create a new CA, generate a server and client certificate and key, and then import the latter into ACM.

You download and install the OpenVPN software and EasyRSA CLI utility to create a root CA, and request and sign your certificates. For this walkthrough, we use the Windows version for both OpenVPN and EasyRSA.

1. Visit the OpenVPN Community Downloads page, download the installer for your operating system, and run the installer.
2. Visit the EasyRSA releases page and download the appropriate asset for your operating system.
3. Extract the ZIP file and copy the EasyRSA folder to the \Program Files\OpenVPN folder.
4. Open the command prompt as an administrator, navigate to the \Program Files\OpenVPN\EasyRSA directory, and run the following command to open the EasyRSA 3 shell:

   C:\Program Files\OpenVPN\EasyRSA>EasyRSA-Start

   You should see output similar to the following, confirming you’re in the EasyRSA shell:

   EasyRSA Shell
   #

5. Initialize a new public key infrastructure (PKI) environment with the following code:

   EasyRSA Shell
   # ./easyrsa init-pki

   You should see an output similar to the following:

   ...
   ...
   init-pki complete; you may now create a CA or requests.
   Your newly created PKI dir is: C:/Program Files/OpenVPN2/EasyRSA/pki

6. To build a new CA, run the following command and follow the prompts. When prompted, provide a common name.

   EasyRSA Shell
   # ./easyrsa build-ca nopass
   

   You should see an output similar to the following:

   Using SSL: openssl OpenSSL 1.1.0j  20 Nov 2018
   ...
   ...
   Common Name (eg: your user, host, or server name) [Easy-RSA CA]:user
   
   CA creation complete and you may now import and sign cert requests.
   Your new CA certificate file for publishing is at:
   C:/Program Files/OpenVPN2/EasyRSA/pki/ca.crt

7. Generate the server certificate and key:

   EasyRSA Shell
   # ./easyrsa build-server-full server nopass

   You should see an output similar to the following:

   Using SSL: openssl OpenSSL 1.1.0j  20 Nov 2018
   ...
   ...
   Write out database with 1 new entries
   Data Base Updated

8. Generate the client certificate and key:

   EasyRSA Shell
   # ./easyrsa build-client-full client1.domain.tld nopass

   You should see an output similar to the following:

   Using SSL: openssl OpenSSL 1.1.0j  20 Nov 2018
   ...
   ...
   Write out database with 1 new entries
   Data Base Updated

9. You can now exit the EasyRSA 3 shell:

   EasyRSA Shell
   # exit

10. Create a new folder. Copy the new CA, server certificate and key, and client certificate and key to a custom folder and navigate to the new folder. You can run the following commands to do this from the command prompt:

    copy "C:\Program Files\OpenVPN\EasyRSA\pki\ca.crt" C:\custom_folder
    copy "C:\Program Files\OpenVPN\EasyRSA\pki\issued\server.crt" C:\custom_folder
    copy "C:\Program Files\OpenVPN\EasyRSA\pki\issued\client1.domain.tld.crt" C:\custom_folder
    copy "C:\Program Files\OpenVPN\EasyRSA\pki\private\server.key" C:\custom_folder
    copy "C:\Program Files\OpenVPN\EasyRSA\pki\private\client1.domain.tld.key” C:\custom_folder

11. Upload the server certificate and key to ACM. Be sure to upload them in the same Region in which you intend to create the Client VPN endpoint. The following commands use the AWS Command Line Interface (AWS CLI) to upload the certificates:

    aws acm import-certificate --certificate fileb://server.crt --private-key fileb://server.key --certificate-chain fileb://ca.crt

Confirm that you have configured the AWS CLI through aws configure with appropriate permissions to perform these actions. To upload the certificates using the ACM console instead, see Importing a certificate.

Create the Client VPN endpoint manually

This section is provided if you wanted to complete the steps of creating the Client VPN endpoint manually. If you’re using the CloudFormation template that we provide, you can skip this section and continue at section Connect to your VPN Client .

With your new private certificate and key, you create a Client VPN endpoint to connect your local machine to the VPC that Amazon DocumentDB resides within.

1. On the Amazon VPC console, choose Client VPN Endpoints under Virtual private network (VPN) in the navigation pane.
2. Choose Create client VPN endpoint.
3. Provide a unique name tag, such as DocDB-ClientVPN, and a brief description.
4. For Client IPv4 CIDR, choose an IP address for your VPN clients that doesn’t overlap with the resources you want to access via the Client VPN endpoint.
   For this example, we use a /22 address space, which is the smallest subnet that can be used. You can specify a larger subnet if required (up to /18). Note that Client VPN uses source NAT (SNAT) to connect to resources in the associated VPCs.
5. Under Authentication information, choose the private certificate you imported earlier for the Server certificate ARN.
6. Select Use mutual authentication for Authentication options.
7. Choose your private certificate for Client certificate ARN. If your server and client certificates have been issued by the same CA, you can use the server certificate ARN for both server and client when you create the Client VPN endpoint. For more information about authentication options, refer to Client authentication.For this example, you can leave Enable log details on client connections under Connection logging to No. However, if you want to enable logging, you can set up an Amazon CloudWatch log group for this purpose. With connection logging, you can get forensics on which clients attempted to connect and the result of the connection attempt.
8. Leave all other option parameters as their default values and choose Create Client VPN Endpoint.
   You receive confirmation that your Client VPN endpoint successfully created with a status of Pending-associate. You now associate your VPN endpoint with a target network (a VPC subnet).
9. On the Client VPN console, choose your Client VPN endpoint ID.
10. On the Target network associations tab, choose Associate target network.
11. Choose the VPC your Amazon DocumentDB cluster resides within and choose one of the private subnets.
12. Choose Associate target network to begin associating a target network (subnet in a VPC).
13. Follow this same process for the public subnet assigned to the Amazon DocumentDB VPC.
    The public subnet can’t be in the same Availability Zone as the private subnet you used in the previous step. After these steps, the state shows as Associating. You now set up authorization to your VPN Client endpoint.
14. On the Client VPN console, choose your Client VPN endpoint ID.
15. On the Authorization rules tab, choose Add authorization rule.
16. Set Destination network to enable access to 0.0.0.0/0 to enable traffic to flow through the client VPN endpoint, including internet traffic (through a NAT gateway running in your VPC).
17. Select Allow access to all users and choose Add authorization rule.
    To allow your VPC association to provide internet connectivity to VPN clients (though a NAT gateway already running in your VPC), you need to add a default route of 0.0.0.0/0 to the route table.
18. On the Client VPN console, choose your Client VPN endpoint ID.
19. On the Route table tab, choose Create route.
20. Enter a Route destination of 0.0.0.0/0 and choose the public subnet.
21. Choose Create route.
    After a few minutes, the state of your Client VPN endpoint changes to Active.
22. Select your Client VPN endpoint and choose Download client configuration.
23. Choose Download client configuration again to get a configuration file that can be imported into your OpenVPN client software.
24. Return to the Client VPN endpoint page and choose your Client VPN endpoint ID.
25. On the Security groups tab, choose the link to your security group under the Security groups column.
26. On the Inbound rules tab, choose Edit inbound rules.
27. Choose Add rule to create a new inbound rule allowing access from your local machine’s public IP address.
28. Set Type to All traffic.
29. Set Source to Custom and enter your public IP address followed by /32.
    You can choose Delete to remove any additional rules listed.
30. Choose Save rules to save the changes.

VPN Client configuration file

You modify your configuration file (OVPN) before you can use it with the OpenVPN client.

1. Locate the client certificate and private key on your local machine that you created earlier and open them with your preferred text editor

   C:\custom_folder\client1.domain.tld.crt
   C:\custom_folder\client1.domain.tld.key

2. In another text editor window, open your configuration file.
3. Within your certificate file, scroll down to the section that looks similar to the following code. This section begins and ends with random characters inserted between BEGIN CERTIFICATE and END CERTIFICATE.

   -----BEGIN CERTIFICATE-----
   T14SFEw0a1…
   -----END CERTIFICATE----- 

   Your private key file begins and ends similar to the following code, with random characters inserted between them:

   -----BEGIN ENCRYPTED PRIVATE KEY-----
   T14IE0ew91…
   -----END ENCRYPTED PRIVATE KEY-----

4. Within your configuration file, locate the section near the bottom that holds your CA details (it begins and ends with <ca>…</ca>).
5. Immediately after </ca>, add new lines with the following values:

   <cert>
   
   </cert>
   <key>
   
   </key>

6. Between <cert> and </cert>, enter the section mentioned earlier from your certificate file, including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.
7. Between <key> and </key>, enter the entire contents of your private key file, including -----BEGIN ENCRYPTED PRIVATE KEY----- and -----END ENCRYPTED PRIVATE KEY-----.Your configuration file should look similar to the following.
   The Client VPN endpoint configuration file includes a parameter called remote-random-hostname. This parameter forces the client to prepend a random string to the DNS name to prevent DNS caching. Some clients don’t recognize this parameter and therefore they don’t prepend the required random string to the DNS name.
8. Within the configuration file, locate the line that specifies the Client VPN endpoint DNS name, and prepend a random string to it so that the format is random_string.displayed_DNS_name. For example:
   Original DNS name – cvpn-endpoint-0102bc4c2eEXAMPLE.clientvpn.us-west-2.amazonaws.com
   Modified DNS name – asdfa.cvpn-endpoint-0102bc4c2eEXAMPLE.clientvpn.us-west-2.amazonaws.com

Connect to your VPN Client

We use the configuration file to create a connection from your local machine to your Amazon DocumentDB resources.

Launch OpenVPN Client and navigate to Import Profile. On the File tab, either drag and drop your configuration file or choose BROWSE and navigate to it. This imports the settings and populates the server host name.

Create a unique profile name, then choose CONNECT.

After you’ve successfully connected, you can see connection statistics and details.

Connect to your Amazon DocumentDB resources

With your VPN Client successfully connected, you can connect to your Amazon DocumentDB resources.

1. To retrieve your cluster endpoint, on the Amazon DocumentDB console, choose Clusters in the navigation pane.
2. Find your cluster and choose the Regional cluster identifier.
3. On the Connectivity & security tab, if you haven’t done so already, download the Amazon DocumentDB CA by following the instructions on the console.
4. Copy the command for connecting to your cluster with the mongo shell.
5. Enter the command into your local machine’s shell.
   If you’re using Studio 3T as a GUI to interact with existing NoSQL databases, you can now take advantage of its powerful capabilities to connect with your Amazon DocumentDB resources directly from your local machine. If you don’t have Studio 3T, download and install it.
6. Launch Studio 3T and choose Connect.
7. Choose New Connection.
8. Select Manually configure my connection settings and choose Next.
9. For Connection name, enter a name.
10. On the Server tab, for Server, enter the name of your Amazon DocumentDB cluster endpoint.
    If you can’t locate your cluster endpoint, refer to Finding a Cluster’s Endpoints.
11. On the Authentication tab, for Authentication Mode, choose Legacy (SCRAM-SHA-1).
12. Enter your Amazon DocumentDB cluster user name and credentials in the User name and Password fields.
13. Enter admin for Authentication DB.
14. On the SSL tab, select Use SSL protocol to connect.
15. Select Use own Root CA file (–sslCAFile) and enter the location of the rds-combined-ca-bundle.pem file you downloaded earlier.
16. Choose Test Connection to verify all your inputs are correct.
    After a successful connection, you see a green status of OK for all operations.
17. Save the connection settings, then select your cluster and choose Connect.
    

Clean up

To clean up the resources created in this post, start by removing the target network associations on your Client VPN endpoint.

1. Navigate to your Client VPN endpoint and the Target network associations section.
2. Select your association ID, then choose Disassociate.
3. Follow this step for each of your target network associations.
4. Select your Client VPN endpoint and on the Actions menu, choose Delete client VPN endpoint.
5. Confirm deletion and choose Delete.
6. On the AWS Certificate Manager console, choose List certificates in the navigation pane.
7. Select your certificate ID, then choose Delete.
8. Confirm deletion and choose Delete again.

If you deployed resources using the CloudFormation template from GitHub, you can select the CloudFormation stack created and choose Delete. Then on the prompt, select “Delete Stack” to proceed with the deletion of the CloudFormation stack. CloudFormation cleanup instructions can also be found within the readme on GitHub.

Summary

There are times when developers, engineers, and architects need to utilize their local development machine with all its libraries, tools, and custom configurations to connect with AWS services. In this post, you deployed an AWS Client VPN endpoint and connected to your Amazon DocumentDB resources using the OpenVPN based client. Connecting this way gives you the ability to continue using local scripts and resources without transferring them to cloud-based IDEs or compute instances.

To learn more about developing with Amazon DocumentDB, refer to Connecting Programmatically to Amazon DocumentDB.

About the Authors

Cody Allen is a Senior DocumentDB Specialist Solutions Architect based out of Texas. He is passionate about working side by side with customers to solve complex problems, and supporting teammates through mentorship and knowledge transfer. He has spent his career deploying and managing systems, softwares, and infrastructure for B2B SaaS providers, materiel and logistics suppliers, the U.S Air Force, and other government agencies domestic and international.

Ramesh Venkataraman is a Senior Solutions Architect who enjoys working with customers to solve their technical challenges using AWS services. Outside of work, Ramesh enjoys following stack overflow questions and answers them in any way he can.