Back to Details

secrets-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OCI Vault and Secrets Management - Expert Knowledge

OCI Vault与密钥管理 - 专家知识

🏗️ Use OCI Landing Zone Terraform Modules

🏗️ 使用OCI Landing Zone Terraform模块

Don't reinvent the wheel. Use oracle-terraform-modules/landing-zone for Vault setup.
Landing Zone solves:
  • ❌ Bad Practice #1: Generic compartments (Landing Zone creates Security compartment for Vault)
  • ❌ Bad Practice #7: No security services (Landing Zone integrates Cloud Guard monitoring)
  • ❌ Bad Practice #10: No audit logging (Landing Zone enables Vault audit logs)
This skill provides: Vault operations, secret management patterns, and troubleshooting for vaults deployed WITHIN a Landing Zone.
不要重复造轮子。 使用oracle-terraform-modules/landing-zone来配置Vault。
Landing Zone可解决以下问题：
  • ❌ 不良实践1：通用 compartments（Landing Zone会为Vault创建Security compartment）
  • ❌ 不良实践7：未配置安全服务（Landing Zone集成了Cloud Guard监控）
  • ❌ 不良实践10：未启用审计日志（Landing Zone会开启Vault审计日志）
本技能提供： 在Landing Zone内部署的Vault的运维操作、密钥管理模式及故障排查方法。

⚠️ OCI CLI/API Knowledge Gap

⚠️ OCI CLI/API知识缺口

You don't know OCI CLI commands or OCI API structure.
Your training data has limited and outdated knowledge of:
  • OCI CLI syntax and parameters (updates monthly)
  • OCI API endpoints and request/response formats
  • Vault service CLI operations (
    oci vault secret
    , 
    oci kms
    )
  • Secret encoding formats and retrieval patterns
  • Latest Vault/KMS features and cross-region replication
When OCI operations are needed:
  1. Use exact CLI commands from this skill's references
  2. Do NOT guess OCI Vault CLI syntax
  3. Do NOT assume AWS Secrets Manager patterns work in OCI
  4. Load reference files for detailed Vault API documentation
What you DO know:
  • General secrets management principles
  • Encryption and key management concepts
  • Secret rotation patterns
This skill bridges the gap by providing current OCI-specific Vault patterns and gotchas.
You are an OCI Vault expert. This skill provides knowledge Claude lacks: anti-patterns, IAM permission gotchas, cost optimization, security vulnerabilities, and OCI-specific operational knowledge.
你不了解OCI CLI命令或OCI API结构。
你的训练数据中关于以下内容的知识有限且过时：
  • OCI CLI语法和参数（每月更新）
  • OCI API端点及请求/响应格式
  • Vault服务CLI操作（
    oci vault secret
    、
    oci kms
    ）
  • 密钥编码格式与检索模式
  • Vault/KMS最新功能及跨区域复制
当需要执行OCI操作时：
  1. 使用本技能参考资料中的准确CLI命令
  2. 请勿猜测OCI Vault CLI语法
  3. 请勿假设AWS Secrets Manager的模式适用于OCI
  4. 加载参考文件以获取详细的Vault API文档
你已掌握的内容：
  • 通用密钥管理原则
  • 加密与密钥管理概念
  • 密钥轮换模式
本技能通过提供当前OCI专属的Vault模式与陷阱知识，填补上述缺口。
你是OCI Vault专家。本技能补充了Claude缺失的知识：反模式、IAM权限陷阱、成本优化、安全漏洞及OCI专属运维知识。

NEVER Do This

绝对禁止的操作

❌ NEVER log secret contents (even in debug/error messages)
python
undefined
❌ 绝对不要记录密钥内容（即使在调试/错误日志中）
python
undefined

WRONG - secret ends up in log aggregation, retained for years

错误做法 - 密钥内容会被存入日志聚合系统，留存多年

logger.debug(f"Retrieved secret: {secret_value}") logger.error(f"Failed to parse secret: {secret_value}")
logger.debug(f"Retrieved secret: {secret_value}") logger.error(f"Failed to parse secret: {secret_value}")

RIGHT - log metadata only

正确做法 - 仅记录元数据

logger.debug(f"Retrieved secret OCID: {secret_ocid[:20]}...") logger.error(f"Failed to parse secret (type: {type(secret_value)})")

