מדיניות OAuthV2

מדיניות ניתנת להרחבה

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

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

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

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

דוגמאות

VerifyAccessToken

VerifyAccessToken

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

<OAuthV2 name="OAuthV2-Verify-Access-Token">
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

אפליקציית לקוח תצטרך לשלוח בקשה עם טוקן. לדוגמה, באמצעות curl:

$ curl https://API_ENDPOINT/weather/forecastrss?w=12797282 \
  -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z"

כאשר API_ENDPOINT הוא הדומיין שמשמש לגישה לממשקי ה-API, כפי שהוגדר במערכת Apigee.

כברירת מחדל, מדיניות OAuthV2 מחלצת את אסימון הגישה מכותרת Authorization, ומסירה את הקידומת Bearer. אפשר לשנות את התנהגות ברירת המחדל הזו באמצעות רכיב ההגדרה AccessToken.

GenerateAccessToken

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

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

GenerateAuthorizationCode

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

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

RefreshAccessToken

רענון של טוקן גישה

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

אסימוני גישה מסוג JWT

אסימוני גישה מסוג JWT

דוגמאות שמראות איך ליצור, לאמת ולרענן אסימוני גישה מסוג JWT מופיעות במאמר שימוש באסימוני גישה מסוג JWT.

טוקן של זרימת התגובה

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

לפעמים צריך ליצור טוקן גישה בתהליך התגובה. לדוגמה, יכול להיות שתעשו את זה בתגובה לאימות מותאם אישית שבוצע בשירות לקצה העורפי. בדוגמה הזו, תרחיש השימוש דורש גם אסימון גישה וגם אסימון רענון, ולכן לא ניתן להשתמש בסוג ההרשאה המרומז. במקרה הזה, נשתמש בסוג ההרשאה password כדי ליצור את הטוקן. כפי שאפשר לראות, כדי שזה יעבוד צריך להעביר כותרת הבקשה של הרשאה עם מדיניות 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 clientId = context.getVariable("local_clientid");
var clientSecret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+ CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(clientId + ':' + clientSecret)));

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

הפניה לרכיב

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

 לא רלוונטי חובה
continueOnError

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

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

 FALSE אופציונלי
enabled

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

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

 TRUE אופציונלי
async

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

 FALSE הוצא משימוש

אלמנט <DisplayName>

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

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

לא רלוונטי

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

אלמנט <AccessToken>

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

כברירת מחדל, כשהערך של Operation הוא VerifyAccessToken, המדיניות מצפה שאסימון הגישה יישלח בכותרת Authorization כאסימון מסוג bearer, כלומר עם הקידומת "Bearer", ואחריה רווח אחד. אפשר לשנות את ברירת המחדל הזו באמצעות הרכיב הזה, ולציין את שם המשתנה שמכיל את אסימון הגישה לאימות. כשמשתמשים ברכיב הזה, המדיניות לא מחפשת קידומת בתוכן של המשתנה כברירת מחדל. אם רוצים לציין שהמדיניות תחפש קידומת, צריך להשתמש גם ברכיב AccessTokenPrefix.

דוגמאות:

  • כשהגדרת המדיניות היא:

      <OAuthV2 name="OAuthV2-Verify-Access-Token-in-Header">
      <Operation>VerifyAccessToken</Operation>
      <AccessToken>request.header.access_token</AccessToken>
  </OAuthV2>

    כדי להעביר את האסימון באמצעות curl, אפשר להשתמש בפקודה הבאה:

      curl https://API_ENDPOINT/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

  • כשהגדרת המדיניות היא:

      <OAuthV2 name="OAuthV2-Verify-Access-Token-in-QueryParam">
      <Operation>VerifyAccessToken</Operation>
      <AccessToken>request.queryparam.token</AccessToken>
  </OAuthV2>

    כדי להעביר את האסימון באמצעות curl, אפשר להשתמש בפקודה הבאה:

      curl "https://API_ENDPOINT/oauth2/validate?token=Rft3dqrs56Blirls56a"

כאשר API_ENDPOINT הוא הדומיין שמשמש לגישה לממשקי ה-API, כפי שהוגדר במערכת Apigee.

ברירת מחדל

לא רלוונטי

נוכחות

אופציונלי
סוג String
ערכים אפשריים

כל שם משתנה
בשימוש בפעולות
  • VerifyAccessToken

