خط‌مشی AccessControl

درحال مشاهده اسناد Apigee Edge هستید.
به اسناد Apigee X بروید. اطلاعات

چه

خط‌مشی «کنترل دسترسی» به شما امکان می‌دهد دسترسی به میاناهای برنامه‌سازی کاربردی خود را براساس نشانی‌های IP خاص مجاز یا رد کنید.

اگرچه می‌توانید این خط‌مشی را در هر جایی از جریان پراکسی API پیوست کنید، اما احتمالاً می‌خواهید نشانی‌های IP را در ابتدای جریان ( درخواست / ProxyEndpoint / PreFlow)، حتی قبل‌از درستی‌سنجی یا بررسی سهمیه بررسی کنید.

نمونه‌ها

مقادیر پوشش در نمونه‌های IPv4 زیر مشخص می‌کند که قانون مطابقت هنگام مجاز کردن یا رد کردن دسترسی کدام‌یک از چهار اکتت (۸، ۱۶، ۲۴، ۳۲ بیت) را درنظر می‌گیرد. مقدار پیش‌فرض ۳۲ است. برای اطلاعات بیشتر، مشخصه 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 شبکه داخلی‌تان را مجاز کنید. توسعه‌دهندگانی که از خانه کار می‌کنند می‌توانند بااستفاده از وی‌پی‌ان به این «میاناهای برنامه‌سازی کاربردی» دسترسی داشته باشند.

پیکربندی و اجرای خط‌مشی «کنترل دسترسی» شامل موارد زیر است:

• مجموعه‌ای از قوانین مطابقت را با یکی از دو کنش (اجازه دادن یا رد کردن) منسوب به هرکدام تعریف کنید.
• برای هر قانون مطابقت، نشانی IP را مشخص کنید (عنصر SourceAddress).
  • برای تعیین اینکه کدام نشانی(های) IP در پیامی که درحال پیکربندی قوانین برای مدیریت آن هستید، خط‌مشی چگونه نشانی IP را برای ارزیابی انتخاب می‌کند را ببینید.
  • برای هر نشانی IP، یک پوشش پیکربندی کنید. دسترسی را براساس مقدار ماسک در نشانی IP مجاز یا رد می‌کنید. به درباره پوشش IP با نماد CIDR مراجعه کنید.
• ترتیب آزمایش قوانین را مشخص کنید.
• همه قوانین مطابقت در ترتیب داده‌شده اجرا می‌شوند. وقتی قانونی مطابقت پیدا می‌کند، کنش مربوطه اجرا می‌شود و قوانین مطابقت بعدی نادیده گرفته می‌شود.
  • اگر قانون یکسانی با هر دو کنش «اجازه دادن» و «رد کردن» پیکربندی شده باشد، قانونی که ابتدا در ترتیب تعریف شده است راه‌اندازی می‌شود و قانون بعدی (با کنش دیگر) نادیده گرفته می‌شود.

نحوه انتخاب نشانی IP برای ارزیابی توسط خط‌مشی

نشانی‌های IP می‌توانند از منابع مختلفی در یک درخواست بیایند. برای مثال، سرایند پیام True-Client-IP ممکن است حاوی نشانی IP باشد، و سرایند X-Forwarded-For ممکن است حاوی یک یا چند نشانی IP باشد. این بخش شرح می‌دهد که چگونه خط‌مشی AccessControl را پیکربندی کنید تا نشانی(های) IP دقیقی را که می‌خواهید ارزیابی کند.

در زیر منطقی که خط‌مشی AccessControl برای تصمیم‌گیری درباره اینکه کدام نشانی IP را ارزیابی کند آمده است:

۱. سرصفحه True-Client-IP

خط‌مشی ابتدا نشانی IP را در سرایند True-Client-IP بررسی می‌کند. اگر سرایند حاوی نشانی IP معتبری باشد، خط‌مشی آن نشانی را ارزیابی می‌کند.

۲. سرایند X-Forwarded-For

اگر سرصفحه True-Client-IP وجود نداشته باشد، یا اگر عنصر <IgnoreTrueClientIPHeader> را روی درست تنظیم کرده باشید، خط‌مشی نشانی(های) IP را در سرصفحه X-Forwarded-For ارزیابی می‌کند.

‫Edge به‌طور خودکار سرصفحه X-Forwarded-For را با نشانی IP که از آخرین دست‌دهی TCP خارجی دریافت کرده است (مثل نشانی IP کارخواه یا مسیریاب) تکمیل می‌کند. اگر چندین نشانی IP در سرایند وجود داشته باشد، آن نشانی‌ها احتمالاً زنجیره سرورهایی هستند که درخواست را پردازش کرده‌اند. بااین‌حال، فهرست نشانی‌ها می‌تواند حاوی نشانی IP جعل‌شده نیز باشد. پس خط‌مشی چگونه می‌فهمد که کدام نشانی‌ها را ارزیابی کند؟

پیکربندی سازمان و پیکربندی خط‌مشی تعیین می‌کند که خط‌مشی کدام نشانی(های) X-Forwarded-For را ارزیابی کند.

ابتدا بررسی کنید که آیا دارایی feature.enableMultipleXForwardCheckForACL در سازمان شما تنظیم شده است یا نه. برای بررسی می‌توانید از میانای برنامه‌سازی کاربردی «دریافت سازمان» استفاده کنید. سپس:

