אבטחת API באמצעות OAuth 2.0

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

במדריך הזה נסביר איך לאבטח proxy ל-API באמצעות אסימון גישה מסוג OAuth 2.0.

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

כדי להשלים את המדריך הזה, צריכה להיות לכם גישה לארגון Apigee שבו יש לכם הרשאה לבצע את הפעולות הבאות:

יצירה ופריסה של שרתי proxy ל-API
יצירת מוצרי API
יצירת אפליקציות למפתחים

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

פריסת שרת ה-proxy של OAuth 2.0

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

מורידים את oauth ה-proxy ל-API לדוגמה לספרייה במערכת הקבצים.

במסוף Google Cloud , נכנסים לדף Apigee > Proxy development > API proxies.

מעבר לשרתי proxy ל-API

הערה: לפני שממשיכים, כדאי לעיין ברשימת ה-API Proxy או לחפש בה. אם כבר יש לכם קובץ בשם oauth, לוחצים עליו ומדלגים לקטע הבא כדי לוודא שהוא מוגדר כמו שמתואר. אם הוא שונה, אפשר למחוק אותו ולהמשיך בשלבים האלה, או לשנות אותו כך שיתאים להגדרה שמתוארת.
בחלונית API Proxies (שרתי proxy של API), לוחצים על + Create (יצירה).
בחלונית Create a proxy (יצירת שרת proxy), בקטע Proxy template (תבנית שרת proxy), בוחרים באפשרות Upload proxy bundle (העלאת חבילת שרת proxy).
בוחרים את הקובץ oauth.zip שהורדתם ולוחצים על הבא.
לוחצים על הבא.
פריסה (אופציונלי):
- סביבות פריסה: אופציונלי. משתמשים בתיבות הסימון כדי לבחור סביבה אחת או יותר שבהן רוצים לפרוס את ה-proxy. אם אתם לא רוצים לפרוס את ה-proxy בשלב הזה, אתם יכולים להשאיר את השדה סביבות פריסה ריק. תמיד אפשר לפרוס את ה-proxy מאוחר יותר.
- חשבון שירות: אופציונלי. מצרפים חשבון שירות לפריסה כדי לאפשר לשרת ה-proxy לגשת לשירותים, כפי שמצוין בתפקיד ובהרשאות של חשבון השירות. Google Cloud
לוחצים על יצירה.

הורדתם ופרסתם בהצלחה פרוקסי של API ליצירת אסימוני גישה בארגון שלכם ב-Apigee.

הצגת תהליך ההרשאה באמצעות OAuth 2.0 והמדיניות

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

בשלב הבא, נבדוק לעומק את מה שכלול ב-proxy ל-API.

בכלי לעריכת proxy ל-API, לוחצים על הכרטיסייה פיתוח.

בחלונית הימנית, יוצגו שתי מדיניות. בקטע Proxy Endpoints (נקודות קצה של שרת proxy) יופיעו גם שני תהליכי POST.
לוחצים על AccessTokenClientCredential בקטע Proxy Endpoints (נקודות קצה של שרת proxy). בכלי לעריכת טקסט מוצג קוד ה-XML של זרימת התנאים AccessTokenClientCredential:
```
<Flow name="AccessTokenClientCredential">
    <Description/>
    <Request>
        <Step>
            <Name>GenerateAccessTokenClient</Name>
        </Step>
    </Request>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/accesstoken") and (request.verb = "POST")</Condition>
</Flow>
```
תהליך הוא שלב עיבוד ב-proxy ל-API. במקרה הזה, התהליך מופעל כשמתקיים תנאי מסוים (זה נקרא 'תהליך מותנה'). התנאי, שמוגדר ברכיב <Condition>, קובע שאם מתבצעת קריאה ל-proxy ל-API למשאב /accesstoken, ופועל ה-request הוא POST, אז תופעל מדיניות GenerateAccessTokenClient, שתייצר את טוקן הגישה.
עכשיו נבדוק איזו מדיניות תופעל על ידי התהליך המותנה. לוחצים על המדיניות GenerateAccessTokenClient בחלונית Request:

מוצגת הגדרת ה-XML הבאה:

<OAuthV2 name="GenerateAccessTokenClient">
    <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
    <Operation>GenerateAccessToken</Operation>
    <!-- This is in milliseconds, so expire in an hour -->
    <ExpiresIn>3600000</ExpiresIn>
    <SupportedGrantTypes>
        <!-- This part is very important: most real OAuth 2.0 apps will want to use other
         grant types. In this case it is important to NOT include the "client_credentials"
         type because it allows a client to get access to a token with no user authentication -->
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GrantType>request.queryparam.grant_type</GrantType>
    <GenerateResponse/>
</OAuthV2>

ההגדרות כוללות את:

הערך <Operation>, שיכול להיות אחד מכמה ערכים מוגדרים מראש, מגדיר מה המדיניות תעשה. במקרה הזה, היא תיצור אסימון גישה.
תוקף הטוקן יפוג שעה אחת (3,600,000 מילישניות) אחרי שהוא נוצר.
ב-<SupportedGrantTypes>, פרוטוקול OAuth 2.0‏ <GrantType> שצפוי לשמש הוא client_credentials (החלפת טוקן צרכן וסוד באסימון OAuth 2.0).
רכיב <GrantType> השני מציין למדיניות איפה לחפש בקריאה ל-API את הפרמטר של סוג ההרשאה, כפי שנדרש במפרט של OAuth 2.0. (הפרטים האלה יופיעו בהמשך בקריאה ל-API). אפשר גם לשלוח את סוג ההרשאה בכותרת ה-HTTP ‏ (request.header.grant_type) או כפרמטר של טופס (request.formparam.grant_type).

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

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

יצירת proxy מוגן ל-API

עכשיו יוצרים את proxy ל-API שרוצים להגן עליו. זו קריאה ל-API שמחזירה משהו שאתם רוצים. במקרה כזה, ה-proxy ל-API יקרא לשירות mocktarget של Apigee כדי להחזיר את כתובת ה-IP שלכם. אבל תוכלו לראות אותו רק אם תעבירו אסימון גישה תקין מסוג OAuth 2.0 עם הקריאה ל-API.

ה-proxy ל-API שיוצרים כאן יכלול מדיניות שבודקת אם יש אסימון OAuth 2.0 בבקשה.

במסוף Google Cloud , נכנסים לדף Apigee > Proxy development > API proxies.

מעבר לשרתי proxy ל-API
בחלונית API Proxies (שרתי proxy של API), לוחצים על + Create (יצירה).
בחלונית Create a proxy (יצירת שרת proxy), בקטע Proxy template (תבנית שרת proxy), בוחרים באפשרות Reverse proxy (most common) (שרת proxy הפוך (הנפוץ ביותר)).

מגדירים את ה-Proxy עם הפרטים הבאים:

בשדה הזה	do this
שם שרת ה-Proxy	מזינים: `helloworld_oauth2`
נתיב בסיסי	החלפה בהגדרה: `/hellooauth2` נתיב הבסיס של הפרויקט הוא חלק מכתובת ה-URL שמשמשת לשליחת בקשות לשרת ה-proxy של ה-API.
תיאור	מזינים: `hello world protected by OAuth 2.0`
יעד (API קיים)	מזינים: `https://mocktarget.apigee.net/ip` ההגדרה הזו מגדירה את כתובת ה-URL של היעד שאליו Apigee שולח בקשה לשרת ה-proxy של ה-API.

לוחצים על הבא.
פריסה (אופציונלי):
- סביבות פריסה: אופציונלי. משתמשים בתיבות הסימון כדי לבחור סביבה אחת או יותר שבהן רוצים לפרוס את ה-proxy. אם אתם לא רוצים לפרוס את ה-proxy בשלב הזה, צריך להשאיר את השדה סביבות פריסה ריק. תמיד אפשר לפרוס את ה-proxy מאוחר יותר.
- חשבון שירות: אופציונלי. מצרפים חשבון שירות לפריסה כדי לאפשר לשרת ה-proxy לגשת לשירותים, כמו שצוין בתפקיד ובהרשאות של חשבון השירות. Google Cloud
לוחצים על יצירה.
לוחצים על הכרטיסייה Develop (פיתוח) של ה-proxy‏ helloworld_oauth2.
בתפריט Policies (מדיניות), לוחצים על Add policy (הוספת מדיניות).
בחלונית Create policy (יצירת מדיניות), בוחרים באפשרות OAuth 2.0.
לוחצים על יצירה.

