Gestione delle versioni dei segreti

Quando si ruota un segreto in IBM Cloud® Secrets Manager, si crea una nuova versione del suo valore. È possibile utilizzare IBM Cloud® Secrets Manager per visualizzare la cronologia delle versioni e aggiornare i metadati delle versioni dei segreti. Se si sostituisce o sovrascrive accidentalmente un segreto, è anche possibile ripristinarlo ad una versione precedente.

Prima di iniziare

Prima di iniziare, assicurarsi di disporre del livello di accesso richiesto. Per aggiornare i metadati di una versione segreta o ripristinare un segreto alla versione precedente, hai bisogno del ruolo del servizio Writer o superiore. Per visualizzare la cronologia della versione di un segreto, hai bisogno del ruolo del servizio Reader o superiore.

Visualizzazione della cronologia delle versioni dei segreti

Quando si ruota un segreto in IBM Cloud® Secrets Manager, si crea una nuova versione del suo valore. Puoi esaminare rapidamente la cronologia delle versioni dei tuoi segreti utilizzando l'IU o l'API.

Secrets Manager conserva fino a 50 versioni di un segreto a fini di verifica, compresi i metadati del segreto. Tuttavia, solo la versione attuale e quella immediatamente precedente includono i dati segreti, mentre le versioni precedenti non li includono.

Visualizzazione della cronologia delle versioni nell'interfaccia utente

Se stai controllando la cronologia della versione di un segreto, puoi utilizzare l'IU Secrets Manager per visualizzare le caratteristiche generali di ciascuna rotazione.

Nella console, fai clic su Menu icon > Resource List.
Dall'elenco di servizi, seleziona la tua istanza di Secrets Manager.
Nell'interfaccia utente Secrets Manager, vai all'elenco Secrets.
Nella riga del segreto che vuoi ispezionare, fai clic sul menu Azioni > Cronologia versioni.
Facoltativo: aggiornare i metadati della versione specifica del segreto che si sta visualizzando.
1. Per aggiornare i metadati della versione segreta, caricare un file o immettere i metadati e i metadati della versione in formato JSON.
2. Fai clic su Aggiorna.

Elenco delle versioni segrete dalla CLI

Se stai controllando la cronologia della versione di un segreto, puoi utilizzare il plug-in CLI Secrets Manager per visualizzare le caratteristiche generali di ogni rotazione.

Per elencare tutte le versioni associate a un segreto, eseguire il comando ibmcloud secrets-manager secret-versions. Le opzioni per SECRET_TYPE sono: arbitrary, iam_credentials, imported_cert, kv, private_cert, public_cert, service_credentials, custom_credentials, e username_password.

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

Il comando emette informazioni sulle versioni correnti e precedenti. Ad esempio, la data in cui è stata creata ciascuna versione. Per ulteriori informazioni relative alle opzioni del comando, consultare ibmcloud secrets-manager secret-versions.

Elenco delle versioni segrete con l'API

Se stai controllando la cronologia delle versione di un segreto, puoi utilizzare l'API Secrets Manager per visualizzare le caratteristiche generali di ogni rotazione.

La seguente richiesta di esempio elenca le proprietà dei metadati per ciascuna versione. Quando si chiama l'API, sostituire le variabili ID e il token IAM con i valori specifici dell'istanza Secrets Manager. Le opzioni per {secret_type} sono: arbitrary, iam_credentials, imported_cert, kv, private_cert, public_cert, service_credentials, custom_credentials, e 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 risposta corretta restituisce i dettagli dei metadati relativi a ciascuna versione segreta.

