Using the Secret Manager with the HashiCorp Vault KV2 compliant API

Objective

The objective of this guide is to present the use of the HashiCorp Vault KV2 compliant API for the Secret Manager.

Requirements

• An OVHcloud customer account.
• Have ordered an OKMS domain or created a first secret.
• An authentication method configured for the OKMS data plane.

Instructions

Description

The Secret Manager is a product that allows you to securely store credentials, API keys, SSH keys, or any other type of secret necessary for the operation of your applications.

A secret is a collection of one or more key-value pairs grouped within a version. Each modification of a secret creates a new version of that secret, allowing you to go back in the history of changes to the secret.

The HashiCorp Vault KV2 compliant APIs are one of the two API sets offered by the Secret Manager, along with the REST API. They are designed to be similar to HashiCorp Vault APIs to ensure compatibility with applications already compatible with HashiCorp Vault.

Contacting the OKMS domain

Communication with the OKMS domain for encryption and signature actions is available via APIs.

Since the OKMS domain is regionalized, you can access the API directly in its region: https://my-region.okms.ovh.net.

For example, for a OKMS domain created in the eu-west-rbx region: https://eu-west-rbx.okms.ovh.net.

It's possible to communicate with the OKMS domain using:

• The Swagger UI
• The OKMS CLI: https://github.com/ovh/okms-cli
• The Golang SDK: https://pkg.go.dev/github.com/ovh/okms-sdk-go

Authenticate using a Personal Access Token, service account, or access certificate. For HashiCorp Vault KV2 compliant API usage, a PAT or service account is recommended.

To test API calls interactively, use the OKMS Swagger UI at https://<region>.okms.ovh.net/swagger/.

Create a Secret

To create a secret, you can use the following API:

The secret's path must be specified in the API path.

The API expects the following values:

For example:

{
  "data": {
      "login": "admin",
      "password": "my_secret_password",
      "address": {
        "ip": "1.1.1.1"
      },
      "ports": [
        "30",
        "31"
      ]
  },
  "options": {
      "cas": 0
  }
}

It is also possible to add metadata to the secret via the API:

The API expects the following values:

For example:

{
  "cas_required": true,
  "custom_metadata": {
    "project": "A",
    "team": "X"
  },
  "deactivate_version_after": "10h30m10s",
  "max_versions": 5
}

Manage Secrets

Update Metadata and configuration

Once the secret is created, it is possible to update the secret's metadata or configuration.

The API expects the following values:

It is also possible to change the default configuration of the OKMS domain for the values cas_required, deactivate_version_after, and max_versions using the API:

Create a new version

It is also possible to modify the secret's content, which implies creating a new version for the secret. New versions can be created using the API:

A secret can contain as many versions as desired, up to the maximum limit of the max_versions parameter. If the maximum number of versions is reached, the oldest version is automatically deleted.

Manage versions

It is possible to manage the different versions of the secret using the API:

Deactivated versions of a secret are still present in the Secret Manager, but their content is no longer accessible.

It is possible to reactivate a version via the API:

Finally, it is possible to permanently delete a version via the API:

It's also possible to permanently delete the whole secret with all his versions:

Go further

OKMS authentication methods

Join our community of users.