Gestión de versiones de secretos

Cuando se rota un secreto en IBM Cloud® Secrets Manager, se crea una nueva versión de su valor. Puede utilizar IBM Cloud® Secrets Manager para ver el historial de versiones y actualizar los metadatos de versión de los secretos. Si sustituye o sobrescribe accidentalmente un secreto, también puede restaurarlo a una versión anterior.

Antes de empezar

Antes de empezar, asegúrese de que tiene el nivel de acceso necesario. Para actualizar los metadatos de una versión secreta o restaurar un secreto a su versión anterior, necesita el rol de servicio de Escritor o superior. Para ver el historial de versiones de un secreto, necesita el rol de servicio de Lector o superior.

Ver el historial de versiones de los secretos

Cuando se rota un secreto en IBM Cloud® Secrets Manager, se crea una nueva versión de su valor. Puede examinar rápidamente el historial de versiones de sus secretos utilizando la interfaz de usuario o la API.

Secrets Manager conserva hasta 50 versiones de un secreto con fines de auditoría, incluidos los metadatos secretos. Sin embargo, sólo la versión actual y la inmediatamente anterior incluyen los datos secretos, las versiones anteriores no.

Visualizar el historial de versiones en la interfaz de usuario

Si está auditando el historial de versiones de un secreto, puede utilizar la interfaz de usuario de Secrets Manager para ver las características generales de cada rotación.

En la consola, pulse el icono Menú > Lista de recursos.
En la lista de servicios, seleccione la instancia de Secrets Manager.
En la interfaz de usuario de Secrets Manager, vaya a la lista de Secretos.
En la fila correspondiente al secreto que desea inspeccionar, pulse el menú Acciones > Historial de versiones.
Opcional: actualice los metadatos de la versión específica del secreto que está visualizando.
1. Para actualizar los metadatos de la versión secreta, cargue un archivo o especifique los metadatos y los metadatos de la versión en formato JSON.
2. Pulse Actualizar.

Listar las versiones de los secretos desde la CLI

Si está auditando el historial de versiones de un secreto, puede utilizar el plug-in de CLI de Secrets Manager para ver las características generales de cada rotación.

Para listar todas las versiones asociadas con un secreto, ejecute el mandato ibmcloud secrets-manager secret-versions. Las opciones para SECRET_TYPE son: arbitrary, iam_credentials, imported_cert, kv, private_cert, public_cert, service_credentials, custom_credentials, y username_password.

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

El mandato genera información sobre las versiones actual y anterior. Por ejemplo, la fecha en la que se ha creado cada versión. Para obtener más información sobre las opciones de mandato, consulte ibmcloud secrets-manager secret-versions.

Listar las versiones de los secretos con la API

Si está auditando el historial de versiones de un secreto, puede utilizar la API de Secrets Manager para ver las características generales de cada rotación.

La siguiente solicitud de ejemplo lista las propiedades de metadatos de cada versión. Cuando llame a la API, sustituya las variables de ID y la señal de IAM por los valores que son específicos de la instancia de Secrets Manager. Las opciones para {secret_type} son: arbitrary, iam_credentials, imported_cert, kv, private_cert, public_cert, service_credentials, custom_credentials, y 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"

Una respuesta satisfactoria devuelve detalles de metadatos sobre cada versión del secreto.

{
  "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
}

La propiedad downloaded indica si ya se han leído o se ha accedido a los datos de cada versión del secreto. Si el campo payload_available tiene el valor true, significa que puede acceder a o restaurar los datos del secreto para dicha versión. Para obtener más información sobre los parámetros de solicitud obligatorios y opcionales, consulte el apartado Referencia de API.

Puede almacenar metadatos que sean relevantes para las necesidades de su organización con el parámetro de solicitud version_custom_metadata. Los metadatos personalizados de tu secreto se almacenan como el resto de metadatos, y no debes incluir datos confidenciales. Para obtener más información sobre los parámetros de solicitud obligatorios y opcionales, consulte la referencia de la API.

Actualización de metadatos de versiones secretas en la interfaz de usuario

Puede actualizar los metadatos de una versión específica de un secreto utilizando la interfaz de usuario de Secrets Manager.

Para actualizar los metadatos de una versión secreta, siga estos pasos.

En la consola, pulse el icono Menú > Lista de recursos.
En la lista de servicios, seleccione la instancia de Secrets Manager.
En la interfaz de usuario de Secrets Manager, vaya a la lista de Secretos.
En la fila correspondiente al secreto que desea inspeccionar, pulse el menú Acciones > Historial de versiones.

