Gerenciando segredos de chave-valor com a API de Vault

Com o IBM Cloud® Secrets Manager, é possível gerenciar várias versões por chave e acessar o histórico e os metadados do seu segredo de chave-valor usando a API HTTP HashiCorp Vault.

Secrets Manager é compatível com a API HashiCorp Vault KV Secrets Engine Version 2. Para obter mais informações sobre a API do KV v2, consulte a documentação do Vault KV v2.

Visão geral

Se você já utiliza a API do Vault, você pode usar seu formato de API e diretrizes para interagir com Secrets Manager. Secrets Manager suporta KV versão 2 apenas. Os terminais para o mecanismo de segredos de valor chave que são definidos na documentação do Vault são compatíveis com a CLI e outras ferramentas aplicáveis.

Para obter mais informações sobre autenticação, consulte API do Vault.

Para usar a API REST padrão para Secrets Manager, consulte a referência da API Secrets Manager.

Diferença entre KV e o Secrets Manager

O mecanismo de segredos de chave-valor usado pelo Secrets Manager difere levemente do mecanismo de segredos KV do Vault.

Não é possível customizar o caminho totalmente. O caminho para um segredo de chave-valor deve ser:
- O {secret_group_id}/{secret_name} para segredos que estão localizados em um grupo de segredo customizado.
- o /{secret_name} para segredos que estão no grupo padrão.
Os métodos que são usados no Vault para configurar o motor key-value engine e read the configuration não são suportados.

Criar ou atualizar um segredo de chave-valor

Crie uma versão de um segredo de chave-valor.

Exemplo de solicitação

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "data": {
                "key":"value"
            }
    }'

Criar ou atualizar parâmetros de solicitação de segredo de valor-chave
Parâmetro de solicitação	Descrição
`instance_id`	O ID da instância do Secrets Manager.
`region`	A região na qual a instância do Secrets Manager foi criada.
`secret_name`	O nome do segredo de chave-valor.
`Vault-Token`	O token de autenticação que é recuperado do Vault.
`data`	Obrigatório. Os dados de segredos em formato JSON para designar ao segredo. O tamanho máximo do arquivo é 512 KB.

Exemplo de resposta

Uma solicitação para atualizar um segredo de chave-valor no grupo de segredo do default retorna a seguinte resposta:

{
    "request_id": "9000000d4-f0000-4c000-000000-800000000f",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "created_time": "2022-02-09T23:41:58.888138788Z",
        "deletion_time": "",
        "destroyed": false,
        "version": 2
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Veja uma versão de um segredo de chave-valor

Obtenha uma versão de um segredo de chave-valor. Uma solicitação bem-sucedida retorna os dados do segredo que estão associados com a versão especificada do seu segredo, junto a outros metadados.

Exemplo de solicitação

curl -X GET 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}?version={version}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}'

Ler uma versão dos parâmetros de uma solicitação de segredo de valor-chave
Parâmetro de solicitação	Descrição
`instance_id`	O ID da instância do Secrets Manager.
`region`	A região na qual a instância do Secrets Manager foi criada.
`secret_name`	O nome do segredo de chave-valor.
`version`	As versões que você deve ler.
`Vault-Token`	O token de autenticação que é recuperado do Vault.

Exemplo de resposta

Uma solicitação para obter uma versão de um segredo de chave-valor no grupo de segredo do default retorna a seguinte resposta:

{
    "request_id": "400000-60000-8e000-0ad0-00000bc0000caebe",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "data": {
            "key": "value"
        },
        "metadata": {
            "created_time": "2022-01-13T21:31:49.893962888Z",
            "deletion_time": "",
            "destroyed": false,
            "version": 1
        }
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Exclua a versão mais recente de um segredo de chave-valor

Exclua a versão mais recente de um segredo de chave-valor. Depois de excluir a versão, não é possível recuperá-la usando chamadas de API do list ou do get. No entanto, é uma exclusão reversível e os dados subjacentes não serão removidos. É possível desfazer a exclusão chamando o terminal da API desfazer exclusão.

Exemplo de solicitação

curl -X DELETE 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}'

Excluir a versão mais recente de um parâmetro de solicitação de segredo de valor-chave
Parâmetro de solicitação	Descrição
`instance_id`	O ID da instância do Secrets Manager.
`region`	A região na qual a instância do Secrets Manager foi criada.
`secret_name`	O nome do segredo de chave-valor.
`Vault-Token`	O token de autenticação que é recuperado do Vault.

Exemplo de resposta

Uma solicitação para excluir a versão mais recente de um segredo de chave-valor no grupo de segredos do default retorna uma resposta em branco com um código de status 204 para confirmar que a versão mais recente foi excluída.

