מדיניות RevokeOAuthV2

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

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

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

המדיניות RevokeOAuthV2 מבטלת אסימוני גישה מסוג OAuth2 שמשויכים למזהה אפליקציית מפתח, למזהה משתמש קצה של אפליקציה או לשניהם.

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

משתמשים במדיניות OAuthv2 כדי ליצור אסימון גישה מסוג OAuth 2.0. אסימון שנוצר על ידי Apigee מופיע בפורמט הבא:

{
  "issued_at" : "1421847736581",
  "application_name" : "a68d01f8-b15c-4be3-b800-ceae8c456f5a",
  "scope" : "READ",
  "status" : "approved",
  "api_product_list" : "[PremiumWeatherAPI]",
  "expires_in" : "3599", //--in seconds
  "developer.email" : "tesla@weathersample.com",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
  "access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
  "organization_name" : "myorg",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

הרכיב application_name מכיל את מזהה האפליקציה של המפתח שמשויך לטוקן.

כברירת מחדל, Apigee לא כולל את מזהה משתמש הקצה בטוקן. אפשר להגדיר את Apigee כך שיכלול את מזהה משתמש הקצה על ידי הוספת הרכיב <AppEndUser> אל מדיניות OAuthv2:

<OAuthV2 name="GenerateAccessTokenClient">
    <Operation>GenerateAccessToken</Operation>
    ...
    <AppEndUser>request.queryparam.app_enduser</AppEndUser>
</OAuthV2>

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

{
 "issued_at" : "1421847736581",
 "application_name" : "a68d01f8-b15c-4be3-b800-ceae8c456f5a",
 "scope" : "READ",
 "app_enduser" : "6ZG094fgnjNf02EK",
 "status" : "approved",
 "api_product_list" : "[PremiumWeatherAPI]",
 "expires_in" : "3599", //--in seconds
 "developer.email" : "tesla@weathersample.com",
 "organization_id" : "0",
 "token_type" : "BearerToken",
 "client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
 "access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
 "organization_name" : "myorg",
 "refresh_token_expires_in" : "0", //--in seconds
 "refresh_count" : "0"
}

ביטול לפי מזהה אפליקציית המפתח

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

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

ביטול הרשאה לפי מזהה משתמש קצה באפליקציה

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

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

כדי לקבל מזהה משתמש קצה של אפליקציה, משתמשים בMethod: organizations.developers.get.

דוגמאות

בדוגמאות הבאות נעשה שימוש במדיניות Revoke OAuth V2 (ביטול OAuth V2) כדי לבטל אסימוני גישה מסוג OAuth2.

מזהה האפליקציה של המפתח

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

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

<RevokeOAuthV2 continueOnError="false" enabled="true" name="MyRevokeTokenPolicy">
  <DisplayName>Revoke OAuth v2.0-1</DisplayName>
  <AppId ref="request.queryparam.app_id"></AppId>
</RevokeOAuthV2>

בהינתן המזהה של אפליקציית המפתח, המדיניות מבטלת את טוקן הגישה.

ביטול לפני חותמת הזמן

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

בדוגמה הבאה מבוטלים אסימוני הגישה לאפליקציית מפתח שנוצרה לפני 1 ביולי 2019:

<RevokeOAuthV2 continueOnError="false" enabled="true" name="MyRevokeTokenPolicy">
  <DisplayName>Revoke OAuth v2.0-1</DisplayName>
  <AppId ref="request.queryparam.app_id"></AppId>
  <RevokeBeforeTimestamp>1561939200000</RevokeBeforeTimestamp>
</RevokeOAuthV2>

האלמנט <RevokeBeforeTimestamp> מקבל מספר שלם (long) של 64 ביט שמייצג את מספר אלפיות השנייה שחלפו מאז חצות, ב-1 בינואר 1970 לפי שעון UTC.

הפניה לרכיב

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RevokeOAuthV2 continueOnError="false" enabled="true" name="GetOAuthV2Info-1">
  <DisplayName>Get OAuth v2.0 Info 1</DisplayName>
  <AppId ref="variable"></AppId>
  <EndUserId ref="variable"></EndUserId>
  <RevokeBeforeTimestamp ref="variable"></RevokeBeforeTimestamp>
  <Cascade>false</Cascade>
</RevokeOAuthV2>

מאפיינים של <RevokeOAuthV2>

<RevokeOAuthV2 continueOnError="false" enabled="true" name="Revoke-OAuth-v20-1">

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

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

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

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

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

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

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

 FALSE אופציונלי
enabled

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

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

 TRUE אופציונלי

אלמנט <DisplayName>

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

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

לא רלוונטי

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

אלמנט <AppId>

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

<AppId>appIdString</AppId>

or:

<AppId ref="request.queryparam.app_id"></AppId>
ברירת מחדל

‫request.formparam.app_id (בפורמט x-www-form-urlencoded ומופיע בגוף הבקשה)
נוכחות

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

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

רכיב <Cascade>

אם true ויש לכם אסימון גישה אטום מסורתי, גם אסימון הרענון וגם אסימון הגישה יבוטלו אם יש התאמה ל-<AppId> או ל-<EndUserId>. אם יש לכם אסימון גישה מסוג JWT, רק אסימון הרענון שהונפק עם אסימון הגישה יבוטל. אסימוני גישה מסוג JWT לא ניתנים לביטול. אם false, רק אסימון הגישה יבוטל ואסימון הרענון לא ישתנה. אותו התנהגות חלה רק על אסימוני גישה אטומים. אי אפשר לבטל אסימוני גישה מסוג JWT.

<Cascade>false<Cascade>
ברירת מחדל

FALSE
נוכחות

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

רכיב <EndUserId>

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

<EndUserId>userIdString</EndUserId>

or:

<EndUserId ref="request.queryparam.access_token"></EndUserId>
ברירת מחדל

‫request.formparam.enduser_id (בפורמט x-www-form-urlencoded ומופיע בגוף הבקשה)
נוכחות

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

משתנה של זרימת נתונים שמכיל מחרוזת של User-ID, או מחרוזת מילולית.

אלמנט <RevokeBeforeTimestamp>

ביטול טוקנים שהונפקו לפני חותמת הזמן. האלמנט הזה פועל עם <AppId> ו-<EndUserId> כדי לאפשר לכם לבטל את האסימונים לפני שעה מסוימת. ערך ברירת המחדל הוא השעה שבה המדיניות מופעלת.

<RevokeBeforeTimestamp>timeStampString</RevokeBeforeTimestamp>

or:

<RevokeBeforeTimestamp ref="request.queryparam.revoke_since_timestamp"></RevokeBeforeTimestamp>
ברירת מחדל

חותמת הזמן שבה המדיניות מופעלת.
נוכחות

אופציונלי
סוג מספר שלם (long) בן 64 ביט שמייצג את מספר המילישניות שחלפו מאז חצות, ב-1 בינואר 1970 לפי שעון UTC.
ערכים תקינים

משתנה של זרימת נתונים שמכיל חותמת זמן, או חותמת זמן מילולית. חותמת הזמן לא יכולה להיות בעתיד ולא יכולה להיות לפני 1 בינואר 2014.

משתני Flow

המדיניות RevokeOAuthV2 לא מגדירה משתני זרימה.

הפניה לשגיאה

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

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

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

קוד תקלה סטטוס HTTP מטרה
steps.oauth.v2.InvalidFutureTimestamp 500 חותמת הזמן לא יכולה להיות בעתיד.
steps.oauth.v2.InvalidEarlyTimestamp 500 חותמת הזמן לא יכולה להיות מוקדמת מ-1 בינואר 2014.
steps.oauth.v2.InvalidTimestamp 500 חותמת הזמן לא תקינה.
steps.oauth.v2.EmptyAppAndEndUserId 500 אי אפשר להשאיר את השדות AppdId ו-EndUserId ריקים.

שגיאות בהטמעה

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

משתני תקלות

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

משתנים כאשר: דוגמה
fault.name="fault_name" ‫fault_name הוא שם התקלה, כפי שמופיע בטבלה Runtime errors שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה. fault.name Matches "IPDeniedAccess"
oauthV2.policy_name.failed ‫policy_name הוא השם שהמשתמש הגדיר למדיניות שגרמה לשגיאה. oauthV2.GetTokenInfo.failed = true
oauthV2.policy_name.fault.name ‫policy_name הוא השם שהמשתמש הגדיר למדיניות שגרמה לשגיאה. oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id
oauthV2.policy_name.fault.cause ‫policy_name הוא השם שהמשתמש הגדיר למדיניות שגרמה לשגיאה. oauthV2.GetTokenInfo.cause = ClientID is Invalid

דוגמה לתגובת שגיאה

{
   "fault":{
      "faultstring":"Timestamp is in the future.",
      "detail":{
         "errorcode":"steps.oauth.v2.InvalidFutureTimestamp"
      }
   }
}

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

<FaultRule name="RevokeOAuthV2 Faults">
    <Step>
        <Name>AM-InvalidTimestamp</Name>
    </Step>
    <Condition>(fault.name = "InvalidFutureTimestamp")</Condition>
</FaultRule>

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