מדיניות OAuthV2

אתה צופה בתיעוד של 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

השם הפנימי של המדיניות. הערך של המאפיין name יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. האורך המקסימלי של הערך הוא 255 תווים.

אפשר להשתמש ברכיב <DisplayName> כדי להוסיף תווית למדיניות בכלי לעריכת שרת proxy של ממשק המשתמש לניהול, ולהשתמש בשם אחר בשפה טבעית.

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

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

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

false אופציונלי
enabled

יש להגדיר את המדיניות true כדי לאכוף את המדיניות.

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

true אופציונלי
async

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

false הוצא משימוש

רכיב <DisplayName>

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

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

לא רלוונטי

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

נוכחות אופציונלי
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
הנתונים משמשים לביצוע פעולות:
  • אימותAccessToken

הרכיב <AccessTokenPrefix>

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

כברירת מחדל, אסימון AccessAccessToken מצפה שיישלחו באסימון הגישה בכותרת ההרשאה כאסימון נושא. לדוגמה:

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

בשלב הזה, הקידומת היחידה נתמכת ב-Bar.

ברירת מחדל:

פרמטרים לרשת

נוכחות:

אופציונלי

סוג: String
ערכים תקינים:

פרמטרים לרשת

הנתונים משמשים לביצוע פעולות:
  • אימותAccessToken

רכיב <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
ערכים תקינים:

כל משתנה זרימה הנגיש למדיניות בזמן ריצה.

השימוש כולל סוגי מענקים:
  • קוד הרשאה
  • מרומז
  • סיסמה
  • client_credentials

<מאפיינים/מאפיין>

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

למידע נוסף, ראו התאמה אישית של אסימונים וקודי הרשאות.

ברירת מחדל:

N/A

נוכחות:

אופציונלי

ערכים תקינים:
  • name – שם המאפיין
  • ref – ערך המאפיין. יכולה להגיע ממשתנה זרימה.
  • display - (אופציונלי) מאפשרת לציין אם מאפיינים מותאמים אישית יופיעו בתגובה. אם הערך true, המאפיינים המותאמים אישית יופיעו בתשובה (אם הפעלת גם את GenerateResponse). אם הערך false, מאפיינים מותאמים אישית לא ייכללו בתגובה. ערך ברירת המחדל הוא true. כדאי לקרוא: הצגה או הסתרה של מאפיינים מותאמים אישית בתגובה.
השימוש כולל סוגי מענקים:
  • קוד הרשאה
  • מרומז
  • סיסמה
  • client_credentials
  • רענון_אסימון
  • אפשר להשתמש גם בפעולה של GenerateAuthorizationCode.

רכיב <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
השימוש כולל סוגי מענקים:
  • קוד הרשאה
  • סיסמה
  • מרומז
  • client_credentials

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

  1. פותחים את הקובץ message-processor.properties בעורך. אם הקובץ לא קיים, יוצרים אותו:
    vi /opt/apigee/customer/application/message-processor.properties
  2. מגדירים את הנכס באופן הרצוי:
    conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000
  3. חשוב לוודא שקובץ הנכסים נמצא בבעלות המשתמש 'pigee':
    chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
  4. מפעילים מחדש את מעבד ההודעות.
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

ברירת מחדל:

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

נוכחות:

אופציונלי

סוג: מספר שלם
ערכים תקינים:
השימוש כולל סוגי מענקים:
  • קוד הרשאה
  • מרומז
  • סיסמה
  • client_credentials
  • רענון_אסימון

בשימוש גם עם פעולת 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
ערכים תקינים: נכון או לא נכון
השימוש כולל סוגי מענקים:
  • קוד הרשאה
  • סיסמה
  • client_credentials

רכיב <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

נוכחות:

אופציונלי

סוג: מחרוזת
ערכים תקינים: נכון או לא נכון
השימוש כולל סוגי מענקים:
  • מרומז
  • סיסמה
  • client_credentials
  • רענון_אסימון
  • אפשר להשתמש גם בפעולה GenerateAuthorizationCode.

הרכיב <CreateErrorResponse>

<GenerateErrorResponse enabled='true'/>

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

ברירת מחדל:

false

נוכחות:

אופציונלי

סוג: מחרוזת
ערכים תקינים: נכון או לא נכון
השימוש כולל סוגי מענקים:
  • מרומז
  • סיסמה
  • client_credentials
  • רענון_אסימון
  • אפשר להשתמש גם בפעולה GenerateAuthorizationCode.

<סוג מענק>

<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, כפי שצוין בגוף הבקשה)

נוכחות:

אופציונלי

סוג: מחרוזת
ערכים תקינים: משתנה, כפי שמוסבר למעלה.
השימוש כולל סוגי מענקים:
  • קוד הרשאה
  • סיסמה
  • מרומז
  • client_credentials
  • רענון_אסימון