Exclua versões especificadas de um segredo de chave-valor

Exclua as versões especificadas de um segredo de chave-valor. Depois de excluir as versões, não será possível recuperá-las usando chamadas de API do list ou do get. No entanto, é uma exclusão reversível e os dados subjacentes não serão removidos. É possível desfazer a exclusão chamando o terminal da API desfazer exclusão.

Exemplo de solicitação

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/delete/test-kv' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -d '{
            "versions": [1, 2]
            }'

Excluir versões especificadas de parâmetros de solicitação de segredo de valor-chave
Parâmetro de solicitação	Descrição
`instance_id`	O ID da instância do Secrets Manager.
`region`	A região na qual a instância do Secrets Manager foi criada.
`secret_name`	O nome do segredo de chave-valor.
`Vault-Token`	O token de autenticação que é recuperado do Vault.
`versions`	As versões especificadas que devem ser excluídas.

Exemplo de resposta

Uma solicitação para obter as versões especificadas excluídas de um segredo de chave-valor no grupo de segredos do default retorna a resposta a seguir:

{
    "request_id": "43abde16-6a33-971f-1690-469eccc00d91",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": null,
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Desfazer a exclusão de um segredo de chave-valor

Restaurar uma versão excluída anteriormente de um segredo de chave-valor.

Exemplo de solicitação

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/undelete/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "versions": [
                1, 2
                ]
            }

Anular a exclusão de uma versão de parâmetros de solicitação de segredo de valor-chave
Parâmetro de solicitação	Descrição
`instance_id`	O ID da instância do Secrets Manager.
`region`	A região na qual a instância do Secrets Manager foi criada.
`secret_name`	O nome do segredo de chave-valor.
`Vault-Token`	O token de autenticação que é recuperado do Vault.
`versions`	As versões do segredo de chave-valor que você deseja excluir.

Exemplo de resposta

Uma solicitação para restaurar uma versão de um segredo de chave-valor no grupo de segredo default retorna uma resposta em branco com um código de status 204 para confirmar se as versões especificadas foram restauradas.

Destruir versões de um segredo

Saiba como destruir versões especificadas de um segredo de chave-valor permanentemente. Para fazer a exclusão reversível de versões de um segredo, use o terminal de API de versões especificadas para exclusão.

Exemplo de solicitação

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/destroy/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "versions": [1, 3]
            }'

Destruir versões de parâmetros de solicitação de segredo de valor-chave
Parâmetro de solicitação	Descrição
`instance_id`	O ID da instância do Secrets Manager.
`region`	A região na qual a instância do Secrets Manager foi criada.
`secret_name`	O nome do segredo de chave-valor.
`Vault-Token`	O token de autenticação que é recuperado do Vault.
`versions`	As versões do segredo de chave-valor que você deve destruir permanentemente.

Exemplo de resposta

Uma solicitação para destruir permanentemente versões de um segredo de chave-valor no grupo de segredo do default retorna uma resposta em branco com um código de status 204 para confirmar que as versões do segredo foram destruídas.

Criar ou atualizar metadados de segredos de chave-valor

Crie ou atualize os metadados de um segredo de chave-valor, como o número máximo de versões ou outros valores customizados. Para atualizar o conteúdo real do segredo, use o método para Criar ou atualizar um segredo.

Exemplo de solicitação

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/metadata/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "custom_metadata": {
                "meta1": "data1",
                "meta2": "data2"
                }
            }'

Atualizar os metadados dos parâmetros de uma solicitação de segredo de valor-chave
Parâmetro de solicitação	Descrição
`instance_id`	O ID da instância do Secrets Manager.
`region`	A região na qual a instância do Secrets Manager foi criada.
`secret_name`	O nome do segredo de chave-valor.
`Vault-Token`	O token de autenticação que é recuperado do Vault.

Exemplo de resposta

Uma solicitação para atualizar os metadados de um segredo de chave-valor no grupo de segredo do default retorna uma resposta em branco com um código de status 204 para confirmar que os metadados do segredo foram atualizados.

Ler metadados de segredo de chave-valor

Obtenha os metadados de um segredo de chave-valor especificando o ID da versão.

Exemplo de solicitação

curl -X GET 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/metadata/{secret_name}' \
    -H 'Accept: application/json'
    -H 'X-Vault-Token: {Vault-Token}'

Ler os metadados de um parâmetro de solicitação de segredo de valor-chave
Parâmetro de solicitação	Descrição
`instance_id`	O ID da instância do Secrets Manager.
`region`	A região na qual a instância do Secrets Manager foi criada.
`secret_name`	O nome do segredo de chave-valor.
`Vault-Token`	O token de autenticação que é recuperado do Vault.

