כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של
Apigee X. מידע
מה
OAuthV2 היא מדיניות רב-שלבית לביצוע פעולות של הרשאות מסוג OAuth 2.0. זאת המדיניות הראשית שמשמשת להגדרת נקודות קצה של OAuth 2.0 ב-Apigee Edge.
טיפ: בדף הבית של OAuth מפורט מידע נוסף על OAuth ב-Apigee Edge. הוא כולל קישורים למשאבים, לדוגמאות, לסרטונים ועוד. אפשר לעיין בדוגמה המתקדמת של OAuth ב-GitHub כדי לקבל הדגמה טובה של אופן השימוש במדיניות הזו באפליקציה פעילה.
טעימות
VerifyAccessToken
VerifyAccessToken
ההגדרה של מדיניות OAuthV2 (עם הפעולה verificationAccessToken) מאמתת שאסימון גישה שנשלח ל-Apigee Edge חוקי. כשפעולת המדיניות הזו מופעלת, Edge מחפש אסימון גישה חוקי בבקשה. אם אסימון הגישה תקין, מותר להמשיך את הבקשה. אם השיטה לא תקינה, כל העיבודים יופסקו ותוחזר שגיאה בתגובה.
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2"> <DisplayName>OAuth v2.0 2</DisplayName> <Operation>VerifyAccessToken</Operation> <AccessTokenPrefix>Bearer</AccessTokenPrefix> <!-- Optional, default is Bearer --> </OAuthV2>
הערה: יש תמיכה רק באסימוני OAuth 2.0. אין תמיכה באסימונים של קוד אימות הודעות (MAC).
לדוגמה:
$ curl -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282
כברירת מחדל, Edge מקבל אסימוני גישה בכותרת Authorization
עם
הקידומת Bearer
. אפשר לשנות את ברירת המחדל באמצעות הרכיב <AccessToken>
.
GenerateAccessToken
יצירת אסימוני גישה
במאמר בקשת אסימוני גישה וקודי הרשאה מופיעות דוגמאות לכך. הנושא כולל דוגמאות לפעולות הבאות:
GenerateAuthorizationCode
יצירת קוד הרשאה
בקטע בקשת קוד הרשאה מופיעות דוגמאות לכך.
RefreshAccessToken
רענון של אסימון גישה
במאמר רענון של אסימון גישה מופיעות דוגמאות לאופן שבו מבקשים אסימוני גישה באמצעות אסימון רענון.
אסימון של תהליך תגובה
יצירת אסימון גישה בתהליך התגובה
לפעמים תצטרכו ליצור אסימון גישה בתהליך התגובה. לדוגמה, אפשר לעשות זאת בתגובה לאימות מותאם אישית כלשהו שבוצע בשירות לקצה העורפי. בדוגמה הזו, התרחיש לדוגמה מחייב גם אסימון גישה וגם אסימון רענון, ללא קשר לסוג ההרשאה המשתמעת. במקרה הזה, נשתמש בסוג מתן הסיסמה כדי ליצור את האסימון. כמו שרואים, הטריק שצריך לגרום לביצוע הפעולה הזו הוא להעביר אותה בכותרת של בקשת הרשאה עם מדיניות JavaScript.
תחילה נבחן את המדיניות לדוגמה:
<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken"> <Operation>GenerateAccessToken</Operation> <AppEndUser>Doe</AppEndUser> <UserName>jdoe</UserName> <PassWord>jdoe</PassWord> <GrantType>grant_type</GrantType> <ClientId>a_valid_client_id</ClientId> <SupportedGrantTypes> <GrantType>password</GrantType> </SupportedGrantTypes> </OAuthV2>
אם תוסיפו את המדיניות הזו לתהליך התגובה, היא תיכשל ותוצג שגיאת ' 401 UnAuthorized' למרות שהפרמטרים הנכונים של ההתחברות מצוינים במדיניות. כדי לפתור את הבעיה, צריך להגדיר כותרת של בקשת הרשאה.
כותרת ההרשאה צריכה להכיל סכמת גישה בסיסית עם client_id:client_secret בקידוד Base64.
אפשר להוסיף את הכותרת הזו באמצעות מדיניות JavaScript שמוצבת ממש לפני מדיניות OAuthV2, בצורה הזו. המשתנים "local_clientid" ו-"local_secret" חייבים להיות מוגדרים קודם לכן וזמינים בתהליך:
var client_id = context.getVariable("local_clientid"); var client_secret = context.getVariable("local_secret"); context.setVariable("request.header.Authorization","Basic "+CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1 .parse(client_id + ':' + client_secret)));
למידע נוסף, ראו "קידוד של פרטי כניסה לאימות בסיסי".
הפניה לרכיב
בהפניה למדיניות מתוארים הרכיבים והתכונות של מדיניות OAuthV2.
המדיניות לדוגמה שמוצגת בהמשך היא אחת ממגוון הגדרות אפשריות. בדוגמה הזו מוצגת מדיניות OAuthV2 שהוגדרה לפעולה GenerateAccessToken. הוא כולל רכיבי חובה ואופציונליים. לקבלת פרטים, עיינו בתיאורי הרכיבים בקטע הזה.
<OAuthV2 name="GenerateAccessToken"> <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type --> <Operation>GenerateAccessToken</Operation> <!-- This is in millseconds, so expire in an hour --> <ExpiresIn>3600000</ExpiresIn> <SupportedGrantTypes> <GrantType>client_credentials</GrantType> </SupportedGrantTypes> <GrantType>request.queryparam.grant_type</GrantType> <GenerateResponse/> </OAuthV2>
מאפייני <OAuthV2>
<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">
בטבלה הבאה מפורטים המאפיינים שמשותפים לכל רכיבי ההורה של המדיניות:
מאפיין | התיאור | ברירת המחדל | נוכחות |
---|---|---|---|
name |
השם הפנימי של המדיניות. הערך של המאפיין אפשר להשתמש באלמנט |
לא רלוונטי | נדרש |
continueOnError |
צריך להגדיר את הערך צריך להגדיר את הערך |
false | אופציונלי |
enabled |
צריך להגדיר את הערך צריך להגדיר את הערך |
true | אופציונלי |
async |
המאפיין הזה הוצא משימוש. |
false | הוצא משימוש |
רכיב <DisplayName>
יש להשתמש במאפיין הזה בנוסף למאפיין name
כדי להוסיף למדיניות
בכלי לעריכת שרת ה-proxy לניהול ממשק משתמש עם שם אחר בשפה טבעית.
<DisplayName>Policy Display Name</DisplayName>
ברירת המחדל |
לא רלוונטי אם משמיטים את הרכיב הזה, המערכת משתמשת בערך של מאפיין |
---|---|
נוכחות | אופציונלי |
תיאור | מחרוזת |
רכיב <AccessToken>
<AccessToken>request.header.access_token</AccessToken>
כברירת מחדל, המטרה שלVerifyAccessToken היא שאסימון הגישה יישלח בכותרת
Authorization
.
תוכלו לשנות את ברירת המחדל באמצעות הרכיב הזה. לדוגמה,
השדה request.queryparam.access_token
מציין שאסימון הגישה
צריך להיות קיים כפרמטר של שאילתה בשם access_token
.
<AccessToken>request.header.access_token</AccessToken>
:
curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"דוגמה שבה מצוין
<AccessToken>request.queryparam.access_token</AccessToken>
:
curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"
ברירת מחדל: |
לא רלוונטי |
נוכחות: |
אופציונלי |
סוג: | מחרוזת |
לשימוש בפעולות: |
|
רכיב <AccessTokenPrefix>
<AccessTokenPrefix>Bearer</AccessTokenPrefix>
כברירת מחדל, ConfirmAccessToken מצפה שאסימון הגישה יישלח בכותרת Authorization כאסימון גישה. לדוגמה:
-H "Authorization: Bearer Rft3dqrs56Blirls56a"
נכון לעכשיו, התחילית שנתמכת היא Bearer.
ברירת מחדל: |
פרמטרים לרשת |
נוכחות: |
אופציונלי |
סוג: | מחרוזת |
ערכים חוקיים: |
פרמטרים לרשת |
לשימוש בפעולות: |
|
רכיב <AppEndUser>
<AppEndUser>request.queryparam.app_enduser</AppEndUser>
במקרים שבהם צריך לשלוח את מזהה משתמש הקצה של האפליקציה לשרת ההרשאות, הרכיב הזה מאפשר לציין איפה Edge יחפש את מזהה משתמש הקצה. לדוגמה, אפשר לשלוח אותו כפרמטר של שאילתה או בכותרת HTTP.
לדוגמה, request.queryparam.app_enduser
מציין
שה-AppEndUser צריך להיות נוכח כפרמטר של שאילתה, כמו, למשל, ?app_enduser=ntesla@theramin.com
. כדי לדרוש את AppEndUser בכותרת HTTP, למשל, צריך להגדיר את הערך הזה כ-request.header.app_enduser
.
ציון ההגדרה הזו מאפשר לכלול מזהה משתמש קצה של אפליקציה באסימון הגישה. התכונה כדאית אם ברצונך שתהיה לך אפשרות לאחזר או לבטל אסימוני גישה מסוג OAuth 2.0 לפי מזהה משתמש קצה. אפשר לקרוא מידע נוסף במאמר הפעלה של אחזור וביטול אסימוני גישה מסוג OAuth 2.0 לפי מזהה משתמש קצה, מזהה אפליקציה או שניהם.
ברירת מחדל: |
לא רלוונטי |
נוכחות: |
אופציונלי |
סוג: | מחרוזת |
ערכים חוקיים: |
כל משתנה זרימה שניתן לגשת אליו מהמדיניות בזמן הריצה. |
בשימוש עם סוגי המענק: |
|
<מאפיינים/מאפיין>
<Attributes> <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute> <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute> </Attributes>
ניתן להשתמש ברכיב הזה כדי להוסיף מאפיינים מותאמים אישית לאסימון גישה או לקוד הרשאה. לדוגמה, יכול להיות שתרצו להטמיע מזהה משתמש או מזהה סשן באסימון גישה שאפשר לחלץ ולבדוק בזמן ריצה.
הרכיב הזה מאפשר לציין ערך במשתנה זרימה או ממחרוזת מילולית. אם תציינו גם משתנה וגם מחרוזת, המערכת תשתמש בערך שצוין במשתנה הזרימה. אם אי אפשר לפענח את המשתנה, אז המחרוזת מוגדרת כברירת המחדל.
מידע נוסף על השימוש ברכיב הזה זמין במאמר התאמה אישית של אסימונים וקודי הרשאה.
הצגה או הסתרה של מאפיינים מותאמים אישית בתשובה
חשוב לזכור שאם מגדירים את הרכיב GenerateResponse של המדיניות הזו כ-true, יוחזר הייצוג המלא של האסימון ב-JSON בתגובה, כולל מאפיינים מותאמים אישית שהגדרת. במקרים מסוימים, כדאי להסתיר חלק מהמאפיינים המותאמים אישית או את כולם בתשובה, כדי שלא יהיו גלויים לאפליקציות לקוח.
כברירת מחדל, מאפיינים מותאמים אישית כן מופיעים בתשובה. כדי להסתיר אותן, אפשר להגדיר את הערך false בפרמטר display. לדוגמה:
<Attributes> <Attribute name="employee_id" ref="employee.id" display="false"/> <Attribute name="employee_name" ref="employee.name" display="false"/> </Attributes>
הערך של המאפיין display
לא
קבוע. נניח שיצרתם אסימון גישה עם מאפיינים מותאמים אישית שאתם רוצים להסתיר
בתגובה שנוצרה. הגדרה של display=false
משיגה את היעד הזה. עם זאת, אם
אסימון גישה חדש ייווצר במועד מאוחר יותר באמצעות אסימון רענון, המאפיינים המותאמים אישית המקוריים
מאסימון הגישה יופיעו בתגובה של אסימון הרענון. הסיבה לכך היא ש-Edge לא זוכר שהמאפיין display
הוגדר במקור כ-false
במדיניות יצירת אסימון הגישה. המאפיין המותאם אישית הוא פשוט חלק מהמטא-נתונים של אסימון הגישה.
ההתנהגות הזו תפעל גם אם תוסיפו מאפיינים מותאמים אישית לקוד הרשאה. אם נוצר אסימון גישה באמצעות הקוד הזה, המאפיינים המותאמים אישית יופיעו בתגובה לאסימון הגישה. שוב, ייתכן שזו לא ההתנהגות שהתכוונתם אליה.
כדי להסתיר מאפיינים מותאמים אישית במקרים כאלה, אפשר לבחור באפשרויות הבאות:
- צריך לאפס באופן מפורש את המאפיינים המותאמים אישית במדיניות אסימון הרענון ולהגדיר אותם כ-False. במקרה כזה, ייתכן שיהיה צורך לאחזר את הערכים המותאמים אישית המקוריים מאסימון הגישה המקורי באמצעות המדיניות GetOAuthV2Info.
- אפשר להשתמש במדיניות JavaScript לאחר עיבוד כדי לחלץ באופן ידני מאפיינים מותאמים אישית שאינך רוצה לראות בתגובה.
למידע נוסף, ראו התאמה אישית של אסימונים וקודי הרשאות.
ברירת מחדל: |
|
נוכחות: |
אופציונלי |
ערכים חוקיים: |
|
בשימוש עם סוגי המענק: |
|
האלמנט <ClientId>
<ClientId>request.formparam.client_id</ClientId>
במקרים מסוימים, אפליקציית הלקוח צריכה לשלוח את מזהה הלקוח לשרת ההרשאות. הרכיב הזה מאפשר לציין איפה Edge אמור לחפש את מזהה הלקוח. המיקום החוקי היחיד שניתן להגדיר הוא מיקום ברירת המחדל, משתנה הזרימה request.formparam.client_id
. לא ניתן להגדיר את ClientId
לכל משתנה אחר.
למידע נוסף, ראו בקשת אסימוני גישה וקודי הרשאה.
ברירת מחדל: |
request.formparam.client_id (כתובת x-www-form-urlencoded ומצוינת בגוף הבקשה) |
נוכחות: |
אופציונלי |
סוג: | מחרוזת |
ערכים חוקיים: | משתנה הזרימה: request.formparam.client_id |
בשימוש עם סוגי המענק: |
יכול לשמש גם לפעולה GenerateAuthorizationCode. |
רכיב <Code>
<Code>request.queryparam.code</Code>
בתהליך של סוג ההרשאה, הלקוח צריך לשלוח קוד הרשאה לשרת ההרשאות (Apigee Edge). הרכיב הזה מאפשר לציין איפה Edge אמור לחפש את קוד ההרשאה. לדוגמה, אפשר לשלוח אותו בתור פרמטר של שאילתה, כותרת HTTP או פרמטר טופס (ברירת המחדל).
המשתנה request.queryparam.auth_code
מציין
שקוד ההרשאה צריך להופיע כפרמטר של שאילתה, כמו,
לדוגמה, ?auth_code=AfGlvs9
. כדי לדרוש את קוד ההרשאה בכותרת HTTP, למשל, מגדירים את הערך הזה כ-request.header.auth_code
. למידע נוסף, ראו בקשת אסימוני גישה וקודי הרשאה.
ברירת מחדל: |
request.formparam.code (כתובת x-www-form-urlencoded ומצוינת בגוף הבקשה) |
נוכחות: |
אופציונלי |
סוג: | מחרוזת |
ערכים חוקיים: | כל משתנה זרימה שאפשר לגשת אליו מהמדיניות בזמן ריצה |
בשימוש עם סוגי המענק: | authorization_code |
הרכיב<expirationIn>
<ExpiresIn>10000</ExpiresIn>
המדיניות הזו אוכפת את זמן התפוגה של אסימוני גישה וקודי הרשאה באלפיות שנייה. (לאסימוני
רענון, יש להשתמש ב-<RefreshTokenExpiresIn>
.) ערך זמן התפוגה הוא
ערך שנוצר על-ידי המערכת בתוספת הערך <ExpiresIn>
. אם הערך של
<ExpiresIn>
הוא 1-, התוקף של האסימון או הקוד יפוג בהתאם לתפוגת התוקף המקסימלית של אסימון הגישה ל-OAuth.
אם לא מציינים את <ExpiresIn>
, המערכת מחילה
ערך ברירת מחדל שהוגדר ברמת המערכת.
ניתן גם להגדיר את זמן התפוגה בזמן ריצה באמצעות ערך ברירת מחדל בתוך הקוד או באמצעות הפניה למשתנה זרימה. לדוגמה, אפשר לשמור ערך תפוגה של אסימון במפת ערכי מפתח, לאחזר אותו, להקצות אותו למשתנה ולהפנות אליו במדיניות. לדוגמה,
kvm.oauth.expires_in
.
באמצעות Apigee Edge ל-Public Cloud, Edge שומר את הישויות הבאות במטמון למשך 180 שניות לפחות אחרי גישה לישויות.
- אסימוני גישה מסוג OAuth. המשמעות היא שאסימון שבוטל יוכל בכל זאת לפעול במשך עד שלוש דקות, עד שיפוג התוקף של מגבלת המטמון שלו.
- ישויות של שירות ניהול מפתחות (KMS) (אפליקציות, מפתחים, מוצרי API).
- מאפיינים מותאמים אישית באסימוני OAuth וישויות KMS.
הבית הבא מציין משתנה זרימה וערך ברירת מחדל גם כן. שימו לב שערך משתנה הזרימה מקבל עדיפות על פני ערך ברירת המחדל שצוין.
<ExpiresIn ref="kvm.oauth.expires_in"> 3600000 <!--default value in milliseconds--> </ExpiresIn>
ב-Edge אין תמיכה בדרך לאילוץ תפוגה של אסימון לאחר יצירתו. אם צריך לאלץ תאריך תפוגה של אסימון (למשל על סמך תנאי מסוים), תוכלו לקרוא על פתרון אפשרי בפוסט הזה בקהילת Apigee.
כברירת מחדל, אסימוני גישה שתוקפם פג נמחקים ממערכת Apigee Edge באופן אוטומטי 3 ימים לאחר התפוגה. למידע נוסף, ראו ניקוי אסימוני גישה
ענן פרטי: ב-Edge להתקנה של ענן פרטי, ערך ברירת המחדל מוגדר על ידי הנכס conf_keymanagement_oauth_auth_code_expiry_time_in_millis
.
כדי להגדיר את המאפיין הזה:
- פותחים את הקובץ
message-processor.properties
בעורך. אם הקובץ לא קיים, יוצרים אותו:vi /opt/apigee/customer/application/message-processor.properties
- מגדירים את הנכס באופן הרצוי:
conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000
- מוודאים שקובץ המאפיינים שייך למשתמש ה-API:
chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
- מפעילים מחדש את מעבד ההודעות.
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
ברירת מחדל: |
אם לא מציינים ערך, המערכת מחילה ערך ברירת מחדל שהוגדר ברמת המערכת. |
נוכחות: |
אופציונלי |
סוג: | מספר שלם |
ערכים חוקיים: |
|
בשימוש עם סוגי המענק: |
בשימוש גם עם פעולה GenerateAuthorizationCode. |
רכיב <ExternalAccessToken>
<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>
ההגדרה הזו מציינת ל-Apigee Edge איפה למצוא אסימון גישה חיצוני (אסימון גישה שלא נוצר על ידי Apigee Edge).
המשתנה request.queryparam.external_access_token
מציין
שאסימון הגישה החיצוני צריך להופיע כפרמטר של שאילתה, כמו, לדוגמה, ?external_access_token=12345678
. כדי לדרוש אסימון גישה חיצוני
בכותרת HTTP, למשל, מגדירים את הערך
כ-request.header.external_access_token
. למידע נוסף, ראו שימוש באסימוני OAuth של צד שלישי.
האלמנט <ExternalAuthorization>
<ExternalAuthorization>true</ExternalAuthorization>
אם הרכיב הזה שגוי או לא קיים, Edge מאמת את client_id ו-client_secret כרגיל מול מאגר ההרשאות של Apigee Edge. יש להשתמש ברכיב הזה כשרוצים לעבוד עם אסימוני OAuth של צד שלישי. לפרטים על השימוש ברכיב הזה, ראו שימוש באסימוני OAuth של צד שלישי.
ברירת מחדל: |
false |
נוכחות: |
אופציונלי |
סוג: | בוליאני |
ערכים חוקיים: | נכון או לא נכון |
בשימוש עם סוגי המענק: |
|
האלמנט <ExternalAuthorizationCode>
<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>
ההגדרה הזו מציינת ל-Apigee Edge איפה למצוא קוד הרשאה חיצוני (קוד אימות שלא נוצר על ידי Apigee Edge).
המשתנה request.queryparam.external_auth_code
מציין
שקוד ההרשאה החיצוני צריך להופיע כפרמטר של שאילתה, כמו, לדוגמה, ?external_auth_code=12345678
. כדי לדרוש קוד הרשאה חיצוני בכותרת HTTP, לדוגמה, צריך להגדיר את הערך request.header.external_auth_code
. למידע נוסף, ראו שימוש באסימוני OAuth של צד שלישי.
רכיב <ExternalרענןToken>
<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>
ההגדרה הזו מציינת ל-Apigee Edge איפה למצוא אסימון רענון חיצוני (אסימון רענון שלא נוצר על ידי Apigee Edge).
המשתנה request.queryparam.external_refresh_token
מציין
שאסימון הרענון החיצוני צריך להופיע כפרמטר של שאילתה, כמו, לדוגמה, ?external_refresh_token=12345678
. כדי לדרוש את אסימון הרענון החיצוני בכותרת HTTP, למשל, מגדירים את הערך הזה כ-request.header.external_refresh_token
. למידע נוסף, ראו שימוש באסימוני OAuth של צד שלישי.
האלמנט <GenerateResponse>
<GenerateResponse enabled='true'/>
אם המדיניות מוגדרת לערך true
, המדיניות תיצור תגובה ותחזיר אותה. לדוגמה, ב-GenerateAccessToken, התגובה עשויה להיראות כך:
{ "issued_at" : "1467841035013", "scope" : "read", "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930", "refresh_token_issued_at" : "1467841035013", "status" : "approved", "refresh_token_status" : "approved", "api_product_list" : "[Product1, nhl_product]", "expires_in" : "1799", "developer.email" : "edward@slalom.org", "token_type" : "BearerToken", "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ", "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj", "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a", "organization_name" : "cerruti", "refresh_token_expires_in" : "0", "refresh_count" : "0" }
אם false
, לא תישלח תשובה. במקום זאת, קבוצה של משתני זרימה מאוכלסת
בערכים שקשורים לפונקציית של המדיניות. לדוגמה, משתנה זרימה שנקרא
oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code
יאוכלס בקוד ההרשאה החדש שהופק. חשוב לשים לב שהפרמטר expires_in מבוטא בשניות
בתגובה.
ברירת מחדל: |
false |
נוכחות: |
אופציונלי |
סוג: | מחרוזת |
ערכים חוקיים: | נכון או לא נכון |
בשימוש עם סוגי המענק: |
|
האלמנט <GenerateErrorResponse>
<GenerateErrorResponse enabled='true'/>
אם המדיניות מוגדרת לערך true
, המדיניות יוצרת תשובה ומחזירה תשובה אם
מאפיין ContinueOnError מוגדר כ-True. אם הערך הוא false
(ברירת המחדל), לא תישלח תשובה. במקום זאת, קבוצה של משתני זרימה מאוכלסת בערכים שקשורים לפונקציית
המדיניות.
ברירת מחדל: |
false |
נוכחות: |
אופציונלי |
סוג: | מחרוזת |
ערכים חוקיים: | נכון או לא נכון |
בשימוש עם סוגי המענק: |
|
<GrantType>
<GrantType>request.queryparam.grant_type</GrantType>
שדה זה מגדיר למדיניות איפה נמצא הפרמטר של סוג המענק שמועבר בבקשה. בהתאם למפרט OAuth 2.0, צריך לספק את סוג המענק יחד עם בקשות לאסימוני גישה ולקודי הרשאה. המשתנה יכול להיות כותרת, פרמטר של שאילתה או פרמטר של טופס (ברירת מחדל).
לדוגמה, הקוד request.queryparam.grant_type
מציין שהסיסמה צריכה להופיע כפרמטר של שאילתה, כמו למשל ?grant_type=password
.
כדי לדרוש את סוג ההרשאה בכותרת HTTP, למשל, צריך להגדיר את הערך הזה
כ-request.header.grant_type
. למידע נוסף, ראו בקשת אסימוני גישה וקודי הרשאה.
ברירת מחדל: |
request.formparam.grant_type (כתובת x-www-form-urlencoded ומצוינת בגוף הבקשה) |
נוכחות: |
אופציונלי |
סוג: | מחרוזת |
ערכים חוקיים: | משתנה, כפי שהוסבר למעלה. |
בשימוש עם סוגי המענק: |
|
רכיב <Operation>
<Operation>GenerateAuthorizationCode</Operation>
פעולת OAuth 2.0 בוצעה על ידי המדיניות.
ברירת מחדל: |
אם לא מציינים |
נוכחות: |
אופציונלי |
סוג: | מחרוזת |
ערכים חוקיים: |
|
רכיב <PassWord>
<PassWord>request.queryparam.password</PassWord>
הרכיב הזה משמש רק עבור סוג מתן הסיסמה. בהתאם לסוג מתן הסיסמה, פרטי הכניסה של המשתמש (סיסמה ושם משתמש) חייבים להיות זמינים למדיניות OAuthV2. הרכיבים <PassWord>
ו-<UserName>
משמשים לציון משתנים שבהם Edge תוכל למצוא את הערכים האלה. אם הרכיבים האלה לא צוינו,
המדיניות מצפה למצוא את הערכים (כברירת מחדל) בפרמטרים של טופס שנקראים username
ו-password
. אם הערכים לא יימצאו, המדיניות תציג הודעת שגיאה. אפשר להשתמש ברכיבים <PassWord>
ו-<UserName>
כדי להפנות לכל משתנה זרימה שמכיל את פרטי הכניסה.
לדוגמה, אפשר להעביר את הסיסמה בבקשת אסימון באמצעות פרמטר של שאילתה, ולהגדיר את הרכיב באופן הבא:
<PassWord>request.queryparam.password</PassWord>
.
כדי לדרוש את הסיסמה בכותרת HTTP, צריך להגדיר את הערך
הזה כ-request.header.password
.
מדיניות OAuthV2 לא עושה שום דבר נוסף עם הערכים האלה של פרטי הכניסה. Edge רק מאמתת שהם קיימים. מפתח ה-API יכול לאחזר את בקשת הערכים ולשלוח אותם לספק הזהויות לפני החלת המדיניות ליצירת אסימון.
למידע נוסף, ראו בקשת אסימוני גישה וקודי הרשאה.
ברירת מחדל: |
request.formparam.password (כתובת x-www-form-urlencoded ומצוינת בגוף הבקשה) |
נוכחות: |
אופציונלי |
סוג: | מחרוזת |
ערכים חוקיים: | כל משתנה זרימה הזמין למדיניות בזמן הריצה. |
בשימוש עם סוגי המענק: | סיסמה |
אלמנט <RedirectUri>
<RedirectUri>request.queryparam.redirect_uri</RedirectUri>
ההגדרה קובעת איפה Edge יחפש את הפרמטר redirect_uri
בבקשה.
מידע על מזהי URI של הפניה אוטומטית
מזהי URI של הפניה מחדש משמשים יחד עם קוד ההרשאה וסוגי הרשאות משתמעות. ה-URI של ההפניה מורה לשרת ההרשאות (Edge) לאן לשלוח קוד הרשאה (עבור סוג ההרשאה של קוד ההרשאה) או את אסימון הגישה (לסוג ההרשאה המשתמעת). חשוב להבין מתי הפרמטר הזה נדרש, מתי הוא אופציונלי ואיך משתמשים בו:
-
(חובה) אם רשומה כתובת URL לקריאה חוזרת (callback) באפליקציית הפיתוח שמשויכת למפתחות הלקוח של הבקשה, ואם
redirect_uri
מופיע בבקשה, חייבת להיות התאמה מדויקת בין שניהם. אם הם לא תואמים, תוחזר שגיאה. למידע נוסף על רישום אפליקציות למפתחים ב-Edge וציון כתובת URL של קריאה חוזרת, אפשר לקרוא את המאמר רישום אפליקציות וניהול מפתחות API. - (אופציונלי) אם רשומה כתובת URL לקריאה חוזרת (callback) וחסר הערך
redirect_uri
בבקשה, Edge מפנה לכתובת ה-URL הרשומה לקריאה חוזרת. - (חובה) אם כתובת URL לקריאה חוזרת (callback) לא רשומה, חובה לציין
redirect_uri
. חשוב לשים לב שבמקרה הזה, Edge יקבל כל כתובת URL. מקרה כזה עלול ליצור בעיית אבטחה,ולכן יש להשתמש בו רק עם אפליקציות לקוח מהימנות. אם אפליקציות של לקוח לא מהימנות, השיטה המומלצת היא לדרוש תמיד רישום של כתובת URL לקריאה חוזרת.
אפשר לשלוח את הפרמטר הזה בפרמטר של שאילתה או בכותרת. המשתנה request.queryparam.redirect_uri
מציין שה-RedirectUri
צריך להופיע כפרמטר של שאילתה, כמו, לדוגמה, ?redirect_uri=login.myapp.com
. כדי לדרוש שימוש ב-RedirectUri בכותרת HTTP,
הגדירו את הערך הזה ל-request.header.redirect_uri
. למידע נוסף, ראו בקשת אסימוני גישה וקודי הרשאה.
ברירת מחדל: |
request.formparam.redirect_uri (כתובת x-www-form-urlencoded ומצוינת בגוף הבקשה) |
נוכחות: |
אופציונלי |
סוג: | מחרוזת |
ערכים חוקיים: | כל משתנה זרימה שאפשר לגשת אליו במדיניות בזמן הריצה |
בשימוש עם סוגי המענק: |
בשימוש גם עם הפעולה GenerateAuthorizationCode. |
רכיב <רענןToken>
<RefreshToken>request.queryparam.refreshtoken</RefreshToken>
כשמבקשים אסימון גישה באמצעות אסימון רענון, צריך לספק את אסימון הרענון בבקשה. הרכיב הזה מאפשר לציין איפה Edge יחפש את אסימון הרענון. לדוגמה, הוא יכול להישלח כפרמטר של שאילתה, ככותרת HTTP או כפרמטר טופס (ברירת המחדל).
המשתנה request.queryparam.refreshtoken
מציין שאסימון הרענון צריך להופיע כפרמטר של שאילתה, כמו לדוגמה
?refresh_token=login.myapp.com
. כדי לדרוש את ה-רענן אסימון בכותרת HTTP, למשל, צריך להגדיר את הערך הזה כ-request.header.refresh_token
. למידע נוסף, ראו בקשת אסימוני גישה וקודי הרשאה.
ברירת מחדל: |
request.formparam.refresh_token (קובץ x-www-form-urlencoded ומצוין בגוף הבקשה) |
נוכחות: |
אופציונלי |
סוג: | מחרוזת |
ערכים חוקיים: | כל משתנה זרימה שאפשר לגשת אליו במדיניות בזמן הריצה |
בשימוש עם סוגי המענק: |
|
הרכיב <רענןTokenexpirationIn>
<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>
המדיניות הזו אוכפת את זמן התפוגה של אסימוני הרענון באלפיות השנייה. ערך זמן התפוגה הוא ערך שנוצר על ידי המערכת בתוספת הערך <RefreshTokenExpiresIn>
. אם המדיניות
<RefreshTokenExpiresIn>
מוגדרת לערך -1, התוקף של אסימון הרענון יפוג בהתאם לתפוגה המקסימלית של אסימון הרענון של OAuth. אם לא מציינים את <RefreshTokenExpiresIn>
,
כברירת מחדל אין תאריך תפוגה.
ניתן גם להגדיר את זמן התפוגה בזמן ריצה באמצעות ערך ברירת מחדל בתוך הקוד או באמצעות הפניה למשתנה זרימה. לדוגמה, אפשר לשמור ערך תפוגה של אסימון במפת ערכי מפתח, לאחזר אותו, להקצות אותו למשתנה ולהפנות אליו במדיניות. לדוגמה, kvm.oauth.expires_in
.
הבית הבא מציין משתנה זרימה וערך ברירת מחדל גם כן. שימו לב שערך משתנה הזרימה מקבל קדימות על פני ערך ברירת המחדל שצוין.
<RefreshTokenExpiresIn ref="kvm.oauth.expires_in"> 3600000 <!--default value in milliseconds--> </RefreshTokenExpiresIn>
ענן פרטי: ב-Edge להתקנה של ענן פרטי, ערך ברירת המחדל מוגדר על ידי הנכס conf_keymanagement_oauth_refresh_token_expiry_time_in_millis
.
כדי להגדיר את המאפיין הזה:
- פותחים את הקובץ
message-processor.properties
בעורך. אם הקובץ לא קיים, יוצרים אותו:vi /opt/apigee/customer/application/message-processor.properties
- מגדירים את הנכס באופן הרצוי:
conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000
- מוודאים שקובץ המאפיינים שייך למשתמש ה-API:
chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
- מפעילים מחדש את מעבד ההודעות.
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
ברירת מחדל: |
אם לא מציינים ערך, המערכת מחילה ערך ברירת מחדל שהוגדר ברמת המערכת. |
נוכחות: |
אופציונלי |
סוג: | מספר שלם |
ערכים חוקיים: |
|
בשימוש עם סוגי המענק: |
|
"refresh_token_expires_in" : "0"
.האלמנט <ResponseType>
<ResponseType>request.queryparam.response_type</ResponseType>
הרכיב הזה מודיע ל-Edge איזה סוג הרשאה אפליקציית הלקוח מבקשת. הוא משמש רק עם קוד ההרשאה ותהליכי סוג המענק המשתמע.
כברירת מחדל, Edge מחפש את הערך של סוג התגובה בפרמטר של
response_type
. אם רוצים לשנות את התנהגות ברירת המחדל הזו, משתמשים ברכיב <ResponseType> כדי להגדיר משתנה זרימה שמכיל את הערך של סוג התגובה. לדוגמה, אם מגדירים את הרכיב הזה כ-request.header.response_type
, המערכת מחפשת את סוג התגובה שיועבר בכותרת הבקשה. למידע נוסף, ראו בקשת אסימוני גישה וקודי הרשאה.
ברירת מחדל: |
request.formparam.response_type (מחרוזת x-www-form-urlencoded ומצוינת בגוף הבקשה) |
נוכחות: |
אפשרות. משתמשים ברכיב הזה אם רוצים לשנות את התנהגות ברירת המחדל. |
סוג: | מחרוזת |
ערכים חוקיים: | code (לסוג ההרשאה של קוד ההרשאה) או token
(לסוג ההרשאה המשתמעת) |
בשימוש עם סוגי המענק: |
|
רכיב <ReuseרענןToken>
<ReuseRefreshToken>true</ReuseRefreshToken>
אם היא מוגדרת כ-true
, ייעשה שימוש חוזר באסימון הרענון הקיים עד שתוקפו יפוג. אם
false
, אסימון רענון חדש יונפק על ידי Apigee Edge כשמוצג אסימון רענון
חוקי.
ברירת מחדל: |
|
נוכחות: |
אופציונלי |
סוג: | boolean |
ערכים חוקיים: |
|
בשימוש יחד עם סוג המענק: |
|
רכיב <היקף>
<Scope>request.queryparam.scope</Scope>
אם הרכיב הזה נכלל באחד מכללי המדיניות GenerateAccessToken או GenerateAuthorizationCode, הוא ישמש לציון ההיקפים שצריך להקצות להם את האסימון או הקוד. הערכים האלה מועברים בדרך כלל למדיניות בבקשה מאפליקציית לקוח. אפשר להגדיר שהרכיב יקבל משתנה זרימה, כך שתהיה לך אפשרות לבחור איך ההיקפים יועברו בבקשה. בדוגמה הבאה, request.queryparam.scope
מציין שההיקף צריך להיות כפרמטר של שאילתה, כמו למשל ?scope=READ
. כדי לדרוש את ההיקף בכותרת HTTP, למשל, מגדירים את הערך הזה ל-request.header.scope
.
אם הרכיב הזה מופיע במדיניות VerifyAccessToken, הוא משמש לציון ההיקפים שהמדיניות צריכה לאכוף. במדיניות מהסוג הזה, הערך חייב להיות שם היקף "בקוד קשיח" – לא ניתן להשתמש במשתנים. לדוגמה:
<Scope>A B</Scope>
למידע נוסף, ראו עבודה עם היקפי הרשאות OAuth2 ובקשת אסימוני גישה וקודי הרשאה.
ברירת מחדל: |
אין היקף |
נוכחות: |
אופציונלי |
סוג: | מחרוזת |
ערכים חוקיים: |
אם משתמשים בו במדיניות Generate*, משתנה הזרימה. אם נעשה בה שימוש עם ValidAccessToken, רשימה מופרדת ברווחים של שמות היקפים (מחרוזות). |
בשימוש עם סוגי המענק: |
|
רכיב <State>
<State>request.queryparam.state</State>
במקרים שבהם אפליקציית הלקוח צריכה לשלוח את פרטי המצב לשרת ההרשאות, הרכיב הזה מאפשר לציין איפה אפליקציית Edge יחפש את ערכי המצב. לדוגמה, אפשר לשלוח אותו כפרמטר של שאילתה או בכותרת HTTP. ערך המצב של המדיניות משמש בדרך כלל כאמצעי אבטחה למניעת התקפות CSRF.
לדוגמה, המדיניות request.queryparam.state
מציינת שהמצב צריך להיות
כפרמטר של שאילתה, כמו, למשל, ?state=HjoiuKJH32
. כדי לדרוש
את המצב בכותרת HTTP, לדוגמה, מגדירים את הערך
כ-request.header.state
. למידע נוסף, ראו בקשת אסימוני גישה וקודי הרשאה.
ברירת מחדל: |
אין מדינה |
נוכחות: |
אופציונלי |
סוג: | מחרוזת |
ערכים חוקיים: | כל משתנה זרימה שאפשר לגשת אליו מהמדיניות בזמן ריצה |
בשימוש עם סוגי המענק: |
|
רכיב <StoreToken>
<StoreToken>true</StoreToken>
מגדירים את הרכיב הזה כ-true
כשהרכיב <ExternalAuthorization>
הוא true
. הרכיב <StoreToken>
מורה ל-Apigee Edge
לאחסן את אסימון הגישה החיצוני. אחרת, הערך לא יישמר.
ברירת מחדל: |
false |
נוכחות: |
אופציונלי |
סוג: | בוליאני |
ערכים חוקיים: | נכון או לא נכון |
בשימוש עם סוגי המענק: |
|
אלמנט <SupportedGrantTypes>/<GrantType> .
<SupportedGrantTypes> <GrantType>authorization_code</GrantType> <GrantType>client_credentials</GrantType> <GrantType>implicit</GrantType> <GrantType>password</GrantType> </SupportedGrantTypes>
ההגדרה קובעת את סוגי ההרשאות שנתמכים על ידי נקודת קצה של אסימון OAuth ב-Apigee Edge. נקודת קצה עשויה
לתמוך במספר סוגי הרשאות (כלומר, אפשר להגדיר נקודת קצה אחת לחלק את אסימוני הגישה
לכמה סוגי הרשאות). מידע נוסף על נקודות קצה (endpoint) זמין במאמר הסבר על נקודות קצה של OAuth. סוג המענק מועבר בבקשות לאסימונים בפרמטר grant_type
.
אם לא צוינו סוגי מענקים נתמכים, סוגי המענק היחידים המותרים הם
authorization_code
ו-implicit
. אפשר לעיין גם ברכיב <GrantType> (זהו רכיב ברמה גבוהה יותר שמשמש לציון
המקומות שבהם Apigee Edge צריך לחפש את הפרמטר grant_type
שמועבר בבקשת לקוח. Edge יוודא שהערך של הפרמטר grant_type
תואם לאחד מסוגי המענק הנתמכים).
ברירת מחדל: |
הרשאה _code ו-משתמע |
נוכחות: |
חובה |
סוג: | מחרוזת |
ערכים חוקיים: |
|
רכיב <Tokens>/<Token>
משמש יחד עם פעולות VerifyToken ו-InvalidateToken. למידע נוסף, ראו אישור וביטול של אסימוני גישה. הרכיב <Token> מזהה את משתנה הזרימה שמגדיר את
מקור האסימון שיש לבטל. אם המפתחים צפויים לשלוח אסימוני גישה בתור פרמטרים של שאילתות בשם access_token
, לדוגמה, צריך להשתמש ב-request.queryparam.access_token
.
רכיב <UserName>
<UserName>request.queryparam.user_name</UserName>
הרכיב הזה משמש רק עבור סוג מתן הסיסמה. בהתאם לסוג מתן הסיסמה, פרטי הכניסה של המשתמש (סיסמה ושם משתמש) חייבים להיות זמינים למדיניות OAuthV2. הרכיבים <PassWord>
ו-<UserName>
משמשים לציון משתנים שבהם Edge תוכל למצוא את הערכים האלה. אם הרכיבים האלה לא צוינו,
המדיניות מצפה למצוא את הערכים (כברירת מחדל) בפרמטרים של טופס שנקראים username
ו-password
. אם הערכים לא יימצאו, המדיניות תציג הודעת שגיאה. אפשר להשתמש ברכיבים <PassWord>
ו-<UserName>
כדי להפנות לכל משתנה זרימה שמכיל את פרטי הכניסה.
לדוגמה, ניתן להעביר את שם המשתמש בפרמטר של שאילתה ולהגדיר את הרכיב <UserName>
באופן הבא: <UserName>request.queryparam.username</UserName>
.
כדי לדרוש את שם המשתמש בכותרת HTTP, מגדירים את הערך הזה כ-request.header.username
.
מדיניות OAuthV2 לא עושה שום דבר נוסף עם הערכים האלה של פרטי הכניסה. Edge רק מאמתת שהם קיימים. מפתח ה-API יכול לאחזר את בקשת הערכים ולשלוח אותם לספק הזהויות לפני החלת המדיניות ליצירת אסימון.
למידע נוסף, ראו בקשת אסימוני גישה וקודי הרשאה.
ברירת מחדל: |
request.formparam.username (כתובת x-www-form-urlencoded ומצוינת בגוף הבקשה) |
נוכחות: |
אופציונלי |
סוג: | מחרוזת |
ערכים חוקיים: | כל הגדרה של משתנה. |
בשימוש עם סוגי המענק: | סיסמה |
אימות של אסימוני גישה
אחרי שמגדירים נקודת קצה של אסימון לשרת proxy ל-API, מדיניות OAuthV2 תואמת
שמציינת שהפעולה VerifyAccessToken
תצורף ל-flow שחושף את
המשאב המוגן.
לדוגמה, כדי להבטיח שכל הבקשות ל-API יאושרו, המדיניות הבאה אוכפת אימות של אסימון גישה:
<OAuthV2 name="VerifyOAuthAccessToken"> <Operation>VerifyAccessToken</Operation> </OAuthV2>
המדיניות מצורפת למשאב ה-API המוגן. כדי לוודא שכל הבקשות ל-API מאומתות, מצרפים את המדיניות ל-PreFlow של בקשת ProxyEndpoint באופן הבא:
<PreFlow> <Request> <Step><Name>VerifyOAuthAccessToken</Name></Step> </Request> </PreFlow>
ניתן להשתמש ברכיבים האופציונליים הבאים כדי לשנות את הגדרות ברירת המחדל של הפעולה ValidAccessToken.
שם | תיאור |
---|---|
היקף |
רשימת היקפים מופרדת ברווחים. האימות יצליח אם לפחות אחד מהיקפי ההרשאות המפורטים קיים באסימון הגישה. לדוגמה, במדיניות הבאה תתבצע בדיקה של אסימון הגישה כדי לוודא שהוא מכיל לפחות אחד מההיקפים המפורטים. אם הערכים READ או WRITE נמצאים, האימות יצליח. <OAuthV2 name="ValidateOauthScopePolicy"> <Operation>VerifyAccessToken</Operation> <Scope>READ WRITE</Scope> </OAuthV2> |
AccessToken | המשתנה שבו צפוי להיות אסימון הגישה. לדוגמה
request.queryparam.accesstoken . כברירת מחדל, אסימון הגישה צפוי
להיות מוצג על ידי האפליקציה בכותרת Authorization HTTP, בהתאם למפרט OAuth 2.0. צריך להשתמש בהגדרה הזו אם אסימון הגישה צפוי להיות מוצג במיקום לא סטנדרטי, כמו
פרמטר של שאילתה או כותרת HTTP עם שם שהוא לא Authorization. |
למידע נוסף, ראו אימות אסימוני גישה ובקשת אסימוני גישה וקודי הרשאה.
ציון מיקומים של משתני בקשה
לגבי כל סוג הרשאה, המדיניות מניחה הנחות לגבי המיקום או המידע הנדרש בהודעות הבקשה. ההנחות האלה מבוססות על המפרט של OAuth 2.0. אם האפליקציות שלך צריכות לסטות ממפרט OAuth 2.0, אפשר לציין את המיקומים הצפויים לכל פרמטר. לדוגמה, בעת טיפול בקוד הרשאה, ניתן לציין את המיקום של קוד ההרשאה, את מזהה הלקוח, את ה-URI להפניה אוטומטית ואת ההיקף. אפשר לציין אותם ככותרות HTTP, כפרמטרים של שאילתות או כפרמטרים של טפסים.
הדוגמה הבאה ממחישה איך לציין את המיקום של הפרמטרים הנדרשים של קוד ההרשאה ככותרות HTTP:
... <GrantType>request.header.grant_type</GrantType> <Code>request.header.code</Code> <ClientId>request.header.client_id</ClientId> <RedirectUri>request.header.redirect_uri</RedirectUri> <Scope>request.header.scope</Scope> ...
לחלופין, אם יש צורך לתמוך בבסיס אפליקציות הלקוח, אפשר לשלב בין כותרות ופרמטרים של שאילתות:
... <GrantType>request.header.grant_type</GrantType> <Code>request.header.code</Code> <ClientId>request.queryparam.client_id</ClientId> <RedirectUri>request.queryparam.redirect_uri</RedirectUri> <Scope>request.queryparam.scope</Scope> ...
ניתן להגדיר מיקום אחד בלבד לכל פרמטר.
משתני זרימה
משתני הזרימה שמוגדרים בטבלה הזו מאוכלסים כשמדיניות ה-OAuth המתאימה מיושמת, ולכן הם זמינים לאפליקציות או לכללי מדיניות אחרים שמופעלים בתהליך של שרת ה-API של שרת ה-API.
פעולת verificationAccessToken
הפעולה verificationAccessToken מתבצעת, מספר גדול של משתני זרימה מאוכלסים בהקשר של הביצוע של שרת ה-proxy. המשתנים האלה מספקים מאפיינים שקשורים לאסימון הגישה, לאפליקציית המפתח, למפתח ולחברה. אפשר להשתמש במדיניות הקצאה או מדיניות JavaScript, לדוגמה, כדי לקרוא כל אחד מהמשתנים האלה ולהשתמש בהם לפי הצורך בהמשך הזרימה. המשתנים האלה יכולים לשמש גם למטרות ניפוי באגים.
proxy.pathsuffix
). אין צורך להגדיר במפורש את המשתנהflow.resource.name.
אם מוצרי ה-API לא מוגדרים עם סביבות חוקיות ושרתי proxy של API, צריך להגדיר במפורש את flow.resource.name
לאכלוס משתני מוצר של API בתהליך
ה-API. פרטים נוספים על הגדרת המוצרים זמינים במאמר שימוש ב-Edge Management API לפרסום ממשקי API.
משתנים ספציפיים לאסימון
משתנים | תיאור |
---|---|
organization_name |
שם הארגון שבו פועל שרת ה-proxy. |
developer.id |
המזהה של המפתח שמשויך לאפליקציית הלקוח הרשומה. |
developer.app.name |
שם המפתח שמשויך לאפליקציית הלקוח הרשומה. |
client_id |
מזהה הלקוח של אפליקציית הלקוח הרשומה. |
grant_type |
סוג המענק המשויך לבקשה. |
token_type |
סוג האסימון המשויך לבקשה. |
access_token |
אסימון הגישה שנמצא בתהליך אימות. |
accesstoken.{custom_attribute} |
מאפיין מותאם אישית בעל שם באסימון הגישה. |
issued_at |
התאריך שבו הונפק אסימון הגישה, מבוטא בזמן מערכת Unix, באלפיות השנייה. |
expires_in |
מועד התפוגה של אסימון הגישה. מבוטאת בשניות. על אף שהרכיב ExpiresIn
מגדיר את התפוגה באלפיות שנייה, בתגובת האסימון ובמשתני הזרימה, הערך מתנגן בשניות. |
status |
הסטטוס של אסימון הגישה (למשל, מאושר או בוטל). |
scope |
ההיקף (אם יש) שמשויך לאסימון הגישה. |
apiproduct.<custom_attribute_name> |
מאפיין מותאם אישית בעל שם של מוצר ה-API שמשויך לאפליקציית הלקוח הרשומה. |
apiproduct.name |
השם של מוצר ה-API שמשויך לאפליקציית הלקוח הרשומה. |
revoke_reason |
(Apigee hybrid בלבד) מציין מדוע אסימון הגישה בוטל. הערך יכול להיות |
משתנים ספציפיים לאפליקציה
המשתנים האלה קשורים לאפליקציה למפתחים שמשויכת לאסימון.
משתנים | תיאור |
---|---|
app.name |
|
app.id |
|
app.accessType |
|
app.callbackUrl |
|
app.status |
אושרה או בוטלה |
app.scopes |
|
app.appFamily |
|
app.apiproducts |
|
app.appParentStatus |
|
app.appType |
לדוגמה: מפתח |
app.appParentId |
|
app.created_by |
|
app.created_at |
|
app.last_modified_at |
|
app.last_modified_by |
|
app.{custom_attributes} |
מאפיין מותאם אישית בעל שם של אפליקציית הלקוח הרשומה. |
משתנים ספציפיים למפתחים
אם הערך של app.appType הוא "חברה", מאפייני החברה יאוכלסו ואם app.appType הוא "מפתח", מאפייני המפתח יאוכלסו.
משתנים | תיאור |
---|---|
משתנים ספציפיים למפתחים | |
developer.id |
|
developer.userName |
|
developer.firstName |
|
developer.lastName |
|
developer.email |
|
developer.status |
פעיל או לא פעיל |
developer.apps |
|
developer.created_by |
|
developer.created_at |
|
developer.last_modified_at |
|
developer.last_modified_by |
|
developer.{custom_attributes} |
מאפיין מותאם אישית בעל שם של המפתח. |
משתנים ספציפיים לחברה
אם הערך של app.appType הוא "חברה", מאפייני החברה יאוכלסו ואם app.appType הוא "מפתח", מאפייני המפתח יאוכלסו.
משתנים | תיאור |
---|---|
company.id |
|
company.displayName |
|
company.apps |
|
company.appOwnerStatus |
|
company.created_by |
|
company.created_at |
|
company.last_modified_at |
|
company.last_modified_by |
|
company.{custom_attributes} |
מאפיין מותאם אישית בעל שם של החברה. |
הפעולה GenerateAuthorizationCode
המשתנים האלה מוגדרים כשהפעולה GenerateAuthorizationCode מתבצעת בהצלחה:
קידומת: oauthv2authcode.{policy_name}.{variable_name}
לדוגמה: oauthv2authcode.GenerateCodePolicy.code
משתנה | תיאור |
---|---|
code |
קוד ההרשאה שנוצר כשהמדיניות מופעלת. |
redirect_uri |
כתובת ה-URI של ההפניה האוטומטית המשויכת לאפליקציית הלקוח הרשומה. |
scope |
היקף ה-OAuth האופציונלי שהועבר בבקשת הלקוח. |
client_id |
מזהה הלקוח שהועבר בבקשת הלקוח. |
פעולות GenerateAccessToken ו-רענןAccessToken
המשתנים האלה מוגדרים כשהפעולות GenerateAccessToken ו-רענןAccessToken יבוצעו בהצלחה. חשוב לזכור שהמשתנים של אסימון הרענון לא חלים על התהליך של סוג המענק של פרטי הכניסה של הלקוח.
קידומת: oauthv2accesstoken.{policy_name}.{variable_name}
לדוגמה: oauthv2accesstoken.GenerateTokenPolicy.access_token
שם משתנה | תיאור |
---|---|
access_token |
אסימון הגישה שנוצר. |
client_id |
מזהה הלקוח של אפליקציית הפיתוח שמשויכת לאסימון הזה. |
expires_in |
ערך התפוגה של האסימון. לפרטים נוספים, אפשר לעיין ברכיב <ExpiresIn>. חשוב לשים לב שהתשובה, expires_in מבוטאת בשניות. |
scope |
רשימה של היקפים זמינים שהוגדרו לאסימון. למידע נוסף, ניתן לעיין בעבודה עם היקפי OAuth2. |
status |
approved או revoked . |
token_type |
מוגדר ל-BearerToken . |
developer.email |
כתובת האימייל של המפתח הרשום שבבעלותו אפליקציית המפתח המשויכת לאסימון. |
organization_name |
הארגון שבו מופעל שרת ה-proxy. |
api_product_list |
רשימת המוצרים שמשויכים לאפליקציית הפיתוח התואמת לאסימון. |
refresh_count |
|
refresh_token |
אסימון הרענון שנוצר. חשוב לשים לב שאסימוני רענון לא נוצרים לסוג המענק של פרטי הכניסה של הלקוח. |
refresh_token_expires_in |
משך החיים של אסימון הרענון, בשניות. |
refresh_token_issued_at |
ערך הזמן הזה הוא ייצוג המחרוזת של הכמות התואמת של חותמת הזמן ב-32 ביט. לדוגמה, הביטוי 'Wed, 21 Aug 2013 19:16:47 UTC' תואם לערך של חותמת הזמן של 1377112607413. |
refresh_token_status |
approved או revoked . |
GenerateAccessTokenImplicitGrant
המשתנים האלה מוגדרים כשהפעולה GenerateAccessTokenImplicit מבוצעת בהצלחה במסגרת הזרימה של סוג המענק המשתמע.
קידומת: oauthv2accesstoken.{policy_name}.{variable_name}
לדוגמה: oauthv2accesstoken.RefreshTokenPolicy.access_token
משתנה | תיאור |
---|---|
oauthv2accesstoken.access_token |
אסימון הגישה שנוצר כשהמדיניות מופעלת. |
oauthv2accesstoken.{policy_name}.expires_in |
ערך התפוגה של האסימון, בשניות. לפרטים, אפשר לעיין ברכיב <ExpiresIn>. |
המשמעות של השגיאות
בקטע הזה מתוארים קודי התקלות והודעות השגיאה שמוחזרים, ומשתני השגיאה שמוגדרים על ידי Edge כשהמדיניות הזו גורמת לשגיאה. חשוב לדעת אם אתם מפתחים כללים לתיקון תקלות. מידע נוסף זמין במאמר מה צריך לדעת על שגיאות מדיניות ועל טיפול בפגמים.
שגיאות בזמן ריצה
השגיאות האלה יכולות להתרחש כשהמדיניות מופעלת.
קוד שגיאה | סטטוס HTTP | סיבה | השקה בשל פעולות |
---|---|---|---|
steps.oauth.v2.access_token_expired |
401 | פג התוקף של אסימון הגישה. |
VerifyAccessToken |
steps.oauth.v2.access_token_not_approved |
401 | אסימון הגישה בוטל. | VerifyAccessToken |
steps.oauth.v2.apiresource_doesnot_exist |
401 | המשאב המבוקש לא קיים אף אחד ממוצרי ה-API שמשויכים לאסימון הגישה. | VerifyAccessToken |
steps.oauth.v2.FailedToResolveAccessToken |
500 | המדיניות הצפויה למצוא אסימון גישה במשתנה שצוין
ברכיב <AccessToken> , אבל לא הייתה אפשרות לפענח את המשתנה. |
GenerateAccessToken |
steps.oauth.v2.FailedToResolveAuthorizationCode |
500 | המדיניות צפויה למצוא קוד הרשאה במשתנה שצוין
ברכיב <Code> , אבל לא ניתן לפענח את המשתנה. |
GenerateAuthorizationCode |
steps.oauth.v2.FailedToResolveClientId |
500 | המדיניות שצפויה למצוא את ה-Client-ID במשתנה שצוין
ברכיב <ClientId> , אבל לא הייתה אפשרות לפענח את המשתנה. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
steps.oauth.v2.FailedToResolveRefreshToken |
500 | המדיניות צפויה למצוא אסימון רענון במשתנה שצוין
ברכיב <RefreshToken> , אבל לא ניתן היה לפענח את המשתנה. |
RefreshAccessToken |
steps.oauth.v2.FailedToResolveToken |
500 | המדיניות הצפויה למצוא אסימון במשתנה שצוין
ברכיב <Tokens> , אבל לא הייתה אפשרות לפענח את המשתנה. |
VerifyToken |
steps.oauth.v2.InsufficientScope |
403 | לאסימון הגישה שמוצג בבקשה יש היקף שלא תואם להיקף שצוין במדיניות לאימות אסימון הגישה. למידע נוסף על היקפים, אפשר לעיין במאמר עבודה עם היקפי OAuth2. | VerifyAccessToken |
steps.oauth.v2.invalid_access_token |
401 | אסימון הגישה שנשלח מהלקוח לא תקין. | VerifyAccessToken |
steps.oauth.v2.invalid_client |
401 |
שם השגיאה הזה מוחזר כשהמאפיין הערה: מומלץ לשנות את התנאים הקיימים של כללי התקלה כדי לכלול גם את השם |
GenerateAccessToken רענוןAccessToken |
steps.oauth.v2.invalid_request |
400 | שם השגיאה הזה משמש לסוגים שונים של שגיאות, בדרך כלל לפרמטרים חסרים או שגויים שנשלחים בבקשה. אם המדיניות <GenerateResponse> מוגדרת לערך false , משתמשים במשתני השגיאה (שמתוארים בהמשך) כדי לאחזר פרטים על
השגיאה, כמו שם התקלה והסיבה. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
steps.oauth.v2.InvalidAccessToken |
401 | כותרת ההרשאה לא מכילה את המילה "נושא", שנדרשת. לדוגמה: Authorization: Bearer your_access_token |
VerifyAccessToken |
steps.oauth.v2.InvalidAPICallAsNo\ |
401 |
שרת ה-proxy של ה-API לא נמצא במוצר המשויך לאסימון הגישה. טיפים: כדאי לוודא שהמוצר שמשויך לאסימון הגישה מוגדר בצורה נכונה. לדוגמה, אם משתמשים בתווים כלליים לחיפוש בנתיבי משאבים, חשוב לוודא שנעשה שימוש נכון בתווים הכלליים לחיפוש. פרטים נוספים זמינים במאמר יצירת מוצרים של API. מידע נוסף על הסיבות לשגיאה הזו זמין גם בפוסט הזה בקהילת Apigee. |
VerifyAccessToken |
steps.oauth.v2.InvalidClientIdentifier |
500 |
שם השגיאה הזה מוחזר כשהמאפיין |
GenerateAccessToken |
steps.oauth.v2.InvalidParameter |
500 | המדיניות חייבת לציין אסימון גישה או קוד הרשאה, אבל לא את שניהם. | GenerateAuthorizationCode GenerateAccessTokenImplicitGrant |
steps.oauth.v2.InvalidTokenType |
500 | הרכיב <Tokens>/<Token> מחייב לציין את סוג האסימון (לדוגמה, refreshtoken ). אם הלקוח מעביר את הסוג הלא נכון, המערכת מוסיפה את השגיאה. |
VerifyToken InvalidateToken |
steps.oauth.v2.MissingParameter |
500 | סוג התגובה הוא token , אבל לא צוינו סוגי הרשאות. |
GenerateAuthorizationCode GenerateAccessTokenImplicitGrant |
steps.oauth.v2.UnSupportedGrantType |
500 |
הלקוח ציין סוג מענק שלא נתמך במדיניות (לא רשום ברכיב <SupportedGrantTypes>). הערה: כרגע יש באג שגרם לכך ששגיאות מסוג מענק שלא נתמכות לא יזוזו בצורה נכונה. אם מתרחשת שגיאה מסוג הרשאה שאינו נתמך, שרת ה-proxy לא נכנס לתהליך השגיאה, כצפוי. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
שגיאות בפריסה
השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שכולל את המדיניות הזו.
שם השגיאה | סיבה |
---|---|
InvalidValueForExpiresIn |
לרכיב |
InvalidValueForRefreshTokenExpiresIn |
לרכיב <RefreshTokenExpiresIn> , הערכים החוקיים הם מספרים שלמים חיוביים ו--1 . |
InvalidGrantType |
סוג מענק לא חוקי צוין ברכיב <SupportedGrantTypes> . רשימת הסוגים התקינים זמינה בחומר העזר בנושא מדיניות. |
ExpiresInNotApplicableForOperation |
חשוב לוודא שתוקף הפעולות שצוינו במשתנה <Operations> יפוג. לדוגמה, הפעולהVerifyToken לא עושה זאת. |
RefreshTokenExpiresInNotApplicableForOperation |
חשוב לוודא שהפעולות שצוינו באלמנט <Operations> תומכות באסימון הרענון. לדוגמה, הפעולהVerifyToken לא עושה זאת. |
GrantTypesNotApplicableForOperation |
חשוב לוודא שסוגי ההרשאות שצוינו בערך <SupportedGrantTypes> נתמכים בפעולה שצוינה. |
OperationRequired |
צריך לציין פעולה במדיניות הזו באמצעות הרכיב הערה: אם הרכיב |
InvalidOperation |
צריך לציין פעולה חוקית במדיניות הזו באמצעות הרכיב הערה: אם הרכיב |
TokenValueRequired |
צריך לציין ערך של אסימון <Token> ברכיב <Tokens> . |
משתני שבר
המשתנים האלה מוגדרים כשהמדיניות הזו גורמת לשגיאה בזמן הריצה.
<GenerateResponse>
מוגדר הערך false
. אם הערך של <GenerateResponse>
הוא
true
, המדיניות מחזירה תשובה ללקוח באופן מיידי אם מתרחשת שגיאה –
המערכת מדלגת על תהליך השגיאה והמשתנים האלה לא מאוכלסים. אפשר לקרוא מידע נוסף במאמר מה צריך לדעת על שגיאות מדיניות.משתנים | מיקום | דוגמה |
---|---|---|
fault.name="fault_name" |
fault_name הוא שם התקלה, כפי שמפורט בטבלה שגיאות זמן ריצה שלמעלה. שם הטעות הוא החלק האחרון בקוד השגיאה. | fault.name = "invalid_request" |
oauthV2.policy_name.failed |
policy_name הוא השם שצוין על ידי המשתמש של המדיניות שגרמה לשגיאה. | oauthV2.GenerateAccesstoken.failed = true |
oauthV2.policy_name.fault.name |
policy_name הוא השם שצוין על ידי המשתמש של המדיניות שגרמה לשגיאה. | oauthV2.GenerateAccesstoken.fault.name = invalid_request
הערה: בפעולה ValidAccessToken, שם הכשל כולל את הסיומת הזו: |
oauthV2.policy_name.fault.cause |
policy_name הוא השם שצוין על ידי המשתמש של המדיניות שגרמה לשגיאה. | oauthV2.GenerateAccesstoken.cause = Required param : grant_type |
דוגמה לשגיאה
התשובות האלה נשלחות בחזרה ללקוח אם הרכיב <GenerateResponse>
הוא true.
errorcode
של תגובת השגיאה. אין להסתמך על הטקסט שבfaultstring
, כי הוא עשוי להשתנות.אם הערך של <GenerateResponse>
הוא true, המדיניות תחזיר שגיאות
בפורמט הזה לפעולות שיוצרות אסימונים וקודים. הרשימה המלאה מפורטת במאמר ההפניה לתגובת שגיאות HTTP של OAuth.
{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}
אם הערך של <GenerateResponse>
הוא true, המדיניות תחזיר שגיאות
בפורמט הזה לפעולות אימות ואימות. הרשימה המלאה מפורטת במאמר הפנייה לתגובת שגיאות HTTP של OAuth.
{ { "fault":{ "faultstring":"Invalid Access Token", "detail":{ "errorcode":"keymanagement.service.invalid_access_token" } } }
דוגמה לכלל שגיאה
<FaultRule name=OAuthV2 Faults"> <Step> <Name>AM-InvalidClientResponse</Name> <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition> </Step> <Step> <Name>AM-InvalidTokenResponse</Name> <Condition>(fault.name = "invalid_access_token")</Condition> </Step> <Condition>(oauthV2.failed = true) </Condition> </FaultRule>
סכימת מדיניות
כל סוג מדיניות מוגדר על ידי סכימת XML (.xsd
). לידיעתך, סכימות המדיניות זמינות ב-GitHub.
עבודה עם הגדרת ברירת המחדל של OAuth
כל ארגון (גם ארגון לתקופת ניסיון בחינם) ב-Apigee Edge מקבל נקודת קצה (endpoint) של אסימון OAuth. נקודת הקצה מוגדרת מראש עם כללי מדיניות בשרת ה-API שנקראים oauth. אפשר להתחיל להשתמש בנקודת הקצה של האסימון מיד אחרי יצירת חשבון ב-Apigee Edge. לפרטים נוספים אפשר לעיין במאמר הסבר על נקודות קצה של OAuth.
מחיקה של אסימוני גישה
כברירת מחדל, אסימוני OAuth2 נמחקים באופן סופי ממערכת Apigee Edge 3 ימים (259,200 שניות) אחרי שהתוקף של אסימון הגישה ואסימון הרענון (אם קיים) פג. במקרים מסוימים, כדאי לשנות את ברירת המחדל. לדוגמה, יכול להיות שכדאי לקצר את זמן המחיקה כדי לחסוך מקום בכונן אם נוצרים מספר גדול של אסימונים.
אם אתם משתמשים ב-Edge for Private Cloud, תוכלו לשנות את ברירת המחדל על ידי הגדרה של מאפייני הארגון, כמו שמוסבר בסעיף הזה. (מחיקה למשך 3 ימים של אסימונים שפג תוקפם רלוונטית ל-Edge for Private Cloud בגרסה 4.19.01 ואילך. בגרסאות קודמות, מרווח הזמן למחיקה שמוגדר כברירת מחדל הוא 180 יום.)
עדכון הגדרות המחיקה לצמיתות של גרסת Edge Private Cloud 4.16.01 ואילך
הערה: רק אסימונים שנוצרו אחרי יישום ההגדרות האלה יושפעו. ההגדרות לא חלות על אסימונים שנוצרו קודם לכן.
- יש לפתוח את הקובץ הזה כדי לערוך אותו:
/opt/apigee/customer/application/message-processor.properties
- צריך להוסיף את המאפיין הבא כדי להגדיר את מספר השניות להמתנה לפני מחיקה לצמיתות של אסימון
אחרי שתוקפו יפוג:
conf_keymanagement_oauth.access.token.purge.after.seconds=<number of seconds>
- מפעילים מחדש את המעבד של ההודעות. לדוגמה:
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
<ExpiresIn>
ו-<RefreshTokenExpiresIn>
.
עדכון הגדרות המחיקה לצמיתות של Edge Private Cloud 4.15.07
הערה: רק אסימונים שנוצרו אחרי החלת ההגדרות האלה יושפעו. ההגדרות לא חלות על אסימונים שנוצרו קודם לכן.
-
צריך להגדיר ערכים חיוביים למאפיינים
<ExpiresIn>
ו-<RefreshTokenExpiresIn>
במדיניות OAuthV2. הערכים נמצאים באלפיות השנייה. לדוגמה:<ExpiresIn>1000</ExpiresIn> <RefreshTokenExpiresIn>10000</RefreshTokenExpiresIn>
-
פורסים מחדש את שרת ה-proxy.
-
צריך להשתמש ב-API הזה כדי לעדכן את מאפייני המחיקה של אסימון עבור הארגון:
POST https://<host-name>/v1/organizations/<org-name>
מטען ייעודי (payload):
<Organization name="AutomationOrganization"> <Description>Desc</Description> <Properties> <Property name="keymanagement.oauth20.access.token.purge">true</Property> <Property name="keymanagement.oauth20.access.token.purge.after.seconds">120</Property> </Properties> </Organization>
-
מפעילים מחדש את המעבד של ההודעות. לדוגמה:
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
ה-API הזה מגדיר את מאפיין המחיקה לצמיתות של אסימון כ-True עבור הארגון שנקרא AutomationOrganization. במקרה כזה, אסימון הגישה יימחק לצמיתות ממסד הנתונים 120 שניות אחרי שהתוקף של האסימון וגם של אסימון הרענון יפוג.
התנהגות שאינה תואמת RFC
מדיניות OAuthV2 מחזירה תגובת אסימון שמכילה מאפיינים מסוימים שאינם תואמים ל-RFC. בטבלה הבאה מוצגים הנכסים שלא תואמים למדיניות, שהוחזרו על-ידי מדיניות OAuthV2, והמאפיינים התואמים התואמים.
OAuthV2 מחזיר: | המאפיין התואם ל-RFC הוא: |
---|---|
"token_type":"BearerToken" |
"token_type":"Bearer"
|
"expires_in":"3600" |
"expires_in":3600
(הערך התואם הוא מספר, לא מחרוזת). |
בנוסף, תגובת השגיאה של אסימון רענון שתוקפו פג כאשר grant_type = refresh_token
היא:
{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}
עם זאת, התגובה התואמת ל-RFC תהיה:
{"error" : "invalid_grant", "error_description" :"refresh token expired"}