Utilizar o Secret Manager com a API REST

Objetivo

O objetivo deste manual é apresentar a utilização da API REST para o Secret Manager.

Requisitos

• Uma conta de cliente OVHcloud.
• Ter encomendado um domínio OKMS ou criado um primeiro segredo.
• Ter configurado um método de autenticação para o plano de dados OKMS.

Instruções

Descrição

O Secret Manager é um produto que lhe permite armazenar de forma segura as credenciais, chaves de API, chaves SSH ou qualquer outro tipo de segredo necessário ao funcionamento das suas aplicações.

Um segredo é uma coleção de uma ou várias chaves/valores agrupadas numa versão. Cada modificação de um segredo origina a criação de uma nova versão desse segredo, permitindo recuar no histórico de modificações do segredo.

As API REST são um dos dois conjuntos de API oferecidos pelo Secret Manager, juntamente com as API compatíveis com HashiCorp Vault KV2. Foram concebidas para serem semelhantes ao conjunto de API da OVHcloud, bem como às API OKMS para o Key Management Service.

As API REST podem ser utilizadas através das API centralizadas da OVHcloud ou diretamente no domínio OKMS na região. A única diferença reside no caminho de API exato:

• API centralizada da OVHcloud: /v2/okms/resource/{okmsId}/secret/{path}
• API regionalizada OKMS: /api/{okmsId}/v2/secret/{path}

Esta documentação centrar-se-á nas API do domínio OKMS na região.

Comunicar com o domínio OKMS

A comunicação com o domínio OKMS para as operações de encriptação e assinatura está disponível através da API.

Como o domínio OKMS é regionalizado, o acesso à API é feito diretamente na sua região: https://my-region.okms.ovh.net.

Por exemplo, para um domínio OKMS criado na região eu-west-rbx: https://eu-west-rbx.okms.ovh.net.

É possível comunicar com o domínio OKMS utilizando:

• A interface de utilizador Swagger
• A CLI OKMS: https://github.com/ovh/okms-cli
• O SDK Golang: https://pkg.go.dev/github.com/ovh/okms-sdk-go

Autentique-se através de um token de acesso pessoal, uma conta de serviço ou um certificado de acesso. Para a utilização da API REST, é recomendado um token de acesso pessoal (PAT) ou uma conta de serviço.

Para testar as chamadas à API de forma interativa, utilize a interface Swagger OKMS no endereço https://<region>.okms.ovh.net/swagger/.

Criar um segredo

Para criar um segredo, pode utilizar a seguinte API:

A API espera os seguintes valores:

Por exemplo:

{
  "metadata": {
    "cas_required": true,
    "custom_metadata": {
      "project": "A",
      "team": "X"
    },
    "deactivate_version_after": "10h30m10s",
    "max_versions": 5
  },
  "path": "prod/database/MySQL",
  "version": {
    "data": {
      "login": "admin",
      "password": "my_secret_password",
      "address": {
        "ip": "1.1.1.1"
      },
      "ports": [
        "30",
        "31"
      ]
    }
  }
}

Gerir os segredos

Atualizar os metadados e a configuração

Depois de criado o segredo, é possível atualizar os metadados do segredo ou a sua configuração.

A API espera os seguintes valores:

Também é possível alterar a configuração predefinida do domínio OKMS para os valores cas_required, deactivate_version_after e max_versions através da API:

Criar uma nova versão

Também é possível modificar o conteúdo do segredo, o que implica a criação de uma nova versão para esse segredo. As novas versões podem ser criadas através da API:

Quer a modificação dos data do segredo seja feita através da API geral de atualização do segredo ou da API específica, é criada uma nova versão do segredo.

Um segredo pode conter tantas versões quantas desejar, dentro do limite máximo do parâmetro max_versions. Se o número máximo de versões for atingido, a versão mais antiga é eliminada automaticamente.

Gerir as versões

É possível gerir as diferentes versões do segredo através da API:

A API espera o único valor:

Quer saber mais?

Métodos de autenticação OKMS

Fale com a nossa comunidade de utilizadores.