אלמנט <AccessTokenPrefix>

<AccessTokenPrefix>Prefix</AccessTokenPrefix>

כברירת מחדל, כשהערך של Operation הוא VerifyAccessToken, המדיניות מצפה שטוקן הגישה יישלח בכותרת Authorization כטוקן מסוג bearer, כלומר עם הקידומת Bearer, ואחריה רווח אחד. אם משתמשים ברכיב AccessToken כדי לציין מיקום אחר לטוקן הגישה הנכנס, אפשר גם להשתמש ברכיב הזה, AccessTokenPrefix, כדי לציין קידומת אחרת, לא סטנדרטית.

לדוגמה, אם מציינים:

<OAuthV2 name="OAuthV2-Verify-Access-Token-Alternative-Header">
    <Operation>VerifyAccessToken</Operation>
    <AccessToken>request.header.token</AccessToken>
    <AccessTokenPrefix>KEY</AccessTokenPrefix>
</OAuthV2>

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

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

האלמנט הזה תקף רק אם משתמשים גם באלמנט AccessToken.

ברירת מחדל

-none-

נוכחות

אופציונלי
סוג String
ערכים אפשריים

כל מחרוזת
בשימוש בפעולות
  • VerifyAccessToken

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

מציין את אלגוריתם ההצפנה שמשמש לחתימה על אסימון גישה מסוג JWT. אלגוריתמים מסוג RSA‏ (RS*) משתמשים בזוג מפתחות ציבורי/פרטי, ואלגוריתמים מסוג HMAC‏ (HS*) משתמשים בסוד משותף. הרכיב הזה נדרש לפעולות GenerateJWTAccessToken, VerifyJWTAccessToken ו-RefreshJWTAccessToken.

ברירת מחדל לא רלוונטי
נוכחות מאפיין חובה כשמשתמשים בפעולות GenerateJWTAccessToken, VerifyJWTAccessToken ו-RefreshJWTAccessToken.
סוג String
ערכים אפשריים HS256, ‏ HS384, ‏ HS512, ‏ RS256, ‏ RS384, ‏ RS512

אלמנט <AppEndUser>

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

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

לדוגמה, request.queryparam.app_enduser מציין שצריך להוסיף את AppEndUser כפרמטר של שאילתה, כמו ?app_enduser=ntesla@theramin.com. כדי לדרוש את AppEndUser בכותרת HTTP, לדוגמה, מגדירים את הערך הזה ל-request.header.app_enduser.

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

ברירת מחדל

לא רלוונטי

נוכחות

אופציונלי
סוג String
ערכים אפשריים

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

<Attributes/Attribute>

<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 מאפשרת להשיג את היעד הזה. עם זאת, אם בהמשך נוצר טוקן גישה חדש באמצעות טוקן רענון, המאפיינים המותאמים אישית המקוריים מטוקן הגישה יופיעו בתגובה של טוקן הרענון. הסיבה לכך היא שמערכת Apigee לא זוכרת שהמאפיין display הוגדר במקור ל-false במדיניות של יצירת טוקן גישה – המאפיין המותאם אישית הוא פשוט חלק מהמטא-נתונים של טוקן הגישה.

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

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

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

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

ברירת מחדל

N/A

נוכחות

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

אלמנט <CacheExpiryInSeconds>

<CacheExpiryInSeconds ref="propertyset.settings.token-ttl">60</CacheExpiryInSeconds>

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

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

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

ברירת מחדל

 לא רלוונטי

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

נוכחות

 אופציונלי

סוג

 מספר שלם

ערכים אפשריים

 מספר שלם חיובי שאינו אפס. מציין את זמן התפוגה בשניות.
בשימוש בפעולות
  • VerifyAccessToken

מאפיינים

בטבלה הבאה מפורטים המאפיינים של הרכיב <CacheExpiryInSeconds>

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

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

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

 לא רלוונטי אופציונלי

רכיב <ClientId>

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

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

ברירת מחדל

request.formparam.client_id (a x-www-form-urlencoded and specified in the request body)

נוכחות

אופציונלי
סוג String
ערכים אפשריים משתנה הזרימה: request.formparam.client_id
שימוש בסוגי מענקים
  • authorization_code
  • סיסמה
  • משתמע
  • client_credentials

אפשר להשתמש בו גם עם הפעולה GenerateAuthorizationCode.

אלמנט <Code>

