מדיניות OAuthV2

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

מה

OAuthV2 היא מדיניות רב-שלבית לביצוע פעולות של הרשאות מסוג OAuth 2.0. זאת המדיניות הראשית שמשמשת להגדרת נקודות קצה של OAuth 2.0 ב-Apigee Edge.

טיפ: בדף הבית של OAuth מפורט מידע נוסף על OAuth ב-Apigee Edge. הוא כולל קישורים למשאבים, לדוגמאות, לסרטונים ועוד. אפשר לעיין בדוגמה המתקדמת של OAuth ב-GitHub כדי לקבל הדגמה טובה של אופן השימוש במדיניות הזו באפליקציה פעילה.

טעימות

VerifyAccessToken

VerifyAccessToken

ההגדרה של מדיניות OAuthV2 (עם הפעולה verificationAccessToken) מאמתת שאסימון גישה שנשלח ל-Apigee Edge חוקי. כשפעולת המדיניות הזו מופעלת, Edge מחפש אסימון גישה חוקי בבקשה. אם אסימון הגישה תקין, מותר להמשיך את הבקשה. אם השיטה לא תקינה, כל העיבודים יופסקו ותוחזר שגיאה בתגובה.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2">
    <DisplayName>OAuth v2.0 2</DisplayName>
    <Operation>VerifyAccessToken</Operation>
    <AccessTokenPrefix>Bearer</AccessTokenPrefix> <!-- Optional, default is Bearer -->
</OAuthV2>

הערה: יש תמיכה רק באסימוני OAuth 2.0. אין תמיכה באסימונים של קוד אימות הודעות (MAC).

לדוגמה:

$ curl -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

כברירת מחדל, Edge מקבל אסימוני גישה בכותרת Authorization עם הקידומת Bearer. אפשר לשנות את ברירת המחדל באמצעות הרכיב <AccessToken>.

GenerateAccessToken

יצירת אסימוני גישה

במאמר בקשת אסימוני גישה וקודי הרשאה מופיעות דוגמאות לכך. הנושא כולל דוגמאות לפעולות הבאות:

GenerateAuthorizationCode

יצירת קוד הרשאה

בקטע בקשת קוד הרשאה מופיעות דוגמאות לכך.

RefreshAccessToken

רענון של אסימון גישה

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

אסימון של תהליך תגובה

יצירת אסימון גישה בתהליך התגובה

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

תחילה נבחן את המדיניות לדוגמה:

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

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

כותרת ההרשאה צריכה להכיל סכמת גישה בסיסית עם client_id:client_secret בקידוד Base64.

אפשר להוסיף את הכותרת הזו באמצעות מדיניות JavaScript שמוצבת ממש לפני מדיניות OAuthV2, בצורה הזו. המשתנים "local_clientid" ו-"local_secret" חייבים להיות מוגדרים קודם לכן וזמינים בתהליך:

var client_id = context.getVariable("local_clientid");
var client_secret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(client_id + ':' + client_secret)));

למידע נוסף, ראו "קידוד של פרטי כניסה לאימות בסיסי".

הפניה לרכיב

בהפניה למדיניות מתוארים הרכיבים והתכונות של מדיניות OAuthV2.

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

<OAuthV2 name="GenerateAccessToken">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

מאפייני <OAuthV2>

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

בטבלה הבאה מפורטים המאפיינים שמשותפים לכל רכיבי ההורה של המדיניות:

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

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

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

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

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

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

false אופציונלי
enabled

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

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

true אופציונלי
async

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

false הוצא משימוש

רכיב <DisplayName>

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

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

לא רלוונטי

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

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

רכיב <AccessToken>

<AccessToken>request.header.access_token</AccessToken>

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

דוגמה שבה מצוין <AccessToken>request.header.access_token</AccessToken>:

curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"
דוגמה שבה מצוין <AccessToken>request.queryparam.access_token</AccessToken>:

curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"

ברירת מחדל:

לא רלוונטי

נוכחות:

אופציונלי

סוג: מחרוזת
לשימוש בפעולות:
  • VerifyAccessToken

רכיב <AccessTokenPrefix>

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

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

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

נכון לעכשיו, התחילית שנתמכת היא Bearer.

ברירת מחדל:

פרמטרים לרשת

נוכחות:

אופציונלי

סוג: מחרוזת
ערכים חוקיים:

פרמטרים לרשת

לשימוש בפעולות:
  • VerifyAccessToken

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

ברירת מחדל:

לא רלוונטי

נוכחות:

אופציונלי

סוג: מחרוזת
ערכים חוקיים:

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

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

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

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

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

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

כדי להסתיר מאפיינים מותאמים אישית במקרים כאלה, אפשר לבחור באפשרויות הבאות:

  • צריך לאפס באופן מפורש את המאפיינים המותאמים אישית במדיניות אסימון הרענון ולהגדיר אותם כ-False. במקרה כזה, ייתכן שיהיה צורך לאחזר את הערכים המותאמים אישית המקוריים מאסימון הגישה המקורי באמצעות המדיניות GetOAuthV2Info.
  • אפשר להשתמש במדיניות JavaScript לאחר עיבוד כדי לחלץ באופן ידני מאפיינים מותאמים אישית שאינך רוצה לראות בתגובה.

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

ברירת מחדל:

N/A

נוכחות:

אופציונלי

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

האלמנט <ClientId>

<ClientId>request.formparam.client_id</ClientId>

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

ברירת מחדל:

request.formparam.client_id (כתובת x-www-form-urlencoded ומצוינת בגוף הבקשה)

נוכחות:

אופציונלי

סוג: מחרוזת
ערכים חוקיים: משתנה הזרימה: request.formparam.client_id
בשימוש עם סוגי המענק:
  • authorization_code
  • סיסמה
  • מרומז
  • 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 ומצוינת בגוף הבקשה)

נוכחות:

אופציונלי

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

הרכיב<expirationIn>

<ExpiresIn>10000</ExpiresIn> 

המדיניות הזו אוכפת את זמן התפוגה של אסימוני גישה וקודי הרשאה באלפיות שנייה. (לאסימוני רענון, יש להשתמש ב-<RefreshTokenExpiresIn>.) ערך זמן התפוגה הוא ערך שנוצר על-ידי המערכת בתוספת הערך <ExpiresIn>. אם הערך של <ExpiresIn> הוא 1-, התוקף של האסימון או הקוד יפוג בהתאם לתפוגת התוקף המקסימלית של אסימון הגישה ל-OAuth. אם לא מציינים את <ExpiresIn>, המערכת מחילה ערך ברירת מחדל שהוגדר ברמת המערכת.

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

באמצעות Apigee Edge ל-Public Cloud, Edge שומר את הישויות הבאות במטמון למשך 180 שניות לפחות אחרי גישה לישויות.

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

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

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

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

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

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

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

ברירת מחדל:

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

נוכחות:

אופציונלי

סוג: מספר שלם
ערכים חוקיים:
בשימוש עם סוגי המענק:
  • authorization_code
  • מרומז
  • סיסמה
  • client_credentials
  • refresh_token

בשימוש גם עם פעולה 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

נוכחות:

אופציונלי

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

רכיב <ExternalרענןToken>

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

ההגדרה הזו מציינת ל-Apigee Edge איפה למצוא אסימון רענון חיצוני (אסימון רענון שלא נוצר על ידי Apigee Edge).

המשתנה request.queryparam.external_refresh_token מציין שאסימון הרענון החיצוני צריך להופיע כפרמטר של שאילתה, כמו, לדוגמה, ?external_refresh_token=12345678. כדי לדרוש את אסימון הרענון החיצוני בכותרת HTTP, למשל, מגדירים את הערך הזה כ-request.header.external_refresh_token. למידע נוסף, ראו שימוש באסימוני OAuth של צד שלישי.

האלמנט <GenerateResponse>

<GenerateResponse enabled='true'/>

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

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

אם false, לא תישלח תשובה. במקום זאת, קבוצה של משתני זרימה מאוכלסת בערכים שקשורים לפונקציית של המדיניות. לדוגמה, משתנה זרימה שנקרא oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code יאוכלס בקוד ההרשאה החדש שהופק. חשוב לשים לב שהפרמטר expires_in מבוטא בשניות בתגובה.

ברירת מחדל:

false

נוכחות:

אופציונלי

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

האלמנט <GenerateErrorResponse>

<GenerateErrorResponse enabled='true'/>

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

ברירת מחדל:

false

