VerifyAPIKey 정책

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

정책 아이콘

개요

API 키 검증 정책을 사용하면 런타임에 API 키 확인을 시행하여 승인된 API 키가 있는 앱만 API에 액세스할 수 있습니다. 이 정책은 API 키가 유효하고 취소되지 않았으며 API 제품과 연결된 특정 리소스를 사용하도록 승인되었습니다.

이 정책은 확장 가능한 정책이며, 이 정책을 사용하면 Apigee 라이선스에 따라 비용 또는 사용률이 영향을 받을 수 있습니다. 정책 유형 및 사용 영향에 대한 자세한 내용은 정책 유형을 참조하세요.

API 키 확인 정책을 사용하는 API 프록시를 빌드하는 방법을 보여주는 튜토리얼은 API 키를 요구하여 API 보호를 참조하세요.

샘플

쿼리 매개변수의 키

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>

이 예시에서 정책은 request.queryparam.apikey라는 흐름 변수에서 API 키를 찾아야 합니다. request.queryparam.{name} 변수는 클라이언트 요청에서 전달된 쿼리 매개변수 값으로 채워진 표준 Apigee 흐름 변수입니다.

다음 curl 명령어는 쿼리 매개변수에서 API 키를 전달합니다.

curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls

헤더의 키

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey" />
</VerifyAPIKey>

이 예시에서 정책은 request.header.x-apikey라는 흐름 변수에서 API 키를 찾아야 합니다. request.header.{name} 변수는 클라이언트 요청에 전달된 헤더 값으로 채워지는 표준 Apigee 흐름 변수입니다.

다음 cURL은 헤더에 API 키를 전달하는 방법을 보여줍니다.

curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"

변수의 키

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="requestAPIKey.key"/>
</VerifyAPIKey>

정책은 키가 포함된 변수를 참조할 수 있습니다. 이 예시에서 정책은 requestAPIKey.key라는 변수에서 API 키를 추출합니다.

이 변수는 자동으로 채워지는 방식입니다. 예를 들어 다음과 같이 변수 추출 정책을 사용하여 requestAPIKey.key라는 쿼리 매개변수에서 requestAPIKey.key를 채울 수 있습니다.

<ExtractVariables async="false" continueOnError="false" enabled="true" name="SetAPIKeyVar">
    <Source>request</Source>
    <QueryParam name="myKey">
        <Pattern ignoreCase="true">{key}</Pattern>
    </QueryParam>
    <VariablePrefix>requestAPIKey</VariablePrefix>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

액세스 정책 흐름 변수

<AssignMessage async="false" continueOnError="false" enabled="true" name="accessverifyvars">
    <AssignVariable>
        <Name>devFirstName</Name>
        <Ref>verifyapikey.verify-api-key.developer.firstName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devLastName</Name>
        <Ref>verifyapikey.verify-api-key.developer.lastName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devEmail</Name>
        <Ref>verifyapikey.verify-api-key.developer.email</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Apigee는 유효한 API 키의 API 키 검증 정책을 실행할 때 흐름 변수 집합을 자동으로 채웁니다. 이러한 변수를 사용하여 앱 이름, 앱 ID, 앱을 등록한 개발자 또는 회사에 대한 정보에 액세스할 수 있습니다. 위의 예시에서 API 키 확인을 실행한 후 메시지 할당 정책을 사용하여 개발자의 이름, 성, 이메일 주소에 액세스할 수 있습니다.

이러한 변수에는 다음 프리픽스가 붙습니다.

verifyapikey.{policy_name}

이 예시에서 API 키 검증 정책 이름은 'verify-api-key'입니다. 따라서 verifyapikey.verify-api-key.developer.firstName. 변수에 액세스하여 요청을 수행하는 개발자의 이름을 참조해야 합니다.

Apigee 알아보기

API 키 검증 정책 정보

개발자가 Apigee에 앱을 등록하면 Apigee는 자동으로 고객 키/비밀번호 조합을 생성합니다. Apigee UI에서 앱의 고객 키/비밀번호 조합을 보거나 Apigee API에서 액세스할 수 있습니다.

