인증, 요청 및 응답Authentication, requests and responses

Azure Key Vault는 JSON 형식 요청과 응답을 지원합니다.Azure Key Vault supports JSON formatted requests and responses. Azure Key Vault에 대한 요청은 일부 URL 매개 변수 및 JSON 인코딩 요청 및 응답 본문을 통해 HTTPS를 사용하여 올바른 Azure Key Vault URL로 이동됩니다.Requests to the Azure Key Vault are directed to a valid Azure Key Vault URL using HTTPS with some URL parameters and JSON encoded request and response bodies.

이 항목에서는 Azure Key Vault 서비스에 대한 구체적인 정보를 다룹니다.This topic covers specifics for the Azure Key Vault service. 인증/권한 부여 및 액세스 토큰을 확보하는 방법을 비롯한 Azure REST 인터페이스 사용에 대한 일반적인 정보는 Azure REST API 참조를 참조하세요.For general information on using Azure REST interfaces, including authentication/authorization and how to acquire an access token, see Azure REST API Reference.

요청 URLRequest URL

키 관리 작업은 HTTP DELETE, GET, PATCH, PUT 및 HTTP POST 및 HTTP POST를 사용하는 기존 키 개체에 대한 암호화 작업을 사용합니다.Key management operations use HTTP DELETE, GET, PATCH, PUT and HTTP POST and cryptographic operations against existing key objects use HTTP POST. 특정 HTTP 동사를 지원할 수 없는 클라이언트는 X-HTTP-REQUEST 헤더를 사용한 HTTP POST를 사용하여 대상 동사를 지정할 수 있습니다. HTTP POST를 사용하는 경우(예: DELETE 대신 POST를 사용하는 경우) 일반적으로 본문이 필요하지 않은 요청은 빈 본문을 포함해야 합니다.Clients that cannot support specific HTTP verbs may also use HTTP POST using the X-HTTP-REQUEST header to specify the intended verb; requests that do not normally require a body should include an empty body when using HTTP POST, for example when using POST instead of DELETE.

Azure Key Vault에 있는 개체를 사용하기 위한 예제 URL은 다음과 같습니다.To work with objects in the Azure Key Vault, the following are example URLs:

  • Key Vault에서 TESTKEY라는 키를 만들려면 PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1 사용To CREATE a key called TESTKEY in a Key Vault use - PUT /keys/TESTKEY?api-version=<api_version> HTTP/1.1

  • Key Vault에서 IMPORTEDKEY라는 키를 가져오려면 POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1 사용To IMPORT a key called IMPORTEDKEY into a Key Vault use - POST /keys/IMPORTEDKEY/import?api-version=<api_version> HTTP/1.1

  • Key Vault에서 MYSECRET이라는 비밀을 가져오려면 GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1 사용To GET a secret called MYSECRET in a Key Vault use - GET /secrets/MYSECRET?api-version=<api_version> HTTP/1.1

  • Key Vault에서 TESTKEY라는 키를 사용하여 다이제스트에 서명하려면 POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1 사용To SIGN a digest using a key called TESTKEY in a Key Vault use - POST /keys/TESTKEY/sign?api-version=<api_version> HTTP/1.1

    Key Vault에 대한 요청을 위한 기관은 항상 다음과 같습니다. https://{keyvault-name}.vault.azure.net/The authority for a request to a Key Vault is always as follows, https://{keyvault-name}.vault.azure.net/

    키는 항상 /keys 경로에 저장되며, 비밀은 항상 /secrets 경로에 저장됩니다.Keys are always stored under the /keys path, Secrets are always stored under the /secrets path.

API 버전API Version

Azure Key Vault 서비스는 일부 기능을 해당 클라이언트에서 사용할 수 있는 하위 수준 클라이언트와의 호환성을 제공하기 위해 프로토콜 버전 관리를 지원합니다.The Azure Key Vault Service supports protocol versioning to provide compatibility with down-level clients, although not all capabilities will be available to those clients. 클라이언트는 기본값이 없으므로 지원하는 프로토콜의 버전을 지정하려면 api-version 쿼리 문자열 매개 변수를 사용해야 합니다.Clients must use the api-version query string parameter to specify the version of the protocol that they support as there is no default.

Azure Key Vault 프로토콜 버전은 {YYYY} {MM} {DD} 형식을 사용하는 날짜 수 스키마를 따릅니다.Azure Key Vault protocol versions follow a date numbering scheme using a {YYYY}.{MM}.{DD} format.

요청 본문Request Body

HTTP 사양에 따라 GET 작업은 요청 본문을 포함할 수 없으며 POST 및 PUT 작업은 요청 본문을 포함해야 합니다.As per the HTTP specification, GET operations must NOT have a request body, and POST and PUT operations must have a request body. DELETE 작업의 본문은 HTTP의 경우 선택 사항입니다.The body in DELETE operations is optional in HTTP.

작업 설명에 별도로 언급되지 않는 한, 요청 본문 콘텐츠 형식은 application/json이어야 하며 콘텐츠 형식을 따르는 직렬화된 JSON 개체를 포함해야 합니다.Unless otherwise noted in operation description, the request body content type must be application/json and must contain a serialized JSON object conformant to content type.

