Codici di errore dell'API REST di Azure Key Vault

Articolo
09/06/2024

I codici di errore seguenti possono essere restituiti da un'operazione in un servizio Web di Azure Key Vault.

HTTP 401: Richiesta non autenticata

401 indica che la richiesta non è autenticata per Key Vault.

Una richiesta viene autenticata se:

L'insieme di credenziali delle chiavi conosce l'identità del chiamante; e
Il chiamante può provare ad accedere alle risorse di Key Vault.

Esistono diversi motivi per cui una richiesta può restituire 401.

Nessun token di autenticazione associato alla richiesta

Ecco una richiesta PUT di esempio, impostando il valore di un segreto:

PUT https://putreqexample.vault.azure.net//secrets/DatabaseRotatingPassword?api-version=7.0 HTTP/1.1
x-ms-client-request-id: 03d275a2-52a4-4bed-82c8-6fe15165affb
accept-language: en-US
Authorization: Bearer     eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Im5iQ3dXMTF3M1hrQi14VWFYd0tSU0xqTUhHUSIsImtpZCI6Im5iQ3dXMTF3M1hrQi14VWFYd0tSU0xqTUhHUSJ9.eyJhdWQiOiJodHRwczovL3ZhdWx0LmF6dXJlLm5ldCIsImlzcyI6Imh0dHBzOi8vc3RzLndpbmRvd3MubmV0LzcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0Ny8iLCJpYXQiOjE1NDg2OTc1MTMsIm5iZiI6MTU0ODY5NzUxMywiZXhwIjoxNTQ4NzAxNDEzLCJhaW8iOiI0MkpnWUhoODVqaVBnZHF5ZlRGZE5TdHY3bGUvQkFBPSIsImFwcGlkIjoiZmFkN2Q1YjMtNjlkNi00YjQ4LTkyNTktOGQxMjEyNGUxY2YxIiwiYXBwaWRhY3IiOiIxIiwiaWRwIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3LyIsIm9pZCI6IjM5NzVhZWVkLTdkMDgtNDUzYi1iNmY0LTQ0NWYzMjY5ODA5MSIsInN1YiI6IjM5NzVhZWVkLTdkMDgtNDUzYi1iNmY0LTQ0NWYzMjY5ODA5MSIsInRpZCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsInV0aSI6IjItZ3JoUmtlSWs2QmVZLUxuNDJtQUEiLCJ2ZXIiOiIxLjAifQ.fgubiz1MKqTJTXI8dHIV7t9Fle6FdHrkaGYKcBeVRX1WtLVuk1QVxzIFDlZKLXJ7QPNs0KWpeiWQI9IWIRK-8wO38yCqKTfDlfHOiNWGOpkKddlG729KFqakVf2w0GPyGPFCONRDAR5wjQarN9Bt8I8YbHwZQz_M1hztlnv-Lmsk1jBmech9ujD9-lTMBmSfFFbHcqquev119V7sneI-zxBZLf8C0pIDkaXf1t8y6Xr8CUJDMdlWLslCf3pBCNIOy65_TyGvy4Z4AJryTPBarNBPwOkNAtjCfZ4BDc2KqUZM5QN_VK4foP64sVzUL6mSr0Gh7lQJIL5b1qIpJxjxyQ
User-Agent: FxVersion/4.7.3324.0 OSName/Windows OSVersion/6.2.9200.0 Microsoft.Azure.KeyVault.KeyVaultClient/3.0.3.0
Content-Type: application/json; charset=utf-8
Host: putreqexample.vault.azure.net
Content-Length: 31

{
   "value": "m*gBJ7$Zuoz)"
}

L'intestazione "Authorization" è il token di accesso necessario con ogni chiamata all'insieme di credenziali delle chiavi per le operazioni del piano dati. Se l'intestazione è mancante, la risposta deve essere 401.

Il token non dispone della risorsa corretta associata

