המדיניות GetOAuthV2Info

אתם צופים במסמכי התיעוד של 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.

הפניה לשגיאה

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes. The error names shown below are the strings that are assigned to the fault.name variable when an error occurs. See the Fault variables section below for more details.

Fault code HTTP status Cause
steps.oauth.v2.access_token_expired 500 The access token sent to the policy is expired.
steps.oauth.v2.authorization_code_expired 500 The authorization code sent to the policy is expired.
steps.oauth.v2.invalid_access_token 500 The access token sent to the policy is invalid.
steps.oauth.v2.invalid_client-invalid_client_id 500 The client ID sent to the policy is invalid.
steps.oauth.v2.invalid_refresh_token 500 The refresh token sent to the policy is invalid.
steps.oauth.v2.invalid_request-authorization_code_invalid 500 The authorization code sent to the policy is invalid.
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound 401 Please see this Apigee Community post for information about troubleshooting this error.
steps.oauth.v2.refresh_token_expired 500 The refresh token sent to the policy is expired.

Deployment errors

Refer to the message reported in the UI for information about deployment errors.

Fault variables

These variables are set when this policy triggers an error at runtime.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "IPDeniedAccess"
oauthV2.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. oauthV2.GetTokenInfo.failed = true
oauthV2.policy_name.fault.name policy_name is the user-specified name of the policy that threw the fault. oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id
oauthV2.policy_name.fault.cause policy_name is the user-specified name of the policy that threw the fault. oauthV2.GetTokenInfo.cause = ClientID is Invalid

Example error response

{  
   "fault":{  
      "faultstring":"ClientId is Invalid",
      "detail":{  
         "errorcode":"keymanagement.service.invalid_client-invalid_client_id"
      }
   }
}

Example fault rule

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

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