נוכחות:

אופציונלי

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

<GrantType>

<GrantType>request.queryparam.grant_type</GrantType>

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

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

ברירת מחדל:

request.formparam.grant_type (כתובת x-www-form-urlencoded ומצוינת בגוף הבקשה)

נוכחות:

אופציונלי

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

רכיב <Operation>

<Operation>GenerateAuthorizationCode</Operation>

פעולת OAuth 2.0 בוצעה על ידי המדיניות.

ברירת מחדל:

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

נוכחות:

אופציונלי

סוג: מחרוזת
ערכים חוקיים:

רכיב <PassWord>

<PassWord>request.queryparam.password</PassWord>

הרכיב הזה משמש רק עבור סוג מתן הסיסמה. בהתאם לסוג מתן הסיסמה, פרטי הכניסה של המשתמש (סיסמה ושם משתמש) חייבים להיות זמינים למדיניות OAuthV2. הרכיבים <PassWord> ו-<UserName> משמשים לציון משתנים שבהם Edge תוכל למצוא את הערכים האלה. אם הרכיבים האלה לא צוינו, המדיניות מצפה למצוא את הערכים (כברירת מחדל) בפרמטרים של טופס שנקראים username ו-password. אם הערכים לא יימצאו, המדיניות תציג הודעת שגיאה. אפשר להשתמש ברכיבים <PassWord> ו-<UserName> כדי להפנות לכל משתנה זרימה שמכיל את פרטי הכניסה.

לדוגמה, אפשר להעביר את הסיסמה בבקשת אסימון באמצעות פרמטר של שאילתה, ולהגדיר את הרכיב באופן הבא: <PassWord>request.queryparam.password</PassWord>. כדי לדרוש את הסיסמה בכותרת HTTP, צריך להגדיר את הערך הזה כ-request.header.password.

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

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

ברירת מחדל:

request.formparam.password (כתובת x-www-form-urlencoded ומצוינת בגוף הבקשה)

נוכחות:

אופציונלי

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

אלמנט <RedirectUri>

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

ההגדרה קובעת איפה Edge יחפש את הפרמטר redirect_uri בבקשה.

מידע על מזהי URI של הפניה אוטומטית

מזהי URI של הפניה מחדש משמשים יחד עם קוד ההרשאה וסוגי הרשאות משתמעות. ה-URI של ההפניה מורה לשרת ההרשאות (Edge) לאן לשלוח קוד הרשאה (עבור סוג ההרשאה של קוד ההרשאה) או את אסימון הגישה (לסוג ההרשאה המשתמעת). חשוב להבין מתי הפרמטר הזה נדרש, מתי הוא אופציונלי ואיך משתמשים בו:

  • (חובה) אם רשומה כתובת URL לקריאה חוזרת (callback) באפליקציית הפיתוח שמשויכת למפתחות הלקוח של הבקשה, ואם redirect_uri מופיע בבקשה, חייבת להיות התאמה מדויקת בין שניהם. אם הם לא תואמים, תוחזר שגיאה. למידע נוסף על רישום אפליקציות למפתחים ב-Edge וציון כתובת URL של קריאה חוזרת, אפשר לקרוא את המאמר רישום אפליקציות וניהול מפתחות API.

  • (אופציונלי) אם רשומה כתובת URL לקריאה חוזרת (callback) וחסר הערך redirect_uri בבקשה, Edge מפנה לכתובת ה-URL הרשומה לקריאה חוזרת.
  • (חובה) אם כתובת URL לקריאה חוזרת (callback) לא רשומה, חובה לציין redirect_uri. חשוב לשים לב שבמקרה הזה, Edge יקבל כל כתובת URL. מקרה כזה עלול ליצור בעיית אבטחה,ולכן יש להשתמש בו רק עם אפליקציות לקוח מהימנות. אם אפליקציות של לקוח לא מהימנות, השיטה המומלצת היא לדרוש תמיד רישום של כתובת URL לקריאה חוזרת.

אפשר לשלוח את הפרמטר הזה בפרמטר של שאילתה או בכותרת. המשתנה request.queryparam.redirect_uri מציין שה-RedirectUri צריך להופיע כפרמטר של שאילתה, כמו, לדוגמה, ?redirect_uri=login.myapp.com. כדי לדרוש שימוש ב-RedirectUri בכותרת HTTP, הגדירו את הערך הזה ל-request.header.redirect_uri. למידע נוסף, ראו בקשת אסימוני גישה וקודי הרשאה.

