מדיניות AccessControl

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X. מידע

מה

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

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

טעימות

ערכי המסכה בדוגמאות הבאות של IPv4 מזהים לאילו מארבע האוקטטים (8, 16, 24, 32 סיביות) כלל ההתאמה לוקח בחשבון כשהוא מאפשר או מונע גישה. ערך ברירת המחדל הוא 32. למידע נוסף, אפשר לעיין במאפיין mask בחומר העזר בנושא Element.

<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 של קבלת הארגון. לאחר מכן:

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

שינוי המאפיין feature.enableMultipleXForwardCheckForACL

אדמינים ארגוניים של Edge יכולים להשתמש ב-API של עדכון המאפיינים של הארגון כדי להגדיר את המאפיין feature.enableMultipleXForwardCheckForACL.

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

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

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"> 

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

רכיב <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

הרכיב <ignoreTrueClientIPHeader>

אם המדיניות מוגדרת כ-True, המערכת תתעלם מהכותרת True-Client-IP ומבצעת הערכה של כתובות ה-IP בכותרת X-Forwarded-For בהתאם להתנהגות של X-Forwarded-For Assessment שהגדרתם.

<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">

מאפיינים

האלמנט <IP Rules>/<MatchRule>

הפעולה שיש לבצע (אישור או דחייה של גישה) אם כתובת ה-IP תואמת לכתובות SourceAddress(כתובות המקור) שהגדרת.

<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>

מאפיינים

הרכיב <IP Rules>/<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 ולפרוס אותו מחדש.

מאפיינים

רכיב <VerifyBasedOn>

כאשר כותרת ה-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>