Azure Key Vault 開發者指南

Azure Key Vault 是一項雲端服務，提供加密金鑰、秘密與憑證的安全儲存與管理。 本指南協助開發者將 金鑰保存庫 整合進他們的應用程式中。

概觀

Azure Key Vault 可以讓你：

• 安全儲存：保護金鑰、秘密與憑證，無需撰寫自訂安全程式碼。
• 簡化金鑰管理：集中加密作業與金鑰生命週期管理。
• 客戶擁有的金鑰：讓客戶自行管理金鑰，同時專注於核心應用功能。
• 外部金鑰管理：使用金鑰進行簽名和加密，同時將它們放在應用程式外部。

關於Azure Key Vault的一般資訊，請參見About Azure Key Vault。

開發人員案例

金鑰保存庫 常見的開發工作包括：

• 儲存與檢索秘密：安全管理連線字串、密碼、API 金鑰及 SAS 令牌。 如需詳細資訊，請參閱關於祕密。
• 使用金鑰進行加密與簽名：執行密碼學操作時，不暴露金鑰資料給應用程式。 如需詳細資訊，請參閱關於金鑰。
• 管理憑證：自動化憑證配置、續期及部署 SSL/TLS。 如需詳細資訊，請參閱關於憑證。

公開預覽

Microsoft 會定期釋出 金鑰保存庫 新功能的公開預覽版。 欲試用預覽功能並提供回饋，請聯絡團隊。azurekeyvault@microsoft.com 有關最新功能與更新資訊，請參見 Azure Key Vault。

建立與管理 Key Vault

金鑰保存庫 採用雙平面存取模式：

• Control plane：管理金鑰保存庫資源本身（建立、刪除、更新屬性、指派存取政策）。 營運透過Azure Resource Manager管理。 關於存取控制，請參見 Assign a 金鑰保存庫 access policy。
• Data plane：管理儲存在金鑰保存庫的資料（金鑰、秘密、憑證）。 存取是透過Azure RBAC 和 金鑰保存庫來控制的。

使用預先定義的 金鑰保存庫 貢獻者 角色來授權管理層存取金鑰保存庫資源。 若要獲得有關驗證和授權的更多資訊，請參閱 Azure Key Vault 中的驗證。

網路安全性

透過配置私有端點、防火牆或服務端點來降低網路暴露。 如需完整的網路安全指引，包括從最嚴格到最不限制的設定選項，請參閱 Secure your Azure Key Vault： Network Security 以及 Configure Azure Key Vault networking settings。

Key Vault 管理的 API 與 SDK

下表列出管理 金鑰保存庫 資源（控制平面操作）的 SDK 與快速啟動工具。 有關最新版本及安裝說明，請參閱 用戶端函式庫。

Azure CLI	PowerShell	REST API	資源管理器	.NET	Python	Java	JavaScript
參考 快速入門	參考 快速入門	參考	參考 快速入門	參考	參考	參考	參考

在程式碼中驗證 金鑰保存庫

金鑰保存庫 採用 Microsoft Entra 認證，該驗證需要 Microsoft Entra 安全原則才能授權存取。 Microsoft Entra 的安全主體可以是使用者、應用程式服務主體、Azure 資源的受控身份，或這些類型中的任一群組。

驗證最佳做法

對於部署到 Azure 的應用程式，可以使用管理身份來消除在程式碼中儲存憑證的需求。 關於不同環境（生產環境、開發環境、本地環境）的詳細認證指導與安全主體建議，請參見Authentication in Azure Key Vault 及 Secure your Azure Key Vault。

Azure 身分識別用戶端程式庫

上述驗證情境由 Azure Identity 用戶端函式庫支援，並與 金鑰保存庫 SDK 整合。 你可以在不同環境和平台間使用 Azure Identity 用戶端函式庫，而不必更改程式碼。 該程式庫會自動從透過 Azure CLI、Visual Studio、Visual Studio Code 及其他方式登入 Azure 的使用者取得驗證權杖。

欲了解更多關於 Azure Identity 用戶端函式庫的資訊，請參閱：

.NET	Python	Java	JavaScript
Azure Identity SDK .NET	Azure Identity SDK Python	Azure Identity SDK Java	Azure Identity SDK JavaScript

備註

我們曾建議在 金鑰保存庫 .NET SDK 第 3 版中使用 App Authentication library，但它現在已被棄用。 若要遷移到 金鑰保存庫 .NET SDK 第 4 版，請依照 AppAuthentication 至 Azure.Identity 的遷移指南。

關於如何在應用程式中驗證 金鑰保存庫 的教學，請參見：

• 在 .NET 的虛擬機中使用 Azure Key Vault
• 在 Python 中將 Azure Key Vault 與虛擬機器一起使用
• 使用受管理身份將金鑰保存庫連接到Azure的.NET網頁應用程式

管理金鑰、憑證與密碼

備註

.NET、Python、Java、JavaScript、PowerShell 及 Azure CLI 的 SDK 是 金鑰保存庫 功能發佈流程的一部分，配合公開預覽及 金鑰保存庫 服務團隊支援的全面可用性。 金鑰保存庫 的其他 SDK 客戶端可用，但它們是由個別 SDK 團隊透過 GitHub 建置與支援，並發布於其 Teams 排程中。 有關最新 SDK 版本與安裝套件，請參閱 用戶端函式庫。