צפייה במדיניות

בואו נבדוק את מה שיצרתם.

בכלי לעריכת proxy ל-API, לוחצים על הכרטיסייה פיתוח. אפשר לראות ששתי מדיניות נוספו לזרימת הבקשות של ה-proxy ל-API:
- ‫Verify OAuth v2.0 Access Token (אימות אסימון גישה מסוג OAuth v2.0) – בודק את קריאה ל-API כדי לוודא שאסימון OAuth 2.0 תקף קיים.
- Remove Header Authorization (הסרת הרשאת הכותרת) – מדיניות Assign Message (הקצאת הודעה) שמסירה את אסימון הגישה אחרי שהוא נבדק, כדי שהוא לא יועבר לשירות היעד. (אם שירות היעד היה צריך את אסימון הגישה מסוג OAuth 2.0, לא הייתם משתמשים במדיניות הזו).
לוחצים על הסמל אימות אסימון גישה מסוג OAuth v2.0 בחלונית השמאלית ומעיינים ב-XML שמתחתיו בעורך הטקסט.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="verify-oauth-v2-access-token">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

שימו לב שהערך של <Operation> הוא VerifyAccessToken. הפעולה מגדירה מה המדיניות אמורה לעשות. במקרה הזה, היא תבדוק אם יש בבקשה אסימון OAuth 2.0 תקין.

הוספת מוצר API

כדי לקבל אסימון גישה מסוג OAuth 2.0, צריך ליצור שלושה ישויות ב-Apigee: מוצר API, מפתח ואפליקציה למפתחים.

יוצרים את מוצר ה-API:

במסוף Google Cloud , נכנסים לדף Apigee > Distribution > API products.

לדף API products

לוחצים על ‎+ Create.

מזינים את פרטי המוצר של מוצר ה-API.

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

בקטע פעולות, לוחצים על הוספת פעולה.
בשדה API Proxy (proxy ל-API), בוחרים את ה-proxy ל-API שיצרתם.
בשדה 'נתיב', מזינים '/'. מתעלמים מהשדות האחרים.
לוחצים על שמירה כדי לשמור את הפעולה.
לוחצים על שמירה כדי לשמור את מוצר ה-API.

הוספת מפתח ואפליקציה לארגון

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

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

יצירת מפתח

ניצור מפתח בשם Nigel Tufnel.

פותחים את העורך Developer.
במסוף Google Cloud , עוברים לדף Apigee > Distribution > Developers.

מעבר אל 'מפתחים'
לוחצים על ‎+ Create.

בחלון הוספת מפתח, מזינים את הפרטים הבאים:

בשדה הזה	Enter
שם פרטי	`Nigel`
שם משפחה	`Tufnel`
אימייל	`nigel@example.com`
שם משתמש	`nigel`

לוחצים על הוספה.

רישום אפליקציה

ניצור אפליקציה בשביל נייג'ל.

במסוף Google Cloud , נכנסים לדף Apigee > Distribution > Apps.

מעבר אל 'אפליקציות'
לוחצים על ‎+ Create.

מזינים את הפרטים הבאים בחלון 'אפליקציה חדשה':

בשדה הזה	do this
שם ושם לתצוגה	מזינים: `nigel_app`
מפתח	לוחצים על Developer (מפתח) ובוחרים באחת מהאפשרויות הבאות: `Nigel Tufnel (nigel@example.com)`
כתובת URL לקריאה חוזרת (callback) והערות	להשאיר ריק

לוחצים על + הוספת פרטי כניסה.
לוחצים על + הוספת מוצרים.
בוחרים את מוצר ה-API שיצרתם.
לוחצים על הוספה.
לוחצים על יצירה.

מקבלים את טוקן הצרכן ואת הסוד לשימוש עם טוקן הצרכן

עכשיו תקבלו את אסימון הצרכן ואת סוד הצרכן שיוחלפו באסימון גישה מסוג OAuth 2.0.

פותחים את הדף nigel_app.

מוודאים שהדף nigel_app מוצג. אם לא, עוברים לדף הפצה > אפליקציות.

