Azure Key Vault REST API 오류 코드

  • 아티클

Azure Key Vault 웹 서비스의 작업에서 다음 오류 코드를 반환할 수 있습니다.

HTTP 401: 인증되지 않은 요청

401은 요청이 Key Vault에 대해 인증되지 않음을 의미합니다.

다음 경우 요청이 인증됩니다.

  • 키 자격 증명 모음은 호출자의 ID를 알고 있습니다. 및
  • 호출자는 Key Vault 리소스에 액세스하려고 할 수 있습니다.

요청이 401을 반환할 수 있는 몇 가지 이유가 있습니다.

요청에 연결된 인증 토큰 없음

다음은 비밀 값을 설정하는 PUT 요청의 예입니다.

PUT https://putreqexample.vault.azure.net//secrets/DatabaseRotatingPassword?api-version=7.0 HTTP/1.1
x-ms-client-request-id: 03d275a2-52a4-4bed-82c8-6fe15165affb
accept-language: en-US
Authorization: Bearer     eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Im5iQ3dXMTF3M1hrQi14VWFYd0tSU0xqTUhHUSIsImtpZCI6Im5iQ3dXMTF3M1hrQi14VWFYd0tSU0xqTUhHUSJ9.eyJhdWQiOiJodHRwczovL3ZhdWx0LmF6dXJlLm5ldCIsImlzcyI6Imh0dHBzOi8vc3RzLndpbmRvd3MubmV0LzcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0Ny8iLCJpYXQiOjE1NDg2OTc1MTMsIm5iZiI6MTU0ODY5NzUxMywiZXhwIjoxNTQ4NzAxNDEzLCJhaW8iOiI0MkpnWUhoODVqaVBnZHF5ZlRGZE5TdHY3bGUvQkFBPSIsImFwcGlkIjoiZmFkN2Q1YjMtNjlkNi00YjQ4LTkyNTktOGQxMjEyNGUxY2YxIiwiYXBwaWRhY3IiOiIxIiwiaWRwIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3LyIsIm9pZCI6IjM5NzVhZWVkLTdkMDgtNDUzYi1iNmY0LTQ0NWYzMjY5ODA5MSIsInN1YiI6IjM5NzVhZWVkLTdkMDgtNDUzYi1iNmY0LTQ0NWYzMjY5ODA5MSIsInRpZCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsInV0aSI6IjItZ3JoUmtlSWs2QmVZLUxuNDJtQUEiLCJ2ZXIiOiIxLjAifQ.fgubiz1MKqTJTXI8dHIV7t9Fle6FdHrkaGYKcBeVRX1WtLVuk1QVxzIFDlZKLXJ7QPNs0KWpeiWQI9IWIRK-8wO38yCqKTfDlfHOiNWGOpkKddlG729KFqakVf2w0GPyGPFCONRDAR5wjQarN9Bt8I8YbHwZQz_M1hztlnv-Lmsk1jBmech9ujD9-lTMBmSfFFbHcqquev119V7sneI-zxBZLf8C0pIDkaXf1t8y6Xr8CUJDMdlWLslCf3pBCNIOy65_TyGvy4Z4AJryTPBarNBPwOkNAtjCfZ4BDc2KqUZM5QN_VK4foP64sVzUL6mSr0Gh7lQJIL5b1qIpJxjxyQ
User-Agent: FxVersion/4.7.3324.0 OSName/Windows OSVersion/6.2.9200.0 Microsoft.Azure.KeyVault.KeyVaultClient/3.0.3.0
Content-Type: application/json; charset=utf-8
Host: putreqexample.vault.azure.net
Content-Length: 31

{
   "value": "m*gBJ7$Zuoz)"
}

"인증" 헤더는 data-plane 작업에 대한 Key Vault를 호출할 때마다 필요한 액세스 토큰입니다. 헤더가 누락된 경우 응답은 401이어야 합니다.

토큰에 연결된 올바른 리소스가 부족합니다.

Azure OAUTH 엔드포인트에서 액세스 토큰을 요청하는 경우 "리소스"라는 매개 변수가 필수입니다. 이 값은 토큰 공급자가 의도한 용도로 토큰 범위를 지정하기 때문에 중요합니다. Key Vault에 액세스하는 모든 토큰에 대한 리소스는 https://vault.keyvault.net(후행 슬래시 없음)입니다.

