OAuth

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

פרוטוקול OAuth הפך לפרוטוקול ההרשאות המוביל לממשקי API. הגרסה של OAuth שמפורטת בנושא הזה מוגדרת ב מפרט OAuth 2.0.

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

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

הגדרת ברירת המחדל של OAuth בארגון שלכם

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

מידע נוסף על הנפקת פרטי כניסה לאפליקציות באמצעות Edge Developer Services זמין במאמר רישום אפליקציות וניהול מפתחות.

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

המפרט המלא של הרשאת פרטי הכניסה של הלקוח מופיע במפרט OAuth 2.0.

הגנה על ממשק ה-API באמצעות מדיניות

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

אפשר להוסיף בקלות אימות OAuth ל-API כשיוצרים proxy ל-API חדש. כשיוצרים proxy ל-API חדש, אפשר ללחוץ על Add Features (הוספת תכונות). כפי שמוצג בהמשך, כדי להוסיף אימות של אסימוני גישה מסוג OAuth 2.0, מסמנים את כפתור הבחירה לצד Secure with OAuth v2.0 Access Tokens (אבטחה באמצעות אסימוני גישה מסוג OAuth 2.0). כשבוחרים באפשרות הזו, שתי מדיניות מצורפות לפרוקסי API שנוצר, אחת לאימות טוקנים של גישה ואחת להסרת הטוקן של הגישה אחרי האימות.

בנוסף, כשבוחרים באפשרות Secure with OAuth v2.0 Access Tokens (אבטחה באמצעות אסימוני גישה מסוג OAuth v2.0), תיבת הסימון Publish API Product (פרסום מוצר API) הופכת לזמינה לסימון ומסומנת באופן אוטומטי. מסמנים את התיבה הזו אם רוצים ליצור מוצר באופן אוטומטי כשיוצרים את שרת ה-proxy החדש של API. המוצר שנוצר אוטומטית יקושר ל-proxy ל-API החדש. אם יש לכם מוצר קיים שאתם רוצים לשייך אליו את ה-API החדש הזה, הקפידו לבטל את סימון התיבה הזו כדי שלא תיצרו מוצר מיותר. מידע על מוצרים זמין במאמר מה זה מוצר API?

אם אתם צריכים להפעיל אימות של אסימון גישה לשרת proxy של API שכבר קיים, כל מה שאתם צריכים לעשות הוא לצרף מדיניות מסוג OAuthV2 ל-API שאתם רוצים להגן עליו. כללי מדיניות של OAuthV2 פועלים על ידי ציון פעולה. אם רוצים לאמת אסימוני גישה, מציינים את הפעולה שנקראת VerifyAccessToken. (סוגים אחרים של פעולות שנתמכות על ידי סוג המדיניות OAuthV2 הם GenerateAccessToken ו- GenerateRefreshToken. מידע על הפעולות האלה יופיע כשמגדירים נקודות קצה של OAuth.)

‫VerifyOAuthTokens policy of type OAuthV2

דוגמה למדיניות לאימות אסימוני גישה: (ההגדרות מוסברות בטבלה שלמטה).

<OAuthV2 name="VerifyOAuthTokens">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

הגדרות מדיניות

שם תיאור ברירת מחדל חובה?
OAuthV2 סוג המדיניות
name השם של המדיניות, שמופיע בהפניה בהגדרות של נקודת הקצה של proxy ל-API. לא רלוונטי כן
Operation הפעולה שתבוצע על ידי מדיניות OAuthV2. ההגדרה VerifyAccessToken מאפשרת להגדיר את המדיניות כך שתבדוק אם יש בבקשות טוקנים של גישה, ותוודא שהטוקן תקף, שלא פג תוקפו ושהוא אושר לשימוש במשאב ה-API המבוקש (URI). (כדי לבצע את הבדיקה הזו, המדיניות קוראת את מוצר ה-API שהאפליקציה קיבלה אישור לצרוך). לא רלוונטי כן

כדי ליצור את המדיניות הזו בממשק הניהול, עוברים אל APIs > API Proxies.

ברשימת ה-API proxies, בוחרים באפשרות weatherapi.

בתצוגה Overview של weatherapi, בוחרים באפשרות Develop.

