The Dapr secrets building block
Dapr 机密构建块
Enterprise applications require secrets. Common examples include:
- A database connection string that contains a username and password.
- An API key for calling an external web API.
- A client certificate for authenticating to an external system.
企业应用程序要求保密。 常见示例包括：
- 包含用户名和密码的数据库连接字符串。
- 用于调用外部 web API 的 API 密钥。
- 外部系统进行身份验证的客户端证书。
Secrets must be carefully managed so that they‘re never disclosed outside of the application.
必须谨慎管理机密，使其不会在应用程序外公开。
Not long ago, it was popular to store application secrets in a configuration file inside the application codebase. .NET developers will fondly recall the web.config file. While simple to implement, integrating secrets to along with code was far from secure. A common misstep was to include the file when pushing to a public GIT repository, exposing the secrets to the world.
不久前，将应用程序机密存储在应用程序代码库内的配置文件中是很常见的。 .NET 开发人员将想到 web.config 的文件。 虽然实现起来很简单，但将机密与代码集成在一起并不安全。 常见的失误是在推送到公共 GIT 存储库时包括文件，从而向世界公开机密。
A widely accepted methodology for constructing modern distributed applications is The Twelve-Factor App. It describes a set of principles and best practices. Its third factor prescribes that configuration and secrets be externalized outside of the code base.
用于构造新式分布式应用程序的一种广泛接受的方法是十二要素应用。 其中介绍了一系列原则和最佳实践。 第三个因素规定， 配置和机密外部化在基本代码外。
To address this concern, the .NET Core platform includes a Secret Manager feature that stores sensitive data in a physical folder outside of the project tree. While secrets are outside of source control, this feature doesn‘t encrypt data. It‘s designed for development purposes only.
为了解决这一问题，.NET Core 平台包含一个 密钥管理器 功能，该功能将敏感数据存储在项目树之外的物理文件夹中。 虽然机密不受源代码管理，但此功能不会对数据进行加密。 它被设计为仅用于 开发目的 。
A more modern and secure practice is to isolate secrets in a secrets management tool like Hashicorp Vault or Azure Key Vault. These tools enable you to store secrets externally, vary credentials across environments, and reference them from application code. However, each tool has its complexities and learning curve.
更新式、安全的做法是在机密管理工具（Hashicorp Vault or Azure Key Vault）中隔离机密。 这些工具使你能够将机密存储在外部，能跨环境改变凭据，能从应用程序代码中引用它们。 然而，每个工具都有其复杂性和学习曲线。
Dapr offers a building block that simplifies managing secrets.
Dapr 提供简化密钥管理的构建块。
What it solves
解决方法
The Dapr secrets building block abstracts away the complexity of working with secrets and secret management tools.
- It hides the underlying plumbing through a unified interface.
- It supports various pluggable secret store components, which can vary between development and production.
- Applications don‘t require direct dependencies on secret store libraries.
- Developers don‘t require detailed knowledge of each secret store.
Dapr 机密构建块 消除了使用机密和机密管理工具的复杂性。
- 它通过统一的接口隐藏基础管道。
- 它支持各种可 插入 的机密存储组件，这些组件在开发和生产之间有所不同。
- 应用程序无需直接依赖于密钥存储库。
- 开发人员无需详细了解每个密钥存储。
Dapr handles all of the above concerns.
Dapr 处理上述所有问题。
Access to the secrets is secured through authentication and authorization. Only an application with sufficient rights can access secrets. Applications running in Kubernetes can also use its built-in secrets management mechanism.
通过身份验证和授权来保护对机密的访问。 只有具有足够权限的应用程序可以访问机密。 在 Kubernetes 中运行的应用程序也可以使用其内置的机密管理机制。
How it works
工作原理
Applications use the secrets building block in two ways:
- Retrieve a secret directly from the application block.
- Reference a secret indirectly from a Dapr component configuration.
应用程序通过两种方式使用机密构建块：
- 直接从应用程序块检索机密。
- 从 Dapr 组件配置中间接引用机密。
Retrieving secrets directly is covered first. Referencing a secret from a Dapr component configuration file is addressed in a later section.
首先介绍如何直接检索机密。 在后面的部分中对从 Dapr 组件配置文件引用机密进行了说明。
The application interacts with a Dapr sidecar when using the secrets building block. The sidecar exposes the secrets API. The API can be called with either HTTP or gRPC. Use the following URL to call the HTTP API:
使用机密构建块时，应用程序与 Dapr边车交互。 边车公开了机密 API。 可以通过 HTTP 或 gRPC 调用 该API。 使用以下 URL 调用 HTTP API：
http://localhost:<dapr-port>/v1.0/secrets/<store-name>/<name>?<metadata>
The URL contains the following segments:
-
<dapr-port>specifies the port number upon which the Dapr sidecar is listening. -
<store-name>specifies the name of the Dapr secret store. -
<name>specifies the name of the secret to retrieve. -
<metadata>provides additional information for the secret. This segment is optional and metadata properties differ per secret store. For more information on metadata properties, see the [secrets API reference](Secrets API reference | Dapr Docs).
URL 包含以下段：
-
<dapr-port>指定 Dapr 边车正在侦听的端口号。 -
<store-name>指定 Dapr 密钥存储的名称。 -
<name>指定要检索的机密的名称。 -
<metadata>提供机密的附加信息。 此段是可选的，每个密钥存储的元数据属性各不相同。 有关元数据属性的详细信息，请参阅 [secrets API 参考](Secrets API reference | Dapr Docs)。
Note
The above URL represents the native Dapr API call available to any development platform that supports HTTP or gRPC. Popular platforms like .NET, Java, and Go have their own custom APIs.
备注
上述 URL 表示可用于支持 HTTP 或 gRPC 的任何开发平台的本机 Dapr API 调用。 .NET、Java 和Go等常用平台都有自己的自定义 Api。
The JSON response contains the key and value of the secret.
JSON 响应包含机密的键和值。
Figure 10-1 shows how Dapr handles a request for the secrets API:
图10-1 显示了 Dapr 如何处理secrets API请求：
Figure 10-1. Retrieving a secret with the Dapr secrets API.
图 10-1。 使用 Dapr secrets API 检索机密。
- The service calls the Dapr secrets API, along with the name of the secret store, and secret to retrieve.
- The Dapr sidecar retrieves the specified secret from the secret store.
- The Dapr sidecar returns the secret information back to the service.
- 服务使用使用机密存储的名称和要检索的机密调用 Dapr secrets API。
- Dapr 边车从机密存储中检索指定的机密。
- Dapr 边车将机密信息返回给服务。
Some secret stores support storing multiple key/value pairs in a single secret. For those scenarios, the response would contain multiple key/value pairs in a single JSON response as in the following example:
某些机密存储支持在单个机密中存储多个键/值对。 对于这些情况，响应会在单个 JSON 响应中包含多个键/值对，如以下示例中所示：
GET http://localhost:3500/v1.0/secrets/secret-store/interestRates?metadata.version_id=3
{ "tier1-percentage": "2.5", "tier2-percentage": "3.8", "tier3-percentage": "5.1" }
The Dapr secrets API also offers an operation to retrieve all the secrets the application has access to:
Dapr secrets API还提供了一个操作，用于检索应用程序有权访问的所有机密：
http://localhost:<dapr-port>/v1.0/secrets/<store-name>/bulk