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

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

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

אלמנט <User>

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

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

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

מאפיינים

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

אלמנט <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 时才会发生此错误。

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。

错误名称	发生的条件	修复
UserNameRequired	已命名的操作必须存在 <User> 元素。
PasswordRequired	已命名的操作必须存在 <Password> 元素。
AssignToRequired	已命名的操作必须存在 <AssignTo> 元素。
SourceRequired	已命名的操作必须存在 <Source> 元素。

故障变量

发生运行时错误时，系统会设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

变量	其中	示例
fault.name="fault_name"	fault_name 是故障名称，如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。	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