AccessControl 정책

<ph type="x-smartling-placeholder"></ph> 현재 Apigee Edge 문서를 보고 있습니다.
Apigee X 문서. 정보

대상

액세스 제어 정책을 사용하면 특정 IP 주소에 따라 API에 대한 액세스를 허용하거나 거부할 수 있습니다.

API 프록시 흐름 어디에서든 이 정책을 연결할 수 있지만, 대부분의 경우 인증 또는 할당량 확인을 수행하기도 전에 흐름 시작 위치(Request/ProxyEndpoint/PreFlow)에서 IP 주소를 확인해야 할 수 있습니다.

샘플

다음 IPv4 샘플의 마스크 값에 따라 액세스 허용 또는 거부 시 일치 규칙에 고려되는 4개 옥텟(8, 16, 24, 32비트)을 확인할 수 있습니다. 기본값은 32입니다. 자세한 내용은 요소 참조의 mask 속성을 참조하세요.

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="32">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="{kvm.mask.value}">{kvm.ip.value}</SourceAddress>
    </MatchRule>
    </IPRules>
</AccessControl>

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
    </MatchRule>
    </IPRules>
</AccessControl>

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
       <SourceAddress mask="16">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "ALLOW">
      <SourceAddress mask="32">192.0.2.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "DENY">
    <MatchRule action = "ALLOW">
      <SourceAddress mask="16">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "DENY">
    <MatchRule action = "ALLOW">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
      <SourceAddress mask="24">192.0.2.1</SourceAddress>
      <SourceAddress mask="24">203.0.113.1</SourceAddress>
     </MatchRule>
  </IPRules>
</AccessControl>

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
      <SourceAddress mask="24">192.0.2.1</SourceAddress>
      <SourceAddress mask="24">203.0.113.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "DENY">
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
      <SourceAddress mask="24">192.0.2.1</SourceAddress>
      <SourceAddress mask="24">203.0.113.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "ALLOW">
      <SourceAddress mask="16">198.51.100.1</SourceAddress>
      <SourceAddress mask="16">192.0.2.1</SourceAddress>
      <SourceAddress mask="16">203.0.113.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

사용 참고사항

악의적인 IP로부터 API를 보호하는 것 외에도 액세스 제어 정책을 사용하면 적법한 IP 액세스를 제어할 수 있습니다. 예를 들어 기업 내에서 관리되는 컴퓨터만 테스트 환경에 노출된 API에 액세스하길 원하는 경우 내부 네트워크의 IP 주소 범위를 허용할 수 있습니다. 재택근무 개발자는 VPN을 사용해서 이러한 API에 액세스할 수 있습니다.

액세스 제어 정책의 구성 및 실행에는 다음이 포함됩니다.

• 서로 연관된 두 작업(ALLOW 또는 DENY) 중 하나로 일치 규칙 집합을 정의합니다.
• 각 일치 규칙에 대해 IP 주소(SourceAddress 요소)를 지정합니다.
  • 메시지에서 처리할 규칙을 구성 중인 IP 주소를 확인하려면 정책에서 평가할 IP 주소를 선택하는 방법을 참조하세요.
  • 각 IP 주소에 대해 마스크를 구성합니다. IP 주소의 마스크 값을 기준으로 액세스를 허용하거나 거부합니다. CIDR 표기법을 사용한 IP 마스킹 정보를 참조하세요.
• 규칙 테스트 순서를 지정합니다.
• 모든 일치 규칙이 지정된 순서로 실행됩니다. 규칙이 일치하면 해당 작업을 실행하고 다음 일치 규칙을 건너뜁니다.
  • ALLOW 및 DENY 작업이 동일 규칙에 구성된 경우, 해당 순서에서 처음 정의된 규칙이 트리거되고 이후 규칙(다른 작업 포함)은 건너뜁니다.

정책에서 평가할 IP 주소를 선택하는 방법

