Ověřování, požadavky a odpovědi

Azure Key Vault poskytuje dva typy kontejnerů pro ukládání a správu tajných kódů pro cloudové aplikace:

Typ kontejneru Podporované typy objektů Koncový bod roviny dat
trezory
  • Softwarově chráněné klíče
  • Klíče chráněné HSM (s SKU Premium)
  • Certifikáty
 https://<vault-name>.vault.azure.net
Spravovaný HSM
  • Klíče chráněné pomocí HSM
 https://<hsm-name>.managedhsm.azure.net

Tady jsou přípony adres URL použitých pro přístup ke každému typu objektu.

Typ objektu Přípona adresy URL
Softwarově chráněné klíče /klíče
Klíče chráněné pomocí HSM /klíče
Tajemství /tajemství
Certifikáty /certifikáty

Azure Key Vault podporuje požadavky a odpovědi ve formátu JSON. Požadavky na Azure Key Vault se přesměrují na platnou adresu URL Azure Key Vault pomocí protokolu HTTPS s některými parametry adresy URL a kódovanými texty požadavků a odpovědí JSON.

Tento článek se zabývá konkrétními informacemi o službě Azure Key Vault. Obecné informace o používání Azure rozhraní REST, včetně ověřování/autorizace a získání přístupového tokenu, najdete v tématu Azure Reference k rozhraní REST API.

Struktura adresy URL požadavku

Operace správy klíčů používají příkazy HTTP, včetně příkazů DELETE, GET, PATCH a PUT. Kryptografické operace s existujícími klíčovými objekty používají HTTP POST.

Pro klienty, kteří nemohou podporovat konkrétní příkazy HTTP, Azure Key Vault umožňuje použít HTTP POST s hlavičkou X-HTTP-REQUEST k určení zamýšleného příkazu. Při použití funkce POST jako náhrady (například místo DELETE) zahrňte prázdný text pro požadavky, které obvykle nevyžadují jeden.

Pro práci s objekty v Azure Key Vault jsou příklady adres URL:

  • Chcete-li vytvořit klíč s názvem TESTKEY v Key Vault, použijte – PUT /keys/TESTKEY?api-version=<api-version> HTTP/1.1

  • Importujte klíč s názvem IMPORTEDKEY do Key Vault použijte – POST /keys/IMPORTEDKEY/import?api-version=<api-version> HTTP/1.1

  • Pro zobrazení tajemství nazvaného MYSECRET v Key Vault použijte – GET /secrets/MYSECRET?api-version=<api-version> HTTP/1.1

  • K podepsání hodnoty hash pomocí klíče s názvem TESTKEY v Key Vault použijte – POST /keys/TESTKEY/sign?api-version=<api-version> HTTP/1.1

  • Orgán pro žádost o Key Vault je vždy následující:

    • Trezory: https://<vault-name>.vault.azure.net/
    • Pro spravované HSM: https://{HSM-name}.managedhsm.azure.net/ Klíče se vždy ukládají pod cestou /keys, zatímco tajné kódy se vždy ukládají pod cestou /secrets.

Podporované verze rozhraní API

Služba Azure Key Vault podporuje správu verzí protokolu, aby byla zajištěna kompatibilita s klienty nižší úrovně, i když pro tyto klienty nejsou dostupné všechny možnosti. Klienti musí použít api-version parametr řetězce dotazu k určení verze protokolu, který podporují, protože neexistuje výchozí nastavení.

Azure Key Vault verze protokolu se řídí schématem číslování datumů ve formátu {YYYY}.{MM}.{DD}.

Požadavky na tělo požadavku

Podle specifikace HTTP nesmí operace GET obsahovat text požadavku a operace POST a PUT musí obsahovat text požadavku. Text v operacích DELETE je volitelný v protokolu HTTP.

Pokud není v popisu operace uvedeno jinak, musí být typ obsahu textu požadavku application/json a musí obsahovat serializovaný objekt JSON odpovídající typu obsahu.

Pokud není uvedeno jinak v popisu operace, hlavička 'Accept' musí obsahovat media type application/json.

Formát textu odpovědi

Pokud není v popisu operace uvedeno jinak, typ obsahu textu odpovědi úspěšných i neúspěšných operací je application/json a obsahuje podrobné informace o chybě.

Použití HTTP POST jako alternativy

Někteří klienti možná nebudou moct používat určité příkazy HTTP, například PATCH nebo DELETE. Azure Key Vault podporuje HTTP POST jako alternativu pro tyto klienty, pokud klient obsahuje také hlavičku X-HTTP-METHOD pro konkrétní původní příkaz HTTP. Podpora protokolu HTTP POST je zaznamenána pro každé rozhraní API definované v tomto dokumentu.

Zpracování chybových odpovědí

Zpracování chyb používá stavové kódy HTTP. Mezi typické výsledky patří:

  • 2xx – Úspěch: Používá se pro běžný provoz. Text odpovědi obsahuje očekávaný výsledek.

  • 3xx – Přesměrování: Stav 304 "Neupraveno" může být vrácen pro splnění podmíněného požadavku GET. Další kódy 3xx lze v budoucnu použít k označení změn DNS a cesty.

  • 4xx – Chyba klienta: Používá se pro chybné požadavky, chybějící klíče, chyby syntaxe, neplatné parametry, chyby ověřování atd. Text odpovědi obsahuje podrobné vysvětlení chyb.

  • 5xx – Chyba serveru: Používá se pro vnitřní chyby serveru. Text odpovědi obsahuje souhrnné informace o chybě.

    Systém je navržený tak, aby fungoval za proxy serverem nebo bránou firewall. Klient proto může obdržet další kódy chyb.

    Azure Key Vault vrátí také informace o chybě v textu odpovědi, když dojde k problému. Text odpovědi je formátovaný ve formátu JSON a má tvar:


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

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

Požadavky na ověření

Všechny požadavky na Azure Key Vault musí být ověřeny. Azure Key Vault podporuje přístupové tokeny Microsoft Entra, které lze získat pomocí OAuth2 [RFC6749].

Další informace o registraci aplikace a ověřování pro použití Azure Key Vault najdete v tématu Register klientské aplikace pomocí Microsoft Entra ID.

Přístupové tokeny musí být odeslány do služby pomocí hlavičky HTTP Authorization:

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

Pokud přístupový token není zadaný nebo pokud služba token nepřijme, vrátí se klientovi chyba HTTP 401 a obsahuje hlavičku WWW-Authenticate, například:

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

Parametry v hlavičce WWW-Authenticate jsou:

  • autorizace: Adresa autorizační služby OAuth2, kterou lze použít k získání přístupového tokenu pro žádost.

  • resource: Název prostředku (https://vault.azure.net), který se má použít v žádosti o autorizaci.

Poznámka:

Key Vault klienti sady SDK pro tajné kódy, certifikáty a klíče v prvním volání Key Vault neposkytují přístupový token pro načtení informací o tenantovi. Očekává se, že pomocí klienta Key Vault SDK obdržíme HTTP 401, kde Key Vault poskytne aplikaci hlavičku WWW-Authenticate obsahující prostředek a tenanta, kam je potřeba se přemístit a požádat o token. Pokud je vše správně nakonfigurované, druhé volání z aplikace do Key Vault bude obsahovat platný token a bude úspěšný.

  • Last updated on