<Code>request.queryparam.code</Code>

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

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

ברירת מחדל

request.formparam.code (a x-www-form-urlencoded and specified in the request body)

נוכחות

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

אלמנט <ExpiresIn>

<ExpiresIn>10000</ExpiresIn>

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

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

‫Apigee שומר את הישויות הבאות במטמון למשך 180 שניות לפחות אחרי הגישה לישויות.

  • אסימוני גישה מסוג OAuth. המשמעות היא שהרכיב ExpiresIn במדיניות OAuth v2 לא יוכל להגדיר תפוגה של אסימון גישה בפחות מ-180 שניות.
  • ישויות של Key Management Service‏ (KMS) (אפליקציות, מפתחים, מוצרי API).
  • מאפיינים מותאמים אישית בטוקנים של OAuth ובסוגי ישויות של KMS.

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

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

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

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

ברירת מחדל

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

נוכחות

אופציונלי
סוג מספר שלם
ערכים אפשריים

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

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

אלמנט <ExternalAccessToken>

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

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

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

רכיב <ExternalAuthorization>

<ExternalAuthorization>true</ExternalAuthorization>

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

ברירת מחדל

FALSE

נוכחות

אופציונלי
סוג בוליאני
ערכים אפשריים true or false
שימוש בסוגי מענקים
  • authorization_code
  • סיסמה
  • client_credentials

רכיב <ExternalAuthorizationCode>

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

היא מציינת ל-Apigee איפה למצוא קוד הרשאה חיצוני (קוד הרשאה שלא נוצר על ידי Apigee).

המשתנה 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 איפה נמצא טוקן רענון חיצוני (טוקן רענון שלא נוצר על ידי Apigee).

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

אלמנט <GenerateResponse>

<GenerateResponse enabled='true'/>

אם הערך הוא true או אם המאפיין enabled לא מצוין, המדיניות יוצרת תגובה ומחזירה אותה. לדוגמה, עבור 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 או אם לא מציינים את הרכיב <GenerateResponse>, לא נשלחת תשובה. במקום זאת, קבוצה של משתני זרימה מאוכלסת בערכים שקשורים לפונקציה של המדיניות. לדוגמה, משתנה זרימה בשם oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code מאוכלס בקוד הרשאה חדש. שימו לב שהערך של expires_in מופיע בתשובה בשניות.

ברירת מחדל

TRUE

נוכחות

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

רכיב <GenerateErrorResponse>

<GenerateErrorResponse enabled='true'/>

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

ברירת מחדל

FALSE

נוכחות

אופציונלי
סוג מחרוזת
ערכים אפשריים true or 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. אפשר לעיין גם במאמר קבלת אסימוני OAuth 2.0.

ברירת מחדל

request.formparam.grant_type (a x-www-form-urlencoded and specified in the request body)

נוכחות

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

אלמנט <Operation>

<Operation>GenerateAuthorizationCode</Operation>

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

ברירת מחדל

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

נוכחות

אופציונלי
סוג String
ערכים אפשריים
  • ‫GenerateAccessToken – יוצר טוקן גישה. אפשר גם לעיין במאמר בנושא קבלת טוקנים מסוג OAuth 2.0.
  • ‫GenerateAccessTokenImplicitGrant – יוצר אסימון גישה לסוג ההרשאה המשתמעת. אפשר גם לעיין במאמר בנושא קבלת טוקנים מסוג OAuth 2.0.
  • ‫GenerateAuthorizationCode – יוצר קוד הרשאה. השימוש נעשה עם סוג ההרשאה Authorization Code Grant. אפשר גם לעיין במאמר בנושא קבלת טוקנים מסוג OAuth 2.0.
  • ‫RefreshAccessToken – החלפת טוקן רענון בטוקן גישה חדש. אפשר גם לעיין במאמר בנושא קבלת טוקנים מסוג OAuth 2.0.
  • ‫VerifyAccessToken – מוודא שאסימון הגישה שנשלח בבקשה הוא תקף. אפשר לעיין בדוגמה VerifyAccessToken שלמעלה ובמאמר אימות אסימוני גישה.
  • ‫InvalidateToken – ביטול של טוקן גישה. אחרי ביטול של טוקן, לקוחות לא יכולים להשתמש בו כדי להפעיל API מוגן. אפשר לקרוא גם על אישור וביטול של אסימוני גישה.
  • ‫ValidateToken – מחזיר לתוקף או "מאשר" אסימון גישה שבוטל בעבר. אפשר לקרוא גם על אישור וביטול של אסימוני גישה.