❌ **NEVER set temp key file permissions AFTER writing content**
```python
logger.debug(f"Retrieved secret OCID: {secret_ocid[:20]}...") logger.error(f"Failed to parse secret (type: {type(secret_value)})")

❌ **绝对不要在写入内容后再设置临时密钥文件权限**
```python

WRONG - world-readable during write (security window)

错误做法 - 写入期间文件对所有人可读（存在安全窗口）

with open('/tmp/key.pem', 'w') as f: f.write(private_key) os.chmod('/tmp/key.pem', 0o600) # Too late!
with open('/tmp/key.pem', 'w') as f: f.write(private_key) os.chmod('/tmp/key.pem', 0o600) # 太晚了！

RIGHT - secure BEFORE writing

正确做法 - 写入前先设置安全权限

fd = os.open('/tmp/key.pem', os.O_CREAT | os.O_WRONLY, 0o600) with os.fdopen(fd, 'w') as f: f.write(private_key)

❌ **NEVER use overly broad IAM policies**
BAD: "Allow any-user to read secret-family in tenancy" BAD: "Allow group Developers to manage secret-family in tenancy" GOOD: "Allow dynamic-group app-prod to read secret-family in compartment AppSecrets where target.secret.name = 'db-*'"

❌ **NEVER retrieve secrets without caching**
- **Cost**: $0.03 per 10,000 requests (first 10k/month free)
- **Without cache**: 1000 req/hr × 24 × 30 = 720k/month = **$2.16/month**
- **With 60min cache**: 1000 req/hr → 24 calls/day = 720/month = **FREE**
- **Savings**: 98% cost reduction

❌ **NEVER use PLAIN content type (deprecated)**
- Always use BASE64 encoding for secrets
- PLAIN is legacy and may not work in future

❌ **NEVER hardcode Vault OCIDs in code**
```python
fd = os.open('/tmp/key.pem', os.O_CREAT | os.O_WRONLY, 0o600) with os.fdopen(fd, 'w') as f: f.write(private_key)

❌ **绝对不要使用过于宽泛的IAM策略**
错误示例: "Allow any-user to read secret-family in tenancy" 错误示例: "Allow group Developers to manage secret-family in tenancy" 正确示例: "Allow dynamic-group app-prod to read secret-family in compartment AppSecrets where target.secret.name = 'db-*'"

❌ **绝对不要不缓存就检索密钥**
- **成本**：每10,000次请求0.03美元（每月前10,000次免费）
- **无缓存**：1000次请求/小时 × 24 × 30 = 720,000次/月 = **每月2.16美元**
- **60分钟缓存**：1000次请求/小时 → 24次/天 = 720次/月 = **免费**
- **节省**：98%的成本降低

❌ **绝对不要使用PLAIN内容类型（已弃用）**
- 始终为密钥使用BASE64编码
- PLAIN是遗留格式，未来可能无法使用

❌ **绝对不要在代码中硬编码Vault OCID**
```python

WRONG - not portable, leaked in repos

错误做法 - 不具备可移植性，会在代码仓库中泄露

VAULT_SECRET_OCID = "ocid1.vaultsecret.oc1.iad.xxxxx"
VAULT_SECRET_OCID = "ocid1.vaultsecret.oc1.iad.xxxxx"

RIGHT - configuration

正确做法 - 使用配置项

VAULT_SECRET_OCID = os.environ['VAULT_SECRET_OCID']
undefined
VAULT_SECRET_OCID = os.environ['VAULT_SECRET_OCID']
undefined

IAM Permission Gotcha (Critical)

IAM权限陷阱（关键）

Secret retrieval requires BOTH permissions:
"Allow dynamic-group X to read secret-family in compartment Y"
"Allow dynamic-group X to use keys in compartment Y"
Why both needed:
  • read secret-family
    → allows listing and reading secret metadata
  • use keys
    → allows decryption of secret content (secrets encrypted with master key)
Without 
use keys
: Get confusing 403 error: "User not authorized to perform this operation"
Common mistake: Forgetting 
use keys
permission, spending hours debugging "authorization failed"
密钥检索需要同时具备以下两项权限：
"Allow dynamic-group X to read secret-family in compartment Y"
"Allow dynamic-group X to use keys in compartment Y"
为何需要两者：
  • read secret-family
    → 允许列出和读取密钥元数据
  • use keys
    → 允许解密密钥内容（密钥使用主密钥加密）
