המדיניות GetOAuthV2Info

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

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

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

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

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

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

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

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

מידע נוסף זמין במאמר GetOAuthV2Info fails if token generated using product with resource paths בקהילת Apigee.

דוגמאות

בדוגמאות הבאות נעשה שימוש במדיניות Get OAuth V2 Info (קבלת מידע על OAuth V2) כדי לאחזר מידע על רכיבים שונים של תהליך העבודה של OAuth2, ולאחר מכן לגשת למידע הזה בתוך הקוד.

טוקן גישה

כדי לקבל הפניה לטוקן גישה, משתמשים ברכיב <AccessToken> במדיניות.

בדוגמה הבאה, המערכת מצפה למצוא את אסימון הגישה בפרמטר שאילתה בשם access_token (פרטי ההטמעה בפועל תלויים בכם):

<GetOAuthV2Info name="MyTokenAttrsPolicy">
  <AccessToken ref="request.queryparam.access_token"></AccessToken>
</GetOAuthV2Info>

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

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

var scope = context.getVariable('oauthv2accesstoken.MyTokenAttrsPolicy.scope');

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

קוד הרשאה

כדי לקבל מאפיינים של קוד הרשאה, משתמשים ברכיב <AuthorizationCode> במדיניות.

בדוגמה הבאה, המערכת מצפה למצוא את אסימון הגישה בפרמטר של טופס בשם code (פרטי ההטמעה בפועל תלויים בכם):

<GetOAuthV2Info name="MyAuthCodeAttrsPolicy">
  <AuthorizationCode ref="request.formparam.code"></AuthorizationCode>
</GetOAuthV2Info>

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

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

var attr = context.getVariable('oauthv2authcode.MyAuthCodeAttrsPolicy.custom_attribute_name');

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

טוקן רענון

כדי לקבל מאפיינים של טוקן לרענון, משתמשים ברכיב <RefreshToken> במדיניות.

בדוגמה הבאה, המערכת מצפה למצוא את אסימון הגישה בפרמטר שאילתה בשם refresh_token (פרטי ההטמעה בפועל תלויים בכם):

<GetOAuthV2Info name="MyRefreshTokenAttrsPolicy">
  <RefreshToken ref="request.queryparam.refresh_token"/>
</GetOAuthV2Info>

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

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

var attr = context.getVariable('oauthv2refreshtoken.MyRefreshTokenAttrsPolicy.accesstoken.custom_attribute_name');

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

סטטי

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

<GetOAuthV2Info name="GetTokenAttributes">
  <AccessToken>shTUmeI1geSKin0TODcGLXBNe9vp</AccessToken>
</GetOAuthV2Info>

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

מזהה לקוח

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

<GetOAuthV2Info name="GetClientAttributes">
  <ClientId ref="request.queryparam.client_id"></ClientId>
</GetOAuthV2Info>

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

context.getVariable("oauthv2client.GetClientAttributes.developer.email");
context.getVariable("oauthv2client.GetClientAttributes.developer.app.name");

---

הפניה לרכיב

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="GetOAuthV2Info-1"
    <DisplayName>Get OAuth v2.0 Info 1</DisplayName>
    <AccessToken ref="variable"></AccessToken>
    <AuthorizationCode ref="variable"></AuthorizationCode>
    <ClientId ref="variable"></ClientId>
    <RefreshToken ref="variable"></RefreshToken>
</GetOAuthV2Info>

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

<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="Get-OAuth-v20-Info-1">

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