ברירת מחדל:

request.formparam.redirect_uri (כתובת x-www-form-urlencoded ומצוינת בגוף הבקשה)

נוכחות:

אופציונלי

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

בשימוש גם עם הפעולה GenerateAuthorizationCode.

רכיב <רענןToken>

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

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

המשתנה request.queryparam.refreshtoken מציין שאסימון הרענון צריך להופיע כפרמטר של שאילתה, כמו לדוגמה ?refresh_token=login.myapp.com. כדי לדרוש את ה-רענן אסימון בכותרת HTTP, למשל, צריך להגדיר את הערך הזה כ-request.header.refresh_token. למידע נוסף, ראו בקשת אסימוני גישה וקודי הרשאה.

ברירת מחדל:

request.formparam.refresh_token (קובץ x-www-form-urlencoded ומצוין בגוף הבקשה)

נוכחות:

אופציונלי

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

הרכיב <רענןTokenexpirationIn>

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

המדיניות הזו אוכפת את זמן התפוגה של אסימוני הרענון באלפיות השנייה. ערך זמן התפוגה הוא ערך שנוצר על ידי המערכת בתוספת הערך <RefreshTokenExpiresIn>. אם המדיניות <RefreshTokenExpiresIn> מוגדרת לערך -1, התוקף של אסימון הרענון יפוג בהתאם לתפוגה המקסימלית של אסימון הרענון של OAuth. אם לא מציינים את <RefreshTokenExpiresIn>, כברירת מחדל אין תאריך תפוגה.

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

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

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</RefreshTokenExpiresIn>

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

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

ברירת מחדל:

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

נוכחות:

אופציונלי

סוג: מספר שלם
ערכים חוקיים:
בשימוש עם סוגי המענק:
  • authorization_code
  • סיסמה
  • refresh_token

האלמנט <ResponseType>

<ResponseType>request.queryparam.response_type</ResponseType>

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

כברירת מחדל, Edge מחפש את הערך של סוג התגובה בפרמטר של response_type. אם רוצים לשנות את התנהגות ברירת המחדל הזו, משתמשים ברכיב <ResponseType> כדי להגדיר משתנה זרימה שמכיל את הערך של סוג התגובה. לדוגמה, אם מגדירים את הרכיב הזה כ-request.header.response_type, המערכת מחפשת את סוג התגובה שיועבר בכותרת הבקשה. למידע נוסף, ראו בקשת אסימוני גישה וקודי הרשאה.

ברירת מחדל:

request.formparam.response_type (מחרוזת x-www-form-urlencoded ומצוינת בגוף הבקשה)

נוכחות:

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

סוג: מחרוזת
ערכים חוקיים: code (לסוג ההרשאה של קוד ההרשאה) או token (לסוג ההרשאה המשתמעת)
בשימוש עם סוגי המענק:
  • מרומז
  • בשימוש גם עם הפעולה GenerateAuthorizationCode.

רכיב <ReuseרענןToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

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

ברירת מחדל:

false

נוכחות:

אופציונלי

סוג: boolean
ערכים חוקיים:

true או false

בשימוש יחד עם סוג המענק:
  • refresh_token

רכיב <היקף>

<Scope>request.queryparam.scope</Scope>

אם הרכיב הזה נכלל באחד מכללי המדיניות GenerateAccessToken או GenerateAuthorizationCode, הוא ישמש לציון ההיקפים שצריך להקצות להם את האסימון או הקוד. הערכים האלה מועברים בדרך כלל למדיניות בבקשה מאפליקציית לקוח. אפשר להגדיר שהרכיב יקבל משתנה זרימה, כך שתהיה לך אפשרות לבחור איך ההיקפים יועברו בבקשה. בדוגמה הבאה, request.queryparam.scope מציין שההיקף צריך להיות כפרמטר של שאילתה, כמו למשל ?scope=READ. כדי לדרוש את ההיקף בכותרת HTTP, למשל, מגדירים את הערך הזה ל-request.header.scope.

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

<Scope>A B</Scope>

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

ברירת מחדל:

אין היקף

נוכחות:

אופציונלי

סוג: מחרוזת
ערכים חוקיים:

אם משתמשים בו במדיניות Generate*, משתנה הזרימה.

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

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

רכיב <State>

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

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

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

ברירת מחדל:

אין מדינה

נוכחות:

אופציונלי

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

רכיב <StoreToken>

 <StoreToken>true</StoreToken> 

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

ברירת מחדל:

false

נוכחות:

אופציונלי

סוג: בוליאני
ערכים חוקיים: נכון או לא נכון
בשימוש עם סוגי המענק:
  • authorization_code
  • סיסמה
  • client_credentials

אלמנט <SupportedGrantTypes>/<GrantType> .

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

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

אם לא צוינו סוגי מענקים נתמכים, סוגי המענק היחידים המותרים הם authorization_code ו-implicit. אפשר לעיין גם ברכיב <GrantType> (זהו רכיב ברמה גבוהה יותר שמשמש לציון המקומות שבהם Apigee Edge צריך לחפש את הפרמטר grant_type שמועבר בבקשת לקוח. Edge יוודא שהערך של הפרמטר grant_type תואם לאחד מסוגי המענק הנתמכים).

ברירת מחדל:

הרשאה _code ו-משתמע

נוכחות:

חובה

סוג: מחרוזת
ערכים חוקיים:
  • client_credentials
  • authorization_code
  • סיסמה
  • מרומז

רכיב <Tokens>/<Token>

משמש יחד עם פעולות VerifyToken ו-InvalidateToken. למידע נוסף, ראו אישור וביטול של אסימוני גישה. הרכיב <Token> מזהה את משתנה הזרימה שמגדיר את מקור האסימון שיש לבטל. אם המפתחים צפויים לשלוח אסימוני גישה בתור פרמטרים של שאילתות בשם access_token, לדוגמה, צריך להשתמש ב-request.queryparam.access_token.

רכיב <UserName>

<UserName>request.queryparam.user_name</UserName>

הרכיב הזה משמש רק עבור סוג מתן הסיסמה. בהתאם לסוג מתן הסיסמה, פרטי הכניסה של המשתמש (סיסמה ושם משתמש) חייבים להיות זמינים למדיניות OAuthV2. הרכיבים <PassWord> ו-<UserName> משמשים לציון משתנים שבהם Edge תוכל למצוא את הערכים האלה. אם הרכיבים האלה לא צוינו, המדיניות מצפה למצוא את הערכים (כברירת מחדל) בפרמטרים של טופס שנקראים username ו-password. אם הערכים לא יימצאו, המדיניות תציג הודעת שגיאה. אפשר להשתמש ברכיבים <PassWord> ו-<UserName> כדי להפנות לכל משתנה זרימה שמכיל את פרטי הכניסה.

לדוגמה, ניתן להעביר את שם המשתמש בפרמטר של שאילתה ולהגדיר את הרכיב <UserName> באופן הבא: <UserName>request.queryparam.username</UserName>.כדי לדרוש את שם המשתמש בכותרת HTTP, מגדירים את הערך הזה כ-request.header.username.

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

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

ברירת מחדל:

request.formparam.username (כתובת x-www-form-urlencoded ומצוינת בגוף הבקשה)

נוכחות:

אופציונלי

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

אימות של אסימוני גישה

אחרי שמגדירים נקודת קצה של אסימון לשרת proxy ל-API, מדיניות OAuthV2 תואמת שמציינת שהפעולה VerifyAccessToken תצורף ל-flow שחושף את המשאב המוגן.

לדוגמה, כדי להבטיח שכל הבקשות ל-API יאושרו, המדיניות הבאה אוכפת אימות של אסימון גישה:

<OAuthV2 name="VerifyOAuthAccessToken">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

המדיניות מצורפת למשאב ה-API המוגן. כדי לוודא שכל הבקשות ל-API מאומתות, מצרפים את המדיניות ל-PreFlow של בקשת ProxyEndpoint באופן הבא:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

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

שם תיאור
היקף

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

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>
AccessToken המשתנה שבו צפוי להיות אסימון הגישה. לדוגמה request.queryparam.accesstoken. כברירת מחדל, אסימון הגישה צפוי להיות מוצג על ידי האפליקציה בכותרת Authorization HTTP, בהתאם למפרט OAuth 2.0. צריך להשתמש בהגדרה הזו אם אסימון הגישה צפוי להיות מוצג במיקום לא סטנדרטי, כמו פרמטר של שאילתה או כותרת HTTP עם שם שהוא לא Authorization.

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