缺少
use keys
权限时：会出现令人困惑的403错误："User not authorized to perform this operation"
常见错误：忘记添加
use keys
权限，花费数小时调试"授权失败"问题

Vault Hierarchy (Often Confused)

Vault层级结构（常被混淆）

Vault (container)
 └─ Master Encryption Key (for encryption/decryption)
     └─ Secret (encrypted data)
         └─ Secret Versions (rotation over time)
Commands use different services:
  • Vault operations: 
    oci kms management vault ...
  • Key operations: 
    oci kms management key ... --endpoint <vault-endpoint>
  • Secret operations: 
    oci vault secret ...
    (NOT kms!)
Common mistake: 
oci vault-secret create
(no such command) vs 
oci vault secret create
(correct)
Vault（容器）
 └─ 主加密密钥（用于加密/解密）
     └─ 密钥（加密后的数据）
         └─ 密钥版本（随时间轮换）
不同操作使用不同服务命令：
  • Vault操作：
    oci kms management vault ...
  • 密钥操作：
    oci kms management key ... --endpoint <vault-endpoint>
  • 密钥对象操作：
    oci vault secret ...
    （不是kms！）
常见错误：使用
oci vault-secret create
（不存在该命令）而非
oci vault secret create
（正确命令）

Secret Retrieval Error Decision Tree

密钥检索错误决策树

Secret retrieval fails?
│
├─ 401 Unauthorized
│  ├─ On OCI compute? → Check dynamic group membership
│  ├─ Local dev? → Check ~/.oci/config, verify API key uploaded
│  └─ After rotation? → Cache still has old credentials (wait for TTL)
│
├─ 403 Forbidden
│  ├─ Have "read secret-family" permission? → Add if missing
│  └─ Have "use keys" permission? → THIS IS USUALLY THE ISSUE
│
├─ 404 Not Found
│  ├─ Wrong secret OCID? → Verify environment variable
│  ├─ Wrong compartment? → Secrets client must use secret's compartment
│  └─ Secret deleted? → Check vault for secret status
│
└─ 500 Internal Server Error
   └─ Vault service issue → Retry with exponential backoff (rate limit)
密钥检索失败？
│
├─ 401 未授权
│  ├─ 在OCI计算实例上？→ 检查动态组成员身份
│  ├─ 本地开发环境？→ 检查~/.oci/config，验证API密钥已上传
│  └─ 轮换后出现？→ 缓存中仍有旧凭据（等待TTL过期）
│
├─ 403 禁止访问
│  ├─ 是否具备"read secret-family"权限？→ 缺失则添加
│  └─ 是否具备"use keys"权限？→ 这通常是问题所在
│
├─ 404 未找到
│  ├─ 密钥OCID错误？→ 验证环境变量
│  ├─ compartment错误？→ 密钥客户端必须使用密钥所在的compartment
│  └─ 密钥已删除？→ 在Vault中检查密钥状态
│
└─ 500 内部服务器错误
   └─ Vault服务问题 → 使用指数退避策略重试（速率限制）

Cost Optimization

成本优化

Vault API Pricing: $0.03 per 10,000 requests (10k/month free)
Vault API定价： 每10,000次请求0.03美元（每月前10,000次免费）

Calculation Examples:

计算示例：

Without caching (retrieve on every API call):
  • 1000 API calls/hour
  • 24 hours × 30 days = 720,000 Vault requests/month
  • (720,000 / 10,000) × $0.03 = $2.16/month
With 60-minute cache TTL:
  • 1000 API calls/hour → 1 Vault request/hour
  • 24 hours × 30 days = 720 Vault requests/month
  • Under 10k free tier = $0/month (FREE)
  • Savings: 98%
Cache TTL Selection:
Security RequirementsCache TTLReasoning
High (rotate daily)5-15 minutesFrequent refresh, still 90%+ savings
Standard (rotate monthly)30-60 minutesBalance security and cost
Dev/TestNo cacheAlways fresh for development
Rule: Cache TTL must be less than secret rotation window
无缓存（每次API调用都检索密钥）：
  • 1000次API调用/小时
  • 24小时 × 30天 = 720,000次Vault请求/月
  • (720,000 / 10,000) × $0.03 = 每月2.16美元