작업 설명에 별도로 언급되지 않는 한, Accept 요청 헤더는 application/json 미디어 유형을 포함해야 합니다.Unless otherwise noted in operation description, the Accept request header must contain the application/json media type.

응답 본문Response Body

작업 설명에 별도로 언급되지 않는 한, 성공 및 실패한 작업의 응답 본문 콘텐츠 형식은 application/json이어야 하며 자세한 오류 정보를 포함합니다.Unless otherwise noted in operation description, the response body content type of both successful and failed operations will be application/json and contains detailed error information.

HTTP POST 사용Using HTTP POST

일부 클라이언트는 PATCH 또는 DELETE와 같은 특정 HTTP 동사를 사용할 수 없습니다.Some clients may not be able to use certain HTTP verbs, such as PATCH or DELETE. Azure Key Vault는 원래 HTTP 동사에 특정적인 “X-HTTP-METHOD” 헤더가 포함되어 제공되는 이러한 클라이언트에 대한 대안으로 HTTP POST를 지원합니다.Azure Key Vault supports HTTP POST as an alternative for these clients provided that the client also includes the “X-HTTP-METHOD” header to specific the original HTTP verb. HTTP POST에 대한 지원은 이 문서에서 정의된 각 API에 대해 언급됩니다.Support for HTTP POST is noted for each of the API defined in this document.

오류 응답Error Responses

오류 처리는 HTTP 상태 코드를 사용합니다.Error handling will use HTTP status codes. 일반적인 결과는 다음과 같습니다.Typical results are:

  • 2xx – 성공: 일반 작업에 사용됩니다.2xx – Success: Used for normal operation. 응답 본문은 예상된 결과를 포함합니다.The response body will contain the expected result

  • 3xx – 리디렉션: 조건부 GET을 충족하기 위해 304 “수정되지 않음”이 반환될 수 있습니다.3xx – Redirection: The 304 "Not Modified" may be returned to fulfill a conditional GET. 나중에 DNS 및 경로 변경을 나타내기 위해 다른 3xx 코드가 사용될 수 있습니다.Other 3xx codes may be used in the future to indicate DNS and path changes.

  • 4xx – 클라이언트 오류: 잘못 된 요청, 누락 된 키, 구문 오류, 잘못 된 매개 변수, 인증 오류 등에 사용 됩니다. 응답 본문에는 자세한 오류 설명이 포함 됩니다.4xx – Client Error: Used for bad requests, missing keys, syntax errors, invalid parameters, authentication errors, etc. The response body will contain detailed error explanation.

  • 5xx – 서버 오류: 내부 서버 오류에 사용됩니다.5xx – Server Error: Used for internal server errors. 응답 본문에는 요약된 오류 정보가 포함됩니다.The response body will contain summarized error information.

    시스템은 프록시 또는 방화벽 뒤에서 작업하도록 고안되었습니다.The system is designed to work behind a proxy or firewall. 따라서 클라이언트는 다른 오류 코드를 받을 수도 있습니다.Therefore, a client might receive other error codes.

    또한 Azure Key Vault는 문제가 발생하는 경우 응답 본문에 오류 정보를 반환합니다.Azure Key Vault also returns error information in the response body when a problem occurs. 응답 본문은 JSON 형식이며 다음과 같은 형식을 사용합니다.The response body is JSON formatted and takes the form:


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

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

인증Authentication

Azure Key Vault에 대한 모든 요청은 인증되어야 합니다.All requests to Azure Key Vault MUST be authenticated. Azure Key Vault는 OAuth2를 사용하여 가져올 수 있는 Azure Active Directory 액세스 토큰을 지원합니다[RFC6749].Azure Key Vault supports Azure Active Directory access tokens that may be obtained using OAuth2 [RFC6749].

애플리케이션 등록 및 Azure Key Vault 사용을 위한 인증에 대한 자세한 내용은 Azure AD로 클라이언트 애플리케이션 등록을 참조하세요.For more information on registering your application and authenticating to use Azure Key Vault, see Register your client application with Azure AD.

액세스 토큰은 HTTP 권한 부여 헤더를 사용하여 서비스에 전송해야 합니다.Access tokens must be sent to the service using the HTTP Authorization header:

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

액세스 토큰이 적용되지 않거나 토큰이 서비스에서 수락되지 않는 경우 HTTP 401 오류가 클라이언트에 반환되고 다음 예제와 같이 WWW-Authenticate 헤더를 포함하게 됩니다.When an access token is not supplied, or when a token is not accepted by the service, an HTTP 401 error will be returned to the client and will include the WWW-Authenticate header, for example:

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

WWW-Authenticate 헤더에 대한 매개 변수는 다음과 같습니다.The parameters on the WWW-Authenticate header are:

  • 권한 부여: 요청에 대한 액세스 토큰을 가져오는 데 사용할 수 있는 OAuth2 권한 부여 서비스의 주소입니다.authorization: The address of the OAuth2 authorization service that may be used to obtain an access token for the request.

  • 리소스: https://vault.azure.net 권한 부여 요청에 사용할 리소스 ()의 이름입니다.resource: The name of the resource (https://vault.azure.net) to use in the authorization request.