管理密鑰版本

當您在 IBM Cloud® Secrets Manager 中旋轉密碼時，您會建立一個新版本的密碼值。您可以使用 IBM Cloud® Secrets Manager 檢視版本歷史和更新機密的版本元資料。如果您意外取代或改寫密鑰，則也可以將它還原至舊版。

開始之前

開始之前，請確定您具有必要的存取層次。若要更新密鑰版本的 meta 資料或將密鑰還原至其舊版，您需要 撰寫者 服務角色或更高版本。若要檢視密鑰的版本歷程，您需要讀者服務角色或更高版本。

檢視密鑰的版本歷程

當您在 IBM Cloud® Secrets Manager 中旋轉密碼時，您會建立一個新版本的密碼值。您可以使用使用者介面或 API 來快速檢查密鑰的版本歷程。

Secrets Manager 為了稽核目的，最多可保留 50 個版本的機密，包括機密元資料。然而，只有目前和緊接之前的版本包含秘密資料，早期版本則不包含。

在使用者介面中檢視版本歷程

如果您要審核密鑰的版本歷程，則可以使用 Secrets Manager 使用者介面來檢視每個旋轉的一般性質。

在主控台中，按一下 功能表 圖示 > 資源清單。
從服務清單中，選取 Secrets Manager的實例。
在 Secrets Manager 使用者介面中，移至密鑰清單。
在您要檢查密鑰的列中，按一下動作功能表 > 版本歷程。
選用項目: 更新您正在檢視之密鑰特定版本的 meta 資料。
1. 若要更新密鑰版本的 meta 資料，請上傳檔案，或以 JSON 格式輸入 meta 資料及版本 meta 資料。
2. 按一下更新。

從 CLI 列出密鑰版本

如果您要審核密鑰的版本歷程，則可以使用 Secrets Manager CLI 外掛程式來檢視每個循環的一般性質。

若要列出與密鑰相關聯的所有版本，請執行 ibmcloud secrets-manager secret-versions 指令。 SECRET_TYPE 的選項有 arbitrary, iam_credentials, imported_cert, kv, private_cert, public_cert, service_credentials, custom_credentials，和 username_password。

ibmcloud secrets-manager secret-versions --secret-id SECRET-ID

此指令會輸出現行及舊版的相關資訊。例如，每一個版本的建立日期。如需指令選項的相關資訊，請參閱 ibmcloud secrets-manager secret-versions。

使用 API 列出密鑰版本

如果您要審核密鑰的版本歷程，則可以使用 Secrets Manager API 來檢視每個循環的一般性質。

下列要求範例列出每一個版本的 meta 資料內容。當您呼叫 API 時，請將 ID 變數和 IAM 令牌換成您 Secrets Manager 範例的特定值。 {secret_type} 的選項有 arbitrary, iam_credentials, imported_cert, kv, private_cert, public_cert, service_credentials, custom_credentials，和 username_password。

curl -X GET
  --H "Authorization: Bearer {iam_token}" \
  --H "Accept: application/json" \
  "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/versions"

成功回應會傳回每一個密鑰版本的 meta 資料詳細資料。

{
  "versions": [
    {
      "created_at": "2022-06-27T11:58:15Z",
      "created_by": "iam-ServiceId-e4a2f0a4-3c76-4bef-b1f2-fbeae11c0f21",
      "expiration_date": "2023-10-05T11:49:42Z",
      "id": "bc656587-8fda-4d05-9ad8-b1de1ec7e712",
      "payload_available": true,
      "secret_group_id": "67d025e1-0248-418f-83ba-deb0ebfb9b4a",
      "secret_id": "67d025e1-0248-418f-83ba-deb0ebfb9b4a",
      "secret_name": "example-imported-certificate",
      "secret_type": "imported_cert",
      "serial_number": "38:eb:01:a3:22:e9:de:55:24:56:9b:14:cb:e2:f3:e3:e2:fb:f5:18",
      "validity": {
        "not_after": "2023-10-05T11:49:42Z",
        "not_before": "2022-06-27T11:58:15Z"
      },
      "version_custom_metadata": {
        "custom_version_key": "custom_version_value"
      }
    }
  ],
  "total_count": 1
}

downloaded 內容指出是否已讀取或存取每一個密鑰版本的資料。如果 payload_available 欄位的值為 true，則表示您可以存取或還原該版本的密碼資料。如需必要及選用要求參數的相關資訊，請參閱 API 參考資料。

您可以使用 version_custom_metadata 要求參數來儲存與組織需求相關的 meta 資料。您的秘密的自訂元資料會像所有其他元資料一樣儲存，您不得包含機密資料。如需必要及選用要求參數的相關資訊，請參閱 API 參考資料。

在使用者介面中更新密鑰版本 meta 資料

您可以使用 Secrets Manager 使用者介面來更新密鑰特定版本的 meta 資料。

要更新保密版本的元資料，請完成下列步驟。

在主控台中，按一下 功能表 圖示 > 資源清單。
從服務清單中，選取 Secrets Manager的實例。
在 Secrets Manager 使用者介面中，移至密鑰清單。
在您要檢查密鑰的列中，按一下動作功能表 > 版本歷程。

如果先前已輪替密鑰，則頁面會顯示現行及舊版的相關資訊，例如每一個版本的建立日期。
上傳檔案或以 JSON 格式輸入 meta 資料及版本 meta 資料。
按一下更新。

從 CLI 更新密鑰版本 meta 資料

您可以使用 Secrets Manager CLI 外掛程式來更新密鑰特定版本的 meta 資料。

若要更新密鑰的 meta 資料，請執行 ibmcloud secrets-manager secret-metadata-update 指令。