토큰이 만료되었습니다.

토큰은 base64로 인코딩되고 값은 http://jwt.calebb.net과 같은 웹 사이트에서 디코딩할 수 있습니다. 디코딩된 위의 토큰은 다음과 같습니다.

    {
 typ: "JWT",
 alg: "RS256",
 x5t: "nbCwW11w3XkB-xUaXwKRSLjMHGQ",
 kid: "nbCwW11w3XkB-xUaXwKRSLjMHGQ"
}.
{
 aud: "https://vault.azure.net",
 iss: "https://sts.windows.net/72f988bf-86f1-41af-91ab-2d7cd011db47/",
 iat: 1548697513,
 nbf: 1548697513,
 exp: 1548701413,
 aio: "42JgYHh85jiPgdqyfTFdNStv7le/BAA=",
 appid: "fad7d5b3-69d6-4b48-9259-8d12124e1cf1",
 appidacr: "1",
 idp: "https://sts.windows.net/72f988bf-86f1-41af-91ab-2d7cd011db47/",
 oid: "3975aeed-7d08-453b-b6f4-445f32698091",
 sub: "3975aeed-7d08-453b-b6f4-445f32698091",
 tid: "72f988bf-86f1-41af-91ab-2d7cd011db47",
 uti: "2-grhRkeIk6BeY-Ln42mAA",
 ver: "1.0"
}.
[signature]

이 토큰에서 여러 가지 중요한 부분을 확인할 수 있습니다.

  • aud(대상 그룹): 토큰의 리소스입니다. https://vault.azure.net이 그것입니다. 이 토큰은 그래프와 같이 이 값과 명시적으로 일치하지 않는 리소스에는 작동하지 않습니다.
  • iat(발급 시): 토큰이 발급된 Epoch가 시작된 이후의 틱 수입니다.
  • nbf(이전이 아님): 이 토큰이 유효해질 때 Epoch가 시작된 이후의 틱 수입니다.
  • exp(expiration): 이 토큰이 만료될 때 Epoch가 시작된 이후 발생되는 틱 수입니다.
  • appid(애플리케이션 ID): 이 요청을 만드는 애플리케이션 ID의 GUID입니다.
  • tid(테넌트 ID): 이 요청을 만드는 보안 주체의 테넌트 ID에 대한 GUID입니다.

요청이 작동하려면 토큰에서 모든 값을 올바르게 식별해야 합니다. 모든 것이 올바르면 요청이 401로 이어지지 않습니다.

문제 해결 401

키 자격 증명 모음에 대한 요청이 이루어지기 전에 토큰 생성 시점부터 401을 조사해야 합니다. 일반적으로 토큰을 요청하는 데 코드가 사용됩니다. 토큰이 수신되면 Key Vault 요청에 전달됩니다. 코드가 로컬로 실행되는 경우 Fiddler를 사용하여 요청/응답을 캡처할 https://login.microsoftonline.com수 있습니다. 요청은 다음과 같은 형태입니다.


POST https://login.microsoftonline.com/<key vault tenant ID>/oauth2/token HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: login.microsoftonline.com
Content-Length: 192

resource=https%3A%2F%2Fvault.azure.net&client_id=<registered-app-ID>&client_secret=<registered-app-secret>&client_info=1&grant_type=client_credentials

다음 사용자가 제공한 정보는 정확해야 합니다.

  • Key Vault 테넌트 ID
  • https%3A%2F%2Fvault.azure.net으로 설정된 리소스 값(URL 인코딩)
  • 클라이언트 ID
  • 클라이언트 암호

나머지 요청이 거의 동일한지 확인합니다.

응답 액세스 토큰만 가져올 수 있는 경우 테넌트 ID, 클라이언트 ID(앱 ID) 및 리소스를 확인하기 위해 디코딩할 수 있습니다.

HTTP 403: 권한 부족

