כרגע מוצג התיעוד של 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 |
השם הפנימי של המדיניות. הערך של המאפיין אפשר להשתמש באלמנט |
לא רלוונטי | נדרש |
continueOnError |
צריך להגדיר את הערך צריך להגדיר את הערך |
false | אופציונלי |
enabled |
צריך להגדיר את הערך צריך להגדיר את הערך |
true | אופציונלי |
async |
המאפיין הזה הוצא משימוש. |
false | הוצא משימוש |
רכיב <DisplayName>
יש להשתמש במאפיין הזה בנוסף למאפיין name
כדי להוסיף למדיניות
בכלי לעריכת שרת ה-proxy לניהול ממשק משתמש עם שם אחר בשפה טבעית.
<DisplayName>Policy Display Name</DisplayName>
ברירת המחדל |
לא רלוונטי אם משמיטים את הרכיב הזה, המערכת משתמשת בערך של מאפיין |
---|---|
נוכחות | אופציונלי |
תיאור | מחרוזת |
רכיב <Operation>
המדיניות הזו קובעת אם המדיניות Base64 תקודד או תפענח פרטי כניסה.
<Operation>Encode</Operation>
ברירת מחדל: | לא רלוונטי |
נוכחות: | נדרש |
סוג: |
מחרוזת. הערכים החוקיים כוללים:
|
הרכיב <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"). | build |
steps.basicauthentication.UnresolvedVariable |
500 | משתני המקור הנדרשים לפענוח או לקידוד לא נמצאים. השגיאה הזו יכולה
להתרחש רק אם הערך של IgnoreUnresolvedVariables הוא False. |
build |
שגיאות בפריסה
השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שכולל את המדיניות הזו.
שם השגיאה | מופיע כאשר | תיקון |
---|---|---|
UserNameRequired |
הרכיב <User> חייב להיכלל בפעולה בעלת השם. |
build |
PasswordRequired |
הרכיב <Password> חייב להיכלל בפעולה בעלת השם. |
build |
AssignToRequired |
הרכיב <AssignTo> חייב להיכלל בפעולה בעלת השם. |
build |
SourceRequired |
הרכיב <Source> חייב להיכלל בפעולה בעלת השם. |
build |
משתני שבר
המשתנים האלה מוגדרים כשמתרחשת שגיאה בזמן הריצה. אפשר לקרוא מידע נוסף במאמר מה צריך לדעת על שגיאות מדיניות.
משתנים | מיקום | דוגמה |
---|---|---|
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>