Verwendung des Secret Manager mit der REST-API

Auf die Secrets des Secret Manager über die REST-API zugreifen und sie verwalten

Ziel

Das Ziel dieser Anleitung ist es, die Verwendung der REST-API für den Secret Manager vorzustellen.

Voraussetzungen

Sie verfügen über einen OVHcloud Kunden-Account.
Sie haben eine OKMS-Domain bestellt oder ein erstes Secret erstellt.
Sie haben für die OKMS-Datenebene eine Authentifizierungsmethode konfiguriert.

In der praktischen Anwendung

Beschreibung

Der Secret Manager ist ein Produkt, mit dem Sie Zugangsdaten, API-Schlüssel, SSH-Schlüssel oder jede andere Art von Secret, die für den Betrieb Ihrer Anwendungen erforderlich ist, sicher speichern können.

Ein Secret ist eine Sammlung eines oder mehrerer Schlüssel-Wert-Paare, die innerhalb einer Version zusammengefasst sind. Jede Änderung eines Secrets erzeugt eine neue Version dieses Secrets, wodurch Sie im Änderungsverlauf des Secrets zurückgehen können.

Die REST-APIs sind eines der beiden API-Sets, die der Secret Manager bietet, neben der mit HashiCorp Vault KV2 kompatiblen API. Diese APIs sind so konzipiert, dass sie dem OVHcloud API-Set sowie den OKMS-APIs für den Key Management Service ähneln.

Die REST-APIs können entweder über die zentralisierte OVHcloud API oder direkt auf der OKMS-Domain in der Region verwendet werden. Der einzige Unterschied liegt im genauen API-Pfad:

Zentralisierte OVHcloud API: /v2/okms/resource/{okmsId}/secret/{path}
Regionalisierte OKMS-API: /api/{okmsId}/v2/secret/{path}

Diese Dokumentation konzentriert sich auf die APIs der OKMS-Domain in der Region.

Kommunikation mit der OKMS-Domain

Die Kommunikation mit der OKMS-Domain für Verschlüsselungs- und Signaturaktionen ist über APIs verfügbar.

Da die OKMS-Domain regionalisiert ist, können Sie direkt in ihrer Region auf die API zugreifen: https://my-region.okms.ovh.net.

Zum Beispiel für eine OKMS-Domain, die in der Region eu-west-rbx erstellt wurde: https://eu-west-rbx.okms.ovh.net.

Es ist möglich, mit der OKMS-Domain über Folgendes zu kommunizieren:

Die Swagger-Benutzeroberfläche
Die OKMS-CLI: https://github.com/ovh/okms-cli
Das Golang-SDK: https://pkg.go.dev/github.com/ovh/okms-sdk-go

Authentifizieren Sie sich mit einem Personal Access Token, einem Service-Account oder einem Zugriffszertifikat. Für die Nutzung der REST-API wird ein PAT oder ein Service-Account empfohlen.

Um API-Aufrufe interaktiv zu testen, verwenden Sie die OKMS-Swagger-Benutzeroberfläche unter https://<region>.okms.ovh.net/swagger/.

Ein Secret erstellen

Um ein Secret zu erstellen, können Sie die folgende API verwenden:

Methode	Pfad	Beschreibung
POST	/api/{okmsId}/v2/secret/	Ein Secret erstellen

Die API erwartet die folgenden Werte:

Feld	Wert	Beschreibung
cas_required	boolean	Wenn aktiviert, muss bei Änderungen stets die aktuelle Versionsnummer angegeben werden
custom_metadata	Json	Zusätzliche mit dem Secret verknüpfte Daten. Diese Daten werden nicht durch das Secret geschützt
deactivate_version_after	Duration String	Dauer, nach der Versionen deaktiviert werden
max_versions	Integer	Maximale Anzahl von Versionen für das Secret
path	String	Pfad des Secrets
version	Json	Inhalt des Secrets. Verschachtelte JSON sind möglich

Zum Beispiel:

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

Secrets verwalten

Metadaten und Konfiguration aktualisieren

Sobald das Secret erstellt ist, können Sie die Metadaten oder die Konfiguration des Secrets aktualisieren.

Methode	Pfad	Beschreibung
PUT	/v2/secret/{path}	Ein Secret aktualisieren

Die API erwartet die folgenden Werte:

Feld	Wert	Beschreibung
cas_required	boolean	Wenn aktiviert, muss bei Änderungen stets die aktuelle Versionsnummer angegeben werden
custom_metadata	Json	Zusätzliche mit dem Secret verknüpfte Daten. Diese Daten werden nicht durch das Secret geschützt
deactivate_version_after	Duration String	Dauer, nach der Versionen deaktiviert werden
max_versions	Integer	Maximale Anzahl von Versionen für das Secret

Es ist außerdem möglich, die Standardkonfiguration der OKMS-Domain für die Werte cas_required, deactivate_version_after und max_versions über die API zu ändern:

Methode	Pfad	Beschreibung
PUT	/v2/secretConfig	Die Standardkonfiguration der OKMS-Domain festlegen

Eine neue Version erstellen

Es ist außerdem möglich, den Inhalt des Secrets zu ändern, was das Erstellen einer neuen Version für das Secret bedeutet. Neue Versionen können über die API erstellt werden:

Methode	Pfad	Beschreibung
PUT	/v2/secret/{path}	Ein Secret aktualisieren
PUT	/v2/secret/{path}/version	Eine neue Version eines Secrets erstellen

Ob die Änderung der data des Secrets über die allgemeine API zur Aktualisierung des Secrets oder über die spezifische API erfolgt, es wird eine neue Version des Secrets erstellt.

Ein Secret kann beliebig viele Versionen enthalten, bis zur maximalen Grenze des Parameters max_versions. Wenn die maximale Anzahl von Versionen erreicht ist, wird die älteste Version automatisch gelöscht.

Versionen verwalten

Sie können die verschiedenen Versionen des Secrets über die API verwalten:

Methode	Pfad	Beschreibung
PUT	/v2/secret/{path}/version/{version}	Die Version eines Secrets aktualisieren

Die API erwartet den einzigen Wert:

Feld	Wert	Beschreibung
state	active , deactivated, deleted	active: Der Wert dieser Version ist zugänglich deactivated: Der Wert dieser Version ist noch im System vorhanden, aber nicht mehr zugänglich, bis die Version wieder aktiviert wird deleted: Der Wert dieser Version ist nicht mehr im System vorhanden und kann nicht wiederhergestellt werden.

Weiterführende Informationen

OKMS-Authentifizierungsmethoden

Treten Sie unserer User Community bei.

War diese Seite hilfreich?