Quando si richiede un token di accesso dall'endpoint OAUTH di Azure, è obbligatorio un parametro denominato "resource". Il valore è importante per il provider di token perché definisce l'ambito del token per l'uso previsto. La risorsa per tutti i token per accedere a un insieme di credenziali delle chiavi è https://vault.keyvault.net (senza barra finale).

Il token è scaduto

I token sono codificati in base64 e i valori possono essere decodificati in siti Web come http://jwt.calebb.net. Ecco il token precedente decodificato:

    {
 typ: "JWT",
 alg: "RS256",
 x5t: "nbCwW11w3XkB-xUaXwKRSLjMHGQ",
 kid: "nbCwW11w3XkB-xUaXwKRSLjMHGQ"
}.
{
 aud: "https://vault.azure.net",
 iss: "https://sts.windows.net/72f988bf-86f1-41af-91ab-2d7cd011db47/",
 iat: 1548697513,
 nbf: 1548697513,
 exp: 1548701413,
 aio: "42JgYHh85jiPgdqyfTFdNStv7le/BAA=",
 appid: "fad7d5b3-69d6-4b48-9259-8d12124e1cf1",
 appidacr: "1",
 idp: "https://sts.windows.net/72f988bf-86f1-41af-91ab-2d7cd011db47/",
 oid: "3975aeed-7d08-453b-b6f4-445f32698091",
 sub: "3975aeed-7d08-453b-b6f4-445f32698091",
 tid: "72f988bf-86f1-41af-91ab-2d7cd011db47",
 uti: "2-grhRkeIk6BeY-Ln42mAA",
 ver: "1.0"
}.
[signature]

È possibile visualizzare molte parti importanti in questo token:

aud (gruppo di destinatari): risorsa del token. Si noti che si tratta di https://vault.azure.net. Questo token non funzionerà per qualsiasi risorsa che non corrisponde in modo esplicito a questo valore, ad esempio il grafico.
iat (emesso in): numero di tick dall'inizio dell'epoca in cui è stato rilasciato il token.
nbf (non prima): numero di tick dall'inizio dell'epoca quando questo token diventa valido.
exp (scadenza): numero di tick dall'inizio dell'epoca alla scadenza del token.
appid (ID applicazione): GUID per l'ID applicazione che effettua questa richiesta.
tid (ID tenant): GUID per l'ID tenant dell'entità che effettua questa richiesta

È importante che tutti i valori siano identificati correttamente nel token affinché la richiesta funzioni. Se tutto è corretto, la richiesta non restituirà 401.

Risoluzione dei problemi 401

I 401 devono essere esaminati dal punto di generazione del token, prima che venga effettuata la richiesta all'insieme di credenziali delle chiavi. In genere il codice viene usato per richiedere il token. Dopo aver ricevuto il token, viene passato alla richiesta di Key Vault. Se il codice è in esecuzione in locale, è possibile usare Fiddler per acquisire la richiesta/risposta a https://login.microsoftonline.com. Una richiesta è simile alla seguente:


POST https://login.microsoftonline.com/<key vault tenant ID>/oauth2/token HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: login.microsoftonline.com
Content-Length: 192

resource=https%3A%2F%2Fvault.azure.net&client_id=<registered-app-ID>&client_secret=<registered-app-secret>&client_info=1&grant_type=client_credentials

Le informazioni fornite dall'utente seguenti devono essere corrette:

ID tenant dell'insieme di credenziali delle chiavi
Valore della risorsa impostato su https%3A%2F%2Fvault.azure.net (con codifica URL)
ID client
Segreto client

Verificare che il resto della richiesta sia quasi identico.

Se è possibile ottenere solo il token di accesso alla risposta, è possibile decodificarlo per assicurarsi l'ID tenant, l'ID client (ID app) e la risorsa.

HTTP 403: Autorizzazioni insufficienti

