Metodi di autenticazione OKMS

Obiettivo

Questa guida spiega come autenticarsi sul piano dati OKMS — l'API REST regionale esposta sul tuo dominio OKMS (ad esempio https://eu-west-rbx.okms.ovh.net). Questa API è condivisa dal Key Management Service (KMS) e dal Secret Manager.

Per l'API REST sono disponibili tre metodi di autenticazione. Le integrazioni KMIP supportano solo i certificati di accesso — ti consigliamo di riservare i certificati ai casi d'uso KMIP, poiché la loro configurazione è più complessa di quella dei token.

Prerequisiti

• Un account cliente OVHcloud.
• Un dominio OKMS nella regione di destinazione (creato al momento dell'ordine di un KMS o dell'attivazione di Secret Manager in quella regione).

Procedura

Comprendere il piano dati OKMS

Il piano dati OKMS è il punto di accesso API regionale per le operazioni crittografiche (KMS) e l'archiviazione dei secret (Secret Manager). È distinto dal piano di controllo centralizzato dell'API OVHcloud (/v2/okms/...), che gestisce il provisioning e la configurazione dei domini OKMS.

Puoi interagire con il piano dati tramite l'interfaccia Swagger unificata all'indirizzo https://<region>.okms.ovh.net/swagger/, la CLI OKMS o l'SDK Go.

Scegliere il metodo di autenticazione

Configurare l'autenticazione

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

Utilizzare l'interfaccia Swagger OKMS

Il dominio OKMS espone un'interfaccia Swagger unificata all'indirizzo https://<region>.okms.ovh.net/swagger/. Ad esempio, per un dominio in eu-west-rbx: https://eu-west-rbx.okms.ovh.net/swagger/.

Puoi aprirla anche dal link Swagger presente nella dashboard del tuo dominio OKMS.

L'interfaccia Swagger supporta tutti e tre i metodi di autenticazione dell'API REST. Esegui i passaggi di configurazione per il metodo scelto, inclusa la policy IAM richiesta, prima di eseguire le richieste.

Token di accesso personale (PAT)

1. Clicca sul pulsante Authorize (icona del lucchetto) nell'interfaccia Swagger.
2. In personalAccessToken (HTTP Bearer, formato JWT), incolla il PAT che hai creato per il tuo utente locale.
3. Clicca su Authorize, poi su Close.

Swagger invia il tuo token in un'intestazione Authorization: Bearer <token> per ogni richiesta che esegui.

Account di servizio

1. Clicca sul pulsante Authorize nell'interfaccia Swagger.
2. In oAuth2ClientCredentials, inserisci il client_id e il client_secret del tuo account di servizio. Consulta Come utilizzare gli account di servizio per connettersi alle API OVHcloud per ottenere queste credenziali.
3. Swagger ottiene un token di accesso OAuth2 tramite il flusso client-credentials e lo aggiunge alle richieste successive.

Certificato di accesso

L'autenticazione tramite certificato di accesso utilizza il TLS mutuo (mTLS) a livello di trasporto. Il certificato viene presentato dal tuo browser al momento della connessione all'URL Swagger — non si configura tramite la finestra di dialogo Authorize.

Importare il tuo certificato nel browser

Converti il tuo certificato OKMS e la tua chiave privata nel formato PKCS#12 (supponendo file denominati ID_certificate.pem e ID_privatekey.pem):

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

Ti verrà chiesto di impostare una password per il file crittografato. Importa client.p12 nel tuo browser:

Su Firefox

• Digita about:preferences#privacy nella barra degli indirizzi.
• Scorri verso il basso fino alla sezione Certificati.

• Clicca su Mostra certificati..., apri la scheda Certificati personali, quindi Importa... e seleziona il tuo file client.p12.
• Inserisci la password PKCS#12 quando ti viene richiesto.

Su Chrome/Chromium

• Digita chrome://settings/certificates nella barra degli indirizzi.
• Apri la scheda I tuoi certificati, clicca su Importa e seleziona il tuo file client.p12.
• Inserisci la password PKCS#12 quando ti viene richiesto.

Accedere a Swagger con il tuo certificato

Apri https://<region>.okms.ovh.net/swagger/ nel tuo browser. Ti verrà chiesto di selezionare il certificato importato:

Ora puoi eseguire chiamate API in modo interattivo dall'interfaccia Swagger.

Diritti IAM per OKMS

Le azioni IAM di OKMS seguono il modello okms:<channel>:<resource>/<operation>:

Azioni okms:apiovh comuni

Consulta l'elenco completo delle azioni nella console API OVHcloud sotto il tipo di prodotto Key Management System (KMS), oppure nelle policy IAM al momento della creazione di una policy.

Modelli di policy IAM suggeriti

Applica questi modelli alla risorsa del tuo dominio OKMS (urn:v1:<region>:resource:okms:<okmsId>). Sostituisci <identity_urn> e <okms_urn> con i tuoi valori. Crea le policy tramite lo Spazio Cliente o l'API IAM.

Amministrazione completa — controllo totale del dominio OKMS tramite 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:*"]
}

Sola lettura — elencare e ispezionare le risorse senza operazioni di scrittura o crittografiche:

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

Aggiungi okms:apiovh:secret/version/getData se l'identità deve leggere i valori dei secret.

Solo operazioni crittografiche — utilizzare le chiavi per crittografare, decrittografare, firmare e verificare senza gestire le chiavi o i secret:

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

Solo accesso ai secret — leggere i secret di Secret Manager senza accesso alle chiavi KMS, ai certificati o alla configurazione del dominio:

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

Aggiungi okms:apiovh:secret/create, okms:apiovh:secret/update e okms:apiovh:secret/delete se l'identità deve gestire i secret.

Per saperne di più

Utilizzare il tuo OVHcloud Key Management Service (KMS)

Utilizzare Secret Manager con l'API REST

Come connettere un prodotto compatibile utilizzando il protocollo KMIP

Generare un certificato di accesso OKMS

Contatta la nostra Community di utenti.