פעולות נוספות באסימוני גישה מסוג JWT

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

אלמנט <PassWord>

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

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

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

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

אפשר גם לעיין במאמר בנושא קבלת טוקנים מסוג OAuth 2.0.

ברירת מחדל

request.formparam.password (a x-www-form-urlencoded and specified in the request body)

נוכחות

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

<PrivateKey>/<Value>

<PrivateKey>
  <Value ref="variable-name-here"/>
</PrivateKey>

המפתח הפרטי שמשמש לאימות או לחתימה על אסימוני גישה בפורמט JWT באמצעות אלגוריתם RSA. משתמשים במאפיין ref כדי להעביר את המפתח במשתנה של זרימת נתונים. השימוש במאפיין הזה מותר רק אם הערך של רכיב Algorithm הוא אחד מהערכים RS256,‏ RS384 או RS512. מידע נוסף זמין במאמר בנושא שימוש בפעולות של אסימוני OAuth מסוג JWT.

ברירת מחדל לא רלוונטי
נוכחות חובה אם הערך של רכיב Algorithm הוא אחד מהערכים הבאים: HS256,‏ HS384 או HS512.
סוג String
ערכים אפשריים משתנה של זרימת נתונים שמכיל מחרוזת שמייצגת ערך של מפתח פרטי מסוג RSA שעבר קידוד PEM.

<PublicKey>/<Value>

<PublicKey>
   <Value ref="variable-name-here"/>
</PublicKey>

מציינים את המפתח הציבורי או את האישור הציבורי שמשמשים לאימות החתימה באסימון גישה בפורמט JWT שנחתם באמצעות אלגוריתם RSA. משתמשים במאפיין ref כדי להעביר את המפתח או האישור במשתנה של Flow. השימוש במאפיין הזה מותר רק אם הערך של רכיב Algorithm הוא אחד מהערכים RS256,‏ RS384 או RS512.

ברירת מחדל לא רלוונטי
נוכחות כדי לאמת JWT שנחתם באמצעות אלגוריתם RSA, צריך להשתמש ברכיבי Certificate,‏ JWKS או Value.
סוג String
ערכים אפשריים משתנה או מחרוזת של זרימת נתונים.

רכיב <RedirectUri>

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

מציין איפה בבקשה מערכת Apigee צריכה לחפש את הפרמטר redirect_uri.

מידע על מזהי URI של הפניה לכתובת אחרת

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

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

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

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

ברירת מחדל

request.formparam.redirect_uri (a x-www-form-urlencoded and specified in the request body)

נוכחות

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

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

אלמנט <RefreshToken>

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

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

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

ברירת מחדל

request.formparam.refresh_token (a x-www-form-urlencoded and specified in the request body)

נוכחות

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

אלמנט <RefreshTokenExpiresIn>

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

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

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

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

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

ברירת מחדל

‫2,592,000,000 מילי-שניות (30 ימים) (בתוקף מ-31 במאי 2023)

נוכחות

אופציונלי
סוג מספר שלם
ערכים אפשריים

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

רכיב <ResponseType>

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

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

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

ברירת מחדל

request.formparam.response_type (a x-www-form-urlencoded and specified in the request body)

נוכחות

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

סוג String
ערכים אפשריים ‫code (לסוג ההרשאה Authorization Code Grant) או token (לסוג ההרשאה Implicit Grant)
שימוש בסוגי מענקים
  • משתמע
  • משמש גם בפעולה GenerateAuthorizationCode.

רכיב <ReuseRefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

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

ברירת מחדל

false

נוכחות

אופציונלי
סוג בוליאני
ערכים אפשריים

true או false
שימוש בסוגי מענקים
  • refresh_token

רכיב <RFCCompliantRequestResponse>

<RFCCompliantRequestResponse>[true | false]</RFCCompliantRequestResponse>

מדיניות OAuthV2, עם הפעולה GenerateAccessToken, יכולה להחזיר תגובה שלא תואמת למפרטים הקשורים של IETF OAuth 2.0, כולל RFC 6749 ו-RFC 6750. אם כוללים את הרכיב RFCCompliantRequestResponse במדיניות, עם ערך של true, מדיניות OAuthV2 מחזירה תגובה שתואמת ל-RFC.

