מדיניות OAuthOAuthV2Info

אתם צופים במסמכי התיעוד של Apigee Edge.
אפשר לעבור אל מסמכי התיעוד של Apigee X. מידע

מה

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

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

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

דוגמאות

בדוגמאות הבאות נעשה שימוש במדיניות Get OAuth V2 Info כדי לאחזר מידע על רכיבים שונים של תהליך העבודה של 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 בפרמטר של שאילתה שנקרא 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> כדי להוסיף תווית למדיניות עורך ה-Proxy של ממשק המשתמש לניהול בעל שם אחר בשפה טבעית.

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

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

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

 false אופציונלי
enabled

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

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

 true אופציונלי
async

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

 false הוצא משימוש

&lt;DisplayName&gt; רכיב

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

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

לא רלוונטי

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

אלמנט <AccessToken>

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

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

ברירת מחדל:

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

נוכחות:

אופציונלי
סוג: מחרוזת
ערכים תקינים:

משתנה של זרימת נתונים שמכיל מחרוזת של אסימון גישה, או מחרוזת מילולית.

אלמנט <AuthorizationCode>

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

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

ברירת מחדל:

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

נוכחות:

אופציונלי
סוג: מחרוזת
ערכים תקינים:

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

אלמנט <ClientId>

אחזור מידע שקשור למזהה לקוח. בדוגמה הזו, ה-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 או false

אלמנט <RefreshToken>

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

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

ברירת מחדל:

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

נוכחות:

אופציונלי
סוג: מחרוזת
ערכים תקינים:

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

משתני 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.

הפניה לשגיאה

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

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

השגיאות האלה עשויות להתרחש כשהמדיניות מופעלת. שמות השגיאות שמוצגים בהמשך הם המחרוזות שמוקצות למשתנה 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 מומלץ לעיין ב- בפוסט הזה בקהילה של Apigee אפשר למצוא מידע על פתרון בעיות בשגיאה הזו.
steps.oauth.v2.refresh_token_expired 500 פג התוקף של אסימון הרענון שנשלח למדיניות.

שגיאות פריסה

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

משתני כשל

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

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

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