מעבר אל 'אפליקציות'
בדף nigel_app, לוחצים על בעמודות Key ו-Secret. שימו לב שהמפתח והסוד משויכים למוצר ה-API שיצרתם קודם.

בוחרים את הערכים של Key (מפתח) ו-Secret (סוד) ומעתיקים אותם. מדביקים אותם בקובץ טקסט זמני. תשתמשו בהם בשלב מאוחר יותר, כשתיגשו ל-proxy ל-API שיחליף את פרטי הכניסה האלה באסימון גישה מסוג OAuth 2.0.

מנסים לשלוח קריאה ל-API כדי לקבל את כתובת ה-IP (נכשל!)

מנסים לקרוא ל-proxy המוגן של ה-API שיצרתם. שימו לב שלא מעבירים אסימון גישה מסוג OAuth 2.0 בקריאה.

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

מכיוון שב-proxy ל-API מוגדרת מדיניות Verify OAuth v2.0 Access Token שבודקת אם יש בבקשה אסימון OAuth 2.0 תקף, הקריאה אמורה להיכשל עם ההודעה הבאה:

{"fault":{"faultstring":"Invalid access token","detail":{"errorcode":"oauth.v2.InvalidAccessToken"}}}

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

קבלת אסימון גישה מסוג OAuth 2.0

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

בעזרת המפתח והסוד האלה, מבצעים את קריאת ה-cURL הבאה (שימו לב שהפרוטוקול הוא https):

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
"https://YOUR ENV_GROUP_HOSTNAME/oauth/client_credential/accesstoken?grant_type=client_credentials" \
-d "client_id=CLIENT_KEY&client_secret=CLIENT_SECRET"

שימו לב: אם אתם משתמשים בלקוח כמו Postman כדי לבצע את הקריאה, הפרמטרים client_id ו-client_secret צריכים להיות בגוף הבקשה, והם חייבים להיות x-www-form-urlencoded.

אמורה להתקבל תגובה כמו זו:

{
  "issued_at" : "1466025769306",
  "application_name" : "716bbe61-f14a-4d85-9b56-a62ff8e0d347",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[helloworld_oauth2-Product]",
  "expires_in" : "3599", //--in seconds
  "developer.email" : "nigel@example.com",
  "token_type" : "BearerToken",
  "client_id" : "xNnREu1DNGfiwzQZ5HUN8IAUwZSW1GZW",
  "access_token" : "GTPY9VUHCqKVMRB0cHxnmAp0RXc0",
  "organization_name" : "myOrg",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

קיבלתם אסימון גישה מסוג OAuth 2.0. מעתיקים את הערך access_token (ללא המירכאות) ומדביקים אותו בקובץ הטקסט. תשתמשו בו עוד מעט.

מה קרה עכשיו?

זוכרים שקודם הסתכלנו על ה-flow המותנה ב-proxy של OAuth? זה שאומר שאם ה-URI של המשאב הוא /accesstoken ופועל הפעולה של הבקשה הוא POST, צריך להפעיל את מדיניות OAuth 2.0 שיוצרת אסימון גישה.GenerateAccessTokenClient פקודת cURL שלך עמדה בתנאים האלה, ולכן מדיניות OAuth 2.0 הופעלה. המערכת אימתה את טוקן הצרכן ואת הסוד של הצרכן והחליפה אותם באסימון OAuth 2.0 שתוקפו יפוג תוך שעה.

שליחת קריאה ל-API עם אסימון גישה (הצלחה!)

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

curl https://YOUR ENV_GROUP_HOSTNAME/hellooauth2 -H "Authorization: Bearer TOKEN"

עכשיו אמורה להתקבל קריאה מוצלחת ל-proxy ל-API שמחזירה את כתובת ה-IP שלכם. לדוגמה:

{"ip":"::ffff:192.168.14.136"}

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

כל הכבוד! יצרתם proxy ל-API והגנתם עליו באמצעות דרישה לכלול בקריאה אסימון גישה תקף מסוג OAuth 2.0.

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

דף הבית של OAuth 2.0
מדיניות OAuthV2
הורדת שרתי proxy ל-API (שמוסבר בו איך לארוז שרת proxy ל-API בקובץ ZIP כמו זה שהורדתם)