VerifyAPIKey 정책

Apigee Edge 문서를 보고 있습니다.
Apigee X 문서로 이동하세요. info

대상

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

샘플

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

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

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

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

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

<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>

verifyapikey.{policy_name}

API 키 검증 정책 정보

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

앱 등록 시 개발자는 하나 이상의 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">

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

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>

<APIKey> 요소

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

속성

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

예시

이 예시에서는 키가 매개변수와 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

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

앱 흐름 변수

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

verifyapikey.{policy_name}.app

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

verifyapikey.{policy_name}.app.name

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

개발자 흐름 변수

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

verifyapikey.{policy_name}.developer

예:

verifyapikey.{policy_name}.developer.id

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

회사 흐름 변수

회사 정보가 포함된 다음 흐름 변수는 정책에서 채웁니다. 이러한 변수에는 다음 프리픽스가 붙습니다.

verifyapikey.{policy_name}.company

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

verifyapikey.{policy_name}.company.name

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

분석 변수

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

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

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

오류 참조

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

런타임 오류

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

배포 오류

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

오류 변수

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

오류 응답 예시

{  
   "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>

관련 주제