מדיניות AccessControl

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

מה

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

אפשר לצרף את המדיניות הזו בכל מקום בתהליך ה-Proxy ל-API, אבל סביר להניח שתרצו לבדוק את כתובות ה-IP בתחילת התהליך ( בקשה / 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 של הארגון. לאחר מכן:

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

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

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

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

<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 האחרונה, או ה-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>