CyberArk Conjur

資訊

✨ 這是企業版功能

功能	支援	說明
讀取密鑰	✅	讀取密鑰，例如 `OPENAI_API_KEY`
寫入密鑰	✅	儲存密鑰，例如 `Virtual Keys`
刪除密鑰	❌	必須透過政策更新移除密鑰

從 CyberArk Conjur（自架密鑰管理工具）讀取和寫入密鑰

步驟 1. 在您的環境中新增 CyberArk Conjur 詳細資訊

LiteLLM 支援兩種驗證方式：

API key 驗證 - CYBERARK_API_KEY（建議）
憑證驗證 - CYBERARK_CLIENT_CERT 和 CYBERARK_CLIENT_KEY

Environment Variables
CYBERARK_API_BASE="http://your-conjur-instance:8080"
CYBERARK_ACCOUNT="default"
CYBERARK_USERNAME="admin"

# Authentication via API key (recommended)
CYBERARK_API_KEY="your-api-key-here"

# OR - Authentication via certificate
CYBERARK_CLIENT_CERT="path/to/client.pem"
CYBERARK_CLIENT_KEY="path/to/client.key"

# OPTIONAL
CYBERARK_REFRESH_INTERVAL="300" # defaults to 300 seconds (5 minutes), frequency of token refresh
CYBERARK_SSL_VERIFY="true" # defaults to true, set to "false" to disable SSL verification (for self-signed certificates)

步驟 2. 新增至 proxy config.yaml

Proxy Config
general_settings:
  key_management_system: "cyberark"

  # [OPTIONAL SETTINGS]
  key_management_settings: 
    store_virtual_keys: true # OPTIONAL. Defaults to False, when True will store virtual keys in secret manager
    prefix_for_stored_virtual_keys: "litellm/" # OPTIONAL. If set, this prefix will be used for stored virtual keys in the secret manager
    access_mode: "read_and_write" # Literal["read_only", "write_only", "read_and_write"]

步驟 3. 啟動 + 測試 proxy

Start Proxy
$ litellm --config /path/to/config.yaml

快速測試 Proxy

將 Virtual Key 寫入 CyberArk

當您在 LiteLLM UI 中建立 virtual key 時，它會自動儲存在 CyberArk Conjur 中。

步驟 1： 在 LiteLLM Admin UI 中建立 virtual key

在這個範例中，我們建立一個名為 litellm-cyber-ark-secret-key 的 key：

步驟 2： 驗證該密鑰是否存在於 CyberArk

您可以透過查詢 secrets API 來驗證 virtual key 已儲存在 CyberArk 中：

Verify Secret in CyberArk
TOKEN=$(curl -s -X POST http://0.0.0.0:8080/authn/default/admin/authenticate \
  -d "your-api-key" | base64 | tr -d '\n')

curl -H "Authorization: Token token=\"$TOKEN\"" \
  "http://0.0.0.0:8080/resources/default/variable" | jq .

回應顯示 litellm-cyber-ark-secret-key 存在於 CyberArk 中：

virtual key 會以完整路徑儲存：default:variable:litellm/litellm-cyber-ark-secret-key

運作方式

驗證

CyberArk Conjur 使用兩步驟驗證流程：

LiteLLM 使用您的 API key 進行驗證以取得 session token
session token（經 base64 編碼）用於後續的 API 請求
token 會在約 8 分鐘後過期，因此 LiteLLM 會自動快取並重新整理它們

讀取密鑰

LiteLLM 使用下列 URL 格式從 CyberArk Conjur 讀取密鑰：

{CYBERARK_API_BASE}/secrets/{ACCOUNT}/variable/{SECRET_NAME}

例如，如果您有：

CYBERARK_API_BASE="http://conjur.example.com:8080"
CYBERARK_ACCOUNT="default"
密鑰名稱：AZURE_API_KEY

LiteLLM 會查詢：

http://conjur.example.com:8080/secrets/default/variable/AZURE_API_KEY

寫入密鑰

當在 LiteLLM 上建立 Virtual Key 時，會自動發生以下動作：

LiteLLM 建立一筆 policy 項目，在 Conjur 中定義該變數（若尚不存在）
LiteLLM 透過 Conjur API 設定密鑰值

LiteLLM 會將密鑰儲存在 prefix_for_stored_virtual_keys 路徑下（預設：litellm/）

例如，virtual key 會儲存為：litellm/virtual-key-name

重要注意事項

變數必須先在 Conjur policy 中定義，才能設定其值
LiteLLM 在寫入新密鑰時會自動建立 policy 項目
含有斜線的密鑰名稱（例如：litellm/key）會自動進行 URL 編碼
預設會快取 session token 5 分鐘，以將 API 呼叫降到最低

疑難排解

如果您在 LiteLLM 整合上遇到問題，請先驗證您的 CyberArk Conjur 執行個體是否正常運作。直接針對您的 CyberArk 端點執行這些 curl 指令，以確認連線與驗證是否正常：

步驟 1：驗證並取得 token

將 http://conjur.example.com:8080 替換為您的 CYBERARK_API_BASE，並使用您的實際憑證：

Authenticate
TOKEN=$(curl -s -X POST http://conjur.example.com:8080/authn/default/admin/authenticate \
  -d "your-api-key" | base64 | tr -d '\n')

步驟 2：測試讀取密鑰

Read Secret
curl -H "Authorization: Token token=\"$TOKEN\"" \
  "http://conjur.example.com:8080/secrets/default/variable/test-secret"

步驟 3：測試寫入密鑰

Write Secret
curl -X POST \
  -H "Authorization: Token token=\"$TOKEN\"" \
  --data "my-secret-value" \
  "http://conjur.example.com:8080/secrets/default/variable/test-secret"

如果這些指令能在您的 CyberArk 執行個體上成功執行，則代表 CyberArk 運作正常，問題出在您的 LiteLLM 設定。請檢查：

您的環境變數是否已正確設定
CYBERARK_API_BASE URL 是否可從您的 LiteLLM 執行個體存取
您的 API key 或憑證在 CyberArk 中是否具有必要權限

SSL 憑證錯誤

如果您遇到如下的 SSL 憑證驗證錯誤：

RuntimeError: Could not authenticate to CyberArk Conjur: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain

這通常發生在您的 CyberArk Conjur 執行個體使用自簽憑證時。您可以透過設定下列項目來停用 SSL 驗證：

CYBERARK_SSL_VERIFY="false"

注意

停用 SSL 驗證是不安全的，且僅應在使用自簽憑證的測試或開發環境中使用。對於正式環境，請正確設定您的憑證鏈，或使用搭配 CYBERARK_CLIENT_CERT 和 CYBERARK_CLIENT_KEY 的憑證式驗證。

影片導覽

這部影片示範如何使用 CyberArk Conjur 作為 LiteLLM 的密鑰管理工具。我們會在 LiteLLM Admin UI 中建立一個 virtual key，並驗證它是否存在於 CyberArk 中。接著我們會輪替密鑰並驗證它是否存在於 CyberArk 中。

將 Virtual Key 寫入 CyberArk​

運作方式​

疑難排解​

SSL 憑證錯誤​

影片導覽​

將 Virtual Key 寫入 CyberArk

運作方式

疑難排解

SSL 憑證錯誤

影片導覽