מדיניות OAuthV2

אתה צופה בתיעוד של Apigee Edge.
הצג תיעוד של Apigee X.

מה

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">

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

רכיב <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

רכיב <AccessToken>

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

כברירת מחדל, הכלי AccessAccessToken מצפה שיישלחו את אסימון הגישה בכותרת 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>

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

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

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

רכיב <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>

במקרים מסוימים, אפליקציית הלקוח חייבת לשלוח את מספר הלקוח לשרת ההרשאות. הרכיב הזה מאפשר לך לציין היכן ב-Edge יש לחפש את מספר הלקוח. המיקום החוקי היחיד שניתן להגדיר הוא מיקום ברירת המחדל, משתנה הזרימה 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 ל-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 לענן פרטי, ערך ברירת המחדל מוגדר בנכס 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. חשוב לוודא שקובץ הנכסים נמצא בבעלות המשתמש 'pigee':

   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 של צד שלישי.

רכיב <CreateResponse>

<GenerateResponse enabled='true'/>

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

{
  "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 מופיעה בשניות.

הרכיב <CreateErrorResponse>

<GenerateErrorResponse enabled='true'/>

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

<סוג מענק>

<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 לקריאה חוזרת (callback) רשומה באפליקציה למפתחים שמשויכת למפתחות הלקוח של הבקשה, ואם השדה redirect_uri נמצא בבקשה, שתי הכתובות צריכות להיות זהות. אם הם לא תואמים, תוחזר שגיאה. מידע על רישום אפליקציות למפתחים ב-Edge וציון כתובת URL לקריאה חוזרת (callback) זמין במאמר רישום אפליקציות וניהול של מפתחות API.

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

אפשר לשלוח את הפרמטר הזה בפרמטר שאילתה או בכותרת. המשתנה request.queryparam.redirect_uri מציין שההפניה האוטומטית (URI) צריכה להופיע כפרמטר של שאילתה, למשל ?redirect_uri=login.myapp.com. כדי לדרוש את ההפניה האוטומטית ל-HTTP בכותרת 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>, כברירת מחדל התפוגה היא בלתי מוגבלת.

אפשר להגדיר את זמן התפוגה גם בזמן ריצה, באמצעות ערך ברירת מחדל בתוך הקוד או על ידי הפניה למשתנה זרימה. לדוגמה, אפשר לשמור ערך תפוגת אסימון במפת ערך מפתח, לאחזר אותו, להקצות אותו למשתנה ולציין אותו במדיניות. לדוגמה: 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. חשוב לוודא שקובץ הנכסים נמצא בבעלות המשתמש 'pigee':

   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', הוא משמש לציון ההיקפים שהמדיניות צריכה לאכוף. בסוג המדיניות הזה, הערך חייב להיות שם היקף 'מקודד{/1}. לא ניתן להשתמש במשתנים. לדוגמה:

<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 לאחסן את אסימון הגישה החיצוני. אחרת, הערך לא יימחק.

הרכיב <SupportgrantTypes>/<grantType>

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

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

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

הרכיב <Tokens>/<Token>

בשימוש עם הפעולות VerifyToken ו-InverifyToken. למידע נוסף, ניתן לעיין במאמר אישור וביטול אסימוני גישה. הרכיב <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 מאומתות, יש לצרף את המדיניות לבקשת ProxyEnd של AdSense. כך עושים זאת:

<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 המתאימה מופעלת, ולכן הם זמינים לכללי מדיניות או לאפליקציות אחרים שפועלים בתהליך שרת ה-proxy של ה-API.

פעולת אימותAccessToken

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

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

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

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

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

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

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

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

פעולת AuthorizationAuthorizationCode

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

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

דוגמה: oauthv2authcode.GenerateCodePolicy.code

פעולות CREATEAccessToken ו- RefreshAccessToken

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

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

דוגמה: oauthv2accesstoken.GenerateTokenPolicy.access_token

CreateAccessTokenImplicitgrant

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

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

דוגמה: oauthv2accesstoken.RefreshTokenPolicy.access_token

הפניה לשגיאה

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

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

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

שגיאות פריסה

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

משתני כשל

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

דוגמה לשגיאה

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

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

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

אם הערך של <GenerateResponse> הוא true, המדיניות מחזירה שגיאות בפורמט הזה לאימות ולאימות. לרשימה מלאה, אפשר לעיין בחומר העזר בנושא תגובת שגיאה ב-HTTP 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 מוקצה נקודת קצה (endpoint) של אסימון OAuth. נקודת הקצה מוגדרת מראש באמצעות כללי המדיניות בשרת ה-proxy של ה-API, שנקרא authauth. אפשר להתחיל להשתמש בנקודת הקצה של האסימון מיד לאחר יצירת החשבון ב-Apigee Edge. לפרטים נוספים קראו את המאמר הסבר על נקודות קצה (endpoint) ב-OAuth.

מחיקה לצמיתות של אסימוני גישה

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

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

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

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

עדכון הגדרות מחיקה לצמיתות של Edge Private Cloud 4.15.07

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

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

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

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

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

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

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

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

• מבוא ל-OAuth 2.0