資料平面控制對金鑰、憑證與密碼的存取。 你可以用 Azure RBAC 搭配 金鑰保存庫 來透過資料平面進行存取控制。

金鑰的 API 與 SDK

下表列出用於金鑰操作（資料平面操作）的 SDK 與快速啟動工具。 欲了解更多關於鑰匙的資訊，請參閱 關於鑰匙。

Azure CLI	PowerShell	REST API	資源管理器	.NET	Python	Java	JavaScript
參考 快速入門	參考 快速入門	參考	參考 快速入門	參考 快速入門	參考 快速入門	參考 快速入門	參考 快速入門

其他程式庫

金鑰保存庫 與 Managed HSM 的密碼學客戶端

此模組提供適用於 Go 語言版本 Azure Key Vault Keys 客戶端模組的加密客戶端。

備註

此專案未獲 Azure SDK 團隊支援，但與其他支援語言的密碼學用戶端相符。

語言	參考文獻
Go	參考

憑證的 API 與 SDK

下表列出用於憑證（資料平面操作）的 SDK 與快速啟動工具。 欲了解更多關於憑證的資訊，請參閱 關於憑證。

Azure CLI	PowerShell	REST API	資源管理器	.NET	Python	Java	JavaScript
參考 快速入門	參考 快速入門	參考	N/A	參考 快速入門	參考 快速入門	參考 快速入門	參考 快速入門

密碼的 API 與 SDK

下表列出用於處理秘密（資料平面操作）的 SDK 與快速啟動工具。 欲了解更多關於秘密的資訊，請參見 「關於秘密」。

Azure CLI	PowerShell	REST API	資源管理器	.NET	Python	Java	JavaScript
參考 快速入門	參考 快速入門	參考	參考 快速入門	參考 快速入門	參考 快速入門	參考 快速入門	參考 快速入門

密碼的使用方式

使用 Azure Key Vault 只儲存應用程式的秘密。 應儲存在 金鑰保存庫 的秘密範例包括：

• 客戶端應用程式密碼
• 連線字串
• 密碼
• 共用存取金鑰
• SSH 金鑰

任何與密碼相關的資訊，例如使用者名稱與應用程式 ID，都可以作為密碼的標籤儲存。 對於其他敏感設定，你應該使用 Azure 應用程式組態。

有關安裝套件與原始程式碼，請參閱用戶端程式庫。

在應用程式中使用 金鑰保存庫

為了善用 金鑰保存庫 最新的功能，我們建議你使用 金鑰保存庫 SDK 來在應用程式中使用秘密、憑證和金鑰。 金鑰保存庫 SDK 與 REST API 會隨著產品新功能的釋出而持續更新，並遵循最佳實務與指引。

對於基本情境，還有其他函式庫與整合解決方案，提供 Microsoft 合作夥伴或開源社群的支援，方便簡化使用。

對於憑證，您可以使用：

• 金鑰保存庫虛擬機（VM）擴充功能，提供Azure key vault中憑證的自動更新。 如需詳細資訊，請參閱：
  • 金鑰保存庫 Windows 虛擬機器擴充功能
  • 金鑰保存庫 虛擬機器擴充功能（Linux 版）
  • 金鑰保存庫 支援 Azure Arc 伺服器的虛擬機器擴充功能
• Azure App 服務 整合，可以匯入並自動刷新 金鑰保存庫 的憑證。 更多資訊請參見 從 金鑰保存庫 匯入憑證。

對於密碼，您可以使用：

• 使用 App Service 應用程式設定的 金鑰保存庫 密碼。 欲了解更多資訊，請參閱 將 金鑰保存庫 參考用於 App Service 和 Azure Functions。
• 使用 Azure 應用程式組態的 金鑰保存庫 參考，以簡化應用程式對組態與密碼的存取。 欲了解更多資訊，請參閱在 Azure 應用程式組態 中使用 金鑰保存庫 參考。

程式碼範例

關於在應用程式中使用金鑰保存庫的完整範例，請參見 Azure Key Vault 程式碼範例 。

工作專屬指引

以下文章與情境提供針對 Azure Key Vault 的任務指引：

• 要存取 Key Vault，您的客戶端應用程式需要能存取多個端點以支援不同功能。 請參考 在防火牆後方存取金鑰庫。
• 在 Azure VM 上運行的雲端應用程式需要憑證。 如何將此憑證放入 VM？ 請參見 金鑰保存庫 虛擬機擴充功能 Windows 或 金鑰保存庫 虛擬機器擴充功能 Linux。
• 若要使用 Azure CLI、PowerShell 或 Azure 入口網站來指派存取政策，請參見 Assign a 金鑰保存庫 access policy。
• 關於啟用軟刪除的金鑰保險庫及各種金鑰金庫物件的使用與生命週期指引，請參見 Azure Key Vault 恢復管理與軟刪除與清除保護。
• 當你需要在部署時傳遞一個安全值（例如密碼）作為參數時，你可以將該值作為一個秘密存放在密碼保管庫中，並在其他 Resource Manager 範本中引用該值。 請參見 Use Azure Key Vault 以在部署期間傳遞安全參數值。

