Hitelesítés, kérelmek és válaszok

Az Azure Key Vault kétféle tárolót biztosít a felhőalkalmazások titkos kulcsainak tárolásához és kezeléséhez:

Tároló típusa Támogatott objektumtípusok Adatsík végpontja
Boltívek
  • Szoftverrel védett kulcsok
  • HSM által védett kulcsok (prémium termékváltozattal)
  • Certificates
  • Tárfiókkulcsok
https://{vault-name}.vault.azure.net
Felügyelt HSM
  • HSM-védett kulcsok
https://{hsm-name}.managedhsm.azure.net

Az egyes objektumtípusok eléréséhez használt URL-utótagok

Objektumtípus URL-cím utótagja
Szoftverrel védett kulcsok /Kulcsok
HSM-védett kulcsok /Kulcsok
Titkos kódok /Titkok
Certificates /Tanúsítványok
Tárfiókkulcsok /storageaccounts

Az Azure Key Vault támogatja a JSON formátumú kéréseket és válaszokat. Az Azure Key Vaulthoz érkező kérelmek egy érvényes Azure Key Vault-URL-címre lesznek irányítva HTTPS használatával, néhány URL-paraméterrel és JSON-kódolt kérés- és választestekkel.

Ez a témakör az Azure Key Vault szolgáltatásra vonatkozó részleteket ismerteti. Az Azure REST-felületek használatával kapcsolatos általános információkért, beleértve a hitelesítést/engedélyezést és a hozzáférési jogkivonat beszerzését, tekintse meg az Azure REST API-referencia című témakört.

Kérelem URL-címe

A kulcskezelési műveletek HTTP DELETE, GET, PATCH, PUT és HTTP POST műveletet használnak, a meglévő kulcsobjektumok titkosítási műveletei pedig HTTP POST-et használnak. Az adott HTTP-parancsokat nem támogató ügyfelek a HTTP POST-ot is használhatják az X-HTTP-REQUEST fejléc használatával a kívánt ige megadásához; az olyan kéréseknek, amelyek általában nem igényelnek törzset, egy üres törzset kell tartalmazniuk a HTTP POST használatakor, például a DELETE helyett a POST használata esetén.

Ha az Azure Key Vaultban lévő objektumokkal szeretne dolgozni, az alábbiakban példa URL-címeket láthat:

  • TESTKEY nevű kulcs létrehozása Key Vault-használatban – PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1

  • IMPORTEDKEY nevű kulcs importálása Key Vault-használatba – POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1

  • A MY Standard kiadás CRET nevű titkos kód lekérése Key Vault-használatban –GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1

  • Kivonat aláírása a KEY Vaultban a TESTKEY nevű kulccsal – POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1

  • A Key Vaulthoz irányuló kérések szolgáltatói mindig a következők:

    • Tárolók esetén: https://{keyvault-name}.vault.azure.net/
    • Felügyelt HSM-ekhez: https://{HSM-name}.managedhsm.azure.net/

    A kulcsok mindig a /keys elérési út alatt vannak tárolva, a titkos kulcsok pedig mindig a /secrets elérési út alatt vannak tárolva.

API Version

Az Azure Key Vault szolgáltatás támogatja a protokoll verziószámozását, hogy kompatibilitást biztosítson a alacsonyabb szintű ügyfelekkel, bár nem minden képesség érhető el az ügyfelek számára. Az ügyfeleknek a lekérdezési sztring api-version paraméterrel kell megadniuk a protokoll azon verzióját, amelyet támogatnak, mivel nincs alapértelmezett.

Az Azure Key Vault protokollverziói egy dátumszámozási sémát követnek egy {YYYY} használatával. {MM}. {DD} formátum.

A kérelem törzse

A HTTP-specifikációnak megfelelően a GET-műveleteknek NEM lehet kérelemtörzsük, a POST és a PUT műveleteknek pedig kérelemtörzset kell tartalmazniuk. A DELETE műveletek törzse nem kötelező a HTTP-ben.

Ha a művelet leírásában másként nem szerepel, a kérelem törzsének tartalomtípusának application/json típusúnak kell lennie, és a tartalomtípusnak megfelelő szerializált JSON-objektumot kell tartalmaznia.

