מדיניות OAuthV2

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

מה

OAuthV2 היא מדיניות רב-גונית לביצוע פעולות מסוג הרשאה ב-OAuth 2.0. זוהי המדיניות הראשית שמשמשת להגדרת נקודות קצה של OAuth 2.0 ב-Apigee Edge.

טיפ: מידע נוסף על OAuth ב-Apigee Edge זמין בדף הבית של OAuth. באתר יש קישורים למקורות מידע, לדוגמאות, לסרטונים ועוד. דוגמה מתקדמת ל-OAuth ב-GitHub היא הדגמה טובה לאופן שבו המדיניות הזו משמשת באפליקציה שפועלת.

טעימות

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2">
    <DisplayName>OAuth v2.0 2</DisplayName>
    <Operation>VerifyAccessToken</Operation>
    <AccessTokenPrefix>Bearer</AccessTokenPrefix> <!-- Optional, default is Bearer -->
</OAuthV2>

$ curl -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

var client_id = context.getVariable("local_clientid");
var client_secret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(client_id + ':' + client_secret)));

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

הפנייה לרכיב

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

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

<OAuthV2 name="GenerateAccessToken">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

מאפייני <OAuthV2>

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

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

&lt;DisplayName&gt; רכיב

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

<DisplayName>Policy Display Name</DisplayName>

האלמנט <AccessToken>

<AccessToken>request.header.access_token</AccessToken>

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

curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"

האלמנט <AccessTokenPrefix>

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

כברירת מחדל, VerifyAccessToken מצפה שאסימון הגישה יישלח בכותרת Authorization בתור אסימון למוכ"ז. לדוגמה:

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

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

האלמנט <AppEndUser>

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

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

לדוגמה, הערך request.queryparam.app_enduser מציין ש-AppEndUser צריך להופיע כפרמטר של שאילתה, לדוגמה ?app_enduser=ntesla@theramin.com. לדוגמה, כדי לדרוש את AppEndUser בכותרת HTTP, מגדירים את הערך הזה כ-request.header.app_enduser.

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

<מאפיינים/מאפיין>

<Attributes>
    <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute>
    <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute>
</Attributes>

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

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

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

הצגה או הסתרה של מאפיינים מותאמים אישית בתגובה

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

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

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

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

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

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

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

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

אלמנט <ClientId>

<ClientId>request.formparam.client_id</ClientId>

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

רכיב <Code>

<Code>request.queryparam.code</Code>

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

המשתנה request.queryparam.auth_code מציין שקוד ההרשאה צריך להופיע כפרמטר של שאילתה, לדוגמה ?auth_code=AfGlvs9. לדוגמה, כדי לדרוש את קוד ההרשאה בכותרת HTTP, מגדירים את הערך הזה כ-request.header.auth_code. למידע נוסף, ראו בקשת אסימוני גישה וקודי הרשאה.

האלמנט<ExpiresIn>

<ExpiresIn>10000</ExpiresIn> 

אכיפת מועד התפוגה של אסימוני גישה וקודי הרשאה באלפיות שנייה. (באסימוני רענון, צריך להשתמש ב-<RefreshTokenExpiresIn>). הערך של זמן התפוגה הוא ערך שנוצר על ידי המערכת בתוספת הערך של <ExpiresIn>. אם הערך של <ExpiresIn> מוגדר לערך -1, התוקף של האסימון או הקוד יפוג בהתאם לתפוגת התוקף המקסימלית של אסימון גישה ל-OAuth. אם לא מציינים את <ExpiresIn>, המערכת מחילה ערך ברירת מחדל שהוגדר ברמת המערכת.

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

ב-Apigee Edge for Public Cloud, הישויות הבאות נשמרות במטמון של Edge למשך 180 שניות לפחות אחרי הגישה אליהן.

• אסימוני גישה מסוג OAuth. כלומר, אסימון מבוטל עדיין יכול להצליח למשך עד שלוש דקות, עד שתוקף המכסה שלו במטמון יפוג.
• ישויות של שירות ניהול מפתחות (KMS) (אפליקציות, מפתחים, מוצרי API).
• מאפיינים מותאמים אישית בטוקני OAuth ובישויות KMS.

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

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

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

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