與 金鑰保存庫 的整合

以下服務與情境使用或整合 金鑰保存庫：

• 靜態資料加密允許在資料持久化時進行編碼 (加密)。 資料加密金鑰通常會被 Azure Key Vault 中的金鑰加密金鑰加密，以進一步限制存取權限。
• Azure 資訊保護 允許你管理自己的租戶金鑰。 例如，你可以自己管理租戶金鑰（預設），而不是由 Microsoft 管理，以符合適用於你組織的特定法規。 自行管理租用戶金鑰亦稱為自帶金鑰 (BYOK)。
• Azure Private Link 允許您透過您的虛擬網路中的私有端點存取 Azure 服務（例如，Azure Key Vault、Azure 儲存體 和 Azure Cosmos DB）以及由 Azure 託管的客戶/合作夥伴服務。
• 金鑰保存庫與 Azure 事件方格 的整合，讓使用者能在 金鑰保存庫 中儲存的秘密狀態變更時收到通知。 您可以將新版本的密碼分發給應用程式，或在密碼即將到期時進行輪換，以防止中斷。
• 保護你的 Azure DevOps 秘密，防止在 金鑰保存庫 中被不想要的存取。
• 利用儲存在金鑰保存庫中的機密從Azure Databricks連接到Azure 儲存體。
• 在 Kubernetes 上設定並執行 Secrets Store CSI 驅動程式 的 Azure Key Vault 提供者。

災害復原和商務持續性

金鑰保存庫 提供內建的災難復原功能，並具備自動區域複製功能。 在生產部署時，啟用軟刪除與清除保護，並實施定期備份。 欲了解更多資訊，請參閱 Azure Key Vault 可用性與冗餘、Azure Key Vault 復原管理，以及 Azure Key Vault backup。

效能和可擴縮性

在開發使用 金鑰保存庫 的應用程式時，請考慮以下效能與可擴展性的最佳實務：

• 服務限制：金鑰保存庫 在每個區域的每個保存庫都有交易次數限制。 超過這些限制將導致節流。 欲了解更多資訊，請參閱Azure Key Vault服務限制。
• 限速指引：實作帶有指數回退的重試邏輯來處理限速回應。 更多資訊請參閱 Azure Key Vault節流指引。
• Caching：在應用程式中快取機密資訊與憑證，以減少呼叫"金鑰保存庫"並提升效能。
• Connection management：盡可能重用 HTTP 連線來金鑰保存庫，以降低延遲並提升效能。

監視與記錄

啟用日誌與監控功能，以提升安全性、合規性及故障排除。 配置診斷設定、事件網格通知及關鍵事件警示。 詳細指引請參閱監控 Azure Key Vault、Azure Key Vault 日誌記錄、使用 Azure 事件方格 監控 金鑰保存庫，以及確保 Azure Key Vault 的安全：日誌記錄和威脅偵測。

常見參數與請求模式

在使用 金鑰保存庫 REST API 時，了解常見參數及請求/回應模式會很有幫助：

• API 版本：金鑰保存庫 使用版本限制 API。 請在請求中明確指定 API 版本。
• 認證請求：了解認證憑證的取得與使用方式，包括常見的請求標頭與回應格式。 欲了解更多資訊，請參閱 認證、請求與回應。
• 錯誤代碼：熟悉常見的 REST API 錯誤代碼，以優雅地處理故障。 欲了解更多資訊，請參閱 Azure Key Vault REST API 錯誤代碼。

故障排除

需要解決常見問題的協助：

• 存取遭拒錯誤：驗證您的認證，以及您的安全主體是否透過 RBAC 指派具有必要的權限。 請參見 Azure RBAC 以了解金鑰保存庫資料平面操作。
• Network connectivity：若從防火牆後存取金鑰保存庫，請確保所需端點可存取。 請參考 在防火牆後方存取金鑰庫。
• 限速：若收到 429 個（請求過多）回應，則實施指數退換。 請參見 Azure Key Vault節流指引。

安全性最佳做法

如需完整的安全指引，包括身份與存取管理、資料保護、合規、治理及備份策略，請參見 Secure your Azure Key Vault。

其他資源

金鑰保存庫 概念

• Azure Key Vault 基本概念 - 金鑰保存庫工作基礎概念。
• Azure Key Vault 軟刪除概覽 - 恢復已刪除的物件。
• Azure Key Vault 節流指引 - 您的應用程式的基本概念和方法。
• Azure Key Vault 安全世界與地理邊界 - 區域與安全關係。
• Azure Key Vault 服務限制 - 交易限制及其他服務限制。

管理與作業

• 監控 Azure Key Vault - 設定監控與診斷。
• Azure Key Vault logging - 啟用並分析金鑰保存庫日誌。

社區和支持

• Microsoft 問與答A - 向社群提問並獲得答案。
• Stack Overflow for 金鑰保存庫 - 來自開發者的技術問答。
• Azure 回饋 - 提交功能請求與回饋。