Ha a művelet leírásában másként nem szerepel, a Kérelem elfogadása fejlécnek tartalmaznia kell az alkalmazás/json adathordozó típusát.

Válasz törzse

Ha a művelet leírásában másként nem szerepel, a sikeres és a sikertelen műveletek válasz törzsének tartalomtípusa az application/json lesz, és részletes hibainformációkat tartalmaz.

HTTP POST használata

Előfordulhat, hogy egyes ügyfelek nem tudják használni bizonyos HTTP-parancsokat, például a PATCH-et vagy a DELETE-t. Az Azure Key Vault ezen ügyfelek alternatívaként támogatja a HTTP POST-t, feltéve, hogy az ügyfél az "X-HTTP-METHOD" fejlécet is tartalmazza az eredeti HTTP-igéhez. A HTTP POST támogatása a dokumentumban definiált api-k mindegyikéhez fel van jegyezve.

Hibaválaszok

A hibakezelés HTTP-állapotkódokat fog használni. A tipikus eredmények a következők:

  • 2xx – Siker: Normál működéshez használatos. A válasz törzse a várt eredményt fogja tartalmazni

  • 3xx – Átirányítás: A 304 "Nem módosult" visszaadható a feltételes GET teljesítéséhez. A jövőben további 3xx kódok is használhatók a DNS és az elérési út változásainak jelzésére.

  • 4xx – Ügyfélhiba: Hibás kérésekhez, hiányzó kulcsokhoz, szintaxishibákhoz, érvénytelen paraméterekhez, hitelesítési hibákhoz stb. használatos. A válasz törzse részletes hibamagyarázatot tartalmaz.

  • 5xx – Kiszolgálóhiba: Belső kiszolgálóhibák esetén használatos. A válasz törzse összegzett hibainformációkat tartalmaz.

    A rendszer úgy lett kialakítva, hogy proxy vagy tűzfal mögött működjön. Ezért előfordulhat, hogy az ügyfél más hibakódokat is kap.

    Az Azure Key Vault hibainformációkat is visszaad a válasz törzsében, ha probléma merül fel. A válasz törzse JSON formátumú, és a következő formában történik:


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

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

Authentication

Az Azure Key Vaultba irányuló összes kérést hitelesíteni kell. Az Azure Key Vault támogatja az OAuth2 használatával beszerezhető Microsoft Entra hozzáférési jogkivonatokat [RFC6749].

Az alkalmazás regisztrálásával és az Azure Key Vault használatához való hitelesítéssel kapcsolatos további információkért lásd : Ügyfélalkalmazás regisztrálása a Microsoft Entra-azonosítóval.

A hozzáférési jogkivonatokat a HTTP-hitelesítés fejlécével kell elküldeni a szolgáltatásnak:

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

Ha nem ad meg hozzáférési jogkivonatot, vagy ha a szolgáltatás nem fogad el jogkivonatot, a rendszer HTTP 401-hibát ad vissza az ügyfélnek, és tartalmazza a WWW-Authenticate fejlécet, például:

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

A WWW-Authenticate fejléc paraméterei a következők:

  • engedélyezés: Az OAuth2 engedélyezési szolgáltatás címe, amely a kérelem hozzáférési jogkivonatának beszerzésére használható.

  • erőforrás: Az engedélyezési kérelemben használni kívánt erőforrás (https://vault.azure.net) neve.

Megjegyzés:

A titkos kulcsok, tanúsítványok és kulcsok Key Vault SDK-ügyfelei a Key Vaulthoz intézett első hívás során nem adnak meg hozzáférési jogkivonatot a bérlő adatainak lekéréséhez. A rendszer egy HTTP 401-es üzenetet vár a Key Vault SDK-ügyféltől, amelyben a Key Vault megjeleníti az alkalmazásnak azt az erőforrást és bérlőt tartalmazó WWW-Authenticate fejlécet, ahol a tokent kell kérnie. Ha minden megfelelően van konfigurálva, az alkalmazástól a Key Vaulthoz befutó második hívás érvényes tokent fog tartalmazni, és sikeres lesz.