ענן פרטי: בהתקנה של Edge for Private Cloud, ערך ברירת המחדל מוגדר על ידי המאפיין conf_keymanagement_oauth_auth_code_expiry_time_in_millis. כדי להגדיר את הנכס הזה:

1. פותחים את הקובץ message-processor.properties בכלי לעריכה. אם הקובץ לא קיים, יוצרים אותו:

   vi /opt/apigee/customer/application/message-processor.properties

2. מגדירים את הנכס הרצוי:

   conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

3. מוודאים שהבעלים של קובץ המאפיינים הוא המשתמש 'apigee':

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. מפעילים מחדש את מעבד ההודעות.

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

רכיב <ExternalAccessToken>

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

מציין ל-Apigee Edge איפה נמצא אסימון גישה חיצוני (אסימון גישה שלא נוצר על ידי Apigee Edge).

המשתנה request.queryparam.external_access_token מציין שאסימון הגישה החיצוני צריך להופיע כפרמטר של שאילתה, לדוגמה ?external_access_token=12345678. לדוגמה, כדי לדרוש את אסימון הגישה החיצוני בכותרת HTTP, מגדירים את הערך הזה ל-request.header.external_access_token. מידע נוסף זמין במאמר שימוש באסימוני OAuth של צד שלישי.

הרכיב <ExternalAuthorization>

<ExternalAuthorization>true</ExternalAuthorization>

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

האלמנט <ExternalAuthorizationCode>

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

קובע איפה Apigee Edge ימצא קוד אימות חיצוני (קוד אימות שלא נוצר על ידי Apigee Edge).

המשתנה request.queryparam.external_auth_code מציין שקוד האימות החיצוני צריך להופיע כפרמטר של שאילתה, לדוגמה ?external_auth_code=12345678. לדוגמה, כדי לדרוש את קוד האימות החיצוני בכותרת HTTP, מגדירים את הערך הזה כ-request.header.external_auth_code. ראו גם שימוש באסימוני OAuth של צד שלישי.

האלמנט <ExternalRefreshToken>

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

מגדיר לאיפה Apigee Edge צריך לחפש אסימון רענון חיצוני (אסימון רענון שלא נוצר על ידי Apigee Edge).

המשתנה request.queryparam.external_refresh_token מציין שצריך להוסיף את אסימון הרענון החיצוני כפרמטר של שאילתה, לדוגמה ?external_refresh_token=12345678. לדוגמה, כדי לדרוש את אסימון הרענון החיצוני בכותרת HTTP, מגדירים את הערך הזה ל-request.header.external_refresh_token. מידע נוסף זמין במאמר שימוש באסימוני OAuth של צד שלישי.

האלמנט <GenerateResponse>

<GenerateResponse enabled='true'/>

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

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

אם הערך הוא false, לא נשלחת תגובה. במקום זאת, קבוצה של משתני תהליך מאוכלסת בערכים שקשורים לפונקציה של המדיניות. לדוגמה, משתנה תהליך שנקרא oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code מאוכלס בקוד האימות החדש שנוצר. חשוב לזכור ש-expires_in מופיע בתגובה בשניות.

האלמנט <GenerateErrorResponse>

<GenerateErrorResponse enabled='true'/>

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

<GrantType>

<GrantType>request.queryparam.grant_type</GrantType>

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

לדוגמה, הערך request.queryparam.grant_type מציין שהסיסמה צריכה להופיע כפרמטר של שאילתה, לדוגמה ?grant_type=password. לדוגמה, כדי לדרוש את סוג ההענקה בכותרת HTTP, מגדירים את הערך הזה לערך request.header.grant_type. אפשר לעיין גם במאמר בקשה לאסימוני גישה ולקודי הרשאה.

רכיב <Operation>

<Operation>GenerateAuthorizationCode</Operation>

פעולת OAuth 2.0 שמבוצעת על ידי המדיניות.

אלמנט <PassWord>

<PassWord>request.queryparam.password</PassWord>