רכיב <Operation>

<Operation>GenerateAuthorizationCode</Operation>

פעולת OAuth 2.0 שהוגדרה על ידי המדיניות.

ברירת מחדל:

אם לא מציינים את <Operation>, אפליקציית Edge בודקת את הרשימה של <SupportedGrantTypes>. רק הפעולות באותם סוגים של מענקים יצליחו. במילים אחרות, אפשר להשמיט את <Operation> אם מציינים <GrantType> ברשימה <SupportedGrantTypes>. אם לא צוינו <Operation> וגם <SupportedGrantTypes>, סוג ברירת המחדל למענק הוא הרשאה_קוד. כלומר, בקשות להענקת הרשאה מסוג הרשאה_code יצליחו, אבל כל השאר ייכשלו.

נוכחות:

אופציונלי

סוג: 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. כדי להגדיר את הנכס הזה:

  1. פותחים את הקובץ message-processor.properties בעורך. אם הקובץ לא קיים, יוצרים אותו:
    vi /opt/apigee/customer/application/message-processor.properties
  2. מגדירים את הנכס באופן הרצוי:
    conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000
  3. חשוב לוודא שקובץ הנכסים נמצא בבעלות המשתמש 'pigee':
    chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
  4. מפעילים מחדש את מעבד ההודעות.
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

ברירת מחדל:

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

נוכחות:

אופציונלי

סוג: מספר שלם
ערכים תקינים:
השימוש כולל סוגי מענקים:
  • קוד הרשאה
  • סיסמה
  • רענון_אסימון

רכיב <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 (לסוג המענק המשתמע)
השימוש כולל סוגי מענקים:
  • מרומז
  • בשימוש גם עם הפעולה GenerateAuthorizationCode.

הרכיב <ReuseRefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

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

ברירת מחדל:

false

נוכחות:

אופציונלי

סוג: בוליאני
ערכים תקינים:

true או false

נעשה שימוש בסוג המענק:
  • רענון_אסימון

רכיב <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, רשימה מופרדת של שמות היקפים (מחרוזות).

השימוש כולל סוגי מענקים:
  • קוד הרשאה
  • מרומז
  • סיסמה
  • client_credentials
  • אפשר להשתמש בפעולה הזו גם עם הפעולות CREATEAuthorizationCode ו-VerifyAccessToken.

רכיב <State>

<State>request.queryparam.state</State>

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

לדוגמה: request.queryparam.state צריך לציין שהמצב צריך להופיע כפרמטר של שאילתה, למשל ?state=HjoiuKJH32. כדי לדרוש את המצב בכותרת HTTP, למשל צריך להגדיר את הערך הזה כ-request.header.state. עיינו גם בקטע בקשת אסימוני גישה וקודי הרשאות.

ברירת מחדל:

ללא מדינה

נוכחות:

אופציונלי

סוג: String
ערכים תקינים: כל משתנה זרימה הנגיש למדיניות בזמן ריצה
השימוש כולל סוגי מענקים:
  • הכול
  • אפשר להשתמש גם בפעולה GenerateAuthorizationCode

רכיב <StoreToken>

 <StoreToken>true</StoreToken> 

יש להגדיר את הרכיב הזה כ-true כשהרכיב <ExternalAuthorization> הוא true. הרכיב <StoreToken> מבקש מ-Apigee Edge לאחסן את אסימון הגישה החיצוני. אחרת, הערך לא יימחק.

ברירת מחדל:

false

נוכחות:

אופציונלי

סוג: Boolean
ערכים תקינים: נכון או לא נכון
השימוש כולל סוגי מענקים:
  • קוד הרשאה
  • סיסמה
  • client_credentials

הרכיב <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
ערכים תקינים:
  • client_credentials
  • קוד הרשאה
  • סיסמה
  • מרומז

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

משתנים ספציפיים לאסימונים

משתנים תיאור
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 בלבד) מציין למה בוטל אסימון הגישה.

הערך יכול להיות REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER או TOKEN_REVOKED.

משתנים ספציפיים לאפליקציה

המשתנים האלה קשורים לאפליקציה למפתחים שמשויכת לאסימון.

משתנים תיאור
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
InvalidatorToken

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
InverifyToken

steps.oauth.v2.InsufficientScope 403 האסימון לגישה מפורטת שצוין בבקשה הוא בהיקף שאינו תואם להיקף שצוין במדיניות אימות אסימון הגישה. מידע נוסף על היקף ההרשאות זמין במאמר עבודה עם היקפי OAuth2. אימותAccessToken
steps.oauth.v2.invalid_access_token 401 אסימון הגישה שנשלח מהלקוח לא חוקי. אימותAccessToken
steps.oauth.v2.invalid_client 401

