כרגע מוצג התיעוד של 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 |
השם הפנימי של המדיניות. הערך של המאפיין אפשר להשתמש באלמנט |
לא רלוונטי | נדרש |
continueOnError |
צריך להגדיר את הערך צריך להגדיר את הערך |
false | אופציונלי |
enabled |
צריך להגדיר את הערך צריך להגדיר את הערך |
true | אופציונלי |
async |
המאפיין הזה הוצא משימוש. |
false | הוצא משימוש |
רכיב <DisplayName>
יש להשתמש במאפיין הזה בנוסף למאפיין name
כדי להוסיף למדיניות
בכלי לעריכת שרת ה-proxy לניהול ממשק משתמש עם שם אחר בשפה טבעית.
<DisplayName>Policy Display Name</DisplayName>
ברירת המחדל |
לא רלוונטי אם משמיטים את הרכיב הזה, המערכת משתמשת בערך של מאפיין |
---|---|
נוכחות | אופציונלי |
תיאור | מחרוזת |
רכיב <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>