OAuth

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X.
מידע

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

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

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

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

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

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

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

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

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

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

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

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

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

אימות מדיניות OAuthTokens מסוג OAuthV2

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

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

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

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

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

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

מתוך Overview של מזג האוויר, בוחרים בתצוגה פיתוח.

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

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

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

בוחרים באפשרות Add (הוספה) והמדיניות תיווצר ותצורף לבקשה PreFlow של מזג האוויר.

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

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

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

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

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

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

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

אפשר לראות את כל האפליקציות בארגון בממשק המשתמש לניהול של 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.)

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

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

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

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

/oauth/client_credential/accesstoken

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

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

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 זמינים במאמר בנושא מדיניות OAuth v1.0a.

עזרה

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