Autenticazione, richieste e risposte

Azure Key Vault offre due tipi di contenitori per archiviare e gestire i segreti per le applicazioni cloud:

Ecco i suffissi degli URL usati per accedere a ogni tipo di oggetto

Azure Key Vault supporta richieste e risposte in formato JSON. Le richieste al servizio Azure Key Vault vengono indirizzate a un URL valido utilizzando HTTPS, con alcuni parametri URL e con corpi di richiesta e risposta codificati in JSON.

Questo articolo illustra le specifiche per il servizio Azure Key Vault. Per informazioni generali sull'uso di interfacce REST di Azure, tra cui autenticazione/autorizzazione e come acquisire un token di accesso, vedere Informazioni di riferimento sull'API REST di Azure.

Struttura URL richiesta

Le operazioni di gestione delle chiavi usano verbi HTTP, tra cui DELETE, GET, PATCH e PUT. Le operazioni di crittografia sugli oggetti chiave esistenti usano HTTP POST.

Per i client che non supportano verbi HTTP specifici, Azure Key Vault consente di usare HTTP POST con l'intestazione X-HTTP-REQUEST per specificare il verbo previsto. Quando si usa POST come sostituto (ad esempio, anziché DELETE), includere un corpo vuoto per le richieste che normalmente non ne richiedono uno.

Di seguito sono riportati gli URL di esempio per lavorare con gli oggetti in Azure Key Vault:

• Per creare una chiave denominata TESTKEY in Key Vault usare - PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1

• Per importare una chiave denominata IMPORTEDKEY in una Key Vault, usare: POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1

• Per ottenere un segreto chiamato MYSECRET in un Key Vault, utilizzare: GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1

• Per firmare un digest usando una chiave denominata TESTKEY in un Key Vault, usare POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1

• L'autorità per una richiesta a Key Vault è sempre la seguente:

  • Per gli insiemi di credenziali: https://{keyvault-name}.vault.azure.net/
  • Per i moduli di protezione hardware gestiti: https://{HSM-name}.managedhsm.azure.net/ le chiavi vengono sempre archiviate nel percorso /keys, mentre i segreti vengono sempre archiviati nel percorso /secrets.

Versioni dell'API supportate

Il servizio Azure Key Vault supporta il controllo delle versioni del protocollo per garantire la compatibilità con i client di livello inferiore, anche se non tutte le funzionalità sono disponibili per tali client. I client devono usare il api-version parametro della stringa di query per specificare la versione del protocollo supportato perché non esiste un valore predefinito.

Le versioni del protocollo di Azure Key Vault seguono uno schema di numerazione delle date nel formato {YYYY}.{MM}.{DD}.

Requisiti corpo della richiesta

In base alla specifica HTTP, le operazioni GET non devono avere un corpo della richiesta e le operazioni POST e PUT devono avere un corpo della richiesta. Il corpo delle operazioni DELETE è opzionale in HTTP.

Se non diversamente indicato nella descrizione dell'operazione, il tipo di contenuto del corpo della richiesta deve essere application/json e deve contenere un oggetto JSON serializzato conforme al tipo di contenuto.

Se non diversamente indicato nella descrizione dell'operazione, l'intestazione Accept request deve contenere il tipo di supporto application/json.

Formato del corpo della risposta

Se non diversamente indicato nella descrizione dell'operazione, il tipo di contenuto del corpo della risposta delle operazioni riuscite e non riuscite è application/json e contiene informazioni dettagliate sull'errore.

Uso di HTTP POST come alternativa

Alcuni client potrebbero non essere in grado di usare determinati verbi HTTP, ad esempio PATCH o DELETE. Azure Key Vault supporta HTTP POST come alternativa per questi client se il client include anche l'intestazione "X-HTTP-METHOD" per specificare il verbo HTTP originale. Il supporto per HTTP POST è indicato per ogni API definita in questo documento.

Gestione delle risposte agli errori

La gestione degli errori usa codici di stato HTTP. I risultati tipici sono:

• 2xx - Successo: Usato per operazioni normali. Il corpo della risposta contiene il risultato previsto

• 3xx - Reindirizzamento: il 304 "Non modificato" può essere restituito per soddisfare un GET condizionale. Altri codici 3xx possono essere usati in futuro per indicare le modifiche al DNS e al percorso.

• 4xx - Errore client: usato per richieste non valide, chiavi mancanti, errori di sintassi, parametri non validi, errori di autenticazione e così via. Il corpo della risposta contiene una spiegazione dettagliata dell'errore.

• 5xx - Errore del server: usato per gli errori interni del server. Il corpo della risposta contiene informazioni di errore riepilogate.

  Il sistema è progettato per funzionare dietro un proxy o un firewall. Pertanto, un client potrebbe ricevere altri codici di errore.

  Azure Key Vault restituisce anche informazioni sull'errore nel corpo della risposta quando si verifica un problema. Il corpo della risposta è in formato JSON e assume il formato seguente:

{  
  "error":  
  {  
    "code": "BadArgument",  
    "message":  

      "’Foo’ is not a valid argument for ‘type’."  
    }  
  }  
}  

Requisiti di autenticazione

Tutte le richieste ad Azure Key Vault devono essere autenticate. Azure Key Vault supporta i token di accesso microsoft Entra che possono essere ottenuti usando OAuth2 [RFC6749].

Per altre informazioni sulla registrazione dell'applicazione e sull'autenticazione per l'uso di Azure Key Vault, vedere Registrare l'applicazione client con Microsoft Entra ID.

I token di accesso devono essere inviati al servizio usando l'intestazione di autorizzazione HTTP:

PUT /keys/MYKEY?api-version=<api_version>  HTTP/1.1  
Authorization: Bearer <access_token>  

Quando non viene fornito un token di accesso o quando il servizio non accetta un token, viene restituito un errore HTTP 401 al client e include l'intestazione WWW-Authenticate, ad esempio:

401 Not Authorized  
WWW-Authenticate: Bearer authorization="…", resource="…"  

I parametri nell'intestazione WWW-Authenticate sono:

• authorization: indirizzo del servizio di autorizzazione OAuth2 che può essere usato per ottenere un token di accesso per la richiesta.

• resource: nome della risorsa (https://vault.azure.net) da usare nella richiesta di autorizzazione.