导出要用于 Java、Python 和 Node.js 应用的 Azure Cosmos DB 模拟器证书Export the Azure Cosmos DB Emulator certificates for use with Java, Python, and Node.js apps

适用于: SQL API Cassandra API Gremlin API 表 API Azure Cosmos DB API for MongoDB

为方便进行开发,Azure Cosmos DB 模拟器提供了一个模拟 Azure Cosmos DB 服务的本地环境。The Azure Cosmos DB emulator provides a local environment that emulates the Azure Cosmos DB service for development purposes. Azure Cosmos 模拟器仅支持通过 TLS 连接进行安全通信。Azure Cosmos emulator supports only secure communication through TLS connections.

首次运行 Azure Cosmos DB 本地模拟器时,会在该模拟器中生成证书。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. 要导出的证书是友好名称为“DocumentDBEmulatorCertificate”的连接证书。The certificate you want to export is the connection certificate with the friendly name "DocumentDBEmulatorCertificate".

当你使用模拟器以各种语言(例如 Java、Python 或 Node.js)开发应用时,你需要导出模拟器证书,并将其导入到所需的证书存储中。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.

当应用程序在 Windows OS 主机上运行时,.NET 语言和运行时使用 Windows 证书存储来安全地连接到 Azure Cosmos DB 本地模拟器。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. 例如,Java 使用其自己的证书存储,Python 使用套接字包装器,Node.js 使用 tlsSocketFor example, Java uses its own certificate store, Python uses socket wrappers, and Node.js uses tlsSocket.

本文演示了如何导出 TLS/SSL 证书,此类证书用于未集成 Windows 证书存储的各种语言和运行时环境。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. 可以在使用 Azure Cosmos DB 模拟器进行开发和测试中了解有关模拟器的更多信息。You can read more about the emulator in Use the Azure Cosmos DB Emulator for development and testing.

导出 Azure Cosmos DB TLS/SSL 证书Export the Azure Cosmos DB TLS/SSL certificate

你需要导出模拟器证书,才能成功地通过未集成 Windows 证书存储的语言和运行时环境使用模拟器终结点。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. 你可以使用 Windows 证书管理器导出证书。You can export the certificate using the Windows Certificate Manager. 使用以下分步说明,将“DocumentDBEmulatorCertificate”证书导出为 BASE-64 编码的 X.509 (.cer) 文件:Use the following step-by-step instructions to export the "DocumentDBEmulatorCertificate" certificate as a BASE-64 encoded X.509 (.cer) file:

  1. 通过运行 certlm.msc 启动 Windows 证书管理器并导航到“个人”->“证书”文件夹,打开友好名称为“DocumentDbEmulatorCertificate”的证书。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 本地模拟器导出步骤 1

  2. 单击“详细信息”,并单击“确定”。Click on Details then OK.

    Azure Cosmos DB 本地模拟器导出步骤 2

  3. 单击“复制到文件...” 。Click Copy to File....

    Azure Cosmos DB 本地模拟器导出步骤 3

  4. 单击“下一步”。Click Next.

    Azure Cosmos DB 本地模拟器导出步骤 4

  5. 单击“否,不导出私钥”,并单击“下一步”。Click No, do not export private key, then click Next.

    Azure Cosmos DB 本地模拟器导出步骤 5

  6. 单击“Base-64 编码 X.509 (.CER)”,并单击“下一步”。Click on Base-64 encoded X.509 (.CER) and then Next.

    Azure Cosmos DB 本地模拟器导出步骤 6

  7. 为证书指定名称。Give the certificate a name. 在本示例中为“documentdbemulatorcert”。单击“下一步”。In this case documentdbemulatorcert and then click Next.

    Azure Cosmos DB 本地模拟器导出步骤 7

  8. 单击“完成” 。Click Finish.

    Azure Cosmos DB 本地模拟器导出步骤 8

将证书用于 Java 应用Use the certificate with Java apps

运行使用基于 Java 的客户端的 Java 应用程序或 MongoDB 应用程序时,将证书安装到 Java 默认证书存储比传递 -Djavax.net.ssl.trustStore=<keystore> -Djavax.net.ssl.trustStorePassword="<password>" 标志更简单。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. 例如,包含的 Java 演示应用程序 (https://localhost:8081/_explorer/index.html) 依赖于默认证书存储。For example, the included Java Demo application (https://localhost:8081/_explorer/index.html) depends on the default certificate store.

请按照将证书添加到 Java 证书存储中的说明将 X.509 证书导入到默认 Java 证书存储。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. 请注意,运行 keytool 时会在 %JAVA_HOME% 目录中执行操作。Keep in mind you will be working in the %JAVA_HOME% directory when running keytool. 证书导入证书存储后,SQL 和 Azure Cosmos DB API for MongoDB 的客户端就能连接到 Azure Cosmos 模拟器。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 Emulator.

也可运行以下 bash 脚本来导入证书: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

安装“CosmosDBEmulatorCertificate”TLS/SSL 证书后,应用程序应该能够连接并使用本地 Azure Cosmos DB 模拟器。Once the "CosmosDBEmulatorCertificate" TLS/SSL certificate is installed, your application should be able to connect and use the local Azure Cosmos DB Emulator. 如果有任何问题,可以按照调试 SSL/TLS 连接一文进行操作。If you have any issues, you can follow the Debugging SSL/TLS connections article. 在大多数情况下,证书可能未安装到 %JAVA_HOME%/jre/lib/security/cacerts 存储中。In most cases, the certificate may not be installed into the %JAVA_HOME%/jre/lib/security/cacerts store. 例如,如果已安装多个 Java 版本,则应用程序使用的 cacerts 存储可能与你更新的存储不同。For example, if you have multiple installed versions of Java your application may be using a different cacerts store than the one you updated.

将证书用于 Python 应用Use the certificate with Python apps

从 Python 应用连接到模拟器时,会禁用 TLS 验证。When connecting to the emulator from Python apps, TLS verification is disabled. 默认情况下,用于 SQL API 的 Python SDK(2.0.0 或更高版本)在连接到本地模拟器时不会尝试使用 TLS/SSL 证书。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. 但是,如果要使用 TLS 验证,则可以按照 Python 套接字包装器文档中的示例进行操作。If however you want to use TLS validation, you can follow the examples in the Python socket wrappers documentation.

如何在 Node.js 中使用证书How to use the certificate in Node.js

从 Node.js SDK 连接到模拟器时,会禁用 TLS 验证。When connecting to the emulator from Node.js SDKs, TLS verification is disabled. 默认情况下,用于 SQL API 的 Node.js SDK(1.10.1 或更高版本)在连接到本地模拟器时不会尝试使用 TLS/SSL 证书。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. 但是,如果要使用 TLS 验证,则可以按照 Node.js 文档中的示例进行操作。If however you want to use TLS validation, you can follow the examples in the Node.js documentation.

轮换模拟器证书Rotate emulator certificates

可以通过在 Azure Cosmos DB 模拟器(在 Windows 任务栏中运行)中选择“重置数据”,强制重新生成模拟器证书。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 本地模拟器重置数据

如果已将证书安装到 Java 证书存储中或在其他位置使用它们,则需要使用当前证书重新导入它们。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