• اگر feature.enableMultipleXForwardCheckForACL را در فهرست دارایی‌های سازمانتان نمی‌بینید، یعنی آن دارایی روی false (پیش‌فرض) تنظیم شده است. اگر این دارایی روی «نادرست» تنظیم شود، خط‌مشی آخرین نشانی در سرایند (قابل‌مشاهده در ابزار ردیابی) را ارزیابی می‌کند، که نشانی IP دریافتی Edge از آخرین دست‌دهی TCP خارجی است.
• اگر feature.enableMultipleXForwardCheckForACL در سازمانتان روی درست تنظیم شده است، عنصر <ValidateBasedOn> را پیکربندی کنید تا مشخص شود خط‌مشی کدام نشانی‌های IP را ارزیابی می‌کند.

درحال تغییر دادن دارایی feature.enableMultipleXForwardCheckForACL

«سرپرستان سازمان Edge» می‌توانند از میانای برنامه‌سازی کاربردی «به‌روزرسانی ویژگی‌های سازمان» برای تنظیم ویژگی feature.enableMultipleXForwardCheckForACL استفاده کنند.

مثال API زیر دارایی را در Edge for 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>"

در Edge for Private Cloud، پس‌از تغییر مقدار دارایی feature.enableMultipleXForwardCheckForACL، باید پردازشگرهای پیام را طبق آنچه در شروع/توقف/بازراه‌اندازی اجزای جداگانه توضیح داده شده است بازراه‌اندازی کنید.

ابعاد X-Forwarded-For در Apigee analytics

«تحلیل لبه‌ای» مقدار سرایند X-Forwarded-For را در ابعاد x_forwarded_for_ip می‌نویسد. برای تعیین IP کلاینتی که درخواست را به Edge ارسال کرده است، از مقادیر موجود در ابعاد ax_true_client_ip یا ax_resolved_client_ip استفاده کنید. برای اطلاعات بیشتر، مرجع سنجه‌ها، ابعاد، و فیلترهای Analytics را ببینید.

درباره پنهان کردن نشانی IP با نماد CIDR

نشانه‌گذاری CIDR (مسیریابی بین دامنه‌ای بدون کلاس) روشی برای نشان دادن محدوده نشانی‌های IP ازطریق ماسک کردن است. این مورد هم برای IPv4 و هم برای IPv6 اعمال می‌شود. نحوه عملکرد آن به این صورت است. برای سادگی، در مثال‌هایمان از IPv4 استفاده خواهیم کرد.

نشانی‌های IP گروه‌هایی از اعداد هستند که با نقطه از هم جدا می‌شوند. ازنظر دودویی، هر گروه تعداد مشخصی بیت است (۸ برای IPv4 و ۱۶ برای IPv6). نشانی IPv4‏ 198.51.100.1 در سیستم دودویی به‌صورت زیر است:

11000110.00110011.01100100.00000001

این یعنی ۴ گروه ۸ بیتی، یا در مجموع ۳۲ بیت. با CIDR، می‌توانید با افزودن /عدد (۱ تا ۳۲) به نشانی IP، مانند این، محدوده‌ای را مشخص کنید:

198.51.100.1/24

در این مورد، ۲۴ عددی است که برای مقدار mask در این خط‌مشی استفاده می‌کنید.

این نشانه به این معنی است که «۲۴ بیت اول را دقیقاً همان‌گونه که هست نگه دارید، بیت‌های باقی‌مانده می‌توانند هر مقداری از ۰ تا ۲۵۵ داشته باشند.» برای مثال:

توجه داشته باشید که ماسک در انتهای گروه سه اتفاق می‌افتد. این کار باعث می‌شود همه چیز مرتب و منظم باشد، درواقع ماسکی مانند این ایجاد می‌کند: 198.51.100.*. در بیشتر موارد، استفاده از مضرب‌های ۸ (IPv4) و ۱۶ (IPv6) سطح پوششی موردنظرتان را به شما می‌دهد:

‫IPv4: 8،‏ 16،‏ 24،‏ 32

‫IPv6: 16،‏ 32،‏ 48،‏ 64،‏ 80،‏ 96،‏ 112،‏ 128

بااین‌حال، می‌توانید از شماره‌های دیگر برای کنترل دقیق‌تر استفاده کنید که شامل کمی محاسبات باینری می‌شود. در اینجا مثالی بااستفاده از ماسک ۳۰، مانند 198.51.100.1/30، ارائه شده است که در آن آخرین ۱ در باینری ۰۰۰۰۰۰۰۱ است:

در این مثال، با پیکربندی تنظیم‌شده روی <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 برای برچسب‌گذاری خط‌مشی در ویرایشگر پروکسی رابط کاربری مدیریت با نامی متفاوت و به زبان طبیعی، از آن استفاده کنید.

<DisplayName>Policy Display Name</DisplayName>

عنصر <IgnoreTrueClientIPHeader>

وقتی این را روی درست تنظیم می‌کنید، خط‌مشی سرصفحه True-Client-IP را نادیده می‌گیرد و نشانی‌های IP را در سرصفحه X-Forwarded-For ارزیابی می‌کند و از رفتار ارزیابی 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 از الگوهای پیام برای mask نشانی IP یا مشخصه نیز پشتیبانی می‌کند، که یعنی می‌توانید مقادیر را بااستفاده از متغیرهایی که درحال‌حاضر در جریان پراکسی API دردسترس هستند تنظیم کنید.

برای مثال، می‌توانید نشانی IP را در نقشه مقدار کلید (KVM) ذخیره کنید و از خط‌مشی 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 موردنظر برای ارزیابی مطمئن باشید. برای مثال، اگر انتخاب کنید همه نشانی‌های IP در سرایند X-Forwarded-For را ارزیابی کنید، باید بتوانید به معتبر بودن آن نشانی‌ها اعتماد کنید و/یا قوانین «رد کردن» یا «اجازه دادن» جامعی راه‌اندازی کنید تا فقط نشانی‌های IP مورداعتماد بتوانند کارگزار API شما را فراخوانی کنند.

نشانی 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>