VerifyAPIKey 정책

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보

내용

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 키 검증 정책으로 채운 일반적인 흐름 변수가 나와 있습니다. 이러한 변수에는 다음 프리픽스가 붙습니다.

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

오류 참조

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error responses

{  
   "fault":{  
      "faultstring":"Invalid ApiKey",
      "detail":{  
         "errorcode":"oauth.v2.InvalidApiKey"
      }
   }
}

{  
   "fault":{  
      "detail":{  
         "errorcode":"keymanagement.service.DeveloperStatusNotActive"
      },
      "faultstring":"Developer Status is not Active"
   }
}

Example fault rule

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

관련 주제