מדיניות AccessControl

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

מה

מדיניות בקרת הגישה מאפשרת לכם לאשר או לדחות גישה לממשקי ה-API שלכם לפי כתובות IP ספציפיות.

אפשר לצרף את המדיניות הזו לכל מקום בתהליך של proxy ל-API, אבל כדאי לבדוק את כתובות ה-IP בתחילת התהליך ( Request / ProxyEndpoint / PreFlow), עוד לפני אימות או בדיקת מכסת השימוש.

דוגמאות

ערכי המסכה בדוגמאות הבאות של IPv4 מזהים את אחד מארבעת האוקטטים (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>

הערות שימוש

בנוסף להגנה על ממשקי ה-API מפני כתובות IP זדוניות, מדיניות בקרת הגישה מאפשרת לכם גם לשלוט בגישה של כתובות IP לגיטימיות. לדוגמה, אם רוצים שמחשבים שנמצאים בשליטת הארגון בלבד יוכלו לגשת לממשקי ה-API שמוצגים בסביבת הבדיקה, אפשר לאפשר את טווח כתובות ה-IP של הרשת הפנימית. מפתחים שעובדים מהבית יכולים לגשת לממשקי ה-API האלה באמצעות VPN.

ההגדרה וההפעלה של מדיניות בקרת גישה כוללות את הפעולות הבאות:

• מגדירים קבוצה של כללי התאמה עם אחת משתי פעולות (ALLOW או DENY) שמשויכות לכל אחד מהם.
• לכל כלל התאמה, מציינים את כתובת ה-IP (רכיב SourceAddress).
  • כדי לקבוע אילו כתובות IP בהודעה אתם מגדירים כללים לטיפול בהן, כדאי לעיין במאמר איך המדיניות בוחרת איזו כתובת IP להעריך.
  • מגדירים מסכה לכל כתובת IP. אתם מאשרים או דוחים גישה על סמך ערך מסכה בכתובת ה-IP. מידע נוסף זמין במאמר מידע על אנונימיזציה של כתובות IP באמצעות סימון CIDR.
• מציינים את הסדר שבו הכללים נבדקים.
• כל כללי ההתאמה מופעלים לפי הסדר שמופיע. כשכלל מתאים, הפעולה המתאימה מבוצעת וכללים נוספים שמתאימים להודעה נדלגים.
  • אם אותו כלל מוגדר עם הפעולות ALLOW ו-DENY, הכלל שמוגדר ראשון בסדר מופעל והכלל הבא (עם הפעולה האחרת) מדלג.

איך המדיניות בוחרת איזו כתובת IP להעריך

כתובות IP יכולות להגיע ממקורות שונים בבקשה. לדוגמה, הכותרת של ההודעה True-Client-IP עשויה להכיל כתובת IP, והכותרת X-Forwarded-For עשויה להכיל כתובת IP אחת או יותר. בקטע הזה מוסבר איך להגדיר את מדיניות AccessControl כדי להעריך את כתובות ה-IP המדויקות שרוצים שהיא תעריך.

הלוגיקה שבה מדיניות AccessControl משתמשת כדי להחליט איזו כתובת IP להעריך:

1. כותרת True-Client-IP

המדיניות בודקת קודם אם יש כתובת IP בכותרת True-Client-IP. אם הכותרת מכילה כתובת IP תקינה, המדיניות מעריכה את הכתובת הזו.

2. כותרת X-Forwarded-For

אם אין כותרת True-Client-IP, או אם הגדרתם את הרכיב <IgnoreTrueClientIPHeader> כ-true, המדיניות בודקת את כתובות ה-IP בכותרת X-Forwarded-For.

‫Edge מאכלס אוטומטית את הכותרת X-Forwarded-For בכתובת ה-IP שהוא קיבל מהלחיצת היד האחרונה של TCP חיצונית (כמו כתובת ה-IP של הלקוח או הנתב). אם יש כמה כתובות IP בכותרת, סביר להניח שהכתובות האלה הן שרשרת השרתים שעיבדו את הבקשה. עם זאת, רשימת הכתובות יכולה להכיל גם כתובת IP מזויפת. אז איך המדיניות יודעת אילו כתובות להעריך?

ההגדרות של הארגון וההגדרות של המדיניות קובעות את הכתובות X-Forwarded-For שהמדיניות חלה עליהן.

קודם כול, בודקים אם המאפיין feature.enableMultipleXForwardCheckForACL מוגדר בארגון. אפשר להשתמש ב-API‏ Get organization כדי לבדוק. לאחר מכן:

• אם לא רואים את feature.enableMultipleXForwardCheckForACL ברשימת הנכסים של הארגון, המשמעות היא שהנכס מוגדר כ-false (ברירת המחדל). אם המאפיין הזה מוגדר כ-False, המדיניות מעריכה את כתובת ה-last בכותרת (מופיעה בכלי המעקב), שהיא כתובת ה-IP ש-Edge קיבל מהלחיצת היד האחרונה של TCP חיצוני.
• אם הערך של feature.enableMultipleXForwardCheckForACL בארגון שלכם מוגדר כ-true, צריך להגדיר את הרכיב <ValidateBasedOn> כדי לקבוע את כתובות ה-IP שהמדיניות תבדוק.

שינוי הנכס feature.enableMultipleXForwardCheckForACL

אדמינים בארגון Edge יכולים להשתמש ב-API‏ Update organization properties כדי להגדיר את המאפיין 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

‫Edge Analytics כותב את הערך של הכותרת X-Forwarded-For למאפיין x_forwarded_for_ip. כדי לקבוע את כתובת ה-IP של הלקוח ששלח את הבקשה ל-Edge, משתמשים בערכים במימדים ax_true_client_ip או ax_resolved_client_ip. מידע נוסף זמין במאמר בנושא מדדים, מאפיינים ומסננים ב-Analytics.

מידע על אנונימיזציה של כתובות IP באמצעות סימון CIDR

סימון CIDR‏ (Classless Inter-Domain Routing) הוא דרך לציין טווח של כתובות IP באמצעות מיסוך. ההגדרה הזו רלוונטית גם ל-IPv4 וגם ל-IPv6. ככה זה עובד: בדוגמאות שלנו נשתמש ב-IPv4 כדי לפשט את הדברים.

כתובות IP הן קבוצות של מספרים שמופרדים בנקודות. במונחים בינאריים, כל קבוצה היא מספר מסוים של ביטים (8 ל-IPv4 ו-16 ל-IPv6). כתובת ה-IPv4‏ 198.51.100.1 נראית כך בפורמט בינארי:

11000110.00110011.01100100.00000001

כלומר 4 קבוצות של 8 ביט, או 32 ביט בסך הכול. ב-CIDR, אפשר לציין טווח על ידי הוספת ‎/number (1-32) לכתובת ה-IP, כך:

198.51.100.1/24

במקרה הזה, המספר 24 הוא הערך שבו תשתמשו במאפיין mask במדיניות הזו.

הסימון הזה אומר: 'שומרים את 24 הביטים הראשונים בדיוק כמו שהם, והביטים הנותרים יכולים להיות כל ערך מ-0 עד 255'. לדוגמה:

שימו לב שהמסכה מופיעה בסוף קבוצה שלוש. כך הכל מסודר וברור, ובעצם נוצרת מסכה כזו: 198.51.100.*. ברוב המקרים, שימוש בכפולות של 8 (IPv4) ו-16 (IPv6) ייתן לכם את רמת המיסוך הרצויה:

IPv4: ‏ 8, ‏ 16, ‏ 24, ‏ 32

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

עם זאת, אפשר להשתמש במספרים אחרים כדי לקבל שליטה מדויקת יותר, שכוללת חישוב בינארי. דוגמה לשימוש במסכה של 30, כמו ב-198.51.100.1/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"> 

בטבלה הבאה מתוארים מאפיינים שמשותפים לכל רכיבי ההורה של המדיניות:

&lt;DisplayName&gt; רכיב

צריך להשתמש בנוסף למאפיין name כדי להוסיף תווית למדיניות עורך proxy של ממשק משתמש לניהול עם שם אחר בשפה טבעית.

<DisplayName>Policy Display Name</DisplayName>

אלמנט <IgnoreTrueClientIPHeader>

אם מגדירים את המדיניות הזו כ-True, המדיניות מתעלמת מהכותרת 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 תואמת לכתובות המקור שהגדרתם.

<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, מה שאומר שאפשר להגדיר את הערכים באמצעות משתנים שזמינים כרגע בתהליך של proxy ל-API.

לדוגמה, אפשר לאחסן כתובת IP במפת ערכי מפתח (KVM) ולהשתמש במדיניות KeyValueMapOperations כדי לאחזר את כתובת ה-IP ולהקצות אותה למשתנה (למשל, kvm.ip.value). לאחר מכן אפשר להשתמש במשתנה הזה לכתובת ה-IP:

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

הגדרת מסכה ו/או כתובת IP באמצעות משתנה מאפשרת לכם לשנות ערכים בזמן ריצה בלי שתצטרכו לשנות ולפרוס מחדש את proxy ל-API שלכם.

מאפיינים

אלמנט <ValidateBasedOn>

כשכותרת ה-HTTP‏ X-Forwarded-For מכילה כמה כתובות IP, משתמשים ברכיב ValidateBasedOn הזה כדי לקבוע אילו כתובות IP ייבדקו.

כדאי להשתמש בגישה הזו להערכת כתובות IP רק אם אתם בטוחים בתוקף של כתובות ה-IP שאתם רוצים להעריך. לדוגמה, אם בוחרים להעריך את כל כתובות ה-IP בכותרת X-Forwarded-For, צריך להיות בטוחים בתוקף של הכתובות האלה, או להגדיר כללי DENY או ALLOW מקיפים כדי לאפשר רק לכתובות IP מהימנות לקרוא ל-proxy ל-API.

כתובת ה-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>