60分钟缓存TTL：
  • 1000次API调用/小时 → 1次Vault请求/小时
  • 24小时 × 30天 = 720次Vault请求/月
  • 低于10,000次免费额度 → 每月0美元（免费）
  • 节省：98%
缓存TTL选择：
安全要求缓存TTL理由
高（每日轮换）5-15分钟频繁刷新，仍可节省90%+成本
标准（每月轮换）30-60分钟平衡安全性与成本
开发/测试环境无缓存始终使用最新密钥用于开发
规则：缓存TTL必须短于密钥轮换窗口

Secret Rotation (Zero-Downtime)

密钥轮换（零停机）

WRONG (causes downtime):
bash
undefined
错误做法（会导致停机）：
bash
undefined

Don't delete and recreate - breaks running apps

不要删除后重新创建 - 会中断运行中的应用

oci vault secret delete --secret-id <secret-ocid> oci vault secret create ... # New OCID, apps break

**RIGHT** (zero-downtime):
```bash
oci vault secret delete --secret-id <secret-ocid> oci vault secret create ... # 新OCID，应用会中断

**正确做法**（零停机）：
```bash

Create new VERSION of existing secret

为现有密钥创建新版本

oci vault secret update-base64
--secret-id <secret-ocid>
--secret-content-content "$(echo -n 'new-value' | base64)"
oci vault secret update-base64
--secret-id <secret-ocid>
--secret-content-content "$(echo -n 'new-value' | base64)"

Secret OCID stays same, apps automatically get new version

密钥OCID保持不变，应用会自动获取新版本

Old version kept as "previous" for rollback

旧版本会保留为"previous"版本用于回滚


**Key points:**
- Secret OCID doesn't change (apps continue working)
- Vault serves latest version by default
- Previous versions retained for rollback
- Applications pick up new version on next cache refresh (no restart needed)

**关键点：**
- 密钥OCID不会改变（应用可继续正常运行）
- Vault默认提供最新版本
- 保留旧版本用于回滚
- 应用会在下次缓存刷新时获取新版本（无需重启）

Instance Principal Authentication

实例主体认证

Production compute instances should use instance principals:
bash
undefined
生产环境计算实例应使用实例主体认证：
bash
undefined

1. Create dynamic group

1. 创建动态组

oci iam dynamic-group create
--name "app-instances"
--matching-rule "instance.compartment.id = '<compartment-ocid>'"
oci iam dynamic-group create
--name "app-instances"
--matching-rule "instance.compartment.id = '<compartment-ocid>'"

2. Grant Vault access

2. 授予Vault访问权限

"Allow dynamic-group app-instances to read secret-family in compartment Secrets"

"Allow dynamic-group app-instances to read secret-family in compartment Secrets"

"Allow dynamic-group app-instances to use keys in compartment Secrets"

"Allow dynamic-group app-instances to use keys in compartment Secrets"

3. Application code (no credentials needed)

3. 应用代码（无需凭据）

signer = oci.auth.signers.InstancePrincipalsSecurityTokenSigner() secrets_client = oci.secrets.SecretsClient(config={}, signer=signer)

**Benefits:**
- No credentials to manage or rotate
- No secrets stored on compute instances
- Automatic token refresh
- Audit trail shows which instance accessed what
signer = oci.auth.signers.InstancePrincipalsSecurityTokenSigner() secrets_client = oci.secrets.SecretsClient(config={}, signer=signer)

**优势：**
- 无需管理或轮换凭据
- 计算实例上无需存储密钥
- 自动刷新令牌
- 审计跟踪可显示哪个实例访问了哪些资源

Audit Logging

审计日志

Enable Vault access logging:
bash
undefined
启用Vault访问日志：
bash
undefined

Create log group

创建日志组

oci logging log-group create
--compartment-id <ocid>
--display-name "vault-audit-logs"
oci logging log-group create
--compartment-id <ocid>
--display-name "vault-audit-logs"

Enable read access logging

启用读取访问日志

oci logging log create
--log-group-id <log-group-ocid>
--display-name "secret-read-audit"
--log-type SERVICE
--configuration '{ "source": { "sourceType": "OCISERVICE", "service": "vaults", "resource": "<vault-ocid>", "category": "read" } }'

**What gets logged:**
- Who: User OCID or instance principal identity
- What: Secret OCID accessed
- When: Timestamp (UTC)
- Where: Source IP address
- Result: Success (200) or failure (403, 404, etc.)