ציון מיקומים של משתני בקשה

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

הדוגמה הבאה ממחישה איך לציין את המיקום של הפרמטרים הנדרשים של קוד ההרשאה ככותרות HTTP:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.header.client_id</ClientId>
  <RedirectUri>request.header.redirect_uri</RedirectUri>
  <Scope>request.header.scope</Scope>
  ...

לחלופין, אם יש צורך לתמוך בבסיס אפליקציות הלקוח, אפשר לשלב בין כותרות ופרמטרים של שאילתות:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
  ...

ניתן להגדיר מיקום אחד בלבד לכל פרמטר.

משתני זרימה

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

פעולת verificationAccessToken

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

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

משתנים תיאור
organization_name שם הארגון שבו פועל שרת ה-proxy.
developer.id המזהה של המפתח שמשויך לאפליקציית הלקוח הרשומה.
developer.app.name שם המפתח שמשויך לאפליקציית הלקוח הרשומה.
client_id מזהה הלקוח של אפליקציית הלקוח הרשומה.
grant_type סוג המענק המשויך לבקשה.
token_type סוג האסימון המשויך לבקשה.
access_token אסימון הגישה שנמצא בתהליך אימות.
accesstoken.{custom_attribute} מאפיין מותאם אישית בעל שם באסימון הגישה.
issued_at התאריך שבו הונפק אסימון הגישה, מבוטא בזמן מערכת Unix, באלפיות השנייה.
expires_in מועד התפוגה של אסימון הגישה. מבוטאת בשניות. על אף שהרכיב ExpiresIn מגדיר את התפוגה באלפיות שנייה, בתגובת האסימון ובמשתני הזרימה, הערך מתנגן בשניות.
status הסטטוס של אסימון הגישה (למשל, מאושר או בוטל).
scope ההיקף (אם יש) שמשויך לאסימון הגישה.
apiproduct.<custom_attribute_name> מאפיין מותאם אישית בעל שם של מוצר ה-API שמשויך לאפליקציית הלקוח הרשומה.
apiproduct.name השם של מוצר ה-API שמשויך לאפליקציית הלקוח הרשומה.
revoke_reason

(Apigee hybrid בלבד) מציין מדוע אסימון הגישה בוטל.

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

הפעולה GenerateAuthorizationCode

המשתנים האלה מוגדרים כשהפעולה GenerateAuthorizationCode מתבצעת בהצלחה:

קידומת: oauthv2authcode.{policy_name}.{variable_name}

לדוגמה: oauthv2authcode.GenerateCodePolicy.code

משתנה תיאור
code קוד ההרשאה שנוצר כשהמדיניות מופעלת.
redirect_uri כתובת ה-URI של ההפניה האוטומטית המשויכת לאפליקציית הלקוח הרשומה.
scope היקף ה-OAuth האופציונלי שהועבר בבקשת הלקוח.
client_id מזהה הלקוח שהועבר בבקשת הלקוח.

פעולות GenerateAccessToken ו-רענןAccessToken

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

קידומת: oauthv2accesstoken.{policy_name}.{variable_name}

לדוגמה: oauthv2accesstoken.GenerateTokenPolicy.access_token

שם משתנה תיאור
access_token אסימון הגישה שנוצר.
client_id מזהה הלקוח של אפליקציית הפיתוח שמשויכת לאסימון הזה.
expires_in ערך התפוגה של האסימון. לפרטים נוספים, אפשר לעיין ברכיב <ExpiresIn>. חשוב לשים לב שהתשובה, expires_in מבוטאת בשניות.
scope רשימה של היקפים זמינים שהוגדרו לאסימון. למידע נוסף, ניתן לעיין בעבודה עם היקפי OAuth2.
status approved או revoked.
token_type מוגדר ל-BearerToken.
developer.email כתובת האימייל של המפתח הרשום שבבעלותו אפליקציית המפתח המשויכת לאסימון.
organization_name הארגון שבו מופעל שרת ה-proxy.
api_product_list רשימת המוצרים שמשויכים לאפליקציית הפיתוח התואמת לאסימון.
refresh_count
refresh_token אסימון הרענון שנוצר. חשוב לשים לב שאסימוני רענון לא נוצרים לסוג המענק של פרטי הכניסה של הלקוח.
refresh_token_expires_in משך החיים של אסימון הרענון, בשניות.
refresh_token_issued_at ערך הזמן הזה הוא ייצוג המחרוזת של הכמות התואמת של חותמת הזמן ב-32 ביט. לדוגמה, הביטוי 'Wed, 21 Aug 2013 19:16:47 UTC' תואם לערך של חותמת הזמן של 1377112607413.
refresh_token_status approved או revoked.

