מדיניות BasicAuthentication

מדיניות ניתנת להרחבה

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

המדיניות BasicAuthentication מאפשרת להשתמש באימות בסיסי קל משקל לאבטחת השלב האחרון בתהליך. המדיניות מקבלת שם משתמש וסיסמה, מקודדת אותם בפורמט Base64 וכותבת את הערך שמתקבל למשתנה. הערך שמתקבל הוא בפורמט Basic Base64EncodedString. בדרך כלל כותבים את הערך הזה בכותרת HTTP, כמו הכותרת Authorization.

למדיניות יש שני מצבי פעולה:

• קידוד: קידוד Base64 מקודד שם משתמש וסיסמה שמאוחסנים במשתנים
• ‫Decode: פענוח שם המשתמש והסיסמה ממחרוזת בקידוד Base64

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

המדיניות הזו לא אוכפת אימות בסיסי בבקשה ל-proxy ל-API. במקום זאת, אפשר להשתמש בו כדי לקודד או לפענח פרטי כניסה בפורמט Base64, בדרך כלל כשמתחברים לשרת backend או כשמשתמשים במדיניות של קריאה לשירות, כמו מדיניות של קריאה לשירות, שדורשת אימות בסיסי.

אזהרה: אימות בסיסי לא מספק סודיות. תמיד שולחים את פרטי הכניסה דרך חיבור עם TLS (HTTPS) לשירות העורפי.

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

דוגמאות

קידוד בשיחות יוצאות

<BasicAuthentication name="ApplyBasicAuthHeader">
   <DisplayName>ApplyBasicAuthHeader</DisplayName>
   <Operation>Encode</Operation>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <User ref="BasicAuth.credentials.username" />
   <Password ref="BasicAuth.credentials.password" />
   <AssignTo createNew="false">request.header.Authorization</AssignTo>
</BasicAuthentication>

בהגדרת המדיניות לדוגמה שלמעלה, שם המשתמש והסיסמה שצריך לקודד נגזרים מהמשתנים שצוינו במאפיינים ref ברכיבים <User> ו-<Password>. צריך להגדיר את המשתנים לפני שהמדיניות הזו מופעלת. בדרך כלל, המשתנים מאוכלסים בערכים שנקראים ממפת מפתח/ערך. ראו מדיניות בנושא פעולות של Key Value Map.

ההגדרה הזו גורמת להוספת כותרת HTTP בשם Authorization, כפי שצוין ברכיב <AssignTo>, להודעת הבקשה היוצאת שנשלחת לשרת העורפי:

Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk

הערכים של <User> ו-<Password> משורשרים עם נקודתיים לפני הקידוד בפורמט Base64.

נניח שיש לכם מיפוי של מפתח/ערך עם הרשומה הבאה:

{
  "encrypted" : true,
  "entry" : [ {
    "name" : "username",
    "value" : "MyUsername
  }, {
    "name" : "password",
    "value" : "MyPassword
  } ],
  "name" : "BasicAuthCredentials"
}
      

כדי לחלץ את הערכים של הרכיבים <User> ו-<Password> מחנות המפתחות/ערכים ולאכלס אותם במשתנים credentials.username ו-credentials.password, צריך לצרף את כללי המדיניות הבאים של KeyValueMapOperations לפני כלל המדיניות BasicAuthentication:

<KeyValueMapOperations name="getCredentials" mapIdentifier="BasicAuthCredentials">
  <Scope>apiproxy</Scope>
  <Get assignTo="credentials.username" index='1'>
    <Key>
      <Parameter>username</Parameter>
    </Key>
  </Get>
  <Get assignTo="credentials.password" index='1'>
    <Key>
      <Parameter>password</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>
      

פענוח של שיחות נכנסות

<BasicAuthentication name="DecodeBaseAuthHeaders">
   <DisplayName>Decode Basic Authentication Header</DisplayName>
   <Operation>Decode</Operation>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <User ref="request.header.username" />
   <Password ref="request.header.password" />
   <Source>request.header.Authorization</Source>
</BasicAuthentication>

בדוגמה הזו למדיניות, המדיניות מפענחת את שם המשתמש והסיסמה מתוך Authorization כותרת ה-HTTP, כפי שמצוין ברכיב <Source>. המחרוזת בקידוד Base64 צריכה להיות בפורמט Basic Base64EncodedString.

המדיניות כותבת את שם המשתמש המפוענח למשתנה request.header.username ואת הסיסמה המפוענחת למשתנה request.header.password.

הפניה לרכיב

ההפניה לרכיב מתארת את הרכיבים והמאפיינים של מדיניות BasicAuthentication.

