מדיניות Basicאימות

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

מה

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

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

סרטון: הסרטון הזה מדגים איך לבצע קידוד base64 של שם משתמש וסיסמה באמצעות מדיניות האימות הבסיסי.

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

טעימות

קידוד יוצא

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

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

Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk

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

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

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

כדי שתהיה אפשרות לחלץ את הערכים של רכיבי <User> ו-<Password> ממאגר המפתח/ערך (key/value) ולאכלס אותם במשתנים 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>

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

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


מידע על המדיניות בנושא אימות בסיסי

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

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

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

הפניה לרכיב

בהפניה לרכיב מתוארים הרכיבים והמאפיינים של מדיניות 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> כדי להוסיף למדיניות בכלי לעריכת שרת ה-proxy לניהול ממשק משתמש עם שם בשפה טבעית אחרת.

לא רלוונטי נדרש
continueOnError

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

צריך להגדיר את הערך true כדי להפעיל את התהליך גם אחרי כישלון במדיניות.

false אופציונלי
enabled

צריך להגדיר את הערך true כדי לאכוף את המדיניות.

צריך להגדיר את הערך false כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.

true אופציונלי
async

המאפיין הזה הוצא משימוש.

false הוצא משימוש

רכיב <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>
ברירת המחדל

לא רלוונטי

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

נוכחות אופציונלי
תיאור מחרוזת

רכיב <Operation>

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

<Operation>Encode</Operation>
ברירת מחדל: לא רלוונטי
נוכחות: נדרש
סוג:

מחרוזת.

הערכים החוקיים כוללים:

  • לקודד
  • Decode

הרכיב <ignoreUnresolvedVariables>>

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

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
ברירת מחדל: true
נוכחות: אופציונלי
סוג:

בוליאני

רכיב <User>

  • לקידוד, צריך להשתמש ברכיב <User> כדי לציין את המשתנה שמכיל את שם המשתמש. הערכים של שם המשתמש והסיסמה משורשרים באמצעות נקודתיים לפני קידוד Base64.
  • לפענוח, מציינים את המשתנה שבו נכתב שם המשתמש המפוענח.
<User ref="request.queryparam.username" /> 
ברירת מחדל: לא רלוונטי
נוכחות: נדרש
סוג:

לא רלוונטי

מאפיינים

מאפיין התיאור ברירת המחדל נוכחות
ר'

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

לא רלוונטי נדרש

רכיב <Password>

  • לקידוד, צריך להשתמש ברכיב <Password> כדי לציין את המשתנה שמכיל את הסיסמה.
  • לפענוח, מציינים את המשתנה שבו כתובה הסיסמה המפוענחת.
<Password ref="request.queryparam.password" />
ברירת מחדל: לא רלוונטי
נוכחות: נדרש
סוג:

לא רלוונטי

מאפיינים

מאפיין התיאור ברירת המחדל נוכחות
ר'

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

לא רלוונטי נדרש

הרכיב <assignTo>

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

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

<AssignTo createNew="false">request.header.Authorization</AssignTo>
ברירת מחדל: לא רלוונטי
נוכחות: נדרש
סוג:

מחרוזת

מאפיינים

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

אם הערך הוא 'false', ההקצאה למשתנה מתרחשת רק אם הוא לא מוגדר כרגע (null).

כשהערך הוא "true", ההקצאה למשתנה תמיד מתרחשת.

בדרך כלל המאפיין הזה מוגדר כ-"false" (ברירת המחדל).

false אופציונלי

רכיב <Source>

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

<Source>request.header.Authorization</Source>
ברירת מחדל: לא רלוונטי
נוכחות: נדרש לפעולת פענוח הקוד.
סוג:

לא רלוונטי

משתני זרימה

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

  • BasicAuthentication.{policy_name}.failed (עם ערך True)

הפניה לשגיאות

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

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

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

קוד שגיאה סטטוס 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 הוא שם התקלה, כפי שמפורט בטבלה שגיאות זמן ריצה שלמעלה. שם הטעות הוא החלק האחרון בקוד השגיאה. fault.name Matches "UnresolvedVariable"
BasicAuthentication.policy_name.failed policy_name הוא השם שצוין על ידי המשתמש של המדיניות שגרמה לשגיאה. BasicAuthentication.BA-Authenticate.failed = true

דוגמה לשגיאה

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

סכימות

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

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