Exemplo de resposta

Uma solicitação para obter os metadados de um segredo de chave-valor no grupo de segredo do default retorna a resposta a seguir:

{
    "request_id": "400000-60000-8e000-0ad0-00000bc0000caebe",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "cas_required": false,
        "created_time": "2022-01-13T21:31:49.893962888Z",
        "current_version": 3,
        "custom_metadata" : {
              "meta1": "data1",
              "meta2": "data2"    
        },
        "delete_version_after": "0s",
        "max_versions": 0,
        "oldest_version": 0,
        "updated_time": "2022-02-09T23:54:16.313286558Z",
        "versions": {
            "1": {
                "created_time": "2022-01-13T21:31:49.893962888Z",
                "deletion_time": "",
                "destroyed": false
            },
            "2": {
                "created_time": "2022-02-09T23:41:58.888138788Z",
                "deletion_time": "",
                "destroyed": false
            },
            "3": {
                "created_time": "2022-02-09T23:54:16.313286558Z",
                "deletion_time": "",
                "destroyed": false
            }
        }
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Exclua os metadados e todas as versões de um segredo de chave-valor

Exclua os metadados e todos os dados de versão de um segredo de chave-valor especificado permanentemente. Todo o histórico da versão é removido quando você usa este terminal de API.

Exemplo de solicitação

curl -X DELETE 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/metadata/{secret_name}' \
    -H 'Accept: application/json'
    -H 'X-Vault-Token: {Vault-Token}'

Excluir os metadados de um parâmetro de solicitação de segredo de valor-chave
Parâmetro de solicitação	Descrição
`instance_id`	O ID da instância do Secrets Manager.
`region`	A região na qual a instância do Secrets Manager foi criada.
`secret_name`	O nome do segredo de chave-valor.
`Vault-Token`	O token de autenticação que é recuperado do Vault.

Exemplo de resposta

Uma solicitação para excluir os metadados e todas as versões de um segredo de chave-valor no grupo de segredo do default retorna a resposta a seguir:

{
    "request_id": "62b1e2c2-801a-6592-0526-edb38896a546",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": null,
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Liste os nomes de um segredo de chave-valor

Obtenha uma lista com os principais nomes de um segredo de chave-valor. Não codifique informações sensíveis em nomes de chaves. Os valores das chaves não são acessíveis usando este comando.

Em {sm-short}, você não pode usar o verbo LIST HTTP para obter a lista de nomes de chaves. É possível fazer isso apenas na API do KV do Vault

Exemplo de solicitação

curl -X GET "https://{instance_id}.{region}.secrets-manager.test.appdomain.cloud/v1/ibmcloud/kv/metadata/?list=true" \
    -H 'Accept: application/json'\
    -H 'X-Vault-Token: {Vault-Token}'

Listar os nomes das chaves de um parâmetro de solicitação de segredo de valor-chave
Parâmetro de solicitação	Descrição
`instance_id`	O ID da instância do Secrets Manager.
`region`	A região na qual a instância do Secrets Manager foi criada.
`Vault-Token`	O token de autenticação que é recuperado do Vault.

Exemplo de resposta

Uma solicitação para listar os principais nomes de um segredo de chave-valor no grupo de segredos do default retorna a seguinte resposta:

{
    "request_id": "a21993df-a4b7-21f1-95a9-c1af7be87d1b",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "keys": [
            "secret1",
            "secret2"
        ]
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Patch um segredo de valor chave

Atualize um segredo de valor de chave existente fornecendo apenas os detalhes que você deseja alterar. Quando você patch um segredo, uma nova versão é criada. Qualquer dado que você não mude permanece exatamente como ele está na versão anterior do segredo.

Exemplo de solicitação

curl -X PATCH 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/merge-patch+json' \
    -d '{
            "data": {
                "key":"value"
            }
    }'

Criar ou atualizar parâmetros de solicitação de segredo de valor-chave
Parâmetro de solicitação	Descrição
`instance_id`	O ID da instância do Secrets Manager.
`region`	A região na qual a instância do Secrets Manager foi criada.
`secret_name`	O nome do segredo de chave-valor.
`Vault-Token`	O token de autenticação que é recuperado do Vault.
`data`	Obrigatório. Os dados secretos em formato JSON para corrigir o segredo com. O tamanho máximo do arquivo é 512 KB.

Exemplo de resposta

Uma solicitação para atualizar um segredo de chave-valor no grupo de segredo do default retorna a seguinte resposta:

{
    "request_id": "9000000d4-f0000-4c000-000000-800000000f",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "created_time": "2022-02-09T23:41:58.888138788Z",
        "deletion_time": "",
        "destroyed": false,
        "version": 2
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}