앱 등록 시 개발자는 하나 이상의 API 제품을 선택하여 앱에 연결합니다. 여기서 API 제품은 API 프록시를 통해 액세스할 수 있는 리소스 모음입니다. 그런 다음 개발자는 앱과 관련된 API 제품의 API에 대한 모든 요청 중에 API 키 (고객 키)를 전달합니다. 자세한 내용은 게시 개요를 참조하세요.

API 키를 인증 토큰으로 사용하거나 OAuth 액세스 토큰을 얻는 데 사용할 수 있습니다. OAuth에서는 API 키를 '클라이언트 ID'라고 합니다. 이름은 서로 바꿔서 사용할 수 있습니다. 자세한 내용은 OAuth 홈을 참조하세요.

Apigee는 API 키 검증 정책을 실행할 때 일련의 흐름 변수를 자동으로 채웁니다. 자세한 내용은 아래의 흐름 변수를 참조하세요.

요소 참조

이 정책에 구성할 수 있는 요소와 속성은 다음과 같습니다.

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <APIKey ref="variable_containing_api_key"/>
    <CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Default value</CacheExpiryInSeconds/>
</VerifyAPIKey>

<VerifyAPIKey> 속성

다음 예시는 <VerifyAPIKey> 태그의 속성을 보여줍니다.

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">

다음 표는 모든 정책 상위 요소의 공통 속성에 대해 설명합니다.

속성 설명 기본값 Presence
name

정책의 내부 이름입니다. name 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다.

원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.

 해당 사항 없음 필수
continueOnError

정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다.

정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다. 참조:

 false 선택사항
enabled

정책을 시행하려면 true로 설정합니다.

정책을 중지하려면 false로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.

 true 선택사항
async

이 속성은 지원이 중단되었습니다.

 false 지원 중단됨

<DisplayName> 요소

name 속성 외에도 이 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름으로 라벨을 지정합니다.

<DisplayName>Policy Display Name</DisplayName>
기본값

해당 사항 없음

이 요소를 생략하면 정책 name 속성 값이 사용됩니다.
Presence 선택사항
유형 문자열

<APIKey> 요소

이 요소는 API 키가 포함된 흐름 변수를 지정합니다. 일반적으로 클라이언트는 쿼리 매개변수, HTTP 헤더, 양식 매개변수로 API 키를 보냅니다. 예를 들어 키가 x-apikey라는 헤더로 전송되면 키는 변수 request.header.x-apikey에서 찾을 수 있습니다.

기본값 NA
Presence 필수
유형 문자열

속성

다음 표에서는 <APIKey> 요소의 속성을 설명합니다.

속성 설명 기본값 Presence
ref

API 키가 포함된 변수에 대한 참조입니다. 정책당 하나의 위치만 허용됩니다.

 해당 사항 없음 필수

예시

이 예시에서는 키가 매개변수와 x-apikey라는 헤더에 전달됩니다.

쿼리 매개변수:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.x-apikey"/>
</VerifyAPIKey>

HTTP 헤더:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey"/>
</VerifyAPIKey>

HTTP 양식 매개변수:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.formparam.x-apikey"/>
</VerifyAPIKey>

<CacheExpiryInSeconds> 요소

이 요소는 캐시에 TTL을 적용하여 캐시된 액세스 토큰 만료 기간을 맞춤설정할 수 있습니다. 지원되는 범위는 1~180초입니다. 흐름 변수와 기본 변수를 제공할 수 있습니다. 제공된 경우 흐름 변수 값이 지정된 기본값보다 우선 적용됩니다. 

<CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Value 1</CacheExpiryInSeconds>
기본값 해당 사항 없음

이 요소를 생략하면 캐시된 액세스 토큰의 기본 만료 기간은 180초입니다.
Presence 선택사항
유형 정수
유효한 값 0이 아닌 양의 정수. 만료 시간을 초 단위로 지정합니다.

속성

