Méthodes d'authentification OKMS

Objectif

Ce guide explique comment s'authentifier sur le plan de données OKMS — l'API REST régionale exposée sur votre domaine OKMS (par exemple https://eu-west-rbx.okms.ovh.net). Cette API est partagée par le Key Management Service (KMS) et le Secret Manager.

Trois méthodes d'authentification sont disponibles pour l'API REST. Les intégrations KMIP ne prennent en charge que les certificats d'accès — nous recommandons de réserver les certificats aux cas d'usage KMIP, car leur configuration est plus complexe que celle des jetons.

Prérequis

• Disposer d'un compte client OVHcloud.
• Disposer d'un domaine OKMS dans la région cible (créé lors de la commande d'un KMS ou de l'activation du Secret Manager dans cette région).

En pratique

Comprendre le plan de données OKMS

Le plan de données OKMS est le point d'accès API régional pour les opérations cryptographiques (KMS) et le stockage de secrets (Secret Manager). Il est distinct du plan de contrôle centralisé de l'API OVHcloud (/v2/okms/...), qui gère le provisionnement et la configuration des domaines OKMS.

Vous pouvez interagir avec le plan de données via l'interface Swagger unifiée à l'adresse https://<region>.okms.ovh.net/swagger/, la CLI OKMS ou le SDK Go.

Choisir votre méthode d'authentification

Configurer l'authentification

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

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

Utiliser l'interface Swagger OKMS

Le domaine OKMS expose une interface Swagger unifiée à l'adresse https://<region>.okms.ovh.net/swagger/. Par exemple, pour un domaine en eu-west-rbx : https://eu-west-rbx.okms.ovh.net/swagger/.

Vous pouvez aussi l'ouvrir depuis le lien Swagger du tableau de bord de votre domaine OKMS.

L'interface Swagger prend en charge les trois méthodes d'authentification de l'API REST. Effectuez les étapes de configuration pour la méthode choisie, y compris la politique IAM requise, avant d'exécuter des requêtes.

Jeton d'accès personnel (PAT)

1. Cliquez sur le bouton Authorize (icône cadenas) dans l'interface Swagger.
2. Sous personalAccessToken (HTTP Bearer, format JWT), collez le PAT que vous avez créé pour votre utilisateur local.
3. Cliquez sur Authorize, puis sur Close.

Swagger envoie votre jeton dans un en-tête Authorization: Bearer <token> pour chaque requête que vous exécutez.

Compte de service

1. Cliquez sur le bouton Authorize dans l'interface Swagger.
2. Sous oAuth2ClientCredentials, saisissez le client_id et le client_secret de votre compte de service. Consultez Comment utiliser des comptes de service pour se connecter aux API OVHcloud pour obtenir ces identifiants.
3. Swagger obtient un jeton d'accès OAuth2 via le flux client-credentials et l'ajoute aux requêtes suivantes.

Certificat d'accès

L'authentification par certificat d'accès utilise TLS mutuel (mTLS) au niveau du transport. Le certificat est présenté par votre navigateur lors de la connexion à l'URL Swagger — il ne se configure pas via la boîte de dialogue Authorize.

Importer votre certificat dans le navigateur

Convertissez votre certificat OKMS et votre clé privée au format PKCS#12 (en supposant des fichiers nommés ID_certificate.pem et ID_privatekey.pem) :

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

Vous serez invité à définir un mot de passe pour le fichier chiffré. Importez client.p12 dans votre navigateur :

Sur Firefox

• Tapez about:preferences#privacy dans la barre d'adresse.
• Faites défiler jusqu'à la section Certificats.

• Cliquez sur Afficher les certificats..., ouvrez l'onglet Vos certificats, puis Importer... et sélectionnez votre fichier client.p12.
• Saisissez le mot de passe PKCS#12 lorsque vous y êtes invité.

Sur Chrome/Chromium

• Tapez chrome://settings/certificates dans la barre d'adresse.
• Ouvrez l'onglet Vos certificats, cliquez sur Importer et sélectionnez votre fichier client.p12.
• Saisissez le mot de passe PKCS#12 lorsque vous y êtes invité.

Accéder à Swagger avec votre certificat

Ouvrez https://<region>.okms.ovh.net/swagger/ dans votre navigateur. Vous serez invité à sélectionner le certificat importé :

Vous pouvez maintenant exécuter des appels API de manière interactive depuis l'interface Swagger.

Droits IAM pour OKMS

Les actions IAM OKMS suivent le modèle okms:<channel>:<resource>/<operation> :

Actions okms:apiovh courantes

Parcourez la liste complète des actions dans la console API OVHcloud sous le type de produit Key Management System (KMS), ou dans les politiques IAM lors de la création d'une politique.

Modèles de politiques IAM suggérés

Appliquez ces modèles à la ressource de votre domaine OKMS (urn:v1:<region>:resource:okms:<okmsId>). Remplacez <identity_urn> et <okms_urn> par vos valeurs. Créez les politiques via l'espace client ou l'API IAM.

Administration complète — contrôle total du domaine OKMS via l'API REST :

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

Lecture seule — lister et inspecter les ressources sans opérations d'écriture ou cryptographiques :

{
  "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:apiovh:log/get"
  ]
}

Ajoutez okms:apiovh:secret/version/getData si l'identité doit lire les valeurs des secrets.

Opérations cryptographiques uniquement — utiliser les clés pour chiffrer, déchiffrer, signer et vérifier sans gérer les clés ou les secrets :

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

Accès aux secrets uniquement — lire les secrets du Secret Manager sans accès aux clés KMS, aux certificats ou à la configuration du domaine :

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

Ajoutez okms:apiovh:secret/create, okms:apiovh:secret/update et okms:apiovh:secret/delete si l'identité doit gérer les secrets.

Aller plus loin

Utiliser votre OVHcloud Key Management Service (KMS)

Utiliser le Secret Manager avec l'API REST

Comment connecter un produit compatible en utilisant le protocole KMIP

Générer un certificat d'accès OKMS

Échangez avec notre communauté d'utilisateurs.