Skip to content

Files

Latest commit

SnehaGundaSnehaGunda
Updating tooling owners
Jul 6, 2021
4c6c01d · Jul 6, 2021

History

History
104 lines (63 loc) · 8.59 KB

local-emulator-export-ssl-certificates.md

File metadata and controls

104 lines (63 loc) · 8.59 KB
title description ms.service ms.topic ms.date ms.author author ms.custom
Export the Azure Cosmos DB Emulator certificates
Learn how to export the Azure Cosmos DB Emulator certificate for use with Java, Python, and Node.js apps. The certificates should be exported and used for languages and runtime environments that don't use the Windows Certificate Store.
cosmos-db
how-to
09/17/2020
esarroyo
StefArroyo
devx-track-python, devx-track-java, contperf-fy21q1

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

[!INCLUDEappliesto-all-apis]

The Azure Cosmos DB Emulator provides a local environment that emulates the Azure Cosmos DB service for development purposes. Azure Cosmos DB 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.

    :::image type="content" source="./media/local-emulator-export-ssl-certificates/database-local-emulator-export-step-1.png" alt-text="Azure Cosmos DB local emulator export step 1":::

  2. Click on Details then OK.

    :::image type="content" source="./media/local-emulator-export-ssl-certificates/database-local-emulator-export-step-2.png" alt-text="Azure Cosmos DB local emulator export step 2":::

  3. Click Copy to File....

    :::image type="content" source="./media/local-emulator-export-ssl-certificates/database-local-emulator-export-step-3.png" alt-text="Azure Cosmos DB local emulator export step 3":::

  4. Click Next.

    :::image type="content" source="./media/local-emulator-export-ssl-certificates/database-local-emulator-export-step-4.png" alt-text="Azure Cosmos DB local emulator export step 4":::

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

    :::image type="content" source="./media/local-emulator-export-ssl-certificates/database-local-emulator-export-step-5.png" alt-text="Azure Cosmos DB local emulator export step 5":::

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

    :::image type="content" source="./media/local-emulator-export-ssl-certificates/database-local-emulator-export-step-6.png" alt-text="Azure Cosmos DB local emulator export step 6":::

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

    :::image type="content" source="./media/local-emulator-export-ssl-certificates/database-local-emulator-export-step-7.png" alt-text="Azure Cosmos DB local emulator export step 7":::

  8. Click Finish.

    :::image type="content" source="./media/local-emulator-export-ssl-certificates/database-local-emulator-export-step-8.png" alt-text="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.

:::image type="content" source="./media/local-emulator-export-ssl-certificates/database-local-emulator-reset-data.png" alt-text="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