בטבלה הבאה מוצגים ההבדלים בחלק מהערכים שמוחזרים על ידי מדיניות OAuthV2, בהתאם לערך של הרכיב RFCCompliantRequestResponse (true או false).

רכיב הערך הוא false או לא קיים הערך הוא true
Cache-Control כותרת HTTP לא סופק תגובות שגיאה ותגובות שאינן שגיאה יכללו את שדה כותרת התגובה של HTTP Cache-Control כדי לעמוד בדרישות של RFC2616 (Hypertext Transfer Protocol – HTTP/1.1), עם ערך של no-store בכל תגובה שמכילה אסימונים, פרטי כניסה או מידע רגיש אחר, וגם את שדה כותרת התגובה Pragma עם ערך של no-cache.
נכס אחד ("token_type") בתגובה של טוקן תקין

ערך token_type שלא עומד בדרישות.

{
 ...
 "token_type": "BearerToken",
 ...
}

ערך תקין של token_type.

{
 ...
 "token_type": "Bearer",
 ...
}
מאפייני "expires_in" ו-"refresh_token_expires_in" בתגובה חוקית של טוקן

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

{
 ...
 "expires_in": "3600",
 "refresh_token_expires_in":
   "345600",
 ...
}

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

{
 ...
 "expires_in": 3600,
 "refresh_token_expires_in":
   345600,
 ...
}
תגובת שגיאה לטוקן רענון שתוקפו פג כשgrant_type = refresh_token

תגובות השגיאה לא תאמו ל-RFC 6749. דוגמה:

{
 "ErrorCode": "InvalidRequest",
 "Error": "Refresh Token expired"
}

מטענים ייעודיים (payloads) של תגובות שגיאה יכללו את הרכיבים "error" ו-"error_description". דוגמה:

{
 "error": "invalid_grant",
 "error_description":
   "refresh token expired"
}

ברירת מחדל

‫false: כברירת מחדל, המדיניות תציג התנהגויות מסוימות שלא תואמות ל-RFC, כפי שמתואר למעלה.

נוכחות

אופציונלי
סוג בוליאני
ערכים אפשריים true או false
שימוש בסוגי מענקים הכול

<SecretKey>/<Value>

<SecretKey>
  <Value ref="your-variable-name"/>
</SecretKey>

מציין את המפתח הסודי שמשמש לאימות או לחתימה על אסימוני גישה בפורמט JWT באמצעות אלגוריתם HMAC. השימוש במאפיין הזה מותר רק אם האלגוריתם הוא אחד מהאלגוריתמים הבאים: HS256,‏ HS384 או HS512. משתמשים במאפיין ref כדי להעביר את המפתח במשתנה של זרימת נתונים. מידע נוסף זמין במאמר שימוש בפעולות של אסימוני JWT OAuth.

מערכת Apigee אוכפת חוזק מינימלי של מפתח לאלגוריתמים HS256/HS384/HS512. אורך המפתח המינימלי ל-HS256 הוא 32 בייטים, ל-HS384 הוא 48 בייטים ול-HS512 הוא 64 בייטים. שימוש במפתח עם חוזק נמוך יותר גורם לשגיאת זמן ריצה.

ברירת מחדל לא רלוונטי
נוכחות נדרש לאלגוריתמים של HMAC.
סוג String
ערכים אפשריים משתנה של תהליך

אלמנט <Scope>

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

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

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

<Scope>A B</Scope>

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

ברירת מחדל

אין היקף הרשאות

נוכחות

אופציונלי
סוג String
ערכים אפשריים

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

אם משתמשים בפרמטר הזה עם VerifyAccessToken, צריך להזין רשימה של שמות היקפים (מחרוזות) שמופרדים באמצעות רווחים.
שימוש בסוגי מענקים
  • authorization_code
  • משתמע
  • סיסמה
  • client_credentials
  • אפשר להשתמש גם בפעולות GenerateAuthorizationCode ו-VerifyAccessToken.

אלמנט <State>

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

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

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

ברירת מחדל

אין מדינה

נוכחות

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

אלמנט <StoreToken>

 <StoreToken>true</StoreToken>

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

ברירת מחדל

FALSE

נוכחות