שם השגיאה הזה מוחזר כאשר המאפיין <GenerateResponse> של המדיניות מוגדר כ-true ומזהה הלקוח שנשלח בבקשה לא חוקי. עליך לוודא שהשתמשת במפתח הלקוח ובערכי הסוד הנכונים של האפליקציה למפתחים המשויכת לשרת ה-proxy. בדרך כלל הערכים האלה נשלחים ככותרת להרשאה בסיסית בקידוד Base64.

הערה: מומלץ לשנות את התנאים הקיימים של כללי הכשל כדי לקלוט את השם invalid_client ואת השם InvalidClientIdentifier. אפשר לקרוא מידע נוסף ודוגמה בהערות הגרסה 16.09.21.

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\
steps.oauth.v2.ApiProductMatchFound
401

שרת ה-proxy של ממשק ה-API לא נמצא במוצר המשויך לאסימון הגישה.

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

לקבלת הנחיות נוספות לגבי הסיבות לשגיאה הזו, ניתן לעיין בפוסט הזה בקהילה של Apigee.

אימותAccessToken
steps.oauth.v2.InvalidClientIdentifier 500

שם השגיאה הזה מופיע כאשר המאפיין <GenerateResponse> של המדיניות מוגדר כ-false ומזהה הלקוח שנשלח בבקשה לא חוקי. חשוב לוודא שהזנת את מפתח הלקוח ואת ערכי הסוד הנכונים של אפליקציית הפיתוח המשויכת לשרת ה-proxy. לרוב, הערכים האלה נשלחים ככותרת של הרשאות בסיסיות בקידוד Base64.

הערה: במצב הזה, השגיאה הזו נקראה invalid_client. מומלץ לשנות את התנאים הקיימים של כללי השגיאות כדי לתעד את השם invalid_client וגם את InvalidClientIdentifier. אפשר לקרוא מידע נוסף ודוגמה בהערות הגרסה 16.09.21.

CreateAccessToken
רענוןAccessToken

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

עבור הרכיב <ExpiresIn>, הערכים החוקיים הם מספרים שלמים חיוביים ו--1.

InvalidValueForRefreshTokenExpiresIn עבור הרכיב <RefreshTokenExpiresIn>, הערכים החוקיים הם מספרים שלמים חיוביים ו--1.
InvalidGrantType צוין סוג מענק לא חוקי ברכיב <SupportedGrantTypes>. כדי לקבל רשימה של סוגים חוקיים, אפשר לעיין בחומר העזר בנושא מדיניות.
ExpiresInNotApplicableForOperation צריך לוודא שהפעולות המפורטות ברכיב <Operations> תומכות בפקודה. לדוגמה, הפעולה ValidToken לא כוללת אותם.
RefreshTokenExpiresInNotApplicableForOperation צריך לוודא שהפעולות המפורטות ברכיב <Operations> תומכות בתוקפו של אסימון הרענון. לדוגמה, הפעולה ValidToken לא כוללת אותם.
GrantTypesNotApplicableForOperation חשוב לוודא שסוגי המענקים המפורטים ב-<SupportgrantTypes> נתמכים עבור הפעולה שצוינה.
OperationRequired

יש לציין פעולה במדיניות הזו באמצעות הרכיב <Operation>.

הערה: אם הרכיב <Operation> חסר, ממשק המשתמש יציג שגיאת אימות של הסכימה.

InvalidOperation

יש לציין פעולה חוקית במדיניות הזו באמצעות הרכיב <Operation>.

הערה: אם הרכיב <Operation> לא חוקי, ממשק המשתמש יגרום לשגיאה באימות הסכימה.

TokenValueRequired יש לציין ערך של אסימון <Token> ברכיב <Tokens>.

משתני כשל

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

משתנים מיקום דוגמה
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, שם התקלה כולל את הסיומת הזו: keymanagement.service
לדוגמה: keymanagement.service.invalid_access_token

oauthV2.policy_name.fault.cause policy_name הוא השם שצוין על ידי המשתמש במדיניות שגרמה לשגיאה. oauthV2.GenerateAccesstoken.cause = Required param : grant_type

דוגמה לשגיאה

התשובות האלה נשלחות ללקוח אם הרכיב <GenerateResponse> הוא true.

אם המדיניות <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

הערה: רק אסימונים שנוצרו אחרי הוחלו על ההגדרות האלה. ההגדרות לא חלות על אסימונים שנוצרו לפני כן.

עדכון הגדרות מחיקה לצמיתות של Edge Private Cloud 4.15.07

הערה: רק אסימונים שנוצרו אחרי הוחלו על ההגדרות האלה. ההגדרות לא חלות על אסימונים שנוצרו לפני כן.

התנהגות שלא תואמת ל-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"}

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