Gerenciando versões de segredos

Ao girar um segredo no IBM Cloud® Secrets Manager, você cria uma nova versão de seu valor. Você pode usar o site IBM Cloud® Secrets Manager para visualizar o histórico de versões e atualizar os metadados de versão dos segredos. Se você substituir ou sobrescrever acidentalmente um segredo, você também poderá restaurá-lo para uma versão anterior.

Antes de Iniciar

Antes de começar, certifique-se de ter o nível de acesso necessário. Para atualizar os metadados de uma versão de segredo ou restaurar um segredo para sua versão anterior, é necessária a função de serviço Gravador ou superior Para visualizar o histórico de versão de um segredo, é necessária a função de serviço Reader ou superior

Visualizando o histórico de versões dos segredos

Ao girar um segredo no IBM Cloud® Secrets Manager, você cria uma nova versão de seu valor. É possível examinar rapidamente o histórico de versões de seus segredos usando a IU ou API.

Secrets Manager retém até 50 versões de um segredo para fins de auditoria, incluindo metadados secretos. No entanto, somente a versão atual e a imediatamente anterior incluem os dados secretos, enquanto as versões anteriores não.

Visualizando o histórico de versões na IU

Se você estiver auditando o histórico de versões de um segredo, é possível usar a IU do Secrets Manager para visualizar as características gerais de cada rotação.

No console, clique no ícone Menu > Lista de Recursos.
Na lista de serviços, selecione sua instância do Secrets Manager.
Na IU do Secrets Manager, acesse a sua lista de Segredos.
Na linha para o segredo que deseja inspecionar, clique no menu Ações > Histórico da versão.
Opcional: Atualize os metadados da versão específica do segredo que você está visualizando.
1. Para atualizar os metadados de sua versão secreta, faça o upload de um arquivo ou insira os metadados e os metadados da versão no formato JSON.
2. Clique em Atualizar.

Listando versões de segredo da CLI

Se você estiver auditando o histórico de versões de um segredo, é possível usar o plug-in da CLI do Secrets Manager para visualizar as características gerais de cada rotação.

Para listar todas as versões que estão associadas a um segredo, execute o comando ibmcloud secrets-manager secret-versions. As opções para SECRET_TYPE são: 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

O comando supera informações sobre as versões atuais e anteriores. Por exemplo, a data em que cada versão foi criada. Para obter mais informações sobre as opções de comando, consulte ibmcloud secrets-manager secret-versions.

Listando versões de segredo com a API

Se você estiver auditando o histórico de versões de um segredo, é possível usar a API do Secrets Manager para visualizar as características gerais de cada rotação.

A solicitação de exemplo a seguir lista as propriedades de metadados para cada versão. Ao chamar a API, substitua as variáveis de ID e o token IAM pelos valores que são específicos para a sua instância do Secrets Manager. As opções para {secret_type} são: 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"

Uma resposta bem-sucedida retorna detalhes de metadados sobre cada versão de segredo.

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

A propriedade downloaded indica se os dados de cada versão de segredo já foram lidos ou acessados. Se o campo payload_available tiver um valor de true, significa que você é capaz de acessar ou restaurar os dados de segredos dessa versão. Para obter mais informações sobre os parâmetros de solicitação opcionais e necessários, confira a Referência de API.

Você pode armazenar metadados que são relevantes para as necessidades de sua organização com o parâmetro de solicitação version_custom_metadata. Os metadados personalizados de seu segredo são armazenados como todos os outros metadados, e você não deve incluir dados confidenciais. Para obter mais informações sobre os parâmetros de solicitação obrigatórios e opcionais, consulte a referência da API.

Atualização de metadados de versões secretas na UI

Você pode atualizar os metadados de uma versão específica de um segredo usando a UI do Secrets Manager.

Para atualizar os metadados de uma versão secreta, conclua as etapas a seguir.

No console, clique no ícone Menu > Lista de Recursos.
Na lista de serviços, selecione sua instância do Secrets Manager.
Na IU do Secrets Manager, acesse a sua lista de Segredos.
Na linha para o segredo que deseja inspecionar, clique no menu Ações > Histórico da versão.