다음 표에서는 <CacheExpiryInSeconds> 요소의 속성을 설명합니다.

속성 설명 기본값 Presence
ref

캐시 만료 값을 포함하는 흐름 변수에 대한 참조(초 단위)입니다.

제공된 경우 흐름 변수 값이 지정된 기본값보다 우선 적용됩니다.

 해당 사항 없음 선택사항

스키마

흐름 변수

유효한 API 키에 API 키 검증 정책이 적용되면 Apigee가 일련의 흐름 변수를 채웁니다. 이러한 변수는 흐름 후반에 실행되는 정책 또는 코드에 사용할 수 있으며 앱 이름 같은 API 키의 속성, 키 승인에 사용되는 API 제품, 또는 API 키의 커스텀 속성을 기반으로 커스텀 처리를 수행하는 데 자주 사용됩니다.

정책은 다음과 같은 여러 유형의 흐름 변수를 채웁니다.

  • 일반설정
  • 앱
  • 개발자
  • 분석
  • 수익 창출

흐름 변수 유형마다 프리픽스가 다릅니다. 모든 변수는 배열로 특별히 지정된 변수를 제외하고 스칼라입니다.

일반 흐름 변수

다음 표에는 API 키 검증 정책으로 채운 일반적인 흐름 변수가 나와 있습니다. 이러한 변수에는 다음 프리픽스가 붙습니다.

verifyapikey.{policy_name}

예: verifyapikey.{policy_name}.client_id

사용 가능한 변수는 다음과 같습니다.

변수 설명
client_id 요청한 앱에서 제공하는 고객 키(API 키 또는 앱 키라고도 함)입니다.
client_secret 고객 키와 연결된 고객 보안 비밀입니다.
redirection_uris 요청의 모든 리디렉션 URI입니다.
developer.app.id

요청을 실행하는 개발자 또는 AppGroup 앱의 ID입니다.
developer.app.name 요청을 실행하는 개발자 또는 AppGroup 앱의 앱 이름입니다.
developer.id

요청하는 앱의 소유자로 등록된 개발자 또는 AppGroup의 ID입니다.
developer.{custom_attrib_name} 앱 키 프로필에서 파생된 모든 커스텀 속성입니다.
DisplayName 정책의 <DisplayName> 속성 값입니다.
failed API 키 검증이 실패하면 'true'로 설정됩니다.
{custom_app_attrib} 앱 프로필에서 파생된 모든 커스텀 속성입니다. 커스텀 속성의 이름을 지정합니다.
apiproduct.name* 요청 유효성을 검사하는 데 사용되는 API 제품의 이름입니다.
apiproduct.{custom_attrib_name}* API 제품 프로필에서 파생된 모든 커스텀 속성입니다.
apiproduct.developer.quota.limit* API 제품에 설정된 할당량 한도입니다(있는 경우).
apiproduct.developer.quota.interval* API 제품에 설정된 할당량 간격입니다(있는 경우).
apiproduct.developer.quota.timeunit* API 제품에 설정된 할당량 시간 단위입니다(있는 경우).
* API 제품이 유효한 환경, 프록시, 리소스로 구성된 경우(proxy.pathsuffix에서 파생됨) API 제품 변수가 자동으로 채워집니다. API 제품 설정에 대한 자세한 내용은 API 제품 관리를 참조하세요.

앱 흐름 변수

앱에 대한 정보가 포함된 다음 흐름 변수는 정책으로 채워집니다. 이러한 변수에는 다음 프리픽스가 붙습니다.

verifyapikey.{policy_name}.app

예를 들면 다음과 같습니다.

verifyapikey.{policy_name}.app.name

사용 가능한 변수는 다음과 같습니다.

