OKMS-Authentifizierungsmethoden

Ziel

Dieser Leitfaden erläutert, wie Sie sich bei der OKMS-Datenebene authentifizieren — der regionalen REST-API, die auf Ihrer OKMS-Domain bereitgestellt wird (zum Beispiel https://eu-west-rbx.okms.ovh.net). Diese API wird vom Key Management Service (KMS) und vom Secret Manager gemeinsam genutzt.

Für die REST-API stehen drei Authentifizierungsmethoden zur Verfügung. KMIP-Integrationen unterstützen ausschließlich Zugriffszertifikate — wir empfehlen, Zertifikate für KMIP-Anwendungsfälle zu reservieren, da ihre Einrichtung komplexer ist als die von Token.

Voraussetzungen

• Sie verfügen über einen OVHcloud Kunden-Account.
• Sie verfügen über eine OKMS-Domain in der Zielregion (erstellt bei der Bestellung eines KMS oder bei der Aktivierung des Secret Manager in dieser Region).

In der praktischen Anwendung

Die OKMS-Datenebene verstehen

Die OKMS-Datenebene ist der regionale API-Endpunkt für kryptografische Vorgänge (KMS) und die Speicherung von Secrets (Secret Manager). Sie unterscheidet sich von der zentralisierten Steuerungsebene der OVHcloud API (/v2/okms/...), die die Bereitstellung und Konfiguration von OKMS-Domains verwaltet.

Sie können mit der Datenebene über die einheitliche Swagger-Oberfläche unter https://<region>.okms.ovh.net/swagger/, die OKMS CLI oder das Go SDK interagieren.

Ihre Authentifizierungsmethode wählen

Authentifizierung einrichten

curl -H "Authorization: Bearer <your_pat>" \
  https://eu-west-rbx.okms.ovh.net/api/<okmsId>/v1/servicekey

curl -H "Authorization: Bearer <access_token>" \
  https://eu-west-rbx.okms.ovh.net/api/<okmsId>/v1/servicekey

Die OKMS Swagger-Oberfläche verwenden

Die OKMS-Domain stellt eine einheitliche Swagger-Oberfläche unter https://<region>.okms.ovh.net/swagger/ bereit. Zum Beispiel für eine Domain in eu-west-rbx: https://eu-west-rbx.okms.ovh.net/swagger/.

Sie können sie auch über den Swagger-Link auf dem Dashboard Ihrer OKMS-Domain öffnen.

Die Swagger-Oberfläche unterstützt alle drei Authentifizierungsmethoden der REST-API. Führen Sie die Konfigurationsschritte für die gewählte Methode aus, einschließlich der erforderlichen IAM-Richtlinie, bevor Sie Anfragen ausführen.

Personal Access Token

1. Klicken Sie in der Swagger-Oberfläche auf die Schaltfläche Authorize (Schloss-Symbol).
2. Fügen Sie unter personalAccessToken (HTTP Bearer, JWT-Format) das PAT ein, das Sie für Ihren lokalen Benutzer erstellt haben.
3. Klicken Sie auf Authorize und anschließend auf Close.

Swagger sendet Ihr Token in einem Authorization: Bearer <token>-Header bei jeder Anfrage, die Sie ausführen.

Service-Account

1. Klicken Sie in der Swagger-Oberfläche auf die Schaltfläche Authorize.
2. Geben Sie unter oAuth2ClientCredentials die client_id und das client_secret Ihres Service-Accounts ein. Weitere Informationen zum Abrufen dieser Zugangsdaten finden Sie unter So verwenden Sie Service-Accounts für die Verbindung mit den OVHcloud APIs.
3. Swagger ruft über den Client-Credentials-Flow ein OAuth2-Zugriffstoken ab und fügt es den nachfolgenden Anfragen hinzu.

Zugriffszertifikat

Die Authentifizierung per Zugriffszertifikat verwendet gegenseitiges TLS (mTLS) auf Transportebene. Das Zertifikat wird von Ihrem Browser beim Verbinden mit der Swagger-URL präsentiert — es wird nicht über das Dialogfeld Authorize konfiguriert.

Ihr Zertifikat in den Browser importieren

Konvertieren Sie Ihr OKMS-Zertifikat und Ihren privaten Schlüssel in das PKCS#12-Format (angenommen, die Dateien heißen ID_certificate.pem und ID_privatekey.pem):

openssl pkcs12 -export -in ID_certificate.pem -inkey ID_privatekey.pem -out client.p12

Sie werden aufgefordert, ein Passwort für die verschlüsselte Datei festzulegen. Importieren Sie client.p12 in Ihren Browser:

Unter Firefox

• Geben Sie about:preferences#privacy in die Adressleiste ein.
• Scrollen Sie nach unten zum Abschnitt Zertifikate.

• Klicken Sie auf Zertifikate anzeigen..., öffnen Sie den Tab Ihre Zertifikate, dann Importieren... und wählen Sie Ihre Datei client.p12 aus.
• Geben Sie das PKCS#12-Passwort ein, wenn Sie dazu aufgefordert werden.

Unter Chrome/Chromium

• Geben Sie chrome://settings/certificates in die Adressleiste ein.
• Öffnen Sie den Tab Eigene Zertifikate, klicken Sie auf Importieren und wählen Sie Ihre Datei client.p12 aus.
• Geben Sie das PKCS#12-Passwort ein, wenn Sie dazu aufgefordert werden.

Mit Ihrem Zertifikat auf Swagger zugreifen

Öffnen Sie https://<region>.okms.ovh.net/swagger/ in Ihrem Browser. Sie werden aufgefordert, das importierte Zertifikat auszuwählen:

Sie können nun API-Aufrufe interaktiv über die Swagger-Oberfläche ausführen.

IAM-Rechte für OKMS

OKMS-IAM-Aktionen folgen dem Muster okms:<channel>:<resource>/<operation>:

Aktionen zur Domain-Verwaltung über die OVHcloud API v2

Die vollständige Aktionsliste finden Sie in der OVHcloud API-Konsole unter dem Produkttyp Key Management System (KMS) oder in den IAM-Richtlinien beim Erstellen einer Richtlinie.

Aktionen der regionalen KMS-API

Die vollständige Aktionsliste finden Sie in der regionalen Swagger-Oberfläche unter https://<region>.okms.ovh.net/swagger/ oder in den IAM-Richtlinien beim Erstellen einer Richtlinie.

Beispiele für IAM-Richtlinien

Wenden Sie diese Vorlagen auf die Ressource Ihrer OKMS-Domain an. Deren URN wird im Tab Allgemeine Informationen im Dashboard Ihrer OKMS-Domain angezeigt. Ersetzen Sie <identity_urn> und <okms_urn> durch Ihre Werte. Erstellen Sie die Richtlinien über das Kundencenter oder die IAM-API.

Vollständige Administration — vollständige Kontrolle über die OKMS-Domain über die REST-API:

{
  "name": "okms-full-admin",
  "description": "Full administrative access to an OKMS domain",
  "identities": ["<identity_urn>"],
  "resources": [{ "urn": "<okms_urn>" }],
  "action": ["okms:apiovh:*", "okms:apikms:*"]
}

Nur Lesen — Ressourcen auflisten und untersuchen, ohne Schreib- oder kryptografische Vorgänge:

{
  "name": "okms-read-only",
  "description": "Read-only access to an OKMS domain",
  "identities": ["<identity_urn>"],
  "resources": [{ "urn": "<okms_urn>" }],
  "action": [
    "okms:apiovh:serviceKey/get",
    "okms:apiovh:secret/get",
    "okms:apiovh:credential/get",
    "okms:apiovh:secretConfig/get",
    "okms:apikms:serviceKey/get",
    "okms:apikms:secret/get",
    "okms:apikms:secretConfig/get"
  ]
}

Fügen Sie okms:apiovh:secret/version/getData (OVHcloud API v2) oder okms:apikms:secret/version/getData (regionale KMS-API) hinzu, wenn die Identität Secret-Werte lesen können muss.

Nur kryptografische Vorgänge — Schlüssel zum Verschlüsseln, Entschlüsseln, Signieren und Überprüfen verwenden, ohne Schlüssel oder Secrets zu verwalten:

{
  "name": "okms-crypto-only",
  "description": "Cryptographic operations on an OKMS domain",
  "identities": ["<identity_urn>"],
  "resources": [{ "urn": "<okms_urn>" }],
  "action": [
    "okms:apikms:serviceKey/get",
    "okms:apikms:serviceKey/encrypt",
    "okms:apikms:serviceKey/decrypt",
    "okms:apikms:serviceKey/sign",
    "okms:apikms:serviceKey/verify",
    "okms:apikms:serviceKey/dataKey/create",
    "okms:apikms:serviceKey/dataKey/decrypt"
  ]
}

Nur Secret-Zugriff — Secrets des Secret Manager lesen, ohne Zugriff auf KMS-Schlüssel, Zertifikate oder die Domain-Konfiguration:

{
  "name": "okms-secret-access-only",
  "description": "Read-only access to Secret Manager secrets on an OKMS domain",
  "identities": ["<identity_urn>"],
  "resources": [{ "urn": "<okms_urn>" }],
  "action": [
    "okms:apiovh:secret/get",
    "okms:apiovh:secret/version/getData",
    "okms:apikms:secret/get",
    "okms:apikms:secret/version/getData"
  ]
}

Um Secrets über die OVHcloud API v2 zu verwalten, fügen Sie okms:apiovh:secret/create, okms:apiovh:secret/edit, okms:apiovh:secret/updateMetadata und okms:apiovh:secret/delete hinzu. Um sie über die regionale KMS-API zu verwalten, fügen Sie okms:apikms:secret/create, okms:apikms:secret/updateMetadata und okms:apikms:secret/delete hinzu.

Weiterführende Informationen

Ihr OVHcloud Key Management Service (KMS) mit Ihren Daten verwenden

Secret Manager mit der REST-API verwenden

So verbinden Sie ein kompatibles Produkt über das KMIP-Protokoll

Ihr OKMS-Zugriffszertifikat verwalten

Treten Sie unserer User Community bei.