인증, 요청 및 응답

Azure Key Vault는 클라우드 애플리케이션에 대한 비밀을 저장하고 관리하는 두 가지 유형의 컨테이너를 제공합니다.

다음은 각 개체 형식에 액세스하는 데 사용되는 URL의 접미사입니다.

Azure Key Vault는 JSON 형식 요청 및 응답을 지원합니다. Azure Key Vault에 대한 요청은 일부 URL 매개 변수와 JSON 인코딩 요청 및 응답 본문이 있는 HTTPS를 사용하여 유효한 Azure Key Vault URL로 전달됩니다.

이 문서에서는 Azure Key Vault 서비스에 대한 세부 정보를 설명합니다. 인증/권한 부여 및 액세스 토큰을 획득하는 방법을 포함하여 Azure REST 인터페이스 사용에 대한 일반적인 내용은 Azure REST API 참조를 참조하세요.

요청 URL 구조

키 관리 작업은 DELETE, GET, PATCH 및 PUT을 비롯한 HTTP 동사를 사용합니다. 기존 키 개체에 대한 암호화 작업은 HTTP POST를 사용합니다.

특정 HTTP 동사를 지원할 수 없는 클라이언트의 경우 Azure Key Vault에서는 헤더와 함께 X-HTTP-REQUEST HTTP POST를 사용하여 의도한 동사를 지정할 수 있습니다. POST를 대체(예: DELETE 대신)로 사용하는 경우 일반적으로 필요하지 않은 요청에 대해 빈 본문을 포함합니다.

Azure Key Vault에서 개체를 사용하려면 다음 예제 URL이 있습니다.

• Key Vault에서 TESTKEY라는 키를 만들려면 다음을 사용합니다. PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1

• IMPORTEDKEY라는 키를 Key Vault로 가져오려면 다음을 사용합니다. POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1

• Key Vault에서 MYSECRET이라는 비밀을 얻으려면 다음을 사용합니다. GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1

• Key Vault에서 TESTKEY라는 키를 사용하여 다이제스트에 서명하려면 다음을 사용합니다. POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1

• Key Vault에 대한 요청에 대한 권한은 항상 다음과 같습니다.

  • 자격 증명 모음의 경우: https://{keyvault-name}.vault.azure.net/
  • 관리형 HSM의 경우: https://{HSM-name}.managedhsm.azure.net/ 키는 항상 /keys 경로 아래에 저장되지만 비밀은 항상 /secrets 경로 아래에 저장됩니다.

지원되는 API 버전

Azure Key Vault 서비스는 해당 클라이언트에서 모든 기능을 사용할 수 있는 것은 아니지만 하위 수준 클라이언트와의 호환성을 제공하기 위해 프로토콜 버전 관리 기능을 지원합니다. 클라이언트는 쿼리 문자열 매개 변수를 api-version 사용하여 기본값이 없으므로 지원하는 프로토콜의 버전을 지정해야 합니다.

Azure Key Vault 프로토콜 버전은 {YYYY}를 사용하여 날짜 번호 매기기 체계를 따릅니다. {MM}. {DD} 형식입니다.

요청 본문 요구 사항

HTTP 사양에 따라 GET 작업에는 요청 본문이 없어야 하며 POST 및 PUT 작업에는 요청 본문이 있어야 합니다. DELETE 작업의 본문은 HTTP에서 선택 사항입니다.

작업 설명에 달리 명시되지 않는 한 요청 본문 콘텐츠 형식은 애플리케이션/json이어야 하며 콘텐츠 형식에 맞는 직렬화된 JSON 개체를 포함해야 합니다.

작업 설명에 달리 명시되지 않는 한 Accept 요청 헤더에는 애플리케이션/json 미디어 형식이 포함되어야 합니다.

응답 본문 형식

작업 설명에 달리 명시되지 않는 한 성공한 작업과 실패한 작업의 응답 본문 콘텐츠 형식은 애플리케이션/json이며 자세한 오류 정보를 포함합니다.

대안으로 HTTP POST 사용

일부 클라이언트는 PATCH 또는 DELETE와 같은 특정 HTTP 동사를 사용하지 못할 수 있습니다. 클라이언트에 원래 HTTP 동사에 대한 "X-HTTP-METHOD" 헤더도 포함된 경우 Azure Key Vault는 이러한 클라이언트에 대한 대안으로 HTTP POST를 지원합니다. HTTP POST에 대한 지원은 이 문서에 정의된 각 API에 대해 설명합니다.

오류 응답 처리

오류 처리는 HTTP 상태 코드를 사용합니다. 일반적인 결과는 다음과 같습니다.

• 2xx – 성공: 정상 작업에 사용됩니다. 응답 본문에 예상된 결과가 포함됩니다.

• 3xx – 리디렉션: 조건부 GET을 수행하기 위해 304 "수정되지 않음"이 반환될 수 있습니다. 나중에 다른 3xx 코드를 사용하여 DNS 및 경로 변경을 나타낼 수 있습니다.

• 4xx – 클라이언트 오류: 잘못된 요청, 누락된 키, 구문 오류, 잘못된 매개 변수, 인증 오류 등에 사용됩니다. 응답 본문에는 자세한 오류 설명이 포함되어 있습니다.

• 5xx – 서버 오류: 내부 서버 오류에 사용됩니다. 응답 본문에는 요약된 오류 정보가 포함되어 있습니다.

  시스템은 프록시 또는 방화벽 뒤에서 작동하도록 설계되었습니다. 따라서 클라이언트는 다른 오류 코드를 받을 수 있습니다.

  또한 Azure Key Vault는 문제가 발생할 때 응답 본문에 오류 정보를 반환합니다. 응답 본문은 JSON 형식으로 되어 있습니다.

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

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

인증 요구 사항

Azure Key Vault에 대한 모든 요청은 인증되어야 합니다. Azure Key Vault는 OAuth2 [RFC6749]를 사용하여 가져올 수 있는 Microsoft Entra 액세스 토큰을 지원합니다.

애플리케이션을 등록하고 Azure Key Vault를 사용하도록 인증하는 방법에 대한 자세한 내용은 Microsoft Entra ID를 사용하여 클라이언트 애플리케이션 등록을 참조하세요.

HTTP 권한 부여 헤더를 사용하여 서비스에 액세스 토큰을 보내야 합니다.

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

액세스 토큰이 제공되지 않거나 서비스에서 토큰을 수락하지 않으면 HTTP 401 오류가 클라이언트에 반환되고 WWW-Authenticate 헤더가 포함됩니다. 예를 들면 다음과 같습니다.

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

WWW-Authenticate 헤더의 매개 변수는 다음과 같습니다.

• 권한 부여: 요청에 대한 액세스 토큰을 가져오는 데 사용할 수 있는 OAuth2 권한 부여 서비스의 주소입니다.

• resource: 권한 부여 요청에 사용할 리소스(https://vault.azure.net)의 이름입니다.