הרכיב הזה משמש רק עם סוג ההקצאה של סיסמה. כשמשתמשים בסוג ההקצאה 'סיסמה', צריך להפוך את פרטי הכניסה של המשתמש (הסיסמה ושם המשתמש) לזמינים למדיניות OAuthV2. הרכיבים <PassWord> ו-<UserName> משמשים לציון משתנים שבהם Edge יכול למצוא את הערכים האלה. אם לא מציינים את הרכיבים האלה, המדיניות מצפה למצוא את הערכים (כברירת מחדל) בפרמטרים של הטופס בשם username ו-password. אם הערכים לא נמצאים, המדיניות תיצור שגיאה. אפשר להשתמש ברכיבים <PassWord> ו-<UserName> כדי להפנות לכל משתנה זרימה שמכיל את פרטי הכניסה.

לדוגמה, תוכלו להעביר את הסיסמה בבקשת אסימון באמצעות פרמטר של שאילתה, ולהגדיר את הרכיב כך: <PassWord>request.queryparam.password</PassWord>. כדי להזין את הסיסמה בכותרת HTTP, צריך להגדיר את הערך הזה ל-request.header.password.

מדיניות OAuthV2 לא מבצעת פעולות נוספות עם ערכי פרטי הכניסה האלה. Edge רק מאמת שהם נמצאים. מפתח ה-API צריך לאחזר את בקשת הערכים ולשלוח אותם לספק הזהויות לפני שהמדיניות ליצירת אסימונים מופעלת.

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

האלמנט <RedirectUri>

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

מציין איפה Edge צריך לחפש את הפרמטר redirect_uri בבקשה.

מידע על כתובות URI להפניה אוטומטית

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

• (חובה) אם כתובת URL להחזרת קריאה רשומה באפליקציית הפיתוח שמשויכת למפתחות הלקוח של הבקשה, ואם הערך redirect_uri מופיע בבקשה, הערכים האלה חייבים להיות זהים. אם הם לא תואמים, תוחזר שגיאה. למידע על רישום אפליקציות למפתחים ב-Edge ועל ציון כתובת URL להודעת חזרה, ראו רישום אפליקציות וניהול מפתחות API.

• (אופציונלי) אם רשומה כתובת URL לשיחה חוזרת, והשדה redirect_uri חסר בבקשה, Edge מפנה לכתובת ה-URL לשיחה חוזרת הרשומה.
• (חובה) אם לא רשומה כתובת URL להחזרת קריאה, צריך לציין את הערך redirect_uri. חשוב לציין שבמקרה כזה, Edge יקבל כל כתובת URL. מקרה כזה עלול ליצור בעיית אבטחה,ולכן יש להשתמש בו רק עם אפליקציות לקוח מהימנות. אם אפליקציות הלקוח לא מהימנות, מומלץ תמיד לדרוש רישום של כתובת URL להחזרת קריאה.

אפשר לשלוח את הפרמטר הזה כפרמטר של שאילתה או ככותרת. המשתנה request.queryparam.redirect_uri מציין ש-RedirectUri צריך להופיע כפרמטר של שאילתה, לדוגמה ?redirect_uri=login.myapp.com. לדוגמה, כדי לחייב את ה-RedirectUri בכותרת HTTP, מגדירים את הערך הזה כ-request.header.redirect_uri. אפשר לעיין גם במאמר בקשה לאסימוני גישה ולקודי הרשאה.

אלמנט <RefreshToken>

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

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

המשתנה request.queryparam.refreshtoken מציין שאסימון הרענון צריך להופיע כפרמטר של שאילתה, למשל ?refresh_token=login.myapp.com. לדוגמה, כדי לדרוש את RefreshToken בכותרת HTTP, מגדירים את הערך הזה כ-request.header.refresh_token. אפשר לעיין גם במאמר בקשה לאסימוני גישה ולקודי הרשאה.

האלמנט <RefreshTokenExpiresIn>

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