Si el secreto se ha rotado anteriormente, la página muestra información sobre las versiones actual y anterior, por ejemplo la fecha en que se creó cada versión.
Cargue un archivo o especifique los metadatos y los metadatos de versión en formato JSON.
Pulse Actualizar.

Actualización de metadatos de versiones secretas desde la CLI

Puede utilizar el plugin de CLI Secrets Manager para actualizar los metadatos de una versión específica de un secreto.

Para actualizar los metadatos de un secreto, ejecute el mandato ibmcloud secrets-manager secret-metadata-update.

El ejemplo siguiente muestra el formato del mandato 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"}'

Actualización de metadatos de versiones secretas con la API

Si está actualizando los metadatos de una versión secreta, puede utilizar la API Secrets Manager.

La siguiente solicitud de ejemplo actualiza las propiedades de metadatos de cada versión. Cuando llame a la API, sustituya las variables de ID y la señal de IAM por los valores que son específicos de la instancia de Secrets Manager. Las opciones para {secret_type} son: arbitrary, iam_credentials, imported_cert, kv, private_cert, public_cert, service_credentials, custom_credentials, y 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"

Una respuesta satisfactoria devuelve detalles de metadatos sobre cada versión del secreto.

{
  "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"
  }
}

Restaurar secretos a una versión anterior

¿Sustituir o sobrescribir accidentalmente un secreto existente? Puede utilizar IBM Cloud® Secrets Manager para retrotraer inmediatamente a la versión anterior.

Cuando se restaura un secreto a su versión anterior, se crea una nueva versión del secreto. Por ejemplo, si la versión actual de su secreto es 3 y se retrotrae a la versión 2, los datos que se restauraron de la versión 2 pasan a ser la versión 4.

Puede restaurar una versión de nuevo en tipos de secreto soportados. Para fines de auditoría, el servicio conserva los metadatos de hasta 50 versiones para cada secreto, que puede revisar como parte del historial de versiones de un secreto.

Tipos de secretos soportados

La restauración a una versión anterior está soportada para las credenciales de IAM.

Restaurar una versión anterior en la interfaz de usuario

Puede utilizar la interfaz de usuario de Secrets Manager para restaurar un secreto a su versión anterior.

En la consola, pulse el icono Menú > Lista de recursos.
En la lista de servicios, seleccione la instancia de Secrets Manager.
En la interfaz de usuario de Secrets Manager, vaya a la lista de Secretos.
En la fila correspondiente al secreto que desea inspeccionar, pulse el menú Acciones > Historial de versiones.

Si el secreto se ha rotado anteriormente, la página muestra información sobre la versión actual y la anterior.
Pulse el menú Acciones > Restaurar junto a la versión del secreto que desea restaurar.

Actualmente, sólo puede restaurar una versión para el tipo de secreto de credenciales de IAM. Una versión secreta sólo puede restaurarse si no se ha alcanzado el tiempo de vida (TTL) o la duración de alquiler definidos. Si ve que la opción no está disponible, significa que no se permite restaurar una versión.

Restauración de una versión anterior desde la CLI

Puede utilizar la CLI Secrets Manager para restaurar un secreto a su versión anterior.

El siguiente comando ejemplo restaura la versión anterior de un secreto. Cuando llame al mandato, sustituya la variable SECRET_ID por el valor específico de la instancia de Secrets Manager.

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

Actualmente, sólo se puede restaurar una versión para las credenciales IAM y los secretos de certificado importados. Una versión secreta sólo puede restaurarse si no se ha alcanzado el tiempo de vida (TTL) o la duración de alquiler definidos.

Una respuesta correcta devuelve el valor del secreto, junto con otros metadatos. Para obtener más información sobre los parámetros de solicitud necesarios y opcionales, consulte el apartado Referencia de API.

Restauración de una versión anterior con la API

Puede utilizar la API de Secrets Manager para restaurar un secreto a su versión anterior.

La siguiente solicitud de ejemplo restaura la versión anterior de un secreto. Cuando llame a la API, sustituya las variables de ID y la señal de IAM por los valores que son específicos de la instancia de Secrets Manager. Los valores permitidos para {secret_type} son: iam_credentials.

Para listar las versiones de un secreto y obtener el ID de cada versión, utilice API Listar versiones.

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"