מדיניות AccessControl

אתה צופה בתיעוד של Apigee Edge.
הצג תיעוד של Apigee X.

מה

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

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

טעימות

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

הלוגיקה של בקרת הגישה מבוססת על הלוגיקה של כתובת ה-URL שכדאי לבדוק:

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, המדיניות מעריכה את הכתובת האחרונה בכותרת (שגלויה בכלי המעקב), שהיא כתובת ה-IP Edge שהתקבלה מלחיצת היד החיצונית של TCP.
• אם המאפיין feature.enableMultipleXForwardCheckForACL בארגון שלך מוגדר כ-True, צריך להגדיר את הרכיב <VerifyBasedOn> כדי לקבוע אילו כתובות IP ייבדקו במדיניות.

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

אדמינים של הארגון ב-Edge יכולים להשתמש ב- 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>"

ב-Edge for Cloud, אחרי שינוי הערך של המאפיין feature.enableMultipleXForwardCheckForACL, צריך להפעיל מחדש את מעבדי ההודעות, כפי שמתואר ב התחלה/עצירה/הפעלה מחדש של רכיבים נפרדים.

X-Forwarded-For properties in 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 (ניתוב בין דומיינים ללא סיווג) הוא דרך לציון מגוון של כתובות 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) ולהשתמש במדיניות KeyValueMapsOperations כדי לאחזר את כתובת ה-IP ולהקצות אותה למשתנה (כמו kvm.ip.value). לאחר מכן תוכלו להשתמש במשתנה הזה עבור כתובת ה-IP:

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

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

מאפיינים

רכיב <VerifyBasedOn>

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

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

כתובת ה-IP השמאלית ביותר בכותרת שייכת ללקוח, והימין ביותר הוא השרת שהעביר את הבקשה לשירות הנוכחי. כתובת ה-IP האחרונה או האחרונה היא כתובת ה-IP שהתקבלה מלחיצת היד החיצונית של 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>