下列範例顯示 ibmcloud secrets-manager secret-metadata-update 指令的格式。

ibmcloud secrets-manager secret-version-metadata-update --secret-id SECRET-ID --id VERSION-ID --version-custom-metadata='{"anyKey": "anyValue"}'

使用 API 更新密鑰版本 meta 資料

如果您要更新密鑰版本的 meta 資料，則可以使用 Secrets Manager API。

下列範例要求會更新每一個版本的 meta 資料內容。當您呼叫 API 時，請將 ID 變數和 IAM 令牌換成您 Secrets Manager 範例的特定值。 {secret_type} 的選項有 arbitrary, iam_credentials, imported_cert, kv, private_cert, public_cert, service_credentials, custom_credentials，和 username_password。

curl -X PATCH  
  -H "Authorization: Bearer {iam_token}" \
  -H "Accept: application/json" \
  --H "Content-Type: application/merge-patch+json" \
  -d '{ "version_custom_metadata": { "version_special_id" : "someString" } }' \
  "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/versions/{version_id}/metadata"

成功回應會傳回每一個密鑰版本的 meta 資料詳細資料。

{
  "alias": "current",
  "created_at": "2022-06-27T11:58:15Z",
  "created_by": "iam-ServiceId-e4a2f0a4-3c76-4bef-b1f2-fbeae11c0f21",
  "expiration_date": "2023-10-05T11:49:42Z",
  "id": "bc656587-8fda-4d05-9ad8-b1de1ec7e712",
  "payload_available": true,
  "secret_group_id": "67d025e1-0248-418f-83ba-deb0ebfb9b4a",
  "secret_id": "67d025e1-0248-418f-83ba-deb0ebfb9b4a",
  "secret_name": "example-arbitrary-secret",
  "secret_type": "arbitrary",
  "version_custom_metadata": {
    "custom_version_key": "custom_version_value"
  }
}

downloaded 內容指出是否已讀取或存取每一個密鑰版本的資料。如果 payload_available 欄位的值為 true，則表示您可以存取或還原該版本的密碼資料。

您可以使用 version_custom_metadata 要求參數來儲存與組織需求相關的 meta 資料。您的秘密的自訂元資料會像所有其他元資料一樣儲存，您不得包含機密資料。如需必要及選用要求參數的相關資訊，請參閱 API 參考資料

將密鑰還原至舊版

不小心取代或改寫現有密鑰? 您可以使用 IBM Cloud® Secrets Manager 立即回滾到先前的版本。

當您將密鑰還原至其舊版時，會建立該密鑰的新版本。例如，如果密鑰的現行版本為 3，且您回復至第 2 版，則從第 2 版還原的資料會變成第 4 版。

您可以在支援的密鑰類型上還原一個版本。基於審核目的，服務會針對每一個密鑰保留最多 50 個版本的 meta 資料，您可以在密鑰的版本歷程中檢閱這些 meta 資料。

支援的密鑰類型

IAM 認證支援還原至舊版。

在使用者介面中還原舊版

您可以使用 Secrets Manager 使用者介面，將密鑰還原至其舊版。

在主控台中，按一下 功能表 圖示 > 資源清單。
從服務清單中，選取 Secrets Manager的實例。
在 Secrets Manager 使用者介面中，移至密鑰清單。
在您要檢查密鑰的列中，按一下動作功能表 > 版本歷程。

如果先前已輪換密鑰，則頁面會顯示現行及舊版的相關資訊。
按一下您要還原的密鑰版本旁邊的動作功能表 > 還原。

目前，您只能針對 IAM 認證密碼類型還原一個版本。只有在未達到定義的存活時間 (TTL) 或租賃持續時間時，才能還原密鑰版本。如果您沒有看到可用的選項，則不支援還原版本。

從 CLI 還原舊版

您可以使用 Secrets Manager CLI 將密碼還原至舊版。

下列範例指令會還原舊版密鑰。當您呼叫指令時，請將 SECRET_ID 變數取代為 Secrets Manager 實例特定的值。

ibmcloud sm secret-version-create --secret-d SECRET_ID --secret-version-restore-from-version "previous"

目前，您只能針對 IAM 認證及匯入的憑證密碼還原一個版本。只有在未達到定義的存活時間 (TTL) 或租賃持續時間時，才能還原密鑰版本。

成功回應會傳回密鑰的值，以及其他 meta 資料。如需必要及選用要求參數的相關資訊，請參閱 API 參考資料。

使用 API 還原舊版

您可以使用 Secrets Manager API 將密鑰還原至其舊版。

下列範例要求會還原舊版密鑰。當您呼叫 API 時，請將 ID 變數和 IAM 令牌換成您 Secrets Manager 範例的特定值。 {secret_type} 容許的值為: iam_credentials。

若要列出密鑰版本並取得每一個版本的 ID，請使用列出版本 API。

curl -X POST
  --H "Authorization: Bearer {iam_token}" \
  --H "Accept: application/json" \
  --H "Content-Type: application/json" \
  --d '{
         "restore_from_version": "previous",
         "custom_metadata": {
            "metadata_custom_key": "metadata_custom_value"
         },
         "version_custom_metadata": {
            "custom_version_key": "custom_version_value"
         }
      }' \
   "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/versions"

目前，您只能針對 IAM 認證及匯入的憑證密碼還原一個版本。只有在未達到定義的存活時間 (TTL) 或租賃持續時間時，才能還原密鑰版本。

成功回應會傳回密鑰的值，以及其他 meta 資料。如需必要及選用要求參數的相關資訊，請參閱 API 參考資料。