OAuth

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

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

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

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

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

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

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

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

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

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

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

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

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

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

המדיניות בנושא VerifyOAuthTokens מסוג OAuthV2

כך נראה מדיניות לדוגמה לאימות אסימוני גישה. (ההגדרות הן כפי שמוסבר בטבלה שלמטה).

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

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

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

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

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

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

בתפריט הנפתח, בוחרים באפשרות מדיניות חדשה > גרסה 2.0 של OAuth

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

נותנים למדיניות שם תיאורי ומקפידים לבחור באפשרות צירוף מדיניות. Flow PreFlow ו-Request כהגדרות לצירוף מדיניות.

בוחרים באפשרות הוספה. המדיניות תיווצר ותצורף לבקשה של weatherapi קדם-זרימה (preFlow).

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

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

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

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

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

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

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

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

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

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

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

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

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

ברירת המחדל של נקודת הקצה (endpoint) של OAuth חושפת את ה-URI הבא של נקודת הקצה:

/oauth/client_credential/accesstoken

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

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

OAuth 1.0a

לפרטים על מדיניות OAuth 1.0a, ראו מדיניות OAuth v1.0a.

עזרה

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