אכיפת תאריך התפוגה של אסימוני הרענון באלפיות שנייה. הערך של זמן התפוגה הוא ערך שנוצר על ידי המערכת בתוספת הערך של <RefreshTokenExpiresIn>. אם הערך של <RefreshTokenExpiresIn> מוגדר כ- -1, התוקף של טוקן הרענון יפוג בהתאם לתוקף המקסימלי של טוקן רענון OAuth. אם לא מציינים את <RefreshTokenExpiresIn>, המערכת מחילה ערך ברירת מחדל שהוגדר ברמת המערכת. לקבלת מידע נוסף על הגדרות ברירת המחדל של המערכת, אפשר לפנות אל התמיכה של Apigee Edge.

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

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

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</RefreshTokenExpiresIn>

ענן פרטי: ב-Edge להתקנת ענן פרטי, ערך ברירת המחדל נקבע על ידי הנכס conf_keymanagement_oauth_refresh_token_expiry_time_in_millis. כדי להגדיר את הנכס הזה:

1. פותחים את הקובץ message-processor.properties בכלי לעריכה. אם הקובץ לא קיים, יוצרים אותו:

   vi /opt/apigee/customer/application/message-processor.properties

2. מגדירים את הנכס הרצוי:

   conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

3. מוודאים שהבעלים של קובץ המאפיינים הוא המשתמש 'apigee':

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. מפעילים מחדש את מעבד ההודעות.

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

רכיב <ResponseType>

<ResponseType>request.queryparam.response_type</ResponseType>

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

כברירת מחדל, Edge מחפש את הערך של סוג התגובה בפרמטר של השאילתה response_type. אם רוצים לשנות את התנהגות ברירת המחדל הזו, משתמשים באלמנט <ResponseType> כדי להגדיר משתנה תהליך שמכיל את הערך של סוג התגובה. לדוגמה, אם מגדירים את האלמנט הזה לערך request.header.response_type, ‏ Edge מחפש את סוג התגובה שצריך להעביר בכותרת הבקשה. אפשר לעיין גם במאמר בקשה לאסימוני גישה ולקודי הרשאה.

האלמנט <ReuseRefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

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

האלמנט <Scope>

<Scope>request.queryparam.scope</Scope>

אם האלמנט הזה נמצא באחת מהמדיניות של GenerateAccessToken או GenerateAuthorizationCode, הוא משמש לציון את ההיקפים של הרשאות הגישה שרוצים להקצות לאסימון או לקוד. בדרך כלל, הערכים האלה מועברים למדיניות בבקשה מאפליקציית לקוח. אפשר להגדיר את הרכיב כך שיקבל משתנה תהליך, וכך לבחור איך להעביר את ההיקפים בבקשה. בדוגמה הבאה, הערך request.queryparam.scope מציין שההיקף צריך להופיע כפרמטר של שאילתה, למשל ?scope=READ. כדי לדרוש את ההיקף בכותרת HTTP, לדוגמה, מגדירים את הערך הזה ל-request.header.scope.

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

<Scope>A B</Scope>

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

אלמנט <State>

<State>request.queryparam.state</State>

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

לדוגמה request.queryparam.state מציין שהמצב צריך להיות כפרמטר של שאילתה, כמו, למשל, ?state=HjoiuKJH32. לדוגמה, כדי לחייב את המדינה להופיע בכותרת HTTP, צריך להגדיר את הערך הזה לערך request.header.state. מידע נוסף זמין במאמר בקשה לאסימוני גישה ולקודי הרשאה.

האלמנט <StoreToken>

 <StoreToken>true</StoreToken> 

מגדירים את הרכיב הזה כ-true כשהרכיב <ExternalAuthorization> הוא true. הרכיב <StoreToken> מורה ל-Apigee Edge לאחסן את אסימון הגישה החיצוני. אחרת, הוא לא יישמר.

האלמנט <SupportedGrantTypes>/<GrantType>

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

מציינת את סוגי ההרשאות שנתמכים על ידי נקודת קצה של אסימון OAuth ב-Apigee Edge. נקודת קצה יכולה לתמוך בכמה סוגים של הרשאות (כלומר, אפשר להגדיר נקודת קצה אחת כדי להפיץ אסימוני גישה לכמה סוגים של הרשאות). מידע נוסף על נקודות קצה זמין במאמר הסבר על נקודות קצה של OAuth. סוג ההקצאה מועבר בבקשות לאסימונים בפרמטר grant_type.