מאפיין	תיאור	ברירת מחדל	נוכחות
name	השם הפנימי של המדיניות. הערך של מאפיין name יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. הערך הזה לא יכול לחרוג מ-255 תווים. אפשר להשתמש ברכיב <DisplayName> כדי לתת למדיניות תווית בשם אחר בשפה טבעית בכלי לעריכת פרוקסי בממשק הניהול.	לא רלוונטי	חובה
continueOnError	מגדירים את הערך false כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המדיניות. הגדרה ל-true מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מידע נוסף: הפעלת כללי תקלות מתבצעת רק במצב שגיאה (מידע על continueOnError) טיפול בתקלות בתהליך הנוכחי	FALSE	אופציונלי
enabled	מגדירים את המדיניות למצב true כדי לאכוף אותה. מגדירים את הערך false כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.	TRUE	אופציונלי
async	המאפיין הזה הוצא משימוש.	FALSE	הוצא משימוש

אלמנט <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

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

אלמנט <AccessToken>

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

<AccessToken ref="request.queryparam.access_token"></AccessToken>

ברירת מחדל:	request.formparam.access_token (a x-www-form-urlencoded and specified in the request body)
נוכחות:	אופציונלי
סוג:	String
ערכים תקינים:	משתנה של זרימת נתונים שמכיל מחרוזת של אסימון גישה, או מחרוזת מילולית.

אלמנט <AuthorizationCode>

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

<AuthorizationCode ref="request.queryparam.authorization_code"></AuthorizationCode>

ברירת מחדל:	request.formparam.access_token (a x-www-form-urlencoded and specified in the request body)
נוכחות:	אופציונלי
סוג:	String
ערכים תקינים:	משתנה של זרימת עבודה שמכיל מחרוזת של קוד הרשאה, או מחרוזת מילולית.

רכיב <ClientId>

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

<ClientId ref="request.queryparam.client_id"></ClientId>

ברירת מחדל:	request.formparam.access_token (a x-www-form-urlencoded and specified in the request body)
נוכחות:	אופציונלי
סוג:	מחרוזת
ערכים תקינים:	משתנה של זרימת עבודה שמכיל מחרוזת של קוד הרשאה, או מחרוזת מילולית.

אלמנט <IgnoreAccessTokenStatus>

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

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

ברירת מחדל:	FALSE
נוכחות:	אופציונלי
סוג:	בוליאני
ערכים תקינים:	true or false

אלמנט <RefreshToken>

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

הערה: האלמנט הזה פועל באותו אופן בין אם משתמשים באסימון רענון שהונפק עם אסימון גישה מסוג JWT, ובין אם משתמשים באסימון גישה אטום רגיל.

<RefreshToken ref="request.queryparam.refresh_token"></RefreshToken>

ברירת מחדל:	request.formparam.access_token (a x-www-form-urlencoded and specified in the request body)
נוכחות:	אופציונלי
סוג:	String
ערכים תקינים:	משתנה של זרימת עבודה שמכיל מחרוזת של טוקן רענון, או מחרוזת מילולית.

משתני Flow

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

משתנים של מזהה לקוח

המשתנים האלה מאוכלסים כשהרכיב ClientId מוגדר:

oauthv2client.{policy_name}.client_id
oauthv2client.{policy_name}.client_secret
oauthv2client.{policy_name}.redirection_uris // Note the spelling -- 'redirection_uris'
oauthv2client.{policy_name}.developer.email
oauthv2client.{policy_name}.developer.app.name
oauthv2client.{policy_name}.developer.id
oauthv2client.{policy_name}.{developer_app_custom_attribute_name}

משתני טוקן גישה

המשתנים האלה מאוכלסים כשהרכיב AccessToken מוגדר:

oauthv2accesstoken.{policy_name}.developer.id
oauthv2accesstoken.{policy_name}.developer.app.name
oauthv2accesstoken.{policy_name}.developer.app.id
oauthv2accesstoken.{policy_name}.developer.email

oauthv2accesstoken.{policy_name}.organization_name
oauthv2accesstoken.{policy_name}.api_product_list

oauthv2accesstoken.{policy_name}.access_token
oauthv2accesstoken.{policy_name}.scope
oauthv2accesstoken.{policy_name}.expires_in //in seconds
oauthv2accesstoken.{policy_name}.status
oauthv2accesstoken.{policy_name}.client_id
oauthv2accesstoken.{policy_name}.accesstoken.{custom_attribute_name}

