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

Článek
09/06/2024

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é modulem HSM (se skladovou jednotkou Premium) Certifikáty Klíče účtu úložiště	https://{název_trezoru}.vault.azure.net
Spravovaný HSM	Klíče chráněné pomocí HSM	https://{hsm-name}.managedhsm.azure.net

Tady jsou přípony URL používané pro přístup ke každému typu objektu.

Object type	Přípona adresy URL
Softwarově chráněné klíče	/klíče
Klíče chráněné pomocí HSM	/klíče
Tajné kódy	/tajemství
Certifikáty	/certifikáty
Klíče účtu úložiště	/storageaccounts

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

Toto téma popisuje konkrétní informace pro službu Azure Key Vault. Obecné informace o používání rozhraní Azure REST, včetně ověřování/autorizace a získání přístupového tokenu, najdete v referenčních informacích k rozhraní Azure REST API.

Adresa URL požadavku

Operace správy klíčů používají operace HTTP DELETE, GET, PATCH, PUT a HTTP POST a kryptografické operace s existujícími klíčovými objekty používají HTTP POST. Klienti, kteří nemohou podporovat konkrétní příkazy HTTP, mohou také použít HTTP POST pomocí hlavičky X-HTTP-REQUEST k určení zamýšleného příkazu; požadavky, které obvykle nevyžadují tělo, by měly při použití http POST obsahovat prázdný text, například při použití POST místo DELETE.

Pro práci s objekty ve službě Azure Key Vault jsou příklady adres URL:

Vytvoření klíče s názvem TESTKEY ve službě Key Vault použijte – PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1
Import klíče s názvem IMPORTKEY do trezoru klíčů použijte : POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1
Získání tajného kódu mySECRET ve službě Key Vault pomocí : GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1
Podepsání hodnoty hash pomocí klíče s názvem TESTKEY ve službě Key Vault použijte – POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1
Autorita pro žádost o službu Key Vault je vždy následující:
- Trezory: https://{keyvault-name}.vault.azure.net/
- Pro spravované HSM: https://{HSM-name}.managedhsm.azure.net/
Klíče se vždy ukládají pod cestou /keys, tajné kódy se vždy ukládají pod cestou /secrets.

Verze rozhraní API

Služba Azure Key Vault podporuje správu verzí protokolu, která zajišťuje kompatibilitu s klienty nižší úrovně, i když pro tyto klienty nebudou 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í.

Verze protokolu služby Azure Key Vault se řídí schématem číslování kalendářních dat pomocí {YYYY}. {MM}. Formát {DD}.

Text 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 přijmout požadavek musí obsahovat typ média application/json.

Text odpovědi

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

Použití HTTP POST

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 za předpokladu, že 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.

Chybové odpovědi

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

2xx – Úspěch: Používá se pro normální provoz. Text odpovědi bude obsahovat očekávaný výsledek.
3xx – Přesměrování: 304 "Neupraveno" může být vráceno pro splnění podmíněného 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 bude obsahovat podrobné vysvětlení chyby.
5xx – Chyba serveru: Používá se pro vnitřní chyby serveru. Text odpovědi bude obsahovat 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 také vrací 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’."  
    }  
  }  
}

Ověřování

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

Další informace o registraci aplikace a ověřování pro použití služby Azure Key Vault najdete v tématu Registrace klientské aplikace v 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 se přístupový token nezadá nebo když služba token nepřijme, vrátí se klientovi chyba HTTP 401 a bude obsahovat hlavičku WWW-Authenticate, například:

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

Parametry hlavičky WWW-Authenticate jsou:

autorizace: Adresa autorizační služby OAuth2, kterou lze použít k získání přístupového tokenu pro žádost.
prostředek: Název prostředku (https://vault.azure.net) pro použití v žádosti o autorizaci.

Poznámka:

Klienti sady Key Vault SDK pro tajné kódy, certifikáty a klíče při prvním volání služby Key Vault neposkytují přístupový token pro načtení informací o tenantovi. Očekává se přijetí HTTP 401 pomocí klienta sady Key Vault SDK, kde Key Vault zobrazí aplikaci hlavičku WWW-Authenticate obsahující zdroj a tenanta, kam má přejít a požádat o token. Pokud je vše nakonfigurované správně, druhé volání z aplikace do služby Key Vault bude obsahovat platný token a bude úspěšné.

Sdílet prostřednictvím