HTTP 403 indica che la richiesta è stata autenticata (conosce l'identità richiedente), ma l'identità non dispone dell'autorizzazione per accedere alla risorsa richiesta. Esistono due cause:

Non esiste alcun criterio di accesso per l'identità.
L'indirizzo IP della risorsa richiedente non è approvato nelle impostazioni del firewall dell'insieme di credenziali delle chiavi.

HTTP 403 spesso si verifica quando l'applicazione del cliente non usa l'ID client che il cliente ritiene. Ciò significa in genere che i criteri di accesso non sono configurati correttamente per l'identità chiamante effettiva.

Se viene visualizzato un errore 403 immediatamente dopo l'aggiunta di un'identità ai criteri di accesso, è possibile gestirlo aggiungendo tentativi periodici.

Risoluzione dei problemi 403

Attivare prima di tutto la registrazione. Per istruzioni su come eseguire questa operazione, vedere Registrazione di Azure Key Vault.

Dopo aver attivato la registrazione, è possibile determinare se la versione 403 è dovuta ai criteri di accesso o ai criteri firewall.

Errore dovuto ai criteri firewall

"L'indirizzo client (00.00.00.00) non è autorizzato e il chiamante non è un servizio attendibile"

È disponibile un elenco limitato di "Servizi attendibili di Azure". I siti Web di Azure Web non sono un servizio attendibile di Azure. Per altre informazioni, vedere il post di blog Servizi attendibili.

Per poter funzionare, è necessario aggiungere l'indirizzo IP del sito Web di Azure all'insieme di credenziali delle chiavi.

Se a causa dei criteri di accesso: trovare l'ID oggetto per la richiesta e assicurarsi che l'ID oggetto corrisponda all'oggetto a cui l'utente sta tentando di assegnare i criteri di accesso. Ci saranno spesso più oggetti in Microsoft Entra ID, che hanno lo stesso nome, quindi scegliere quello corretto è importante. Eliminando e leggendo i criteri di accesso, è possibile verificare se esistono più oggetti con lo stesso nome.

Inoltre, la maggior parte dei criteri di accesso non richiede l'uso dell'"applicazione autorizzata", come illustrato nel portale. Le applicazioni autorizzate vengono usate per scenari di autenticazione "on-behalf-of", che sono rari.

HTTP 429: Troppe richieste

La limitazione si verifica quando il numero di richieste supera il limite massimo indicato per l'intervallo di tempo. Se si verifica una limitazione, la risposta di Key Vault sarà un errore HTTP 429. Sono indicati i valori massimi per i tipi di richieste effettuate. Ad esempio: la creazione di una chiave HSM a 2048 bit è di 10 richieste per 10 secondi, ma tutte le altre transazioni HSM hanno un limite di 2.000 richieste/10 secondi. È quindi importante comprendere quali tipi di chiamate vengono effettuate quando si determina la causa della limitazione. In generale, le richieste all'insieme di credenziali delle chiavi sono limitate a 4.000 richieste/10 secondi. Le eccezioni sono operazioni chiave, come documentato in Limiti del servizio Key Vault

Risoluzione del problema 429

La limitazione delle richieste può essere mitigata con queste tecniche:

Ridurre il numero di richieste effettuate al Key Vault determinando se sono presenti modelli per una risorsa richiesta e tentando di memorizzarli nella cache nell'applicazione di chiamata.
Quando si verifica la limitazione dell'insieme di credenziali delle chiavi, adattare il codice richiedente per usare un backoff esponenziale per riprovare. L'algoritmo è illustrato qui: Come limitare l'app
Se non è possibile ridurre il numero di richieste mediante la memorizzazione nella cache e il backoff temporizzato non funziona, provare a dividere le chiavi in più Key Vault. Il limite di servizio per una singola sottoscrizione è 5 volte il limite Key Vault singolo. Se si usano più di cinque insiemi di credenziali delle chiavi, è consigliabile considerare l'uso di più sottoscrizioni.

Indicazioni dettagliate, tra cui la richiesta di aumento dei limiti, sono disponibili qui: Linee guida per la limitazione di Key Vault

Condividi tramite