Export the Azure Cosmos DB Emulator certificates for use with Java, Python, and Node.js apps

APPLIES TO: SQL API Cassandra API Gremlin API Table API Azure Cosmos DB API for MongoDB

The Azure Cosmos DB Emulator provides a local environment that emulates the Azure Cosmos DB service for development purposes. Azure Cosmos Emulator supports only secure communication through TLS connections.

Certificates in the Azure Cosmos DB local emulator are generated the first time you run the emulator. There are two certificates. One of them is used to connect to the local emulator and the other is used to manage default encryption of the emulator data within the emulator. The certificate you want to export is the connection certificate with the friendly name "DocumentDBEmulatorCertificate".

When you use the emulator to develop apps in different languages such as Java, Python, or Node.js, you need to export the emulator certificate and import it into the required certificate store.

The .NET language and runtime uses the Windows Certificate Store to securely connect to the Azure Cosmos DB local emulator when the application is run on a Windows OS host. Other languages have their own method of managing and using certificates. For example, Java uses its own certificate store, Python uses socket wrappers, and Node.js uses tlsSocket.

This article demonstrates how to export the TLS/SSL certificates for use in different languages and runtime environments that do not integrate with the Windows Certificate Store. You can read more about the emulator in Use the Azure Cosmos DB Emulator for development and testing.

Export the Azure Cosmos DB TLS/SSL certificate

You need to export the emulator certificate to successfully use the emulator endpoint from languages and runtime environments that do not integrate with the Windows Certificate Store. You can export the certificate using the Windows Certificate Manager. Use the following step-by-step instructions to export the "DocumentDBEmulatorCertificate" certificate as a BASE-64 encoded X.509 (.cer) file:

  1. Start the Windows Certificate manager by running certlm.msc and navigate to the Personal->Certificates folder and open the certificate with the friendly name DocumentDbEmulatorCertificate.

    Azure Cosmos DB local emulator export step 1

  2. Click on Details then OK.

    Azure Cosmos DB local emulator export step 2

  3. Click Copy to File....

    Azure Cosmos DB local emulator export step 3

  4. Click Next.

    Azure Cosmos DB local emulator export step 4

  5. Click No, do not export private key, then click Next.

    Azure Cosmos DB local emulator export step 5

  6. Click on Base-64 encoded X.509 (.CER) and then Next.

    Azure Cosmos DB local emulator export step 6

  7. Give the certificate a name. In this case documentdbemulatorcert and then click Next.

    Azure Cosmos DB local emulator export step 7

  8. Click Finish.

    Azure Cosmos DB local emulator export step 8

Use the certificate with Java apps

When running Java applications or MongoDB applications that uses a Java based client, it is easier to install the certificate into the Java default certificate store than passing the -Djavax.net.ssl.trustStore=<keystore> -Djavax.net.ssl.trustStorePassword="<password>" flags. For example, the included Java Demo application (https://localhost:8081/_explorer/index.html) depends on the default certificate store.

Follow the instructions in the Adding a Certificate to the Java Certificates Store to import the X.509 certificate into the default Java certificate store. Keep in mind you will be working in the %JAVA_HOME% directory when running keytool. After the certificate is imported into the certificate store, clients for SQL and Azure Cosmos DB's API for MongoDB will be able to connect to the Azure Cosmos DB Emulator.

Alternatively you can run the following bash script to import the certificate:

#!/bin/bash

# If emulator was started with /AllowNetworkAccess, replace the below with the actual IP address of it:
EMULATOR_HOST=localhost
EMULATOR_PORT=8081
EMULATOR_CERT_PATH=/tmp/cosmos_emulator.cert
openssl s_client -connect ${EMULATOR_HOST}:${EMULATOR_PORT} </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > $EMULATOR_CERT_PATH
# delete the cert if already exists
sudo $JAVA_HOME/bin/keytool -cacerts -delete -alias cosmos_emulator
# import the cert
sudo $JAVA_HOME/bin/keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH

Once the "CosmosDBEmulatorCertificate" TLS/SSL certificate is installed, your application should be able to connect and use the local Azure Cosmos DB Emulator. If you have any issues, you can follow the Debugging SSL/TLS connections article. In most cases, the certificate may not be installed into the %JAVA_HOME%/jre/lib/security/cacerts store. For example, if you have multiple installed versions of Java your application may be using a different cacerts store than the one you updated.

Use the certificate with Python apps

When connecting to the emulator from Python apps, TLS verification is disabled. By default the Python SDK(version 2.0.0 or higher) for the SQL API will not try to use the TLS/SSL certificate when connecting to the local emulator. If however you want to use TLS validation, you can follow the examples in the Python socket wrappers documentation.

How to use the certificate in Node.js

When connecting to the emulator from Node.js SDKs, TLS verification is disabled. By default the Node.js SDK(version 1.10.1 or higher) for the SQL API will not try to use the TLS/SSL certificate when connecting to the local emulator. If however you want to use TLS validation, you can follow the examples in the Node.js documentation.

Rotate emulator certificates

You can force regenerate the emulator certificates by selecting Reset Data from the Azure Cosmos DB Emulator running in the Windows Tray. Note that this action will also wipe out all the data stored locally by the emulator.

Azure Cosmos DB local emulator reset data

If you have installed the certificate into the Java certificate store or used them elsewhere, you need to re-import them using the current certificates. Your application can't connect to the local emulator until you update the certificates.

Next steps