변수 설명
name 애플리케이션의 이름입니다.
id 앱의 ID입니다.
accessType Apigee에서 사용하지 않습니다.
callbackUrl 앱의 콜백 URL입니다. 일반적으로 OAuth에만 사용됩니다.
DisplayName 앱의 표시 이름입니다.
status 앱 상태입니다(예: '승인됨' 또는 '취소됨').
apiproducts 앱과 연결된 API 제품의 목록이 포함된 배열입니다.
appFamily 앱 또는 '기본값'이 포함된 앱 제품군입니다.
appParentStatus 앱 상위 요소의 상태입니다(예: '활성' 또는 '비활성').
appType '개발자'로서의 앱 유형입니다.
appParentId 상위 앱의 ID입니다.
created_at 앱이 생성된 날짜/시간 스탬프입니다.
created_by 앱을 만든 개발자의 이메일 주소입니다.
last_modified_at 앱이 마지막으로 업데이트된 날짜/시간 스탬프입니다.
last_modified_by 마지막으로 앱을 업데이트한 개발자의 이메일 주소입니다.
{app_custom_attributes} 모든 커스텀 앱 속성입니다. 커스텀 속성의 이름을 지정합니다.

AppGroup 흐름 변수

AppGroups에 대한 정보가 포함된 다음 흐름 변수는 정책으로 채워집니다. 이러한 AppGroup 속성은 verifyapikey.{policy_name}.app.appType이 'AppGroup'인 경우에만 채워집니다.

이러한 변수에는 다음 프리픽스가 붙습니다.

verifyapikey.{policy_name}.appgroup

예를 들면 다음과 같습니다.

verifyapikey.{policy_name}.appgroup.name

사용 가능한 변수는 다음과 같습니다.

변수 설명
name AppGroup의 이름입니다.
id AppGroup ID입니다.
displayName AppGroup 표시 이름입니다.
appOwnerStatus 앱 소유자의 상태: '활성', '비활성' 또는 'login_lock'
created_at AppGroup이 생성된 날짜/시간 스탬프입니다.
created_by AppGroup을 만든 개발자의 이메일 주소입니다.
last_modified_at AppGroup이 마지막으로 수정된 날짜/시간 스탬프입니다.
last_modified_by AppGroup을 마지막으로 수정한 개발자의 이메일 주소입니다.
{appgroup_custom_attributes} 모든 커스텀 AppGroup 속성입니다. 커스텀 속성의 이름을 지정합니다.

개발자 흐름 변수

개발자에 대한 정보가 포함된 다음 흐름 변수는 정책으로 채워집니다. 이러한 변수에는 다음 프리픽스가 붙습니다.

verifyapikey.{policy_name}.developer

예를 들면 다음과 같습니다.

verifyapikey.{policy_name}.developer.id

사용 가능한 변수는 다음과 같습니다.

변수 설명
id {org_name}@@@{developer_id} 반환
userName 개발자의 사용자 이름입니다.
firstName 개발자의 이름입니다.
lastName 개발자의 성
email 개발자의 이메일 주소
status 개발자 상태(active, inactive 또는 login_lock)
apps 개발자와 연결된 앱의 배열입니다.
created_at 개발자가 생성된 날짜/시간 스탬프입니다.
created_by 개발자를 만든 사용자의 이메일 주소입니다.
last_modified_at 개발자가 마지막으로 수정된 날짜/시간 스탬프입니다.
last_modified_by 개발자를 수정한 사용자의 이메일 주소입니다.
{developer_custom_attributes} 모든 커스텀 개발자 속성입니다. 커스텀 속성의 이름을 지정합니다.

분석 변수

다음 변수는 유효한 API 키에 대해 API 키 검증 정책이 시행되면 애널리틱스에서 자동으로 채워집니다. 이러한 변수는 API 키 검증 정책 및 OAuth 정책으로만 채웁니다.

변수와 값을 측정기준으로 사용하여 개발자 및 앱의 사용 패턴을 파악할 수 있습니다.

  • apiproduct.name
  • developer.app.name
  • client_id
  • developer.id

수익 창출 흐름 변수

VerifyAPIKey 정책은 사용자를 인증한 후에 모든 게시된 요금제를 확인하여 활성화 및 만료 시간을 기준으로 활성 상태인 요금제를 확인합니다. 활성 게시 요금제가 있는 경우 다음 흐름 변수가 채워집니다.

