ביטול טוקנים ואישור טוקנים

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

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

הסבר על ביטול טוקנים

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

התקן לביטול טוקנים מוגדר ב-IETF RFC 7009, מפרט ביטול הטוקנים של OAuth 2.0.

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

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

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

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

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

הנה דוגמה להגדרה של מדיניות OAuthV2 שמשתמשת בפעולה InvalidateToken: במקרה הזה, מכיוון שהמאפיין cascade ברכיב Token הוא true, ‏ Apigee מבטל גם את טוקן הגישה וגם את טוקן הרענון המשויך.

  <OAuthV2 name="InvalidateToken">
    <Operation>InvalidateToken</Operation>
    <Tokens>
      <Token type="accesstoken" cascade="true">request.queryparam.token</Token>
    </Tokens>
  </OAuthV2>

מידע נוסף על אופן הפעולה של מאפיין ה-cascade מופיע בקטע הבא בנושא מאפיינים של רכיב ה-Token.

‫<Tokens>/<Token> element

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

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

מאפיינים

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

      הערה: אם מעבירים אסימון שכבר בוטל למדיניות InvalidateToken, המדיניות לא מחזירה שגיאה, למרות שאולי מצפים לכך. לפעולה כזו אין השפעה.
  • ‫cascade (אופציונלי, בוליאני, ברירת מחדל: true) השימוש העיקרי במאפיין הזה הוא ביטול של טוקן רענון בלי לבטל את טוקן הגישה המשויך. כדאי להביא בחשבון את המקרים הבאים:
    • לבטל רק את טוקן הרענון ולא את טוקן הגישה שמשויך אליו. כדי לעשות זאת, מגדירים את הסוג של <Token> ל-refreshtoken ומגדירים את cascade ל-false.
    • מבטלים את טוקן הגישה ואת טוקן הרענון. כדי לעשות זאת, מגדירים את סוג ה-<Token> ל-accesstoken. הערך של cascade יכול להיות true (ברירת המחדל) או false. אם מגדירים אותו ל-true, גם טוקן הגישה וגם טוקן הרענון מבוטלים. אם מגדירים אותו ל-false, טוקן הגישה מבוטל ואי אפשר להשתמש בטוקן הרענון. הסבר נוסף מופיע בהערה שלמטה.
    • לבטל טוקן גישה בלי לבטל את טוקן הרענון המשויך. לא נתמך. הסבר נוסף מופיע בהערה שבהמשך.

הערה: מטעמי אבטחה, אם מבטלים טוקן גישה, גם טוקן הרענון המשויך יבוטל. לכן, אי אפשר להשתמש במאפיין cascade כדי לבטל רק אסימון גישה. לדוגמה, אם מגדירים את סוג ה-<Token> ל-accesstoken ומגדירים את cascade=false, אסימון הגישה מבוטל (כצפוי), אבל אי אפשר להשתמש באסימון הרענון המשויך. אי אפשר להשתמש בו כדי לרענן את אסימון הגישה שבוטל. מקרה השימוש העיקרי במאפיין cascade הוא כשרוצים לבטל רק את טוקן הרענון. במקרה כזה, מגדירים את סוג ה-<Token> ל-refreshtoken, ומגדירים את cascade=false. טוקן הרענון יבוטל, אבל טוקן הגישה המשויך אליו יישאר בתוקף (עד שהוא יפוג או יבוטל). מידע נוסף זמין בדיון הזה בפורום הקהילה.

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

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

<OAuthV2 name="ValidateToken">
  <Operation>ValidateToken</Operation>
  <Tokens>
    <Token type="refreshtoken" cascade="true">flow.variable</Token>
  </Tokens>
</OAuthV2>

‫<Tokens>/<Token> element

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

מאפיינים

  • ‫type (חובה, מחרוזת) סוג הטוקן שמזוהה על ידי המשתנה שצוין. הערכים הנתמכים הם accesstoken ו-refreshtoken.
  • ‫cascade (אופציונלי, בוליאני): כברירת מחדל, האפשרות הזו מוגדרת ל-true, והיא גורמת לאימות להתבצע גם על טוקנים משויכים. לכן, אם היא מוחלת על טוקן רענון, היא מוחלת גם על טוקן הגישה המשויך. אם היא מוחלת על טוקן גישה, היא מוחלת גם על טוקן הרענון המשויך. אם מגדירים את האפשרות הזו ל-false, האימות מתבצע רק על טוקן הגישה או טוקן הרענון שצוינו.