**Monitoring alerts** (recommended):
- \>10 failed access attempts in 5 minutes (unauthorized access)
- Access to secrets not assigned to requesting instance
- Access from unexpected IP ranges
oci logging log create
--log-group-id <log-group-ocid>
--display-name "secret-read-audit"
--log-type SERVICE
--configuration '{ "source": { "sourceType": "OCISERVICE", "service": "vaults", "resource": "<vault-ocid>", "category": "read" } }'

**日志记录内容：**
- 操作者：用户OCID或实例主体身份
- 操作对象：被访问的密钥OCID
- 时间：时间戳（UTC）
- 来源：源IP地址
- 结果：成功（200）或失败（403、404等）

**推荐监控告警：**
- 5分钟内失败访问尝试超过10次（未授权访问）
- 实例访问未分配给它的密钥
- 来自意外IP范围的访问

OCI-Specific Gotchas

OCI专属陷阱

Vault Management Endpoint is Required for Key Operations:
bash
undefined
密钥操作需要Vault管理端点：
bash
undefined

Find your vault's endpoint

查找你的Vault端点

oci kms management vault get --vault-id <vault-ocid>
--query 'data."management-endpoint"' --raw-output
oci kms management vault get --vault-id <vault-ocid>
--query 'data."management-endpoint"' --raw-output

Use in key commands

在密钥命令中使用该端点

oci kms management key create ...
--endpoint https://xxxxx-management.kms.us-ashburn-1.oraclecloud.com

**Regional Vault Availability:**
- Not all OCI regions have Vault service
- Check region availability before designing architecture
- Cross-region secret access adds latency (10-50ms)

**Secret Bundle Base64 Decoding:**
```python
oci kms management key create ...
--endpoint https://xxxxx-management.kms.us-ashburn-1.oraclecloud.com

**区域Vault可用性：**
- 并非所有OCI区域都提供Vault服务
- 设计架构前请检查区域可用性
- 跨区域密钥访问会增加延迟（10-50ms）

**密钥Bundle Base64解码：**
```python

Secret content is base64-encoded

密钥内容是base64编码的

secret_bundle = secrets_client.get_secret_bundle(secret_ocid) encoded = secret_bundle.data.secret_bundle_content.content decoded = base64.b64decode(encoded).decode('utf-8') # Don't forget decode()
undefined
secret_bundle = secrets_client.get_secret_bundle(secret_ocid) encoded = secret_bundle.data.secret_bundle_content.content decoded = base64.b64decode(encoded).decode('utf-8') # 不要忘记decode()
undefined

Progressive Loading References

渐进式加载参考资料

OCI Vault Reference (Official Oracle Documentation)

OCI Vault参考资料（Oracle官方文档）

WHEN TO LOAD 
oci-vault-reference.md
:
  • Need comprehensive Vault and KMS API documentation
  • Understanding key management and encryption options
  • Implementing HSM-backed key protection
  • Need official Oracle guidance on Vault architecture
  • Setting up cross-region secret replication
Do NOT load for:
  • Quick secret retrieval examples (covered in this skill)
  • Permission debugging (decision trees above)
  • Secret rotation patterns (covered above)
何时加载 
oci-vault-reference.md
：
  • 需要全面的Vault和KMS API文档
  • 了解密钥管理与加密选项
  • 实现HSM支持的密钥保护
  • 需要Oracle官方的Vault架构指导
  • 配置跨区域密钥复制
请勿加载的场景：
  • 快速密钥检索示例（本技能已涵盖）
  • 权限调试（上述决策树已涵盖）
  • 密钥轮换模式（上述内容已涵盖）

When to Use This Skill

何时使用本技能

  • Storing credentials in Vault: secret organization, IAM setup
  • Secret retrieval failures: 403 errors, permission debugging
  • Cost optimization: caching strategy, API call reduction
  • Secret rotation: zero-downtime updates, version management
  • Security: temp file handling, logging anti-patterns, audit setup
  • Production: instance principal configuration, monitoring alerts
  • 在Vault中存储凭据：密钥组织、IAM配置
  • 密钥检索失败：403错误、权限调试
  • 成本优化：缓存策略、减少API调用
  • 密钥轮换：零停机更新、版本管理
  • 安全：临时文件处理、日志反模式、审计配置
  • 生产环境：实例主体配置、监控告警