מדיניות OAuthOAuthV2Info

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X.
מידע

מה

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

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

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

דוגמאות

בדוגמאות הבאות נעשה שימוש במדיניות 'קבלת מידע על 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> כדי להוסיף למדיניות בכלי לעריכת שרת ה-proxy לניהול ממשק משתמש עם שם בשפה טבעית אחרת.

לא רלוונטי נדרש
continueOnError

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

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

false אופציונלי
enabled

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

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

true אופציונלי
async

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

false הוצא משימוש

רכיב <DisplayName>

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

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

לא רלוונטי

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

נוכחות אופציונלי
תיאור מחרוזת

רכיב <AccessToken>

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

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

ברירת מחדל:

request.formparam.access_token (קובץ x-www-form-urlencoded ומצוין בגוף הבקשה)

נוכחות:

אופציונלי

סוג: מחרוזת
ערכים חוקיים:

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


אלמנט <AuthorizationCode>

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

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

ברירת מחדל:

request.formparam.access_token (קובץ x-www-form-urlencoded ומצוין בגוף הבקשה)

נוכחות:

אופציונלי

סוג: מחרוזת
ערכים חוקיים:

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

האלמנט <ClientId>

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

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

ברירת מחדל:

request.formparam.access_token (קובץ x-www-form-urlencoded ומצוין בגוף הבקשה)

נוכחות:

אופציונלי

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

הרכיב <IgnoreAccessTokenStatus>

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

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

ברירת מחדל:

false

נוכחות:

אופציונלי

סוג: ערך בוליאני
ערכים חוקיים: נכון או לא נכון

רכיב <רענןToken>

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

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

ברירת מחדל:

request.formparam.access_token (קובץ x-www-form-urlencoded ומצוין בגוף הבקשה)

נוכחות:

אופציונלי

סוג: מחרוזת
ערכים חוקיים:

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

משתני זרימה

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

משתני Client-ID

המשתנים האלה מאוכלסים כשרכיב 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>

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