מדיניות 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)));

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

הפניה לרכיב

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

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

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

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

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

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

הפעולה VerifyAccessToken

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

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

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

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

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

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

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

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

פעולת 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