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

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

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

  2. בחלונית API Proxies (שרתי proxy של API), לוחצים על + Create (יצירה).
  3. בחלונית יצירת שרת proxy, בקטע תבנית שרת proxy, בוחרים באפשרות העלאת חבילת שרת proxy.
  4. בוחרים את הקובץ oauth.zip שהורדתם ולוחצים על הבא.
  5. לוחצים על הבא.
  6. פריסה (אופציונלי):
    • סביבות פריסה: אופציונלי. משתמשים בתיבות הסימון כדי לבחור סביבה אחת או יותר שבהן רוצים לפרוס את ה-proxy. אם אתם לא רוצים לפרוס את ה-proxy בשלב הזה, אתם יכולים להשאיר את השדה סביבות פריסה ריק. תמיד אפשר לפרוס את ה-proxy מאוחר יותר.
    • חשבון שירות: אופציונלי. מצרפים חשבון שירות לפריסה כדי לאפשר לשרת ה-proxy לגשת לשירותים, כמו שצוין בתפקיד ובהרשאות של חשבון השירות. Google Cloud
  7. לוחצים על יצירה.

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

צפייה בתהליך ובמדיניות של OAuth 2.0

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

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

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

    המדיניות שמוצגת בכרטיסייה Develop.

    בחלונית הימנית, יוצגו שני כללי מדיניות. בקטע Proxy Endpoints (נקודות קצה של שרת proxy) יופיעו גם שני תהליכי POST.

  2. לוחצים על 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>

    ‫Flow הוא שלב עיבוד ב-proxy ל-API. במקרה הזה, ה-flow מופעל כשמתקיים תנאי מסוים (הוא נקרא conditional flow). התנאי, שמוגדר ברכיב <Condition>, קובע שאם מתבצעת קריאה ל-proxy ל-API למשאב /accesstoken, ופועל הפעולה של הבקשה הוא POST, אז תופעל המדיניות GenerateAccessTokenClient, שמייצרת את אסימון הגישה.

  3. עכשיו נבדוק את המדיניות שתופעל על ידי התנאי. לוחצים על המדיניות GenerateAccessTokenClient בחלונית Request: לוחצים על GenerateAccessTokenClient מתחת ל-AccessTokenClientCredential.

מוצגת הגדרת ה-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 בבקשה.

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

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

  2. בחלונית API Proxies (שרתי proxy של API), לוחצים על + Create (יצירה).
  3. בחלונית Create a proxy (יצירת שרת proxy), בקטע Proxy template (תבנית שרת proxy), בוחרים באפשרות Reverse proxy (most common) (שרת proxy הפוך (הנפוץ ביותר)).
  4. מגדירים את ה-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.
  5. לוחצים על הבא.
  6. פריסה (אופציונלי):
    • סביבות פריסה: אופציונלי. משתמשים בתיבות הסימון כדי לבחור סביבה אחת או יותר שבהן רוצים לפרוס את ה-proxy. אם אתם לא רוצים לפרוס את ה-proxy בשלב הזה, אתם יכולים להשאיר את השדה סביבות פריסה ריק. תמיד אפשר לפרוס את ה-proxy מאוחר יותר.
    • חשבון שירות: אופציונלי. מצרפים חשבון שירות לפריסה כדי לאפשר לשרת ה-proxy לגשת לשירותים, כמו שצוין בתפקיד ובהרשאות של חשבון השירות. Google Cloud
  7. לוחצים על יצירה.
  8. לוחצים על הכרטיסייה Develop (פיתוח) של ה-proxy‏ helloworld_oauth2.
  9. בתפריט Policies (מדיניות), לוחצים על Add policy (הוספת מדיניות).
  10. בחלונית Create policy (יצירת מדיניות), בוחרים באפשרות OAuth 2.0.
  11. לוחצים על יצירה.

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

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

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

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

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

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

    מעבר אל מוצרי API

  2. לוחצים על ‎+ Create.
  3. מזינים את פרטי המוצר של מוצר ה-API.
    שדה תיאור
    שם השם הפנימי של מוצר ה-API. אל תציינו תווים מיוחדים בשם.
    הערה: אי אפשר לערוך את השם אחרי שיוצרים את מוצר ה-API.
    השם המוצג השם המוצג של מוצר ה-API. השם המוצג משמש בממשק המשתמש, ואפשר לערוך אותו בכל שלב. אם לא מציינים ערך, המערכת משתמשת בערך של Name. השדה הזה מתמלא אוטומטית באמצעות הערך של השם. אפשר לערוך או למחוק את התוכן שלו. השם המוצג יכול לכלול תווים מיוחדים.
    תיאור תיאור של מוצר ה-API.
    סביבה סביבות שמוצר ה-API יאפשר גישה אליהן. בוחרים את הסביבה שבה פרסתם את proxy ל-API.
    גישה בוחרים באפשרות ציבורי.
    אישור אוטומטי של בקשות גישה הפעלת אישור אוטומטי של בקשות למפתחות למוצר ה-API הזה מכל אפליקציה.
    מכסה אפשר להתעלם מההודעה הזו במדריך הזה.
    היקפי הרשאות OAuth 2.0 מותרים אפשר להתעלם מההודעה הזו במדריך הזה.
  4. בקטע פעולות, לוחצים על הוספת פעולה.
  5. בשדה API Proxy (proxy ל-API), בוחרים את ה-proxy ל-API שיצרתם.
  6. בשדה 'נתיב', מזינים '/'. מתעלמים מהשדות האחרים.
  7. לוחצים על שמירה כדי לשמור את הפעולה.
  8. לוחצים על שמירה כדי לשמור את מוצר ה-API.

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

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

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

יצירת מפתח

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

  1. פותחים את העורך Developer.

  2. במסוף Google Cloud , עוברים לדף Apigee > Distribution > Developers.

    מעבר אל 'מפתחים'

  3. לוחצים על ‎+ Create.
  4. בחלון הוספת מפתח, מזינים את הפרטים הבאים:
    בשדה הזה Enter
    שם פרטי Nigel
    שם משפחה Tufnel
    אימייל nigel@example.com
    שם משתמש nigel
  5. לוחצים על הוספה.

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

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

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

    מעבר אל 'אפליקציות'

  2. לוחצים על ‎+ Create.
  3. מזינים את הפרטים הבאים בחלון 'אפליקציה חדשה':
    בשדה הזה do this
    שם ושם לתצוגה מזינים: nigel_app
    מפתח לוחצים על Developer (מפתח) ובוחרים באחת מהאפשרויות הבאות: Nigel Tufnel (nigel@example.com)
    כתובת URL להתקשרות חזרה והערות להשאיר ריק
  4. לוחצים על + הוספת פרטי כניסה.
  5. לוחצים על + הוספת מוצרים.
  6. בוחרים את מוצר ה-API שיצרתם.
  7. לוחצים על הוספה.
  8. לוחצים על יצירה.

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

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

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

      מעבר אל 'אפליקציות'

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

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

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

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

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

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

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

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

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

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

מה קרה עכשיו?

זוכרים שכשבדקתם את ה-proxy של OAuth, ראיתם את ה-flow עם התנאי שאם ה-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.

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