בתפריט הנפתח, בוחרים באפשרות מדיניות חדשה > OAuth v2.0.

אחרי שבוחרים במדיניות OAuth v2.0, מוצג תפריט ההגדרות של New Policy (מדיניות חדשה).

נותנים למדיניות שם תיאורי ולוחצים על Attach Policy (צירוף מדיניות), Flow PreFlow (זרימת PreFlow) ו-Request (בקשה) כהגדרות לצירוף מדיניות.

לוחצים על Add (הוספה) והמדיניות נוצרת ומצורפת ל-PreFlow של הבקשה של weatherapi.

אחרי שמוסיפים את המדיניות, ההגדרה של PreFlow של הבקשה שבהמשך תוצג בחלונית Designer.

אם אתם עובדים באופן מקומי בכלי לעריכת טקסט או בסביבת פיתוח משולבת (IDE), אתם מצרפים את המדיניות לבקשת PreFlow של proxy ל-API שאתם רוצים להגן עליו:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthTokens</Name></Step>
  </Request>
</PreFlow>

אם מצרפים את המדיניות ל-PreFlow של הבקשה, מוודאים שהמדיניות תמיד נאכפת על כל הודעות הבקשה.

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

שימוש בטוקן גישה כדי לגשת למשאב מוגן

עכשיו, כש-weatherapi מאובטח באמצעות OAuth 2.0, האפליקציות צריכות להציג אסימוני גישה כדי להשתמש בממשק ה-API. כדי לגשת למשאב מוגן, האפליקציה מציגה אסימון גישה בבקשה ככותרת HTTP מסוג Authorization באופן הבא:

$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

מכיוון שמדיניות OAuthV2 מצורפת ל-API,‏ Apigee Edge יאמת שאסימון הגישה שמוצג תקף, ואז יאשר גישה ל-API ויחזיר את דוח מזג האוויר לאפליקציה ששלחה את הבקשה.

אבל איך אפליקציות מקבלות אסימוני גישה? בקטע הבא נסביר איך עושים את זה.

איך ממירים פרטי כניסה של לקוח לאסימון גישה

אפליקציות מקבלות טוקני גישה על ידי הצגת צמדי טוקן צרכן/סוד שלהן לנקודת הקצה של הטוקן. נקודת הקצה של הטוקן מוגדרת ב-proxy ל-API שנקרא oauth. לכן, אפליקציות צריכות לשלוח קריאה ל-API שמוצג על ידי פרוקסי של oauth API כדי לקבל אסימון גישה. אחרי שהאפליקציה מקבלת אסימון גישה, היא יכולה להתקשר אל weatherapi שוב ושוב, עד שתוקף אסימון הגישה יפוג או עד שאסימון הגישה יבוטל.

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

כדי לקבל טוקן צרכן וסוד, צריך לרשום אפליקציה בארגון ב-Apigee Edge.

אתם יכולים לראות את כל האפליקציות בארגון בממשק הניהול של Apigee Edge.

תוצג רשימת האפליקציות שרשומות בארגון שלכם.

(אם לא מוצגות אפליקציות, אפשר לקרוא איך לרשום אפליקציה בנושא רישום אפליקציות וניהול מפתחות API).

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

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

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps \
-u myname:mypass

הקריאה הזו מחזירה רשימה של אפליקציות לפי מזהה האפליקציה.

[ "da496fae-2a04-4a5c-b2d0-709278a6f9db", "50e3e831-175b-4a05-8fb6-05a54701af6e" ]

אפשר לאחזר את הפרופיל של אפליקציה באמצעות קריאת GET פשוטה במזהה האפליקציה:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u myname:mypass

לדוגמה:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/da496fae-2a04-4a5c-b2d0-709278a6f9db \
-u myname:mypass

הקריאה ל-API מחזירה את הפרופיל של האפליקציה שציינתם. לדוגמה, פרופיל אפליקציה של weatherapp ייראה כך ב-JSON:

{
  "accessType" : "read",
  "apiProducts" : [ ],
  "appFamily" : "default",
  "appId" : "da496fae-2a04-4a5c-b2d0-709278a6f9db",
  "attributes" : [ ],
  "callbackUrl" : "http://weatherapp.com",
  "createdAt" : 1380290158713,
  "createdBy" : "noreply_admin@apigee.com",
  "credentials" : [ {
    "apiProducts" : [ {
      "apiproduct" : "PremiumWeatherAPI",
      "status" : "approved"
    } ],
    "attributes" : [ ],
    "consumerKey" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
    "consumerSecret" : "hAr4Gn0gA9vAyvI4",
    "expiresAt" : -1,
    "issuedAt" : 1380290161417,
    "scopes" : [ ],
    "status" : "approved"
  } ],
  "developerId" : "5w95xGkpnjzJDBT4",
  "lastModifiedAt" : 1380290158713,
  "lastModifiedBy" : "noreply_admin@apigee.com",
  "name" : "weatherapp",
  "scopes" : [ ],
  "status" : "approved"
}

שימו לב לערכים של consumerKey ו-consumerSecret. משתמשים בפרטי הכניסה האלה כדי לקבל אסימון גישה. לשם כך, שולחים אותם כפרטי כניסה לאימות בסיסי בבקשת HTTP, כמו שמוצג בהמשך. סוג grant מוצג כפרמטר שאילתה בבקשה. (חשוב לשנות את הערך של המשתנה {org_name} כך שישקף את שם הארגון שלכם ב-Apigee Edge).

יצירת בקשה לקבלת אסימון גישה

בבקשה הבאה, מחליפים את הערך של consumerKey בערך של client_id. מחליפים את הערך של מאפיין consumerSecret המשויך בערך client_secret.

$ curl https://{org_name}-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'

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

{
  "issued_at" : "1380892555397",
  "application_name" : "957aa73f-25c2-4ead-8021-adc01f0d2c6b",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[oauth-test]",
  "expires_in" : "3599",
  "developer.email" : "tesla@weathersample.com",
  "organization_id" : "0",
  "client_id" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
  "access_token" : "ylSkZIjbdWybfs4fUQe9BqP0LH5Z",
  "organization_name" : "rqa",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

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

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

עבודה עם הגדרת ברירת המחדל של OAuth

לכל ארגון (גם ארגון עם תקופת ניסיון בחינם) ב-Apigee Edge מוקצה טוקן OAuth endpoint. נקודת הקצה מוגדרת מראש עם מדיניות ב-proxy ל-API שנקרא oauth. אפשר להתחיל להשתמש בנקודת הקצה של הטוקן ברגע שיוצרים חשבון ב-Apigee Edge.

נקודת הקצה של OAuth שמוגדרת כברירת מחדל חושפת את מזהה ה-URI של נקודת הקצה הבא:

/oauth/client_credential/accesstoken

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

נקודת הקצה של הטוקן של פרטי הכניסה של הלקוח שמוגדרת כברירת מחדל נחשפת ברשת בכתובת ה-URL הבאה:

https://{org_name}-{env_name}.apigee.net/oauth/client_credential/accesstoken

לדוגמה, אם שם הארגון הוא apimakers, כתובת ה-URL תהיה:

https://apimakers-test.apigee.net/oauth/client_credential/accesstoken

זו כתובת ה-URL שהמפתחים קוראים לה כדי לקבל טוקנים של גישה.

הגדרות של OAuth תלת-רגלי

הגדרות OAuth עם שלושה רגליים (סוגי הרשאות של קוד הרשאה, הרשאה משתמעת והרשאת סיסמה) מחייבות אתכם, ספקי ה-API, לאמת את משתמשי הקצה של האפליקציה. כל ארגון מאמת משתמשים בדרכים שונות, ולכן נדרשת התאמה אישית של המדיניות או של הקוד כדי לשלב את OAuth עם מאגר המשתמשים. לדוגמה, יכול להיות שכל המשתמשים שלכם מאוחסנים ב-Active Directory, ב-LDAP או במאגר משתמשים אחר. כדי להפעיל OAuth תלת-רגלי, צריך לשלב בדיקה מול מאגר המשתמשים הזה בתהליך ה-OAuth הכולל.

OAuth 1.0a

התמיכה ב-OAuth 1.0a הוצאה משימוש. לפרטים נוספים, אפשר לעיין במאמר בנושא תכונות שיצאו משימוש.

עזרה

לקבלת עזרה, אפשר לעיין במאמר תמיכת לקוחות של Apigee.