אם לא צוינו סוגי הענקות נתמכים, סוגי ההענקות היחידים שמותר להשתמש בהם הם authorization_code ו-implicit. כדאי לעיין גם ברכיב <GrantType> (רכיב ברמה גבוהה יותר שמשמש לציון איפה Apigee Edge צריך לחפש את הפרמטר grant_type שמוענק בבקשת לקוח. ‏Edge יבצע בדיקה כדי לוודא שהערך של הפרמטר grant_type תואם לאחד מסוגי המענקים הנתמכים).

האלמנט <Tokens>/<Token>

משמש עם הפעולות ValidateToken ו-InvalidateToken. אפשר לעיין גם במאמר אישור וביטול של אסימוני גישה. הרכיב <Token> מזהה את משתנה התהליך שמגדיר את המקור של האסימון שרוצים לבטל. אם המפתחים אמורים לשלוח אסימוני גישה כפרמטרים של שאילתות בשם access_token, לדוגמה, צריך להשתמש ב-request.queryparam.access_token.

אלמנט <UserName>

<UserName>request.queryparam.user_name</UserName>

הרכיב הזה משמש רק עם סוג ההקצאה של סיסמה. כשמשתמשים בסוג ההקצאה 'סיסמה', צריך להפוך את פרטי הכניסה של המשתמש (הסיסמה ושם המשתמש) לזמינים למדיניות OAuthV2. הרכיבים <PassWord> ו-<UserName> משמשים לציון משתנים שבהם Edge יכול למצוא את הערכים האלה. אם לא מציינים את הרכיבים האלו, המדיניות מצפה למצוא את הערכים (כברירת מחדל) בפרמטרים של טופס שנקראים username ו-password. אם הערכים לא נמצאים, המדיניות תיצור שגיאה. אפשר להשתמש ברכיבים <PassWord> ו-<UserName> כדי להפנות לכל משתנה זרימה שמכיל את פרטי הכניסה.

לדוגמה, אפשר להעביר את שם המשתמש בפרמטר של שאילתה ולהגדיר את הרכיב <UserName> כך: <UserName>request.queryparam.username</UserName>.כדי לדרוש את שם המשתמש בכותרת HTTP, צריך להגדיר את הערך הזה ל-request.header.username.

מדיניות OAuthV2 לא מבצעת שום פעולה נוספת עם ערכי פרטי הכניסה האלה. Edge פשוט מאמת שהם קיימים. מפתח ה-API הוא זה שיאחזר את ערכי הבקשה וישלח אותם לספק זהויות לפני הפעלת המדיניות של יצירת האסימון.

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

אימות אסימוני הגישה

אחרי שמגדירים נקודת קצה של אסימון לשרת proxy של API, מדיניות OAuthV2 תואמת שמציינת את הפעולה VerifyAccessToken מצורפת לתהליך שחשף את המשאב המוגן.

לדוגמה, כדי לוודא שכל הבקשות ל-API מורשות, המדיניות הבאה אוכפת אימות של אסימון הגישה:

<OAuthV2 name="VerifyOAuthAccessToken">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

המדיניות מצורפת למשאב ה-API שרוצים להגן עליו. כדי לוודא שכל הבקשות ל-API מאומתות, צריך לצרף את המדיניות ל-PreFlow של בקשת ProxyEndpoint באופן הבא:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

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

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>

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

ציון המיקומים של משתני הבקשה

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

בדוגמה הבאה מוסבר איך לציין את המיקום של הפרמטרים הנדרשים של קוד ההרשאה ככותרות HTTP:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.header.client_id</ClientId>
  <RedirectUri>request.header.redirect_uri</RedirectUri>
  <Scope>request.header.scope</Scope>
  ...

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

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
  ...

אפשר להגדיר רק מיקום אחד לכל פרמטר.

משתני תהליך

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

פעולת VerifyAccessToken

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

משתנים ספציפיים לאסימון

משתנים ספציפיים לאפליקציה

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

משתנים ספציפיים למפתחים

אם הערך של app.appType הוא 'חברה', מאפייני החברה מאוכלסים. אם הערך של app.appType הוא 'מפתח', מאפייני המפתח מאוכלסים.

משתנים ספציפיים לחברה