Se o segredo tiver sido girado anteriormente, a página exibirá informações sobre as versões atuais e anteriores, como, por exemplo, a data em que cada versão foi criada.
Faça o upload de um arquivo ou insira os metadados e os metadados da versão no formato JSON.
Clique em Atualizar.

Atualização de metadados de versões secretas da CLI

Você pode usar o plug-in CLI Secrets Manager para atualizar os metadados de uma versão específica de um segredo.

Para atualizar os metadados de um segredo, execute o comando ibmcloud secrets-manager secret-metadata-update.

O exemplo a seguir mostra o formato do 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"}'

Atualização de metadados de versões secretas com a API

Se você está atualizando os metadados de uma versão secreta, você pode usar a API Secrets Manager.

O exemplo de solicitação a seguir atualiza as propriedades de metadados de cada versão. Ao chamar a API, substitua as variáveis de ID e o token IAM pelos valores que são específicos para a sua instância do Secrets Manager. As opções para {secret_type} são: 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"

Uma resposta bem-sucedida retorna detalhes de metadados sobre cada versão de segredo.

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

Restaurando segredos para uma versão anterior

Substituiu ou sobrescreveu acidentalmente um segredo existente? É possível usar o IBM Cloud® Secrets Manager para retroceder imediatamente para a versão anterior.

Ao restaurar um segredo para sua versão anterior, uma nova versão do segredo é criada. Por exemplo, se a versão atual do seu segredo for 3 e você retroceder para a versão 2, os dados que foram restaurados da versão 2 se tornam a versão 4.

Você pode restaurar uma versão de volta em tipos secretos suportados. Para fins de auditoria, o serviço retém os metadados de até 50 versões para cada segredo, o que é possível revisar como parte de um histórico de versões do segredo.

Tipos de segredos suportados

A restauração para uma versão anterior é suportada para credenciais do IAM.

Restaurando uma versão anterior na UI

É possível usar a IU do Secrets Manager para restaurar um segredo para sua versão anterior.

No console, clique no ícone Menu > Lista de Recursos.
Na lista de serviços, selecione sua instância do Secrets Manager.
Na IU do Secrets Manager, acesse a sua lista de Segredos.
Na linha para o segredo que deseja inspecionar, clique no menu Ações > Histórico da versão.

Se o segredo foi girado anteriormente, a página exibirá informações sobre as versões atuais e anteriores.
Clique no menu Ações > Restauração ao lado da versão do segredo que você deseja restaurar.

Atualmente, é possível restaurar apenas uma versão de volta para o tipo de segredo de credenciais do IAM Uma versão secreta pode ser restaurada somente se o tempo de vida (TTL) definido ou a duração da concessão não tiver sido atingida. Se uma opção disponível não for exibida, a restauração de uma versão não é suportada.

Restaurando uma versão anterior a partir da CLI

Você pode usar a CLI do Secrets Manager para restaurar um segredo à sua versão anterior.

O comando de exemplo a seguir restaura a versão anterior de um segredo. Ao chamar o comando, substitua a variável SECRET_ID pelo valor específico para sua instância do Secrets Manager.

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

Atualmente, você pode restaurar apenas uma versão de volta para credenciais IAM e segredos de certificados importados. Uma versão secreta pode ser restaurada somente se o tempo de vida (TTL) definido ou a duração da concessão não tiver sido atingida.

Uma resposta bem-sucedida retorna o valor do segredo, além de outros metadados. Para obter mais informações sobre os parâmetros de solicitação opcionais e necessários, consulte a Referência de API.

Restaurando uma versão anterior com a API

É possível usar a API do Secrets Manager para restaurar um segredo para sua versão anterior.

A solicitação de exemplo a seguir restaura a versão anterior de um segredo. Ao chamar a API, substitua as variáveis de ID e o token IAM pelos valores que são específicos para a sua instância do Secrets Manager. Os valores permitidos para {secret_type} são: iam_credentials.

Para listar as versões de um segredo e obter o ID de cada versão, use a API de versões de lista.

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"