Azure KeyVault Emulator 镜像文档

镜像概述和主要用途

Azure KeyVault Emulator 是一个Docker镜像，用于在本地开发和测试环境中模拟Azure KeyVault服务的核心功能。它允许开发人员无需连接真实的Azure云服务，即可进行密钥管理和机密操作的开发验证，降低云服务依赖和测试成本。

核心功能和特性

支持的操作

密钥（Keys）- RSA类型

• 创建密钥（Create Key）
• 获取密钥（Get Key）
• 按版本获取密钥（Get Key by Version）
• 加密（Encrypt）
• 解密（Decrypt）
• 支持的算法：JSON Web Key加密算法中的RSA1_5和RSA-OAEP

机密（Secrets）

• 设置机密（Set）
• 获取机密（Get Secret）
• 按版本获取机密（Get Secret by Version）

使用场景和适用范围

适用于需要与Azure KeyVault交互的应用程序的本地开发和测试阶段。可替代真实Azure KeyVault服务，用于验证密钥加密/解密、机密存储/获取等功能，避免产生云资源费用，同时支持离线开发环境。

使用方法和配置说明

环境要求

Azure KeyClient需通过HTTPS与模拟器通信：

• 本地localhost访问：使用dotnet dev-certs配置可信TLS证书。
• 非localhost主机名访问：需生成自签名证书并确保客户端信任（详见下文docker-compose配置步骤）。

在docker-compose中配置

步骤1：生成自签名证书

替换<emulator-hostname>（模拟器主机名），执行以下OpenSSL命令生成公钥/私钥对及PFX证书：

# 生成CRT和KEY文件
openssl req \
-x509 \
-newkey rsa:4096 \
-sha256 \
-days 3560 \
-nodes \
-keyout <emulator-hostname>.key \
-out <emulator-hostname>.crt \
-subj '/CN=<emulator-hostname>' \
-extensions san \
-config <( \
  echo '[req]'; \
  echo 'distinguished_name=req'; \
  echo '[san]'; \
  echo 'subjectAltName=DNS.1:localhost,DNS.2:<emulator-hostname>')

# 导出PFX格式证书（用于模拟器服务）
openssl pkcs12 -export -out <emulator-hostname>.pfx \
-inkey <emulator-hostname>.key \
-in <emulator-hostname>.crt

步骤2：配置模拟器服务

在docker-compose.yml中添加Azure KeyVault Emulator服务：

version: '3.7'

services:
  azure-keyvault-emulator:
    container_name: azure-keyvault-emulator
    image: basis-theory/azure-keyvault-emulator:latest
    ports:
      - 5001:5001  # HTTPS端口
      - 5000:5000  # HTTP端口（可选）
    volumes:
      - <path-to-certs>:/https  # 本地证书目录挂载到容器/https路径
    environment:
      - ASPNETCORE_URLS=[***]  # 服务监听地址
      - ASPNETCORE_Kestrel__Certificates__Default__Path=/https/<emulator-hostname>.pfx  # PFX证书路径
      - KeyVault__Name=<emulator-hostname>  # 模拟器实例名称（需与证书CN一致）

步骤3：配置客户端应用

修改客户端应用的docker-compose.yml，将自签名证书添加到信任链并指向模拟器服务：

version: '3.7'

services:
  my-awesome-keyvault-client:
    container_name: my-awesome-client
    build:
      context: .  # 客户端应用构建上下文
    depends_on:
      - azure-keyvault-emulator  # 依赖模拟器服务
    entrypoint: sh -c "cp /https/<emulator-hostname>.crt /usr/local/share/ca-certificates/<emulator-hostname>.crt && update-ca-certificates && exec <original-entrypoint>"  # 添加证书到信任存储
    volumes:
      - <path-to-certs>:/https  # 挂载证书目录（与模拟器共享）
    environment:
      - KeyVault__BaseUrl=[***]  # 模拟器服务地址（容器内主机名）

配置参数说明

环境变量

• ASPNETCORE_URLS：服务监听URL，默认[***]（HTTPS端口5001，HTTP端口5000）。
• ASPNETCORE_Kestrel__Certificates__Default__Path：Kestrel服务器默认证书路径，需指向容器内/https/<emulator-hostname>.pfx。
• KeyVault__Name：模拟器实例名称，需与证书的CN字段一致。
• KeyVault__BaseUrl（客户端）：指向模拟器的HTTPS地址，格式为https://<emulator-service-name>:5001/。

卷挂载

• <path-to-certs>:/https：本地证书目录（包含.crt、.key、.pfx文件）挂载到容器内/https路径，供模拟器和客户端访问证书。