אופציונלי
סוג בוליאני
ערכים אפשריים true or 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. יכול להיות שנקודת קצה תתמוך בכמה סוגי הרשאות (כלומר, אפשר להגדיר נקודת קצה אחת להפצת טוקנים של גישה לכמה סוגי הרשאות). מידע נוסף על נקודות קצה זמין במאמר הסבר על נקודות קצה של OAuth. סוג ההרשאה מועבר בבקשות לאסימון בפרמטר grant_type.

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

ברירת מחדל

קוד הרשאה וקוד משתמע

נוכחות

חובה
סוג String
ערכים אפשריים
  • client_credentials
  • authorization_code
  • סיסמה
  • משתמע

אלמנט <Tokens>/<Token>

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

רכיב <UserName>

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

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

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

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

אפשר גם לעיין במאמר בנושא קבלת טוקנים מסוג OAuth 2.0.

ברירת מחדל

request.formparam.username (a x-www-form-urlencoded and specified in the request body)

נוכחות

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

אימות טוקנים של גישה

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

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

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

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

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

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

שם תיאור
היקף

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

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

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

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

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

אפשר להגדיר רק מיקום אחד לכל פרמטר.

משתני Flow

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

הפעולה VerifyAccessToken

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

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

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

(Apigee hybrid בלבד) מציין למה טוקן הגישה בוטל. הפעולה לא נתמכת עבור VerifyJWTAccessToken.

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

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

משתני הזרימה הבאים מכילים מידע על AppGroup עבור הטוקן, והם מאוכלסים על ידי המדיניות. המאפיינים האלה של AppGroup מאוכלסים רק אם הערך של verifyapikey.{policy_name}.app.appType הוא AppGroup.

משתנים תיאור
appgroup.displayName השם המוצג של קבוצת האפליקציות.
appgroup.name השם של קבוצת האפליקציות.
appgroup.id מזהה קבוצת האפליקציות.
appOwnerStatus הסטטוס של בעל האפליקציה: active,‏ inactive או login_lock.
created_at חותמת התאריך והשעה שבהן נוצרה קבוצת האפליקציות.
created_by כתובת האימייל של המפתח שיצר את קבוצת האפליקציות.
last_modified_at חותמת התאריך והשעה שבה בוצע השינוי האחרון ב-AppGroup.
last_modified_by כתובת האימייל של המפתח שביצע את השינוי האחרון ב-AppGroup.
{appgroup_custom_attributes} כל מאפיין מותאם אישית של קבוצת אפליקציות. מציינים את השם של המאפיין המותאם אישית.

משתנים ספציפיים למפתחים

אם הערך של app.appType הוא Developer, מאפייני המפתח יאוכלסו.

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

פעולה GenerateAuthorizationCode

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

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

דוגמה: oauthv2authcode.GenerateCodePolicy.code

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

הפעולות GenerateAccessToken ו-RefreshAccessToken

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

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

הפניה לשגיאה

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

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

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

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

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

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

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

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

ה-proxy ל-API או הפעולה שמופעלים כרגע לא נמצאים במוצר שמשויך לטוקן הגישה.

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

מידע נוסף על הסיבות לשגיאה הזו זמין גם במאמר Oauth2.0 Access Token Verification throws "Invalid API call as no apiproduct match found" error (אימות אסימון גישה מסוג Oauth2.0 מחזיר את השגיאה 'קריאה לא חוקית ל-API כי לא נמצאה התאמה למוצר API').

 VerifyAccessToken
steps.oauth.v2.InvalidClientIdentifier 500

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

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

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

 GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken

שגיאות זמן ריצה שספציפיות לטוקן JWT

קודי שגיאה בזמן ריצה ותיאורים של תהליכי אסימון אימות JWT תלויים בהקשר של תהליך OAuth2:

קודי שגיאה לתהליכי יצירה ורענון של טוקן JWT

בזרימות OAuth2 שיוצרות או מרעננות טוקנים של JWT, תגובות השגיאה תואמות לתגובות השגיאה שצוינו ב-RFC6749. פרטים נוספים זמינים במאמר בנושא Section 5.2 Error Response.

קודי שגיאה בתהליך אימות הטוקן

קודי השגיאה שמפורטים בטבלה הבאה רלוונטיים רק לפעולה VerifyAccessToken.

קוד תקלה סטטוס HTTP מטרה החריג שמוחזר על ידי פעולות
oauth.v2.JWTSigningFailed 401 המדיניות לא הצליחה לחתום על אסימון ה-JWT.

