<ph type="x-smartling-placeholder"></ph>
현재 Apigee Edge 문서를 보고 있습니다.
Apigee X 문서. 정보
대상
API 키 검증 정책을 사용하면 런타임에 API 키 확인을 시행하여 승인된 API 키가 있는 앱만 API에 액세스할 수 있습니다. 이 정책은 API 키가 유효하고 취소되지 않았으며 API 제품과 연결된 특정 리소스를 사용하도록 승인되었습니다.
샘플
쿼리 매개변수의 키
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.queryparam.apikey" /> </VerifyAPIKey>
이 예시에서 정책은 request.queryparam.apikey
라는 흐름 변수에서 API 키를 찾아야 합니다. request.queryparam.{name}
변수
전달된 쿼리 매개변수의 값으로 채워지는 표준 에지 흐름 변수입니다.
클라이언트 요청에 포함되지 않습니다.
다음 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}
변수
전달된 헤더 값으로 채워지는 표준 에지 흐름 변수입니다.
클라이언트 요청에 포함되지 않습니다.
다음 cURL은 헤더에 API 키를 전달하는 방법을 보여줍니다.
curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"
변수의 키
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="requestAPIKey.key"/> </VerifyAPIKey>
정책은 키가 포함된 변수를 참조할 수 있습니다. 이 예시에서 정책은 requestAPIKey.key라는 변수에서 API 키를 추출합니다.
이 변수는 자동으로 채워지는 방식입니다. 예를 들어 다음과 같이 변수 추출 정책을 사용하여 myKey라는 쿼리 매개변수에서 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>
Verify API 키를 실행할 때 Edge에서 일련의 흐름 변수를 자동으로 채웁니다. 유효한 API 키에 대한 정책입니다. 이러한 변수를 사용하여 앱 이름, 앱 ID, 앱을 등록한 개발자 또는 회사에 대한 정보에 액세스할 수 있습니다. 위의 예시에서 API 키 확인을 실행한 후 메시지 할당 정책을 사용하여 개발자의 이름, 성, 이메일 주소에 액세스할 수 있습니다.
이러한 변수에는 다음 프리픽스가 붙습니다.
verifyapikey.{policy_name}
이 예시에서 API 키 검증 정책 이름은 'verify-api-key'입니다. 따라서 verifyapikey.verify-api-key.developer.firstName.
변수에 액세스하여 요청을 수행하는 개발자의 이름을 참조해야 합니다.
Edge 알아보기
API 키 검증 정책 정보
개발자가 Edge에 앱을 등록하면 Edge는 자동으로 소비자 키를 생성하고 보안 비밀 쌍입니다. Edge UI에서 앱의 고객 키와 비밀번호 쌍을 확인하거나 액세스할 수 있습니다. 사용할 수 있습니다
앱 등록 시 개발자는 하나 이상의 API 제품을 선택하여 앱에 연결합니다. 여기서 API 제품은 API 프록시를 통해 액세스할 수 있는 리소스 모음입니다. 그런 다음 개발자는 앱과 관련된 API 제품의 API에 대한 모든 요청 중에 API 키 (고객 키)를 전달합니다. 자세한 내용은 게시 개요를 참조하세요.
API 키를 인증 토큰으로 사용하거나 OAuth 액세스 토큰을 얻는 데 사용할 수 있습니다. OAuth에서는 API 키를 '클라이언트 ID'라고 합니다. 이름은 서로 바꿔서 사용할 수 있습니다. 자세한 내용은 OAuth 홈을 참조하세요.
Edge는 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"/> </VerifyAPIKey>
<VerifyAPIKey> 속성
다음 예시는 <VerifyAPIKey>
태그의 속성을 보여줍니다.
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
다음 표는 모든 정책 상위 요소의 공통 속성에 대해 설명합니다.
속성 | 설명 | 기본값 | 현재 상태 |
---|---|---|---|
name |
정책의 내부 이름입니다. 원하는 경우 |
해당 없음 | 필수 |
continueOnError |
정책이 실패할 경우 오류가 반환되도록 하려면 정책이 실패해도 흐름 실행이 계속되도록 하려면 |
거짓 | 선택사항 |
enabled |
정책을 시행하려면 정책을 중지하려면 |
참 | 선택사항 |
async |
이 속성은 지원이 중단되었습니다. |
거짓 | 지원 중단됨 |
<DisplayName> 요소
name
속성 외에도 이 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름으로 라벨을 지정합니다.
<DisplayName>Policy Display Name</DisplayName>
기본값 |
해당 없음 이 요소를 생략하면 정책 |
---|---|
현재 상태 | 선택사항 |
유형 | 문자열 |
<APIKey> 요소
이 요소는 API 키가 포함된 흐름 변수를 지정합니다. 일반적으로 클라이언트는 쿼리 매개변수, HTTP 헤더, 양식 매개변수로 API 키를 보냅니다. 예를 들어 키가 x-apikey
라는 헤더로 전송되면 키는 변수 request.header.x-apikey
에서 찾을 수 있습니다.
기본값 | NA |
---|---|
Presence | 필수 |
유형 | 문자열 |
속성
다음 표에서는 <APIKey>
요소의 속성을 설명합니다.
속성 | 설명 | 기본값 | 접속 상태 |
---|---|---|---|
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>
스키마
흐름 변수
유효한 API 키에 API 키 인증 정책이 적용되면 Edge에서 일련의 흐름을 채웁니다. 변수로 사용할 수 있습니다. 이러한 변수는 흐름 후반에 실행되는 정책 또는 코드에 사용할 수 있으며 앱 이름 같은 API 키의 속성, 키 승인에 사용되는 API 제품, 또는 API 키의 커스텀 속성을 기반으로 커스텀 처리를 수행하는 데 자주 사용됩니다.
정책은 다음과 같은 여러 유형의 흐름 변수를 채웁니다.
- 일반
- 앱
- 개발자
- 회사
- 분석
흐름 변수 유형마다 프리픽스가 다릅니다. 모든 변수는 배열로 특별히 지정된 변수를 제외하고 스칼라입니다.
일반 흐름 변수
다음 표에는 API 키 검증 정책으로 채운 일반적인 흐름 변수가 나와 있습니다. 이러한 변수에는 다음 프리픽스가 붙습니다.
verifyapikey.{policy_name}
예: verifyapikey.{policy_name}.client_id
사용 가능한 변수는 다음과 같습니다.
변수 | 설명 |
---|---|
client_id |
요청한 앱에서 제공하는 고객 키(API 키 또는 앱 키라고도 함)입니다. |
client_secret |
고객 키와 연결된 고객 보안 비밀입니다. |
redirection_uris |
요청의 모든 리디렉션 URI입니다. |
developer.app.id |
요청을 실행하는 개발자 앱의 ID입니다. |
developer.app.name |
요청을 보내는 개발자 앱의 앱 이름입니다. |
developer.id |
요청 앱의 소유자로 등록된 개발자의 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} |
모든 커스텀 앱 속성입니다. 커스텀 속성의 이름을 지정합니다. |
개발자 흐름 변수
개발자에 대한 정보가 포함된 다음 흐름 변수는 정책으로 채워집니다. 이러한 변수에는 다음 프리픽스가 붙습니다.
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} |
모든 커스텀 개발자 속성입니다. 커스텀 속성의 이름을 지정합니다. |
Company |
개발자와 연결된 회사의 이름입니다(있는 경우). |
회사 흐름 변수
회사 정보가 포함된 다음 흐름 변수는 정책에서 채웁니다. 이러한 변수에는 다음 프리픽스가 붙습니다.
verifyapikey.{policy_name}.company
예:
verifyapikey.{policy_name}.company.name
사용 가능한 변수는 다음과 같습니다.
변수 | 설명 |
---|---|
name |
회사 이름입니다. |
displayName |
회사의 표시 이름입니다. |
id |
회사 ID입니다. |
apps |
회사 앱 목록이 포함된 배열입니다. |
appOwnerStatus |
앱 소유자의 상태(활성, 비활성, login_lock)입니다.
|
created_at |
회사가 생성된 날짜/시간 스탬프입니다. |
created_by |
회사를 만든 사용자의 이메일 주소입니다. |
last_modified_at |
회사가 마지막으로 수정된 날짜/시간 스탬프입니다. |
last_modified_by |
회사를 마지막으로 수정한 사용자의 이메일 주소입니다. |
{company_custom_attributes} |
모든 커스텀 회사 속성 커스텀 속성의 이름을 지정합니다. |
분석 변수
다음 변수는 유효한 API 키에 대해 API 키 검증 정책이 시행되면 애널리틱스에서 자동으로 채워집니다. 이러한 변수는 API 키 검증 정책 및 OAuth 정책으로만 채웁니다.
변수와 값을 측정기준으로 사용하여 개발자 및 앱의 사용 패턴을 파악할 수 있습니다.
- apiproduct.name
- developer.app.name
- client_id
- developer.id
오류 참조
이 섹션에서는 반환되는 오류 코드, 오류 메시지, 그리고 이 정책이 오류를 트리거할 때 Edge에서 설정하는 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.
런타임 오류
이러한 오류는 정책이 실행될 때 발생할 수 있습니다.
오류 코드 | HTTP 상태 | 원인 |
---|---|---|
keymanagement.service.CompanyStatusNotActive |
401 | 사용 중인 API 키가 있는 개발자 앱과 연결된 회사가 비활성 상태입니다. 회사의 상태가 비활성으로 설정되면 해당 회사와 연결된 개발자 또는 앱에 액세스할 수 없습니다. 조직 관리자는 회사 상태를 변경할 수 있습니다. 관리할 수 있습니다. 회사의 상태 설정을 참조하세요. |
keymanagement.service.DeveloperStatusNotActive |
401 |
사용 중인 API 키가 있는 개발자 앱을 만든 개발자가 비활성 상태입니다. 앱 개발자의 상태가 비활성으로 설정되면 해당 개발자에 의해 생성된 모든 개발자 앱은 비활성화됩니다. 적절한 권한을 가진 관리자(예: 조직 관리자)는 다음과 같은 방법으로 개발자 상태를 변경할 수 있습니다. |
keymanagement.service.invalid_client-app_not_approved |
401 | API 키와 연결된 개발자 앱이 취소되었습니다. 취소된 앱은 모든 API 제품에 액세스할 수 있으며 Apigee Edge에서 관리하는 API를 호출할 수 없습니다. 조직 관리자는 다음을 수행할 수 있습니다. 관리 API를 사용하여 개발자 앱의 상태 변경 개발자 앱 승인 또는 취소를 참조하세요. |
oauth.v2.FailedToResolveAPIKey |
401 | 정책은 정책의 <APIKey> 요소에 지정된 변수에서 API 키를 찾습니다.이 오류는 예상 변수가 존재하지 않는 경우 발생합니다(해결할 수 없음). |
oauth.v2.InvalidApiKey |
401 | Edge에서 API 키를 수신했지만 유효하지 않습니다. Edge가 데이터베이스에서 요청을 전송할 때 요청에서 전송된 와 정확하게 일치해야 합니다. API가 이전에 작동했다면 키가 다시 생성되지 않았는지 확인합니다. 키가 다시 생성된 경우 이전 키를 사용하려고 하면 이 오류가 표시됩니다. 자세한 내용은 앱 등록 및 API 키 관리를 참조하세요. |
oauth.v2.InvalidApiKeyForGivenResource |
401 | Edge에서 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>