변수 설명
mint.mintng_is_apiproduct_monetized true: 활성 게시 요금제가 있는 경우
mint.mintng_rate_plan_id 요금제 ID입니다.
mint.rateplan_end_time_ms 요금제의 만료 시간입니다. 예시: 1619433556408
mint.rateplan_start_time_ms 요금제의 활성화 시간입니다. 예: 1618433956209

오류 참조

이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.

런타임 오류

이러한 오류는 정책이 실행될 때 발생할 수 있습니다.

오류 코드 HTTP 상태 원인
keymanagement.service.consumer_key_missing_api_product_association 400

애플리케이션 사용자 인증 정보에 API 제품 연결이 없습니다. 키의 애플리케이션을 API 제품과 연결하세요. 이는 개발자 앱 및 AppGroup 앱과 같은 모든 애플리케이션 유형에 적용됩니다.
keymanagement.service.DeveloperStatusNotActive 401

사용 중인 API 키가 있는 개발자 앱을 만든 개발자가 비활성 상태입니다. 앱 개발자의 상태가 비활성으로 설정되면 해당 개발자에 의해 생성된 모든 개발자 앱은 비활성화됩니다. 적절한 권한을 가진 관리자(예: 조직 관리자)는 다음과 같은 방법으로 개발자 상태를 변경할 수 있습니다.
keymanagement.service.invalid_client-app_not_approved 401 API 키와 연결된 개발자 앱이 취소되었습니다. 취소된 앱은 API 제품에 액세스할 수 없으며 Apigee에서 관리하는 API를 호출할 수 없습니다. 조직 관리자는 Apigee API를 사용하여 개발자 앱의 상태를 변경할 수 있습니다. 자세한 내용은 키 쌍 생성 또는 개발자 앱 상태 업데이트를 참조하세요.
oauth.v2.FailedToResolveAPIKey 401 정책은 정책의 <APIKey> 요소에 지정된 변수에서 API 키를 찾습니다.이 오류는 예상 변수가 존재하지 않는 경우 발생합니다(해결할 수 없음).
oauth.v2.InvalidApiKey 401 Apigee에서 잘못된 API 키를 수신했습니다. Apigee가 데이터베이스에서 키를 조회할 때, 이는 요청에서 전송된 것과 정확하게 일치해야 합니다. API가 이전에 작동했다면 키가 다시 생성되지 않았는지 확인합니다. 키가 다시 생성된 경우 이전 키를 사용하려고 하면 이 오류가 표시됩니다. 자세한 내용은 앱을 등록하여 API에 대한 액세스 제어를 참조하세요.
oauth.v2.InvalidApiKeyForGivenResource 401 Apigee에서 API 키를 수신했으며 유효한 상태이지만 제품을 통해 API 프록시와 연결된 개발자 앱의 승인된 키와 일치하지 않습니다.

배포 오류

이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.

오류 이름 원인
SpecifyValueOrRefApiKey <APIKey> 요소에 지정된 값 또는 키가 없습니다.

오류 변수

이러한 변수는 런타임 오류가 발생하면 설정됩니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.

변수 장소 예
fault.name="fault_name" fault_name은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다. fault.name Matches "FailedToResolveAPIKey"
oauthV2.policy_name.failed policy_name은 오류를 발생시킨 정책의 사용자 지정 이름입니다. oauthV2.VK-VerifyAPIKey.failed = true

오류 응답 예시

{  
   "fault":{  
      "faultstring":"Invalid ApiKey",
      "detail":{  
         "errorcode":"oauth.v2.InvalidApiKey"
      }
   }
}
 
{  
   "fault":{  
      "detail":{  
         "errorcode":"keymanagement.service.DeveloperStatusNotActive"
      },
      "faultstring":"Developer Status is not Active"
   }
}

오류 규칙 예시

<FaultRule name="FailedToResolveAPIKey">
    <Step>
        <Name>AM-FailedToResolveAPIKey</Name>
    </Step>
    <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition>
</FaultRule>