{
  "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 proprietà downloaded indica se i dati per ciascuna versione segreta sono già stati letti o acceduti. Se il valore del campo payload_available è true, significa che puoi accedere o ripristinare i dati segreti di tale versione. Per ulteriori informazioni sui parametri di richiesta obbligatori e facoltativi, consulta la Guida di riferimento API.

È possibile memorizzare i metadati pertinenti alle necessità della propria azienda con il parametro di richiesta version_custom_metadata. I metadati personalizzati del segreto vengono memorizzati come tutti gli altri metadati e non devono includere dati riservati. Per ulteriori informazioni sui parametri di richiesta obbligatori e facoltativi, consulta la Guida di riferimento API.

Aggiornamento dei metadati delle versioni segrete nell'interfaccia utente

Puoi aggiornare i metadati di una versione specifica di un segreto utilizzando l'IU Secrets Manager.

Per aggiornare i metadati di una versione segreta, completare la seguente procedura.

Nella console, fai clic su Menu icon > Resource List.
Dall'elenco di servizi, seleziona la tua istanza di Secrets Manager.
Nell'interfaccia utente Secrets Manager, vai all'elenco Secrets.
Nella riga del segreto che vuoi ispezionare, fai clic sul menu Azioni > Cronologia versioni.

Se il segreto è stato ruotato in precedenza, la pagina visualizza le informazioni sulle versioni correnti e precedenti, ad esempio la data in cui è stata creata ciascuna versione.
Caricare un file o immettere i metadati e i metadati della versione in formato JSON.
Fai clic su Aggiorna.

Aggiornamento dei metadati delle versioni segrete dalla CLI

Puoi utilizzare il plug-in della CLI Secrets Manager per aggiornare i metadati di una specifica versione di un segreto.

Per aggiornare i metadati di un segreto, eseguire il comando ibmcloud secrets-manager secret-metadata-update.

Il seguente esempio mostra il formato del comando 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"}'

Aggiornamento dei metadati delle versioni segrete con l'API

Se stai aggiornando i metadati di una versione segreta, puoi utilizzare l'API Secrets Manager.

Il seguente esempio di richiesta aggiorna le proprietà dei metadati per ciascuna versione. Quando si chiama l'API, sostituire le variabili ID e il token IAM con i valori specifici dell'istanza Secrets Manager. Le opzioni per {secret_type} sono: arbitrary, iam_credentials, imported_cert, kv, private_cert, public_cert, service_credentials, custom_credentials, e 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 risposta corretta restituisce i dettagli dei metadati relativi a ciascuna versione segreta.

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

Ripristino dei segreti a una versione precedente

Sostituire o sovrascrivere accidentalmente un segreto esistente? È possibile utilizzare IBM Cloud® Secrets Manager per tornare immediatamente alla versione precedente.

Quando si ripristina un segreto alla versione precedente, viene creata una nuova versione del segreto. Ad esempio, se la versione corrente del segreto è 3 e si esegue il rollback alla versione 2, i dati ripristinati dalla versione 2 diventano la versione 4.

Puoi ripristinare una versione su tipi di segreto supportati. Per scopi di verifica, il servizio conserva i metadati fino a 50 versioni per ogni segreto, che puoi esaminare come parte della cronologia delle versioni di un segreto.

Tipi di segreto supportati

Il ripristino a una versione precedente è supportato per credenziali IAM.

Ripristino di una versione precedente nell'interfaccia utente

Puoi utilizzare l'IU Secrets Manager per ripristinare un segreto alla sua versione precedente.

Nella console, fai clic su Menu icon > Resource List.
Dall'elenco di servizi, seleziona la tua istanza di Secrets Manager.
Nell'interfaccia utente Secrets Manager, vai all'elenco Secrets.
Nella riga del segreto che vuoi ispezionare, fai clic sul menu Azioni > Cronologia versioni.

Se il segreto è stato ruotato in precedenza, la pagina visualizza le informazioni sulle versioni correnti e precedenti.
Fare clic sul menu Azioni > Ripristina accanto alla versione del segreto che si desidera ripristinare.

Attualmente, è possibile ripristinare solo una versione per il tipo di segreto delle credenziali IAM. Una versione segreta può essere ripristinata solo se il TTL (time - to - live) definito o la durata del lease non è stata raggiunta. Se non vedi un'opzione disponibile, il ripristino di una versione non è supportato.

Ripristino di una versione precedente dalla CLI

Puoi utilizzare la CLI Secrets Manager per ripristinare un segreto alla versione precedente.

Il seguente comando di esempio ripristina la versione precedente di un segreto. Quando richiami il comando, sostituisci la variabile SECRET_ID con il valore specifico della tua istanza Secrets Manager.

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

Attualmente, puoi ripristinare solo una versione per le credenziali IAM e i segreti dei certificati importati. Una versione segreta può essere ripristinata solo se il TTL (time - to - live) definito o la durata del lease non è stata raggiunta.

Una risposta corretta restituisce il valore del segreto, insieme ad altri metadati. Per ulteriori informazioni sui parametri di richiesta obbligatori e facoltativi, consulta la Guida di riferimento API.

Ripristino di una versione precedente con l'API

Puoi utilizzare l'API Secrets Manager per ripristinare un segreto alla versione precedente.

La seguente richiesta di esempio ripristina la versione precedente di un segreto. Quando si chiama l'API, sostituire le variabili ID e il token IAM con i valori specifici dell'istanza Secrets Manager. I valori consentiti per {secret_type} sono: iam_credentials.

Per elencare le versioni di un segreto e ottenere l'ID di ogni versione, utilizza l'API List versions.

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"