מדיניות OAuthV2

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

מה

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

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

דוגמאות

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

<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. כלומר, יכול להיות שאסימון שבוטל עדיין יפעל למשך שלוש דקות לכל היותר, עד שתוקף המגבלה של המטמון שלו יפוג.
• ישויות של Key Management Service‏ (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>

אם הרכיב הזה הוא false או לא קיים, 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>

האלמנט הזה משמש רק עם סוג ההרשאה 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 של קריאה חוזרת, אפשר לעיין במאמר רישום אפליקציות וניהול מפתחות 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 for Private Cloud, ערך ברירת המחדל מוגדר על ידי המאפיין 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>

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

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

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

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

אימות טוקנים של גישה

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

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

משתני Flow

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

פעולת VerifyAccessToken

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

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

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

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

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

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

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

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

‫GenerateAuthorizationCode operation

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