אם הערך של app.appType הוא 'חברה', מאפייני החברה מאוכלסים. אם הערך של app.appType הוא 'מפתח', מאפייני המפתח מאוכלסים.

הפעולה GenerateAuthorizationCode

המשתנים האלה מוגדרים כשהפעולה GenerateAuthorizationCode מתבצעת בהצלחה:

קידומת: oauthv2authcode.{policy_name}.{variable_name}

דוגמה: oauthv2authcode.GenerateCodePolicy.code

הפעולות GenerateAccessToken ו-RefreshAccessToken

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

קידומת: oauthv2accesstoken.{policy_name}.{variable_name}

לדוגמה: oauthv2accesstoken.GenerateTokenPolicy.access_token

GenerateAccessTokenImplicitGrant

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

קידומת: oauthv2accesstoken.{policy_name}.{variable_name}

דוגמה: oauthv2accesstoken.RefreshTokenPolicy.access_token

מידע על שגיאות

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

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

השגיאות האלה יכולות להתרחש כשהמדיניות מופעלת.

שגיאות בפריסה

השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שמכיל את המדיניות הזו.

משתני תקלה

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

דוגמה לתשובה עם שגיאה

התשובות האלה נשלחות חזרה ללקוח אם הערך של הרכיב <GenerateResponse> הוא true.

אם הערך של <GenerateResponse> הוא true, המדיניות מחזירה שגיאות בפורמט הזה לפעולות שיוצרות אסימונים וקודי. הרשימה המלאה מופיעה במאמר חומר עזר בנושא תגובות שגיאה של OAuth ב-HTTP.

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

אם הערך של <GenerateResponse> הוא true, המדיניות מחזירה שגיאות בפורמט הזה עבור פעולות אימות ותיקוף. הרשימה המלאה מופיעה במאמר חומר עזר בנושא תגובות שגיאה של OAuth ב-HTTP.

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

דוגמה לכלל תקלה

<FaultRule name=OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

סכימה של מדיניות

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

עבודה עם הגדרת ברירת המחדל של OAuth

לכל ארגון (גם ארגון בתקופת ניסיון בחינם) ב-Apigee Edge מוקצית נקודת קצה של אסימון OAuth. נקודת הקצה מוגדרת מראש עם כללי מדיניות בשרת proxy של ה-API שנקרא oauth. אפשר להתחיל להשתמש בנקודת הקצה של האסימון ברגע שיוצרים חשבון ב-Apigee Edge. למידע נוסף, ראו הסבר על נקודות קצה של OAuth.

ניקוי אסימוני גישה

כברירת מחדל, אסימוני OAuth2 נמחקים ממערכת Apigee Edge 3 ימים (259,200 שניות) אחרי שתוקף אסימון הגישה ואסימון הרענון (אם הוא קיים) יפוג. במקרים מסוימים, מומלץ לשנות את ברירת המחדל. לדוגמה, אם נוצרים מספר רב של אסימונים, כדאי לקצר את זמן הניקוי כדי לחסוך מקום בדיסק.

אם אתם משתמשים ב-Edge for Private Cloud, תוכלו לשנות את ברירת המחדל הזו על ידי הגדרת מאפייני הארגון כפי שמוסבר בקטע הזה. (המחיקה של האסימונים שפג תוקפם תוך 3 ימים חלה על Edge for Private Cloud בגרסה 4.19.01 ואילך. בגרסאות קודמות, מרווח המחיקה שמוגדר כברירת מחדל הוא 180 יום).

עדכון ההגדרות של מחיקה סופית ב-Edge Private Cloud בגרסה 4.16.01 ואילך

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

עדכון ההגדרות של מחיקה סופית ב-Edge Private Cloud 4.15.07

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

התנהגות שלא תואמת ל-RFC

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

בנוסף, תגובת השגיאה עבור אסימון רענון שפג תוקפו כאשר grant_type = refresh_token הוא:

{"ErrorCode" : "InvalidRequest", "Error" :"Refresh Token expired"}

עם זאת, התגובה שתואמת ל-RFC היא:

{"error" : "invalid_grant", "error_description" :"refresh token expired"}

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

• מבוא ל-OAuth 2.0