<ph type="x-smartling-placeholder"></ph>
현재 Apigee Edge 문서를 보고 있습니다.
Apigee X 문서. 정보
대상
액세스 제어 정책을 사용하면 특정 IP 주소에 따라 API에 대한 액세스를 허용하거나 거부할 수 있습니다.
동영상: 특정 IP 주소에 따라 API에 대한 액세스를 허용하거나 거부하는 방법을 알아보려면 이 짧은 동영상을 확인하세요.
API 프록시 흐름 어디에서든 이 정책을 연결할 수 있지만, 대부분의 경우 인증 또는 할당량 확인을 수행하기도 전에 흐름 시작 위치(Request/ProxyEndpoint/PreFlow)에서 IP 주소를 확인해야 할 수 있습니다.
샘플
다음 IPv4 샘플의 마스크 값에 따라 액세스 허용 또는 거부 시 일치 규칙에 고려되는 4개 옥텟(8, 16, 24, 32비트)을 확인할 수 있습니다. 기본값은 32입니다. 자세한 내용은 요소 참조의 mask
속성을 참조하세요.
198.51.100.1 거부
<AccessControl name="ACL"> <IPRules noRuleMatchAction = "ALLOW"> <MatchRule action = "DENY"> <SourceAddress mask="32">198.51.100.1</SourceAddress> </MatchRule> </IPRules> </AccessControl>
다음 클라이언트 주소의 모든 요청 거부: 198.51.100.1
다른 클라이언트 주소의 요청은 허용합니다.
변수를 사용하여 거부
<AccessControl name="ACL"> <IPRules noRuleMatchAction = "ALLOW"> <MatchRule action = "DENY"> <SourceAddress mask="{kvm.mask.value}">{kvm.ip.value}</SourceAddress> </MatchRule> </IPRules> </AccessControl>
마스킹 및 IP 값을 저장하기 위해 키-값 맵(KVM)을 사용한다고 가정해보세요.
이렇게 하면 API 프록시를 업데이트하고 재배포하지 않고도 런타임 중에 IP 및 마스킹을 쉽게 변경할 수 있습니다. KeyValueMapOperations 정책을 사용하여 kvm.mask.value
및 kvm.ip.value
에 대한 값이 포함된 변수를 검색할 수 있습니다(KVM 정책에서 KVM의 마스크 및 IP 값이 포함된 변수에 지정한 이름이라고 가정).
검색한 값에서 마스크가 24
이고 IP 주소가 198.51.100.1
인 경우 AccessControl 정책은 198.51.100.*의 모든 요청을 거부합니다.
다른 클라이언트 주소는 모두 허용됩니다.
198.51.100.* 거부
<AccessControl name="ACL"> <IPRules noRuleMatchAction = "ALLOW"> <MatchRule action = "DENY"> <SourceAddress mask="24">198.51.100.1</SourceAddress> </MatchRule> </IPRules> </AccessControl>
다음 클라이언트 주소의 모든 요청 거부: 198.51.100.*
다른 클라이언트 주소의 요청은 허용합니다.
198.51.*.*
<AccessControl name="ACL"> <IPRules noRuleMatchAction = "ALLOW"> <MatchRule action = "DENY"> <SourceAddress mask="16">198.51.100.1</SourceAddress> </MatchRule> </IPRules> </AccessControl>
다음 클라이언트 주소의 모든 요청 거부: 198.51.*.*
다른 클라이언트 주소의 요청은 허용합니다.
198.51.100.* 거부, 192.0.2.1 허용
<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>
다음 클라이언트 주소의 모든 요청 거부: 198.51.100.*, 하지만 192.0.2.1을 허용합니다.
다른 클라이언트 주소의 요청은 허용합니다.
허용: 198.51.*.*
<AccessControl name="ACL"> <IPRules noRuleMatchAction = "DENY"> <MatchRule action = "ALLOW"> <SourceAddress mask="16">198.51.100.1</SourceAddress> </MatchRule> </IPRules> </AccessControl>
다음 주소의 모든 요청 허용: 198.51.*.*
다른 클라이언트 주소의 요청은 거부합니다.
여러 IP 허용
<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>
다음 클라이언트 주소의 요청 허용: 198.51.100.* 192.0.2.* 203.0.113.*
다른 모든 주소를 거부합니다.
여러 IP 거부
<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>
다음 클라이언트 주소의 요청 거부: 198.51.100.* 192.0.2.* 203.0.113.*
다른 모든 주소를 허용합니다.
여러 IP 허용, 여러 IP 거부
<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>
허용: 198.51.*.* 192.0.*.* 203.0.*.*
허용 목록의 하위 집합 거부: 198.51.100.* 192.0.2.* 203.0.113.*
사용 참고사항
악의적인 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 사이의 임의 값일 수 있음"을 의미합니다. 예를 들면 다음과 같습니다.
정확히 있는 그대로 유지 | 마지막 그룹에 사용 가능한 값 |
---|---|
198.51.100. | 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입니다.
정확히 있는 그대로 유지 | 가능한 값 |
---|---|
11000110.00110011.01100100.000000(처음 30비트) | 00000000, 00000001, 00000010, 00000011 |
198.51.100. | 0, 1, 2, 3 |
구성이 <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">
다음 표는 모든 정책 상위 요소의 공통 속성에 대해 설명합니다.
속성 | 설명 | 기본값 | 현재 상태 |
---|---|---|---|
name |
정책의 내부 이름입니다. 원하는 경우 |
해당 없음 | 필수 |
continueOnError |
정책이 실패할 경우 오류가 반환되도록 하려면 정책이 실패해도 흐름 실행이 계속되도록 하려면 |
거짓 | 선택사항 |
enabled |
정책을 시행하려면 정책을 중지하려면 |
참 | 선택사항 |
async |
이 속성은 지원이 중단되었습니다. |
거짓 | 지원 중단됨 |
<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">
기본값 | 해당 사항 없음 |
---|---|
접속 상태 | 선택사항 |
유형 | 해당 사항 없음 |
속성
속성 | 설명 | 유형 | 기본값 | 현재 상태 |
---|---|---|---|---|
noRuleMatchAction |
지정된 일치 규칙이 확인되지 않았을 때(일치하지 않을 때) 수행할 작업(액세스 허용 또는 거부)입니다.
유효한 값: ALLOW 또는 DENY
|
문자열 | 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>
기본값 | 해당 사항 없음 |
---|---|
접속 상태 | 선택사항 |
유형 | 해당 사항 없음 |
속성
속성 | 설명 | 유형 | 기본값 | 현재 상태 |
---|---|---|---|---|
작업 |
지정된 일치 규칙이 확인되지 않았을 때(일치하지 않을 때) 수행할 작업(액세스 허용 또는 거부)입니다. 유효한 값: ALLOW 또는 DENY |
문자열 | ALLOW | 필수 |
<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 프록시를 수정하거나 다시 배포할 필요 없이 런타임에 값을 유연하게 변경할 수 있습니다.
기본값 | 해당 사항 없음 |
---|---|
접속 상태 | 선택사항 |
유형 | 문자열(단일 IP 주소만) |
속성
속성 | 설명 | 유형 | 기본값 | 현재 상태 |
---|---|---|---|---|
마스크 |
다음 CIDR 표기법과 동일: 198.51.100.1/24 유효한 값: IPv4: 1-32 IPv6: 1-128 영 값(0)은 IP 0.0.0.0의 경우에만 유효하므로 실질적이지 않습니다. 변수를 사용하여 마스크 설정
|
정수 | 해당 없음 | 필수 |
<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>
기본값 | X_FORWARDED_FOR_ALL_IP |
---|---|
접속 상태 | 선택사항 |
유효한 값 |
|
스키마
각 정책 유형은 XML 스키마(.xsd)로 정의됩니다. 참고로 정책 스키마는 GitHub에서 사용 가능합니다.
오류 참조
이 섹션에서는 반환되는 오류 코드, 오류 메시지, 그리고 이 정책이 오류를 트리거할 때 Edge에서 설정하는 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.
런타임 오류
이러한 오류는 정책이 실행될 때 발생할 수 있습니다.
오류 코드 | HTTP 상태 | 원인 | 해결 |
---|---|---|---|
accesscontrol.IPDeniedAccess |
403 | 클라이언트 IP 주소 또는 API 요청에서 전달된 IP 주소가 액세스 제어 정책의 <MatchRule> 요소 내 <SourceAddress> 요소에 지정된 IP 주소와 일치하며 <MatchRule> 요소의 action 속성이 DENY 로 설정됩니다. |
build |
오류 변수
이러한 변수는 런타임 오류가 발생하면 설정됩니다. 자세한 내용은 정책 오류 관련 변수를 참조하세요.
변수 | 위치 | 예 |
---|---|---|
fault.name="fault_name" |
fault_name은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다. | fault.name Matches "IPDeniedAccess" |
acl.policy_name.failed |
policy_name은 오류를 발생시킨 정책의 사용자 지정 이름입니다. | acl.AC-AllowAccess.failed = true |
오류 응답 예시
{ "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>