GenerateAccessTokenImplicitGrant

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

קידומת: oauthv2accesstoken.{policy_name}.{variable_name}

לדוגמה: oauthv2accesstoken.RefreshTokenPolicy.access_token

משתנה תיאור
oauthv2accesstoken.access_token אסימון הגישה שנוצר כשהמדיניות מופעלת.
oauthv2accesstoken.{policy_name}.expires_in ערך התפוגה של האסימון, בשניות. לפרטים, אפשר לעיין ברכיב <ExpiresIn>.

המשמעות של השגיאות

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

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

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

קוד שגיאה סטטוס HTTP סיבה השקה בשל פעולות
steps.oauth.v2.access_token_expired 401 פג התוקף של אסימון הגישה.

VerifyAccessToken
InvalidateToken

steps.oauth.v2.access_token_not_approved 401 אסימון הגישה בוטל. VerifyAccessToken
steps.oauth.v2.apiresource_doesnot_exist 401 המשאב המבוקש לא קיים אף אחד ממוצרי ה-API שמשויכים לאסימון הגישה. VerifyAccessToken
steps.oauth.v2.FailedToResolveAccessToken 500 המדיניות הצפויה למצוא אסימון גישה במשתנה שצוין ברכיב <AccessToken>, אבל לא הייתה אפשרות לפענח את המשתנה. GenerateAccessToken
steps.oauth.v2.FailedToResolveAuthorizationCode 500 המדיניות צפויה למצוא קוד הרשאה במשתנה שצוין ברכיב <Code>, אבל לא ניתן לפענח את המשתנה. GenerateAuthorizationCode
steps.oauth.v2.FailedToResolveClientId 500 המדיניות שצפויה למצוא את ה-Client-ID במשתנה שצוין ברכיב <ClientId>, אבל לא הייתה אפשרות לפענח את המשתנה. GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.FailedToResolveRefreshToken 500 המדיניות צפויה למצוא אסימון רענון במשתנה שצוין ברכיב <RefreshToken>, אבל לא ניתן היה לפענח את המשתנה. RefreshAccessToken
steps.oauth.v2.FailedToResolveToken 500 המדיניות הצפויה למצוא אסימון במשתנה שצוין ברכיב <Tokens>, אבל לא הייתה אפשרות לפענח את המשתנה.

VerifyToken
InvalidateToken

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

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

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

GenerateAccessToken
רענוןAccessToken
steps.oauth.v2.invalid_request 400 שם השגיאה הזה משמש לסוגים שונים של שגיאות, בדרך כלל לפרמטרים חסרים או שגויים שנשלחים בבקשה. אם המדיניות <GenerateResponse> מוגדרת לערך false, משתמשים במשתני השגיאה (שמתוארים בהמשך) כדי לאחזר פרטים על השגיאה, כמו שם התקלה והסיבה. GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.InvalidAccessToken 401 כותרת ההרשאה לא מכילה את המילה "נושא", שנדרשת. לדוגמה: Authorization: Bearer your_access_token VerifyAccessToken
steps.oauth.v2.InvalidAPICallAsNo\
steps.oauth.v2.ApiProductMatchFound
401

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

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

מידע נוסף על הסיבות לשגיאה הזו זמין גם בפוסט הזה בקהילת Apigee.

VerifyAccessToken
steps.oauth.v2.InvalidClientIdentifier 500

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

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

GenerateAccessToken
רענוןAccessToken