IP 주소는 한 요청에서 여러 소스로부터 올 수 있습니다. 예를 들어 True-Client-IP 메시지 헤더는 하나의 IP 주소를 포함할 수 있으며, X-Forwarded-For 헤더는 하나 이상의 IP 주소를 포함할 수 있습니다. 이 섹션에서는 평가하려는 IP 주소를 정확하게 평가하도록 AccessControl 정책을 구성하는 방법을 설명합니다.

다음은 AccessControl 정책이 평가할 IP 주소를 결정하기 위해 사용하는 논리입니다.

1. True-Client-IP 헤더

이 정책은 먼저 True-Client-IP 헤더에서 IP 주소를 확인합니다. 헤더에 유효한 IP 주소가 포함된 경우 정책이 이 주소를 평가합니다.

2. X-Forwarded-For 헤더

True-Client-IP 헤더가 없거나 <IgnoreTrueClientIPHeader> 요소를 true로 설정한 경우 정책이 X-Forwarded-For 헤더에 있는 IP 주소를 평가합니다.

Edge에서 X-Forwarded-For 헤더를 자동으로 채웁니다. 마지막 외부 TCP 핸드셰이크에서 수신한 IP 주소 (예: 클라이언트 IP 또는 있습니다. 헤더에 IP 주소가 여러 개 있는 경우 이러한 주소는 요청을 처리한 서버의 체인일 수 있습니다. 하지만 주소 목록에는 스푸핑된 IP 주소도 포함될 수 있습니다. 그렇다면 정책은 평가할 주소를 어떻게 확인할까요?

정책이 평가할 X-Forwarded-For 주소는 조직 구성 및 정책 구성에 따라 결정됩니다.

먼저 feature.enableMultipleXForwardCheckForACL 속성이 조직에 설정되었는지 확인합니다. 조직 가져오기 API를 사용하여 확인할 수 있습니다. 그런 다음 아래를 실행합니다.

• 조직의 속성 목록에 feature.enableMultipleXForwardCheckForACL이 없으면 속성이 false(기본값)로 설정된 것입니다. 이 속성을 false로 설정하면 정책에서 헤더의 마지막 주소( IP 주소인 Trace 도구 마지막 외부 TCP 핸드셰이크에서 에지가 수신되었습니다.
• 조직의 feature.enableMultipleXForwardCheckForACL이 true로 설정된 경우 정책이 평가할 IP 주소를 결정하도록 <ValidateBasedOn> 요소를 구성합니다.

feature.enableMultipleXForwardCheckForACL 속성 변경

에지 조직 관리자는 <ph type="x-smartling-placeholder"></ph> 조직 속성 업데이트 API를 사용하여 feature.enableMultipleXForwardCheckForACL 속성

다음 API 예시에서는 Edge에서 Private Cloud의 속성을 설정합니다. 조직에 설정된 다른 속성이 있는 경우 이러한 속성도 포함해야 합니다. 그렇지 않으면 삭제됩니다.

curl -u email:password -X POST -H "Content-type:application/xml" http://host:8080/v1/o/myorg -d \
"<Organization type="trial" name="MyOrganization">
    <DisplayName>MyOrganization</DisplayName>
    <Properties>
        <Property name="feature.enableMultipleXForwardCheckForACL">true</Property>
        <!-- Include other existing properties as well. -->
    </Properties>
</Organization>"

Private Cloud용 Edge에서 속성 feature.enableMultipleXForwardCheckForACL개, 다음에 설명된 대로 메시지 프로세서를 다시 시작해야 합니다. <ph type="x-smartling-placeholder"></ph> 개별 구성요소를 시작/중지/다시 시작합니다.

Apigee 애널리틱스의 X-Forwarded-For 측정기준

Edge Analytics는 X-Forwarded-For 헤더의 값을 x_forwarded_for_ip 측정기준. www.microsoft.com의 클라이언트 IP를 Edge에 요청을 보내려면 ax_true_client_ip 또는 ax_resolved_client_ip 측정기준. 자세한 내용은 애널리틱스 측정항목, 측정기준, 필터 참조를 확인하세요.

CIDR 표기법을 사용한 IP 마스킹 정보

CIDR 표기법(클래스 없는 도메인 간 라우팅)은 마스킹을 통해 IP 주소 범위를 표현하기 위한 방법입니다. IPv4와 IPv6 모두에 적용됩니다. 작동 방식은 다음과 같습니다. 이 예시에서는 간단한 설명을 위해 IPv4가 사용됩니다.

IP 주소는 마침표로 구분된 숫자 그룹입니다. 바이너리로 표시될 때 각 그룹은 특정 비트 수로 표시됩니다(IPv4는 8비트, IPv6는 16비트). IPv4 주소 198.51.100.1은 바이너리로 표시할 때 다음과 같습니다.

11000110.00110011.01100100.00000001

8비트 4개 그룹 또는 총 32개 비트가 있습니다. CIDR을 사용하면 다음과 같이 IP 주소에 /숫자(1-32)를 추가하여 범위를 표시할 수 있습니다.

198.51.100.1/24

여기에서 24는 이 정책에서 mask 속성에 사용할 숫자입니다.

이 표기법은 '처음 24개 비트를 정확히 있는 그대로 유지하고, 나머지 비트는 0~255 사이의 임의 값일 수 있음"을 의미합니다. 예를 들면 다음과 같습니다.

마스크는 3번 그룹 끝에 표시됩니다. 이렇게 하면 198.51.100.*와 같이 마스크 생성을 쉽고 간단하게 할 수 있습니다. 대부분의 경우 8(IPv4) 및 16(IPv6)의 배수를 사용하면 원하는 마스킹 수준을 얻을 수 있습니다.

IPv4: 8, 16, 24, 32

IPv6: 16, 32, 48, 64, 80, 96, 112, 128

하지만 약간의 바이너리 계산이 필요하더라도 필요에 따라 세부적인 제어를 위해 다른 숫자를 사용할 수 있습니다. 다음은 198.51.100.1/30과 같이 마스크로 30을 사용한 예시입니다. 여기서 마지막 1은 바이너리로 00000001입니다.

구성이 <SourceAddress mask="30">198.51.100.1</SourceAddress>로 설정된 이 예시에서는 다음 IP가 허용됩니다(규칙에 따라 거부됨).

• 198.51.100.0
• 198.51.100.1
• 198.51.100.2
• 198.51.100.3

요소 참조

요소 참조는 액세스 제어 정책의 요소 및 속성을 설명합니다.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">
    <DisplayName>Access Control 1</DisplayName>
    <IPRules noRuleMatchAction = "ALLOW">
        <MatchRule action = "ALLOW">
            <SourceAddress mask="32">198.51.100.1</SourceAddress>
        </MatchRule>
        <MatchRule action = "DENY">
            <SourceAddress mask="24">198.51.100.1</SourceAddress>
        </MatchRule>
    </IPRules>
    <ValidateBasedOn>X_FORWARDED_FOR_ALL_IP</ValidateBasedOn>
</AccessControl>

<AccessControl> 속성

<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1"> 

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

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>

<IgnoreTrueClientIPHeader> 요소

이 요소를 true로 설정하면 정책이 True-Client-IP 헤더를 무시하고 X-Forwarded-For 헤더에서 IP 주소를 평가하고, 사용자가 구성한 X-Forwarded-For 평가 동작을 따릅니다.

<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">
    <DisplayName>Access Control-1</DisplayName>
    <IgnoreTrueClientIPHeader>true</IgnoreTrueClientIPHeader>
    ...
</AccessControl>

<IPRules> 요소

IP 주소를 허용 또는 거부하는 규칙이 포함된 상위 요소입니다. noRuleMatchAction 속성을 사용하여 일치 규칙에 포함되지 않는 IP 주소의 처리 방법을 정의할 수 있습니다.

<IPRules noRuleMatchAction = "ALLOW">

속성

<IPRules>/<MatchRule> 요소

IP 주소가 사용자가 정의한 SourceAddress(es)와 일치할 때 수행할 작업(액세스 허용 또는 거부)입니다.

<IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "ALLOW">
        <SourceAddress mask="32">198.51.100.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "DENY">
        <SourceAddress mask="24">198.51.100.1</SourceAddress>
    </MatchRule>
</IPRules>

속성

<IPRules>/<MatchRule>/<SourceAddress> 요소

클라이언트의 IP 주소 범위입니다.

유효한 값: 유효한 IP 주소(점으로 구분된 숫자 표기법). 와일드 카드 동작의 경우 mask 속성을 사용합니다.

<IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "ALLOW">
        <SourceAddress mask="{variable}">198.51.100.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "DENY">
        <SourceAddress mask="24">{variable}</SourceAddress>
    </MatchRule>
</IPRules>

이전 예시에 표시된 것처럼 SourceAddress 요소는 또한 API 프록시 흐름에서 현재 사용 가능한 변수를 사용하여 값을 설정할 수 있도록 mask 속성 또는 IP 주소에 대한 메시지 템플릿을 지원합니다.

예를 들어 키 값 맵(KVM)에 IP 주소를 저장하고 KeyValueMapOperations 정책을 사용하여 IP 주소를 검색하고 이를 변수(예: kvm.ip.value)에 할당할 수 있습니다. 그런 후 이 변수를 IP 주소에 사용할 수 있습니다.

<SourceAddress mask="24">{kvm.ip.value}</SourceAddress>

변수로 마스크 또는 IP 주소를 설정하면 API 프록시를 수정하거나 다시 배포할 필요 없이 런타임에 값을 유연하게 변경할 수 있습니다.

속성

<ValidateBasedOn> 요소

X-Forwarded-For HTTP 헤더에 여러 IP 주소가 포함된 경우 이 ValidateBasedOn 요소를 사용하여 평가할 IP 주소를 제어합니다.

평가할 IP 주소가 유효한지 확실하지 않은 경우에만 이 방법에 따라 IP 주소를 평가합니다. 예를 들어 X-Forwarded-For 헤더의 모든 IP 주소를 평가하도록 선택할 경우, 해당 주소의 유효성을 신뢰할 수 있어야 하며, 신뢰할 수 있는 IP만 API 프록시를 호출하도록 포괄적인 DENY 또는 ALLOW 규칙을 설정할 수 있어야 합니다.

헤더에서 가장 왼쪽에 있는 IP 주소는 클라이언트에 속하며, 가장 오른쪽에 있는 IP 주소는 요청을 현재 서비스로 전달한 서버입니다. 맨 오른쪽 또는 마지막 IP 주소, Edge가 마지막 외부 TCP 핸드셰이크에서 수신한 주소입니다.

이 요소에 입력한 값에 따라 헤더의 모든 IP 주소를 확인(기본값)하거나 첫 번째 IP 주소 또는 마지막 IP 주소만 확인할지를 결정할 수 있습니다.

<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">
    <DisplayName>Access Control 1</DisplayName>
    <IPRules noRuleMatchAction = "ALLOW">
        <MatchRule action = "DENY">
            <SourceAddress mask="32">198.51.100.1</SourceAddress>
        </MatchRule>
    </IPRules>
    <ValidateBasedOn>X_FORWARDED_FOR_ALL_IP</ValidateBasedOn>
</AccessControl>

스키마

각 정책 유형은 XML 스키마(.xsd)로 정의됩니다. 참고로 정책 스키마는 GitHub에서 사용 가능합니다.

오류 참조

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

런타임 오류

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

오류 변수

이러한 변수는 런타임 오류가 발생하면 설정됩니다. 자세한 내용은 정책 오류 관련 변수를 참조하세요.

오류 응답 예시

{
   "fault":{
     "faultstring":"Access Denied for client ip : 52.211.243.3"
      "detail":{
         "errorcode":"accesscontrol.IPDeniedAccess"
      }
   }
}

오류 규칙 예시

<FaultRule name="IPDeniedAccess">
    <Step>
        <Name>AM-IPDeniedAccess</Name>
        <Condition>(fault.name Matches "IPDeniedAccess") </Condition>
    </Step>
    <Condition>(acl.failed = true) </Condition>
</FaultRule>