GenerateJWTAccessToken
oauth.v2.InvalidValueForJWTAlgorithm 401 הבעיה הזו מתרחשת כשהאלגוריתם לא מופיע בטוקן הגישה של JWT או כשהערך לא נתמך.

GenerateJWTAccessToken
VerifyJWTAccessToken

oauth.v2.InsufficientKeyLength 401 בשלב יצירת ה-JWT, אם המפתח קטן מהגודל המינימלי של האלגוריתמים HS384 או HS512

GenerateJWTAccessToken
VerifyJWTAccessToken

oauth.v2.JWTAlgorithmMismatch 401 האלגוריתם שצוין במדיניות Generate לא תאם לזה שצוין במדיניות Verify. האלגוריתמים שצוינו צריכים להיות זהים.

VerifyJWTAccessToken
oauth.v2.JWTDecodingFailed 401 המדיניות לא הצליחה לפענח את ה-JWT. יכול להיות ש-JWT פגום.

VerifyJWTAccessToken
oauth.v2.MissingMandatoryClaimsInJWT 401 השגיאה מתרחשת כשההצהרות הנדרשות לא מופיעות באסימון הגישה של JWT

VerifyJWTAccessToken
oauth.v2.InvalidJWTSignature 401 השגיאה הזו מתרחשת כשאי אפשר לאמת את החתימה של טוקן הגישה של JWT או כשהחתימה לא תקינה.

VerifyJWTAccessToken
oauth.v2.InvalidTypeInJWTHeader 401 השגיאה מתרחשת כשהסוג של ה-JWT הוא לא at+Jwt

VerifyJWTAccessToken

שגיאות פריסה

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

שם השגיאה מטרה
InvalidValueForExpiresIn

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

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

צריך לציין פעולה תקינה במדיניות הזו באמצעות הרכיב <Operation>.
TokenValueRequired צריך לציין ערך של טוקן <Token> באלמנט <Tokens>.

שגיאות פריסה ספציפיות לטוקן JWT

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

שם השגיאה מטרה
InvalidValueForAlgorithm האלגוריתם שצוין ברכיב <Algorithm> לא נמצא ברשימת האלגוריתמים הזמינים או שהוא לא קיים.
MissingKeyConfiguration חסרים רכיבי <SecretKey>, <PrivateKey> או <PublicKey> הנדרשים, בהתאם לאלגוריתם שבו נעשה שימוש.
EmptyValueElementForKeyConfiguration רכיב הצאצא הנדרש <Value> לא מוגדר ברכיבים <PrivateKey>, <PublicKey> או <SecretKey>
InvalidKeyConfiguration האלמנט <PrivateKey> לא נמצא בשימוש באלגוריתמים של משפחת RSA או שהאלמנט <SecretKey> לא נמצא בשימוש באלגוריתמים של משפחת HS.
EmptyRefAttributeForKeyconfiguration המאפיין ref של רכיב הצאצא <Value> של הרכיבים <PrivateKey>, <PublicKey> או <SecretKey> ריק.
InvalidVariableNameForKey שם משתנה הזרימה שצוין במאפיין ref של רכיב הצאצא <Value> של הרכיבים <PrivateKey>, <PublicKey> או <SecretKey> לא מכיל את הקידומת private.

משתני תקלות

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

משתנים כאשר: דוגמה
fault.name="fault_name" ‫fault_name הוא שם התקלה, כפי שמופיע בטבלה שגיאות בזמן ריצה שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה. fault.name = "InvalidRequest"
oauthV2.policy_name.failed ‫policy_name הוא השם שהמשתמש נתן למדיניות שגרמה לשגיאה. oauthV2.GenerateAccesstoken.failed = true
oauthV2.policy_name.fault.name ‫policy_name הוא השם שהמשתמש נתן למדיניות שגרמה לשגיאה. oauthV2.GenerateAccesstoken.fault.name = InvalidRequest
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>

טוקנים באחסון עוברים גיבוב

אם אתם משתמשים ב-Apigee hybrid או ב-Apigee, אסימוני הגישה ואסימוני הרענון של OAuthV2 מגובבים כברירת מחדל כשהם מאוחסנים במסד הנתונים של Cassandra בזמן הריצה. גיבוב מונע שימוש באסימונים אם מסד הנתונים נפרץ.

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

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

ניקוי טוקנים של גישה

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

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