steps.oauth.v2.InvalidParameter 500 המדיניות חייבת לציין אסימון גישה או קוד הרשאה, אבל לא את שניהם. GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.InvalidTokenType 500 הרכיב <Tokens>/<Token> מחייב לציין את סוג האסימון (לדוגמה, refreshtoken). אם הלקוח מעביר את הסוג הלא נכון, המערכת מוסיפה את השגיאה. VerifyToken
InvalidateToken
steps.oauth.v2.MissingParameter 500 סוג התגובה הוא token, אבל לא צוינו סוגי הרשאות. GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.UnSupportedGrantType 500

הלקוח ציין סוג מענק שלא נתמך במדיניות (לא רשום ברכיב <SupportedGrantTypes>).

הערה: כרגע יש באג שגרם לכך ששגיאות מסוג מענק שלא נתמכות לא יזוזו בצורה נכונה. אם מתרחשת שגיאה מסוג הרשאה שאינו נתמך, שרת ה-proxy לא נכנס לתהליך השגיאה, כצפוי.

GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken

שגיאות בפריסה

השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שכולל את המדיניות הזו.

שם השגיאה סיבה
InvalidValueForExpiresIn

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

InvalidValueForRefreshTokenExpiresIn לרכיב <RefreshTokenExpiresIn>, הערכים החוקיים הם מספרים שלמים חיוביים ו--1.
InvalidGrantType סוג מענק לא חוקי צוין ברכיב <SupportedGrantTypes>. רשימת הסוגים התקינים זמינה בחומר העזר בנושא מדיניות.
ExpiresInNotApplicableForOperation חשוב לוודא שתוקף הפעולות שצוינו במשתנה <Operations> יפוג. לדוגמה, הפעולהVerifyToken לא עושה זאת.
RefreshTokenExpiresInNotApplicableForOperation חשוב לוודא שהפעולות שצוינו באלמנט <Operations> תומכות באסימון הרענון. לדוגמה, הפעולהVerifyToken לא עושה זאת.
GrantTypesNotApplicableForOperation חשוב לוודא שסוגי ההרשאות שצוינו בערך <SupportedGrantTypes> נתמכים בפעולה שצוינה.
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

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

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

אם הערך של <GenerateResponse> הוא true, המדיניות תחזיר שגיאות בפורמט הזה לפעולות אימות ואימות. הרשימה המלאה מפורטת במאמר הפנייה לתגובת שגיאות HTTP של OAuth.

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

דוגמה לכלל שגיאה

<FaultRule name=OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

סכימת מדיניות

כל סוג מדיניות מוגדר על ידי סכימת XML (.xsd). לידיעתך, סכימות המדיניות זמינות ב-GitHub.

עבודה עם הגדרת ברירת המחדל של OAuth

כל ארגון (גם ארגון לתקופת ניסיון בחינם) ב-Apigee Edge מקבל נקודת קצה (endpoint) של אסימון OAuth. נקודת הקצה מוגדרת מראש עם כללי מדיניות בשרת ה-API שנקראים oauth. אפשר להתחיל להשתמש בנקודת הקצה של האסימון מיד אחרי יצירת חשבון ב-Apigee Edge. לפרטים נוספים אפשר לעיין במאמר הסבר על נקודות קצה של OAuth.

מחיקה של אסימוני גישה

כברירת מחדל, אסימוני OAuth2 נמחקים באופן סופי ממערכת Apigee Edge 3 ימים (259,200 שניות) אחרי שהתוקף של אסימון הגישה ואסימון הרענון (אם קיים) פג. במקרים מסוימים, כדאי לשנות את ברירת המחדל. לדוגמה, יכול להיות שכדאי לקצר את זמן המחיקה כדי לחסוך מקום בכונן אם נוצרים מספר גדול של אסימונים.

אם אתם משתמשים ב-Edge for Private Cloud, תוכלו לשנות את ברירת המחדל על ידי הגדרה של מאפייני הארגון, כמו שמוסבר בסעיף הזה. (מחיקה למשך 3 ימים של אסימונים שפג תוקפם רלוונטית ל-Edge for Private Cloud בגרסה 4.19.01 ואילך. בגרסאות קודמות, מרווח הזמן למחיקה שמוגדר כברירת מחדל הוא 180 יום.)

עדכון הגדרות המחיקה לצמיתות של גרסת Edge Private Cloud 4.16.01 ואילך

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

עדכון הגדרות המחיקה לצמיתות של 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"}

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