<BasicAuthentication async="false" continueOnError="false" enabled="true" name="Basic-Authentication-1">
   <DisplayName>Basic Authentication 1</DisplayName>
   <Operation>Encode</Operation>
   <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
   <User ref="request.queryparam.username" />
   <Password ref="request.queryparam.password" />
   <AssignTo createNew="false">request.header.Authorization</AssignTo>
   <Source>request.header.Authorization</Source>
</BasicAuthentication>

מאפיינים של <BasicAuthentication>

<BasicAuthentication async="false" continueOnError="false" enabled="true" name="Basic-Authentication-1">

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

מאפיין	תיאור	ברירת מחדל	נוכחות
name	השם הפנימי של המדיניות. הערך של מאפיין name יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. הערך הזה לא יכול לחרוג מ-255 תווים. אפשר להשתמש ברכיב <DisplayName> כדי לתת למדיניות תווית בשם אחר בשפה טבעית בכלי לעריכת פרוקסי בממשק הניהול.	לא רלוונטי	חובה
continueOnError	מגדירים את הערך false כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המדיניות. הגדרה ל-true מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מידע נוסף: הפעלת כללי תקלות מתבצעת רק במצב שגיאה (מידע על continueOnError) טיפול בתקלות בתהליך הנוכחי	FALSE	אופציונלי
enabled	מגדירים את המדיניות למצב true כדי לאכוף אותה. מגדירים את הערך false כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.	TRUE	אופציונלי
async	המאפיין הזה הוצא משימוש.	FALSE	הוצא משימוש

אלמנט <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

ברירת מחדל	לא רלוונטי אם לא מציינים את הרכיב הזה, המערכת משתמשת בערך של המאפיין name של המדיניות.
נוכחות	אופציונלי
סוג	String

אלמנט <Operation>

המדיניות קובעת אם פרטי הכניסה מקודדים או מפוענחים ב-Base64.

<Operation>Encode</Operation>

ברירת מחדל:	לא רלוונטי
נוכחות:	חובה
סוג:	מחרוזת. הערכים התקינים כוללים: קידוד פענוח קוד

אלמנט <IgnoreUnresolvedVariables>

אם המדיניות מוגדרת לערך true, לא תופיע שגיאה אם לא ניתן לפתור משתנה. כשמשתמשים בהגדרה הזו בהקשר של מדיניות BasicAuthentication, בדרך כלל מגדירים אותה ל-false כי בדרך כלל כדאי להקפיץ הודעת שגיאה (throw) אם אי אפשר למצוא שם משתמש או סיסמה במשתנים שצוינו.

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

ברירת מחדל:	TRUE
נוכחות:	אופציונלי
סוג:	בוליאני

אלמנט <User>

• לקידוד, משתמשים ברכיב <User> כדי לציין את המשתנה שמכיל את שם המשתמש. הערכים של שם המשתמש והסיסמה מחוברים באמצעות נקודתיים לפני קידוד Base64.
• לפענוח, מציינים את המשתנה שבו ייכתב שם המשתמש המפוענח.

<User ref="request.queryparam.username" />

ברירת מחדל:	לא רלוונטי
נוכחות:	חובה
סוג:	לא רלוונטי

מאפיינים

מאפיין	תיאור	ברירת מחדל	נוכחות
ref	המשתנה שממנו המדיניות קוראת באופן דינמי את שם המשתמש (encode) או כותבת את שם המשתמש (decode).	לא רלוונטי	חובה

אלמנט <Password>

• לקידוד, משתמשים באלמנט <Password> כדי לציין את המשתנה שמכיל את הסיסמה.
• לפענוח, מציינים את המשתנה שבו הסיסמה המפוענחת נכתבת.

<Password ref="request.queryparam.password" />

ברירת מחדל:	לא רלוונטי
נוכחות:	חובה
סוג:	לא רלוונטי

מאפיינים

מאפיין	תיאור	ברירת מחדל	נוכחות
ref	המשתנה שממנו המדיניות קוראת באופן דינמי את הסיסמה (encode) או כותבת את הסיסמה (decode).	לא רלוונטי	חובה

אלמנט <AssignTo>

המדיניות הזו מציינת את משתנה היעד שיוגדר עם הערך המקודד או המפוענח שנוצר על ידי המדיניות הזו.

בדוגמה הבאה מצוין שהמדיניות צריכה להגדיר את הכותרת Authorization של ההודעה לערך שנוצר:

<AssignTo createNew="false">request.header.Authorization</AssignTo>

ברירת מחדל:	לא רלוונטי
נוכחות:	חובה
סוג:	String

מאפיינים

