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

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

&lt;DisplayName&gt; רכיב

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

<DisplayName>Policy Display Name</DisplayName>

&lt;AccessToken&gt; רכיב

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

&lt;AccessTokenPrefix&gt; רכיב

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

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

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

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

&lt;AppEndUser&gt; רכיב

<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 לפי מזהה משתמש קצה, מזהה אפליקציה או שניהם.

&lt;Attributes/Attribute&gt;

<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 הוא פשוט חלק מהמטא נתונים של אסימון הגישה.

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

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

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

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

&lt;ClientId&gt; רכיב

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

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

&lt;Code&gt; רכיב

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

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

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

&lt;ExpiresIn&gt; רכיב

<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 להתקנת ענן פרטי, ברירת המחדל היא מוגדר על ידי המאפיין 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 user:

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

4. צריך להפעיל מחדש את מעבד ההודעות.

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

&lt;ExternalAccessToken&gt; רכיב

<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 של צד שלישי אסימונים.

&lt;ExternalAuthorization&gt; רכיב

<ExternalAuthorization>true</ExternalAuthorization>

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

&lt;ExternalAuthorizationCode&gt; רכיב

<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 של צד שלישי אסימונים.

&lt;ExternalRefreshToken&gt; רכיב

<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 של צד שלישי אסימונים.

&lt;GenerateResponse&gt; רכיב

<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 מתבטא בשניות תשובה.

&lt;GenerateErrorResponse&gt; רכיב

<GenerateErrorResponse enabled='true'/>

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

&lt;GrantType&gt;

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

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

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

&lt;Operation&gt; רכיב

<Operation>GenerateAuthorizationCode</Operation>

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

&lt;PassWord&gt; רכיב

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

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

&lt;RedirectUri&gt; רכיב

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

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

מידע על מזהי URI של הפניה אוטומטית

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

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

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

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

&lt;RefreshToken&gt; רכיב

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

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

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

&lt;RefreshTokenExpiresIn&gt; רכיב

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

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

4. צריך להפעיל מחדש את מעבד ההודעות.

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

&lt;ResponseType&gt; רכיב

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

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

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

&lt;ReuseRefreshToken&gt; רכיב

<ReuseRefreshToken>true</ReuseRefreshToken>

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

&lt;Scope&gt; רכיב

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

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

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

<Scope>A B</Scope>

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

&lt;State&gt; רכיב

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

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

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

&lt;StoreToken&gt; רכיב

 <StoreToken>true</StoreToken> 

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

&lt;SupportedGrantTypes&gt;/&lt;GrantType&gt; רכיב

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

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

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

&lt;Tokens&gt;/&lt;Token&gt; רכיב

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

&lt;UserName&gt; רכיב

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

פעולת VerifyAccessToken

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

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

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

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

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

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

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

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

GenerateAuthorizationCode פעולה

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

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

לדוגמה: oauthv2authcode.GenerateCodePolicy.code

GenerateAccessToken ו פעולות רענון

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

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

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

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

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

כברירת מחדל, אסימוני 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" : "invalid_request", "Error" :"Refresh Token expired"}

אבל תגובה שתואמת ל-RFC היא:

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

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

• מבוא ל-OAuth 2.0