HTTP 403은 요청이 인증되었지만(요청 ID를 알고) ID에 요청된 리소스에 액세스할 수 있는 권한이 없음을 의미합니다. 다음과 같은 두 가지 원인이 있습니다.

  • ID에 대한 액세스 정책이 없습니다.
  • 요청 리소스의 IP 주소는 키 자격 증명 모음의 방화벽 설정에서 승인되지 않습니다.

HTTP 403은 고객의 애플리케이션이 고객이 생각하는 클라이언트 ID를 사용하지 않을 때 종종 발생합니다. 이는 일반적으로 실제 호출 ID에 대해 액세스 정책이 올바르게 설정되지 않았음을 의미합니다.

액세스 정책에 ID를 추가한 직후 403 오류가 발생하는 경우 주기적인 재시도로 처리할 수 있습니다.

403 문제 해결

먼저 로깅을 켭니다. 이 작업을 수행하는 방법에 대한 지침은 Azure Key Vault 로깅을 참조하세요.

로깅을 켜면 403이 액세스 정책 때문인지 방화벽 정책 때문인지 확인할 수 있습니다.

방화벽 정책으로 인한 오류

"클라이언트 주소(00.00.00.00)는 권한이 없으며 호출자는 신뢰할 수 있는 서비스가 아닙니다."

"Azure 신뢰할 수 있는 서비스" 목록이 제한되어 있습니다. Azure 웹 사이트는 신뢰할 수 있는 Azure 서비스가 아닙니다 . 자세한 내용은 Azure 앱 Services의 Key Vault 방화벽 액세스 후 블로그를 참조하세요.

작동하려면 Azure 웹 사이트의 IP 주소를 Key Vault에 추가해야 합니다.

액세스 정책으로 인해 발생하는 경우: 요청에 대한 개체 ID를 찾고 개체 ID가 사용자가 액세스 정책을 할당하려는 개체와 일치하는지 확인합니다. Microsoft Entra ID에는 이름이 같은 개체가 여러 개 있는 경우가 많으므로 올바른 개체를 선택하는 것이 중요합니다. 액세스 정책을 삭제하고 읽으면 이름이 같은 여러 개체가 있는지 확인할 수 있습니다.

또한 대부분의 액세스 정책에는 포털에 표시된 것처럼 "권한 있는 응용 프로그램"을 사용할 필요가 없습니다. 승인된 애플리케이션은 드물게 "On-Behalf-Of" 인증 시나리오에 사용됩니다.

HTTP 429: 요청이 너무 많음

요청 수가 해당 기간에 대해 명시된 최댓값을 초과할 때 제한이 발생합니다. 제한이 발생하면 Key Vault의 응답은 HTTP 429가 됩니다. 요청 유형에 대해 명시된 최대값이 있습니다. 예: HSM 2048비트 키 만들기는 10초당 10개의 요청이지만 다른 모든 HSM 트랜잭션은 10초당 2,000개의 요청으로 제한됩니다. 따라서 제한의 원인을 확인할 때 어떤 유형의 호출을 수행하는지 파악하는 것이 중요합니다. 일반적으로 Key Vault에 대한 요청은 요청 4,000개/10초로 제한됩니다. 예외는 Key Vault 서비스 제한에 설명된 것처럼 키 작업입니다.

문제 해결 429

제한은 다음 기술을 사용하여 해결됩니다.

  • 요청된 리소스에 대한 패턴이 있는지 확인하고 호출 애플리케이션에서 캐시하려고 시도하여 Key Vault에 대한 요청 수를 줄입니다.

  • Key Vault 제한이 발생하면 재시도에 지수 백오프를 사용하도록 요청 코드를 조정합니다. 알고리즘은 다음과 같이 설명합니다. 앱을 제한하는 방법

  • 캐싱을 통해 요청 수를 줄일 수 없고 시간이 제한된 백오프가 작동하지 않는 경우 키를 여러 Key Vault로 분할하는 것이 좋습니다. 단일 구독에 대한 서비스 제한은 개별 Key Vault 제한의 5배입니다. 5개 이상의 Key Vault를 사용하는 경우 여러 구독을 사용할 때 고려해야 합니다.

한도 증가 요청을 포함한 자세한 지침은 Key Vault 제한 지침에서 확인할 수 있습니다.