מאפיין	תיאור	ברירת מחדל	נוכחות
createNew	קובעת אם המדיניות צריכה להחליף את המשתנה אם הוא כבר מוגדר. אם הערך הוא false, ההקצאה למשתנה מתרחשת רק אם המשתנה לא מוגדר (null). אם הערך הוא true, ההקצאה למשתנה תמיד מתרחשת. בדרך כלל מגדירים את המאפיין הזה לערך false (ברירת המחדל).	FALSE	אופציונלי

רכיב <Source>

לפענוח, המשתנה שמכיל את המחרוזת בקידוד Base64, בצורה Basic Base64EncodedString. לדוגמה, מציינים request.header.Authorization, שמתאים לכותרת Authorization.

<Source>request.header.Authorization</Source>

ברירת מחדל:	לא רלוונטי
נוכחות:	נדרש לפעולת הפענוח.
סוג:	לא רלוונטי

משתנים בתהליך

משתנה הזרימה הבא מוגדר כשהמדיניות נכשלת:

• ‫BasicAuthentication.{policy_name}.failed (עם הערך true)

הערה: אם אתם רואים משתנים בשמות BasicAuthentication.{policy_name}.fault.cause ו-BasicAuthentication.{policy_name}.fault.name, הם לא נמצאים בשימוש ב-Apigee כרגע.

הפניה לשגיאה

בקטע הזה מתוארים קודי התקלה והודעות השגיאה שמוחזרים, ומשתני התקלה שמוגדרים על ידי Apigee כשמדיניות כזו מפעילה שגיאה. המידע הזה חשוב אם אתם מפתחים כללי תקלות לטיפול בשגיאות. מידע נוסף על שגיאות שקשורות למדיניות ועל טיפול בשגיאות

שגיאות זמן ריצה

השגיאות האלה יכולות להתרחש כשהמדיניות מופעלת.

קוד תקלה	סטטוס HTTP	מטרה	תיקון
steps.basicauthentication.InvalidBasicAuthenticationSource	500	בפענוח, אם המחרוזת המקודדת הנכנסת Base64 לא מכילה ערך תקין או שהכותרת לא תקינה (לדוגמה, אם היא לא מתחילה ב-Basic).
steps.basicauthentication.UnresolvedVariable	500	משתני המקור הנדרשים לפענוח או לקידוד לא קיימים. השגיאה הזו יכולה להופיע רק אם הערך של IgnoreUnresolvedVariables הוא False.

שגיאות בהטמעה

השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שמכיל את המדיניות הזו.

שם השגיאה	מתרחש כאשר	תיקון
UserNameRequired	האלמנט <User> חייב להיות קיים עבור הפעולה בעלת השם.
PasswordRequired	האלמנט <Password> חייב להיות קיים עבור הפעולה בעלת השם.
AssignToRequired	האלמנט <AssignTo> חייב להיות קיים עבור הפעולה בעלת השם.
SourceRequired	האלמנט <Source> חייב להיות קיים עבור הפעולה בעלת השם.

משתני תקלות

המשתנים האלה מוגדרים כשמתרחשת שגיאת זמן ריצה. מידע נוסף על שגיאות שקשורות למדיניות

משתנים	כאשר:	דוגמה
fault.name="fault_name"	‫fault_name הוא שם התקלה, כפי שמופיע בטבלה Runtime errors שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה.	fault.name Matches "UnresolvedVariable"
BasicAuthentication.policy_name.failed	‫policy_name הוא השם שהמשתמש הגדיר למדיניות שגרמה לשגיאה.	BasicAuthentication.BA-Authenticate.failed = true

דוגמה לתגובת שגיאה

הערה: כדי לטפל בשגיאות, מומלץ ללכוד את החלק errorcode של תגובת השגיאה. אל תסתמכו על הטקסט ב-faultstring, כי הוא עשוי להשתנות.

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.basicauthentication.UnresolvedVariable"
      },
      "faultstring":"Unresolved variable : request.queryparam.password"
   }
}

דוגמה לכלל שגיאה

<FaultRule name="Basic Authentication Faults">
    <Step>
        <Name>AM-UnresolvedVariable</Name>
        <Condition>(fault.name Matches "UnresolvedVariable") </Condition>
    </Step>
    <Step>
        <Name>AM-AuthFailedResponse</Name>
        <Condition>(fault.name = "InvalidBasicAuthenticationSource")</Condition>
    </Step>
    <Condition>(BasicAuthentication.BA-Authentication.failed = true) </Condition>
</FaultRule>

סכימות

דוגמה: אפשר לעיין בדוגמאות של סכימות עדכניות במאגר שלנו ב-GitHub.

נושאים קשורים

המדיניות בנושא פעולות של Key Value Map