אתה צופה בתיעוד של Apigee Edge.
הצג תיעוד של Apigee X.

מה
OAuthV2 היא מדיניות שכוללת מגוון היבטים לפעולות של מתן רישיונות OAuth 2.0. זוהי המדיניות הראשית שמשמשת להגדרת נקודות קצה ב-OAuth 2.0 ב-Apigee Edge.
טיפ: מידע נוסף על OAuth ב-Apigee Edge זמין בדף הבית של OAuth. הוא מספק קישורים למשאבים, לדוגמאות, לסרטונים ועוד. מומלץ לעיין בדוגמה המתקדמת ל-OAuth ב-GitHub כדי לראות הדגמה של השימוש במדיניות הזו באפליקציה פעילה.
דוגמאות
אימותAccessToken
אימותAccessToken
תצורת המדיניות הזו של OAuthV2 (עם הפעולה ValidAccessToken) מאמתת שאסימון הגישה שנשלח אל 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>
.
CreateAccessToken
יצירת אסימוני גישה
במאמר בקשת אסימוני גישה וקודי הרשאות מוסבר איך לבקש אסימוני גישה לכל אחד מסוגי המענקים הנתמכים. הנושא כולל דוגמאות לפעולות הבאות:
קוד יצירה
יצירת קוד הרשאה
במאמר בקשת קוד הרשאה מוסבר איך לבקש קודי הרשאה.
רענון AccessToken
רענון של אסימון גישה
במאמר רענון אסימון גישה מוסבר איך לבקש אסימוני גישה.
אסימון תהליך התגובה
יצירת אסימון גישה בתהליך התגובה
לפעמים צריך ליצור אסימון גישה בתהליך התגובה. לדוגמה, אפשר לעשות זאת בתגובה לאימות מותאם אישית שבוצע בשירות לקצה העורפי. בדוגמה הזו, לצורך שימוש לדוגמה נדרש אסימון גישה וגם אסימון רענון, וכך לקבוע את סוג ההענקת הרשאה משתמעת. במקרה כזה, נשתמש בסוג של הענקת סיסמה כדי ליצור את האסימון. כפי שניתן לראות, הטריק לעשות את העבודה הזו הוא להעביר כותרת של בקשת הרשאה עם מדיניות 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 שגיאה לא מורשית, למרות שהפרמטרים הנכונים של ההתחברות צוינו במדיניות. כדי לפתור את הבעיה, צריך להגדיר כותרת לבקשת הרשאה.
הכותרת 'Authorization' חייבת להכיל סכימת גישה בסיסית עם 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>
ברירת המחדל |
לא רלוונטי אם משמיטים את הרכיב הזה, המערכת תשתמש בערך שמוגדר במאפיין |
---|---|
נוכחות | אופציונלי |
Type | String |
רכיב <AccessToken>
<AccessToken>request.header.access_token</AccessToken>
כברירת מחדל, הכלי AccessAccessToken מצפה שיישלחו את אסימון הגישה בכותרת 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"
ברירת מחדל: |
לא רלוונטי |
נוכחות: |
אופציונלי |
סוג: | String |
הנתונים משמשים לביצוע פעולות: |
|
הרכיב <AccessTokenPrefix>
<AccessTokenPrefix>Bearer</AccessTokenPrefix>
כברירת מחדל, אסימון AccessAccessToken מצפה שיישלחו באסימון הגישה בכותרת ההרשאה כאסימון נושא. לדוגמה:
-H "Authorization: Bearer Rft3dqrs56Blirls56a"
בשלב הזה, הקידומת היחידה נתמכת ב-Bar.
ברירת מחדל: |
פרמטרים לרשת |
נוכחות: |
אופציונלי |
סוג: | String |
ערכים תקינים: |
פרמטרים לרשת |
הנתונים משמשים לביצוע פעולות: |
|
רכיב <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 לפי מזהה משתמש קצה, מזהה אפליקציה או שניהם.
ברירת מחדל: |
לא רלוונטי |
נוכחות: |
אופציונלי |
סוג: | String |
ערכים תקינים: |
כל משתנה זרימה הנגיש למדיניות בזמן ריצה. |
השימוש כולל סוגי מענקים: |
|
<מאפיינים/מאפיין>
<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 המלא של האסימון מוחזר בתגובה, כולל מאפיינים מותאמים אישית שהגדרתם. במקרים מסוימים, ייתכן שתרצו להסתיר חלק מהמאפיינים המותאמים אישית או את כולם בתשובה, כדי שהם לא יוצגו באפליקציות של הלקוח.
כברירת מחדל, מאפיינים מותאמים אישית מופיעים בתגובה. כדי להסתיר אותם, אפשר להגדיר את הפרמטר display ל-false. לדוגמה:
<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 בגוף הבקשה ) |
נוכחות: |
אופציונלי |
סוג: | String |
ערכים תקינים: | משתנה הזרימה: 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 בגוף הבקשה) |
נוכחות: |
אופציונלי |
סוג: | String |
ערכים תקינים: | כל משתנה זרימה הנגיש למדיניות בזמן ריצה |
השימוש כולל סוגי מענקים: | קוד הרשאה |
רכיב<ExpiresIn>
<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
- חשוב לוודא שקובץ הנכסים נמצא בבעלות המשתמש 'pigee':
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 |
נוכחות: |
אופציונלי |
סוג: | Boolean |
ערכים תקינים: | נכון או לא נכון |
השימוש כולל סוגי מענקים: |
|
רכיב <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 של צד שלישי.
רכיב <ExternalRefreshToken>
<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 של צד שלישי.
רכיב <CreateResponse>
<GenerateResponse enabled='true'/>
אם המדיניות מוגדרת כ-true
, המדיניות יוצרת ומחזירה תגובה. לדוגמה, עבור
CreateAccessToken, התגובה יכולה להיות:
{ "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 |
נוכחות: |
אופציונלי |
סוג: | מחרוזת |
ערכים תקינים: | נכון או לא נכון |
השימוש כולל סוגי מענקים: |
|
הרכיב <CreateErrorResponse>
<GenerateErrorResponse enabled='true'/>
אם המדיניות מוגדרת לערך true
, המדיניות תייצר ותחזיר תשובה אם
המאפיין OnOnError הוגדר כ-True. אם ברירת המחדל היא false
, לא תישלח תגובה. במקום זאת, קבוצה של משתני זרימה מאוכלסת בערכים שקשורים
לפונקציית המדיניות.
ברירת מחדל: |
false |
נוכחות: |
אופציונלי |
סוג: | מחרוזת |
ערכים תקינים: | נכון או לא נכון |
השימוש כולל סוגי מענקים: |
|
<סוג מענק>
<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 (a-x-www-form-urlencoded, כפי שצוין בגוף הבקשה) |
נוכחות: |
אופציונלי |
סוג: | מחרוזת |
ערכים תקינים: | משתנה, כפי שמוסבר למעלה. |
השימוש כולל סוגי מענקים: |
|
רכיב <Operation>
<Operation>GenerateAuthorizationCode</Operation>
פעולת OAuth 2.0 שהוגדרה על ידי המדיניות.
ברירת מחדל: |
אם לא מציינים את |
נוכחות: |
אופציונלי |
סוג: | String |
ערכים תקינים: |
|
רכיב <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, שצוינה בגוף הבקשה) |
נוכחות: |
אופציונלי |
סוג: | String |
ערכים תקינים: | כל משתנה זרימה הזמין למדיניות בזמן הריצה. |
השימוש כולל סוגי מענקים: | סיסמה |
רכיב <RedirectUri>
<RedirectUri>request.queryparam.redirect_uri</RedirectUri>
קביעת הערך שבו הפרמטר Edge צריך לחפש את הפרמטר redirect_uri
בבקשה.
מידע על מזהי URI של הפניה מחדש
נעשה שימוש במזהי URI של הפניה אוטומטית עם קוד ההרשאה וסוגי ההענקת גישה משתמעת. ה-URI של ההפניה אומר לשרת ההרשאות (Edge) לאן לשלוח את קוד ההרשאה (לסוג המענק של קוד האימות) או את אסימון הגישה (לסוג המענק המשתמע). חשוב להבין מתי הפרמטר הזה נדרש, מתי הוא אופציונלי ואיך משתמשים בו:
-
(חובה) אם כתובת ה-URL לקריאה חוזרת (callback) רשומה באפליקציה למפתחים שמשויכת למפתחות הלקוח של הבקשה, ואם השדה
redirect_uri
נמצא בבקשה, שתי הכתובות צריכות להיות זהות. אם הם לא תואמים, תוחזר שגיאה. מידע על רישום אפליקציות למפתחים ב-Edge וציון כתובת URL לקריאה חוזרת (callback) זמין במאמר רישום אפליקציות וניהול של מפתחות API. - (אופציונלי) אם רשומה כתובת URL לקריאה חוזרת (callback) וה
redirect_uri
חסר בבקשה, אז Edge מפנה לכתובת ה-URL החוזרת (callback). - (חובה) אם כתובת URL לקריאה חוזרת (callback) לא רשומה, חובה להזין
redirect_uri
. חשוב לציין שבמקרה הזה, Edge יקבל כל כתובת URL. מקרה כזה עלול לגרום לבעיית אבטחה, ולכן יש להשתמש בו רק באפליקציות מהימנות של לקוח. אם אפליקציות של לקוחות אינן מהימנות, השיטה המומלצת היא תמיד לדרוש רישום של כתובת URL לקריאה חוזרת (callback).
אפשר לשלוח את הפרמטר הזה בפרמטר שאילתה או בכותרת. המשתנה request.queryparam.redirect_uri
מציין שההפניה האוטומטית (URI) צריכה להופיע כפרמטר של שאילתה, למשל ?redirect_uri=login.myapp.com
. כדי לדרוש את ההפניה האוטומטית ל-HTTP בכותרת
HTTP, למשל, צריך להגדיר את הערך הזה כ-request.header.redirect_uri
. למידע נוסף, ראו בקשת אסימוני גישה וקודי הרשאות.
ברירת מחדל: |
request.formparam.redirect_uri (x-www-form-urlencoded and specified in the request ) |
נוכחות: |
אופציונלי |
סוג: | String |
ערכים תקינים: | כל משתנה זרימה שנגיש במדיניות בזמן ריצה |
השימוש כולל סוגי מענקים: |
בשימוש גם עם הפעולה GenerateAuthorizationCode. |
הרכיב <RefreshToken>
<RefreshToken>request.queryparam.refreshtoken</RefreshToken>
כשמבקשים אסימון גישה באמצעות אסימון רענון, צריך לספק בבקשה את אסימון הרענון. הרכיב הזה מאפשר לכם לציין היכן יש לחפש את אסימון הרענון ב-Edge. לדוגמה, ניתן לשלוח אותו כפרמטר של שאילתה, ככותרת HTTP או כפרמטר של טופס (ברירת המחדל).
המשתנה request.queryparam.refreshtoken
מציין שאסימון הרענון צריך להופיע כפרמטר של שאילתה, למשל ?refresh_token=login.myapp.com
. כדי לדרוש את ה-RefreshToken בכותרת ה-HTTP, למשל, צריך להגדיר את הערך הזה כ-request.header.refresh_token
. למידע נוסף, ראו בקשת אסימוני גישה וקודי הרשאות.
ברירת מחדל: |
request.formparam.refresh_token (x-www-form-urlencoded ומצוין בגוף הבקשה) |
נוכחות: |
אופציונלי |
סוג: | String |
ערכים תקינים: | כל משתנה זרימה שנגיש במדיניות בזמן ריצה |
השימוש כולל סוגי מענקים: |
|
הרכיב <RefreshTokenExpiresIn>
<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
- חשוב לוודא שקובץ הנכסים נמצא בבעלות המשתמש 'pigee':
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
, מערכת Edge מחפשת את סוג התגובה שמועבר בכותרת הבקשה. קראו גם את המאמר בקשת אסימוני גישה וקודי הרשאות.
ברירת מחדל: |
request.formparam.response_type (a מסוג x-www-form-urlencoded בגוף ההודעה ) |
נוכחות: |
אופציונלי. יש להשתמש ברכיב הזה כדי לבטל את התנהגות ברירת המחדל. |
סוג: | String |
ערכים תקינים: | code (לסוג האישור של קוד ההרשאה) או token
(לסוג המענק המשתמע) |
השימוש כולל סוגי מענקים: |
|
הרכיב <ReuseRefreshToken>
<ReuseRefreshToken>true</ReuseRefreshToken>
אם המדיניות מוגדרת לערך true
, נעשה שימוש חוזר באסימון הרענון הקיים עד שתוקפו יפוג. אם
false
, אסימון רענון חדש יונפק על ידי Apigee Edge כשיוצג אסימון רענון תקין.
ברירת מחדל: |
|
נוכחות: |
אופציונלי |
סוג: | בוליאני |
ערכים תקינים: |
|
נעשה שימוש בסוג המענק: |
|
רכיב <Scope>
<Scope>request.queryparam.scope</Scope>
אם הרכיב הזה נמצא באחד מכללי המדיניות GenerateAccessToken או GenerateAuthorizationCode, הוא משמש לציון ההיקפים שמעניקים את האסימון או הקוד. הערכים האלה בדרך כלל מועברים למדיניות בבקשה מאפליקציית לקוח. אפשר להגדיר את הרכיב כך שישתמש במשתנה זרימה, שיאפשר לך לבחור איך ההיקפים יועברו בבקשה. בדוגמה הבאה, request.queryparam.scope
מציין שההיקף צריך להופיע כפרמטר של שאילתה, למשל ?scope=READ
. כדי לדרוש את ההיקף בכותרת HTTP, צריך להגדיר את הערך הזה כ-request.header.scope
.
אם הרכיב הזה מופיע במדיניות 'VerifyAccessToken', הוא משמש לציון ההיקפים שהמדיניות צריכה לאכוף. בסוג המדיניות הזה, הערך חייב להיות שם היקף 'מקודד{/1}. לא ניתן להשתמש במשתנים. לדוגמה:
<Scope>A B</Scope>
עיינו גם במאמרים עבודה עם היקפי OAuth2 ובקשת אסימוני גישה וקודי הרשאות.
ברירת מחדל: |
אין היקף |
נוכחות: |
אופציונלי |
סוג: | String |
ערכים תקינים: |
אם אתם משתמשים באפשרות הזו, אתם יכולים להשתמש במשתנה 'זרימה'*. אם משתמשים בה עם הצוות AccessAccessToken, רשימה מופרדת של שמות היקפים (מחרוזות). |
השימוש כולל סוגי מענקים: |
|
רכיב <State>
<State>request.queryparam.state</State>
במקרים שבהם אפליקציית הלקוח חייבת לשלוח את פרטי המצב לשרת ההרשאות, האלמנט הזה מאפשר לציין איפה ב-Edge יש לחפש את ערכי המצב. לדוגמה, ניתן לשלוח אותו כפרמטר של שאילתה או ככותרת HTTP. לרוב, ערך המדינה משמש כאמצעי אבטחה כדי למנוע התקפות של CSRF.
לדוגמה: request.queryparam.state
צריך לציין שהמצב
צריך להופיע כפרמטר של שאילתה, למשל ?state=HjoiuKJH32
. כדי לדרוש את המצב בכותרת HTTP, למשל צריך להגדיר את הערך הזה כ-request.header.state
. עיינו גם בקטע בקשת אסימוני גישה וקודי הרשאות.
ברירת מחדל: |
ללא מדינה |
נוכחות: |
אופציונלי |
סוג: | String |
ערכים תקינים: | כל משתנה זרימה הנגיש למדיניות בזמן ריצה |
השימוש כולל סוגי מענקים: |
|
רכיב <StoreToken>
<StoreToken>true</StoreToken>
יש להגדיר את הרכיב הזה כ-true
כשהרכיב
<ExternalAuthorization>
הוא true
. הרכיב <StoreToken>
מבקש מ-Apigee Edge לאחסן את אסימון הגישה החיצוני. אחרת, הערך לא יימחק.
ברירת מחדל: |
false |
נוכחות: |
אופציונלי |
סוג: | Boolean |
ערכים תקינים: | נכון או לא נכון |
השימוש כולל סוגי מענקים: |
|
הרכיב <SupportgrantTypes>/<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 ומשתמע |
נוכחות: |
חובה |
סוג: | String |
ערכים תקינים: |
|
הרכיב <Tokens>/<Token>
בשימוש עם הפעולות VerifyToken ו-InverifyToken. למידע נוסף, ניתן לעיין במאמר אישור וביטול אסימוני גישה. הרכיב <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 בגוף הבקשה) |
נוכחות: |
אופציונלי |
סוג: | String |
ערכים תקינים: | כל הגדרת משתנה. |
השימוש כולל סוגי מענקים: | סיסמה |
אימות אסימוני גישה
לאחר הגדרת נקודת קצה לאסימון עבור שרת proxy ל-API, מדיניות OAuthV2 תואמת שמציינת את הפעולה VerifyAccessToken
מצורףת לזרימה שחושפת את המשאב המוגן.
לדוגמה, כדי לוודא שכל הבקשות ל-API מורשות, המדיניות הבאה אוכפת את האימות של אסימון הגישה:
<OAuthV2 name="VerifyOAuthAccessToken"> <Operation>VerifyAccessToken</Operation> </OAuthV2>
המדיניות מצורפת למשאב ה-API שצריך להגן עליו. כדי להבטיח שכל הבקשות ל-API מאומתות, יש לצרף את המדיניות לבקשת ProxyEnd של AdSense. כך עושים זאת:
<PreFlow> <Request> <Step><Name>VerifyOAuthAccessToken</Name></Step> </Request> </PreFlow>
אפשר להשתמש באלמנטים האופציונליים הבאים כדי לשנות את הגדרות ברירת המחדל של הפעולה VerifyAccessToken.
שם | תיאור |
---|---|
היקף |
רשימה של היקפים מופרדים ברווחים. האימות יושלם אם לפחות אחד מההיקפים הרשומים נמצאים באסימון הגישה. לדוגמה, המדיניות הבאה תבדוק את אסימון הגישה כדי לוודא שהוא מכיל לפחות אחד מההיקפים הרשומים. אם קריאה או כתיבה קיימות, האימות יצליח. <OAuthV2 name="ValidateOauthScopePolicy"> <Operation>VerifyAccessToken</Operation> <Scope>READ WRITE</Scope> </OAuthV2> |
אסימון גישה | המשתנה שבו נמצא אסימון הגישה. לדוגמה: request.queryparam.accesstoken . כברירת מחדל, אסימון הגישה צפוי להופיע באפליקציה בכותרת HTTP Authorization, בהתאם למפרט של 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 המתאימה מופעלת, ולכן הם זמינים לכללי מדיניות או לאפליקציות אחרים שפועלים בתהליך שרת ה-proxy של ה-API.
פעולת אימותAccessToken
הפעולה של AccessAccessToken מתבצעת. מספר רב של משתני זרימה מאוכלסים בהקשר של ההפעלה של שרת ה-proxy. המשתנים האלה נותנים לכם מאפיינים שקשורים לאסימון הגישה, לאפליקציה למפתחים, למפתח ולחברה. לדוגמה, אפשר להשתמש במדיניות AssignMessage או ב-JavaScript כדי לקרוא את המשתנים האלה ולהשתמש בהם לפי הצורך. המשתנים האלה יכולים להיות שימושיים גם למטרות ניפוי באגים.
proxy.pathsuffix
). אין צורך להגדיר באופן מפורש את משתנהflow.resource.name.
כאשר מוצרי ה-API לא מוגדרים עם סביבות חוקיות ושרתי proxy, צריך להגדיר את flow.resource.name
באופן מפורש כך שיאכלס משתני מוצרים של ה-API בתהליך. מידע נוסף על הגדרות המוצר זמין במאמר שימוש בממשק ה-API לניהול Edge לפרסום ממשקי 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 |
(היברידי ב-Apige בלבד) מציין למה בוטל אסימון הגישה. הערך יכול להיות |
משתנים ספציפיים לאפליקציה
המשתנים האלה קשורים לאפליקציה למפתחים שמשויכת לאסימון.
משתנים | תיאור |
---|---|
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} |
מאפיין מותאם אישית של החברה. |
פעולת AuthorizationAuthorizationCode
המשתנים האלה מוגדרים כשהפעולה CREATEAuthorizationCode מתבצעת בהצלחה:
קידומת: oauthv2authcode.{policy_name}.{variable_name}
דוגמה: oauthv2authcode.GenerateCodePolicy.code
משתנה | תיאור |
---|---|
code |
קוד ההרשאה שנוצר כשהמדיניות מופעלת. |
redirect_uri |
ה-URI של ההפניה המשויכת לאפליקציית הלקוח הרשומה. |
scope |
היקף ה-OAuth האופציונלי שהועבר בבקשת הלקוח. |
client_id |
מספר הלקוח שהועבר בבקשת הלקוח. |
פעולות CREATEAccessToken ו- RefreshAccessToken
המשתנים האלה מוגדרים כשפעולות GenerateAccessToken ו-RefreshAccessToken מתבצעות בהצלחה. חשוב לשים לב שמשתנים של אסימוני רענון לא חלים על תהליך מתן ההרשאה של הלקוח.
קידומת: oauthv2accesstoken.{policy_name}.{variable_name}
דוגמה: oauthv2accesstoken.GenerateTokenPolicy.access_token
שם משתנה | תיאור |
---|---|
access_token |
אסימון הגישה שנוצר. |
client_id |
מספר הלקוח של אפליקציית הפיתוח המשויכת לאסימון הזה. |
expires_in |
ערך התפוגה של האסימון. לפרטים נוספים, אפשר לעיין ברכיב <ExpiresIn>. שימו לב שבתגובה מתבטאת expires_in ב-seconds. |
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 ביט. לדוגמה, 'יום רביעי, 21 באוגוסט 2013 19:16:47 UTC' תואם לערך חותמת הזמן 1377112607413. |
refresh_token_status |
יש להזין את approved או את revoked . |
CreateAccessTokenImplicitgrant
המשתנים האלה מוגדרים כשהפעולה 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 | פג התוקף של אסימון הגישה. |
AccessAccessToken |
steps.oauth.v2.access_token_not_approved |
401 | אסימון הגישה בוטל. | אימותAccessToken |
steps.oauth.v2.apiresource_doesnot_exist |
401 | המשאב המבוקש לא קיים באף אחד ממוצרי ה-API שמשויכים לאסימון הגישה. | אימותAccessToken |
steps.oauth.v2.FailedToResolveAccessToken |
500 | המדיניות צפויה למצוא אסימון גישה במשתנה שצוין ברכיב <AccessToken> , אבל לא ניתן לפענח את המשתנה. |
CreateAccessToken |
steps.oauth.v2.FailedToResolveAuthorizationCode |
500 | המדיניות צפויה למצוא קוד הרשאה במשתנה שצוין ברכיב <Code> , אבל לא ניתן לפענח את המשתנה. |
קוד יצירה |
steps.oauth.v2.FailedToResolveClientId |
500 | המדיניות צפויה למצוא את Client ID במשתנה שצוין ברכיב <ClientId> , אבל לא ניתן לפענח את המשתנה. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitgrant רענון AccessToken |
steps.oauth.v2.FailedToResolveRefreshToken |
500 | המדיניות צפויה למצוא אסימון רענון במשתנה שצוין ברכיב <RefreshToken> , אבל לא ניתן לפענח את המשתנה. |
רענון AccessToken |
steps.oauth.v2.FailedToResolveToken |
500 | המדיניות צפויה למצוא אסימון במשתנה שצוין ברכיב <Tokens> , אבל לא ניתן לפענח את המשתנה. |
VerifyToken |
steps.oauth.v2.InsufficientScope |
403 | האסימון לגישה מפורטת שצוין בבקשה הוא בהיקף שאינו תואם להיקף שצוין במדיניות אימות אסימון הגישה. מידע נוסף על היקף ההרשאות זמין במאמר עבודה עם היקפי OAuth2. | אימותAccessToken |
steps.oauth.v2.invalid_access_token |
401 | אסימון הגישה שנשלח מהלקוח לא חוקי. | אימותAccessToken |
steps.oauth.v2.invalid_client |
401 |
שם השגיאה הזה מוחזר כאשר המאפיין הערה: מומלץ לשנות את התנאים הקיימים של כללי הכשל כדי לקלוט את השם |
CreateAccessToken רענוןAccessToken |
steps.oauth.v2.invalid_request |
400 | שם השגיאה הזה משמש למספר סוגים של שגיאות, לרוב עבור פרמטרים חסרים או שגויים שנשלחים בבקשה. אם המדיניות <GenerateResponse> מוגדרת לערך false , צריך להשתמש במשתני כשל (מתוארים בהמשך) כדי לאחזר פרטים על השגיאה, כמו שם השגיאה והמקור שלה. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitgrant רענון AccessToken |
steps.oauth.v2.InvalidAccessToken |
401 | כותרת ההרשאה אינה מכילה את המילה "דובים", הנדרשת. לדוגמה: Authorization: Bearer your_access_token |
אימותAccessToken |
steps.oauth.v2.InvalidAPICallAsNo\ |
401 |
שרת ה-proxy של ממשק ה-API לא נמצא במוצר המשויך לאסימון הגישה. טיפים: עליכם לוודא שהמוצר שמשויך לאסימון הגישה מוגדר כראוי. לדוגמה, אם אתם משתמשים בתווים כלליים לחיפוש בנתיבי משאבים, ודאו שהשתמשתם בתווים כלליים לחיפוש בצורה נכונה. פרטים נוספים זמינים במאמר יצירת מוצרי API. לקבלת הנחיות נוספות לגבי הסיבות לשגיאה הזו, ניתן לעיין בפוסט הזה בקהילה של Apigee. |
אימותAccessToken |
steps.oauth.v2.InvalidClientIdentifier |
500 |
שם השגיאה הזה מופיע כאשר המאפיין |
CreateAccessToken |
steps.oauth.v2.InvalidParameter |
500 | המדיניות חייבת לציין אסימון גישה או קוד הרשאה, אבל לא את שניהם. | GenerateAuthorizationCode GenerateAccessTokenImplicitgrant |
steps.oauth.v2.InvalidTokenType |
500 | הרכיב <Tokens>/<Token> דורש לציין את סוג האסימון (לדוגמה, refreshtoken ). אם הלקוח מעביר את הסוג הלא נכון, השגיאה
נזרקה. |
VerifyToken InverifyToken |
steps.oauth.v2.MissingParameter |
500 | סוג התגובה הוא token , אבל לא צוינו סוגי מענקים. |
GenerateAuthorizationCode GenerateAccessTokenImplicitgrant |
steps.oauth.v2.UnSupportedGrantType |
500 |
הלקוח ציין סוג מענק שאינו נתמך על ידי המדיניות (לא רשום ברכיב <SupportgrantTypes>). הערה: בשלב זה קיים באג שגרם לשגיאות לא נתמכות של סוג המענק. אם מתרחשת שגיאה בסוג המענק שאינה נתמכת, שרת ה-proxy לא נכנס לזרימת השגיאות כפי שציפית. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitgrant רענון AccessToken |
שגיאות פריסה
השגיאות האלה עשויות להתרחש במהלך פריסת שרת proxy שמכיל את המדיניות הזו.
שם השגיאה | הסיבה |
---|---|
InvalidValueForExpiresIn |
עבור הרכיב |
InvalidValueForRefreshTokenExpiresIn |
עבור הרכיב <RefreshTokenExpiresIn> , הערכים החוקיים הם מספרים שלמים חיוביים ו--1 . |
InvalidGrantType |
צוין סוג מענק לא חוקי ברכיב <SupportedGrantTypes> . כדי לקבל רשימה של סוגים חוקיים, אפשר לעיין בחומר העזר בנושא מדיניות. |
ExpiresInNotApplicableForOperation |
צריך לוודא שהפעולות המפורטות ברכיב <Operations> תומכות בפקודה. לדוגמה, הפעולה ValidToken לא כוללת אותם. |
RefreshTokenExpiresInNotApplicableForOperation |
צריך לוודא שהפעולות המפורטות ברכיב <Operations> תומכות בתוקפו של אסימון הרענון. לדוגמה, הפעולה ValidToken לא כוללת אותם. |
GrantTypesNotApplicableForOperation |
חשוב לוודא שסוגי המענקים המפורטים ב-<SupportgrantTypes> נתמכים עבור הפעולה שצוינה. |
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
הערה: עבור פעולת ה-VerifyAccessToken, שם התקלה כולל את הסיומת הזו: |
oauthV2.policy_name.fault.cause |
policy_name הוא השם שצוין על ידי המשתמש במדיניות שגרמה לשגיאה. | oauthV2.GenerateAccesstoken.cause = Required param : grant_type |
דוגמה לשגיאה
התשובות האלה נשלחות ללקוח אם הרכיב <GenerateResponse>
הוא true.
errorcode
של הודעת השגיאה. אין להסתמך על הטקסט שמופיע
בfaultstring
, כי הוא עשוי להשתנות.אם המדיניות <GenerateResponse>
מוגדרת כ-true, המדיניות מחזירה שגיאות בפורמט הזה עבור פעולות שיוצרות אסימונים וקודים. כדי לקבל רשימה מלאה, קראו את המאמר מידע על תגובות שגיאה ב-HTTP HTTP.
{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}
אם הערך של <GenerateResponse>
הוא true, המדיניות מחזירה שגיאות בפורמט הזה לאימות ולאימות. לרשימה מלאה, אפשר לעיין בחומר העזר בנושא תגובת שגיאה ב-HTTP HTTP.
{ { "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. נקודת הקצה מוגדרת מראש באמצעות כללי המדיניות בשרת ה-proxy של ה-API, שנקרא authauth. אפשר להתחיל להשתמש בנקודת הקצה של האסימון מיד לאחר יצירת החשבון ב-Apigee Edge. לפרטים נוספים קראו את המאמר הסבר על נקודות קצה (endpoint) ב-OAuth.
מחיקה לצמיתות של אסימוני גישה
כברירת מחדל, אסימוני OAuth2 נמחקים לצמיתות ממערכת Apigee Edge במשך 3 ימים (259,200 שניות) אחרי שתוקפו של אסימון הגישה ואסימון הרענון (אם הם קיימים) פג. במקרים מסוימים, כדאי לשנות את ברירת המחדל. לדוגמה, כדאי לקצר את זמן המחיקה כדי לחסוך בנפח אחסון אם נוצר מספר גדול של אסימונים.
אם אתם משתמשים ב-Edge for Cloud Cloud, תוכלו לשנות את ברירת המחדל הזו על ידי הגדרת מאפייני הארגון, כפי שמוסבר בסעיף הזה. (מחיקה לצמיתות של אסימונים שפג תוקפם במשך 3 ימים חלה על Edge ל-Cloud Cloud בגרסה 4.19.01 ואילך. בגרסאות קודמות, מרווח הערכים לצמיתות המוגדר כברירת מחדל הוא 180 ימים).
עדכון של ההגדרות לצמיתות לצמיתות בגרסה 4.16.01 ואילך של Edge Private Cloud
הערה: רק אסימונים שנוצרו אחרי הוחלו על ההגדרות האלה. ההגדרות לא חלות על אסימונים שנוצרו לפני כן.
- פותחים את הקובץ הזה כדי לערוך אותו:
/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 הזה מגדיר את נכס המחיקה לצמיתות של אסימון עבור הארגון בשם 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"}