oauthv2accesstoken.{policy_name}.refresh_token
oauthv2accesstoken.{policy_name}.refresh_token_status
oauthv2accesstoken.{policy_name}.refresh_token_expires_in //in seconds

oauthv2accesstoken.{policy_name}.refresh_count
oauthv2accesstoken.{policy_name}.refresh_token_issued_at
oauthv2accesstoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

משתני קוד הרשאה

המשתנים האלה מאוכלסים כשהרכיב AuthorizationCode מוגדר:

oauthv2authcode.{policy_name}.code
oauthv2authcode.{policy_name}.scope
oauthv2authcode.{policy_name}.redirect_uri
oauthv2authcode.{policy_name}.client_id
oauthv2authcode.{policy_name}.{auth_code_custom_attribute_name}

משתני טוקן רענון

המשתנים האלה מאוכלסים כשהרכיב RefreshToken מוגדר:

oauthv2refreshtoken.{policy_name}.developer.id
oauthv2refreshtoken.{policy_name}.developer.app.name
oauthv2refreshtoken.{policy_name}.developer.app.id
oauthv2refreshtoken.{policy_name}.developer.email
oauthv2refreshtoken.{policy_name}.organization_name
oauthv2refreshtoken.{policy_name}.api_product_list

oauthv2refreshtoken.{policy_name}.access_token
oauthv2refreshtoken.{policy_name}.scope
oauthv2refreshtoken.{policy_name}.expires_in //in seconds

oauthv2refreshtoken.{policy_name}.status
oauthv2refreshtoken.{policy_name}.client_id
oauthv2refreshtoken.{policy_name}.accesstoken.{custom_attribute_name}

oauthv2refreshtoken.{policy_name}.refresh_token
oauthv2refreshtoken.{policy_name}.refresh_token_status
oauthv2refreshtoken.{policy_name}.refresh_token_expires_in //in seconds

oauthv2refreshtoken.{policy_name}.refresh_count
oauthv2refreshtoken.{policy_name}.refresh_token_issued_at
oauthv2refreshtoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

סכימה

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

הפניה לשגיאה

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

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

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

קוד תקלה	סטטוס HTTP	מטרה
steps.oauth.v2.access_token_expired	500	פג התוקף של טוקן הגישה שנשלח למדיניות.
steps.oauth.v2.authorization_code_expired	500	פג התוקף של קוד ההרשאה שנשלח למדיניות.
steps.oauth.v2.invalid_access_token	500	טוקן הגישה שנשלח למדיניות לא תקין.
steps.oauth.v2.invalid_client-invalid_client_id	500	מזהה הלקוח שנשלח למדיניות לא תקין.
steps.oauth.v2.invalid_refresh_token	500	אסימון הרענון שנשלח למדיניות לא תקין.
steps.oauth.v2.invalid_request-authorization_code_invalid	500	קוד ההרשאה שנשלח למדיניות לא תקין.
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound	401	מידע על פתרון בעיות שקשורות לשגיאה הזו זמין במאמר Oauth2.0 Access Token Verification throws "Invalid API call as no apiproduct match found" error.
steps.oauth.v2.refresh_token_expired	500	פג התוקף של אסימון הרענון שנשלח למדיניות.

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

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

משתני תקלות

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

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

משתנים	כאשר:	דוגמה
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":"ClientId is Invalid",
      "detail":{  
         "errorcode":"keymanagement.service.invalid_client-invalid_client_id"
      }
   }
}

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

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientIdResponse</Name>
    </Step>
    <Condition>(fault.name = "invalid_client-invalid_client_id")</Condition>
</FaultRule>

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

• מדיניות OAuthV2
• דף הבית של OAuth
• התאמה אישית של טוקנים וקודי הרשאה