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

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