OAuth ל-Data Plan Plan Agent API

OAuth 2.0 סטנדרטי לפי RFC 6749. ניתן למצוא מסמך מפורט בכתובת https://oauth.net/2. אימות בסיסי של HTTP מוגדר בסעיף 2 של RFC 2617.

סקירה כללית

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

במקום להשתמש בפרטי הכניסה של משתמש הקצה כדי לגשת למשאבים מוגנים, כמו פרטי תוכנית הנתונים, ה-GTAF מקבל אסימון גישה. אסימוני הגישה מונפקים ל-GTAF בשם פרטי הכניסה של GTAF&#39. לאחר מכן, ה-GTAF משתמש בפרטי הגישה כדי לגשת לפרטי תוכנית הנתונים שמתארחים ב-DPA.

האיור הבא מספק זרימת מידע ברמה גבוהה:

איור 1. תהליך מופשט של OAuth.

אסימוני גישה

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

אסימון הגישה מספק שכבת הפשטה, שתחליף מבני הרשאות שונים (למשל שם משתמש וסיסמה) באסימון יחיד שהובא על ידי ה-DPA. ההפשטה הזו מאפשרת להנפיק אסימוני גישה מחמירים יותר מהענקת ההרשאה המשמשת להשגתם, כמו גם את הסרת ה-DPA&#39. חשוב להבין מגוון רחב של שיטות אימות.

לאסימוני גישה יכולים להיות פורמטים, מבנים ושיטות שונים לשימוש (למשל, מאפייני הצפנה) בהתאם לדרישות האבטחה של הספק. GTAF תומך רק באסימונים לגישה מסוג דובים שמוגדרים ב-[RFC6750].

אימות לקוח

ה-GTAF פועל כ &רשימת סודיות;& יכול להיות שהוא מסוגל להגן על סיסמאות. כרגע, ה-GTAF תומך באימות HTTP בסיסי בלבד כדי לבצע אימות באמצעות DPA. מזהה הלקוח מקודד באמצעות האלגוריתם "application/x-www-form-urlencoded" והערך של הקידוד משמש בתור שם המשתמש. הסיסמה מקודדת באמצעות אותו אלגוריתם ומשמשת כסיסמה.

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

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

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

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

  1. הספק יוצר פרטי כניסה חדשים בשרת ה-OAuth ומספק את פרטי הכניסה למנהל החשבון הטכני שלו באופן מאובטח.
  2. Google בודקת את פרטי הכניסה החדשים ומשנה את ההגדרה של GTAF כך שישתמשו בפרטי הכניסה החדשים.
  3. Google מיידעת את הספק שייתכן שפרטי הכניסה הישנים מושבתים.
  4. הספק משבית את פרטי הכניסה ומעדכן את Google
  5. Google מוודאת שפרטי הכניסה הישנים אינם פעילים יותר

שרת ה-OAuth צריך להיות מסוגל לתמוך בתהליך הסיבוב הקודם.

נקודת קצה לאסימון

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

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

  • המיקום של נקודת הקצה לאסימון צריך להופיע במסמכי השירות.
  • ה-URI של נקודת הקצה עשוי לכלול "application/x-www-form-urlencoded" רכיב שאילתה בפורמט שחובה לשמור כשמוסיפים פרמטרים של שאילתה. ה-URI של נקודת הקצה לא יכול לכלול רכיב מקטע.
  • מאחר שבקשות לנקודת הקצה של אסימון גורמות להעברת פרטי כניסה של טקסט ברור (בבקשת ה-HTTP ובתגובה), שרת ה-OAuth של הספק חייב להשתמש ב-TLS כדי לשלוח בקשות לנקודת הקצה של האסימון.
  • ה-GTAF משתמש בשיטה HTTP "POST" בעת שליחת הבקשה לאסימון הגישה.
  • צריך להתייחס לפרמטרים שנשלחים ללא ערך אם הם הושמטו מהבקשה. שרת ה-OAuth צריך להתעלם מפרמטרים של בקשות לא מוכרות. אין לכלול את הפרמטרים של הבקשה והתשובה יותר מפעם אחת.
  • GTAF תומך רק באסימונים לגישה מסוג דוב.

היקף אסימון הגישה

נקודות הקצה (endpoints) של ההרשאה והאסימון מאפשרות ללקוח לציין את ההיקף של בקשת הגישה באמצעות פרמטר הבקשה "scope&quot. בתורו, שרת ההרשאות משתמש בפרמטר התגובה {0}"scope" כדי להודיע ללקוח מה ההיקף של אסימון הגישה שהונפק.

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

 scope = scope-token *( SP scope-token )
 scope-token = 1*( %x21 / %x23-5B / %x5D-7E )

השימוש ב-GTAF לא מחייב הטמעה של ההיקף, אבל הוא תומך בתכונה הזו. למידע נוסף, ראו סעיף 3.3 ב-RFC 6749.

הנפקת אסימון גישה

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

תגובה מוצלחת

כאשר ה-GTAF שולח בקשה, שרת ה-OAuth מייצר אסימון גישה ואסימון רענון אופציונלי, ובונה את התגובה על ידי הוספת הפרמטרים הבאים לגוף הישות של תגובת ה-HTTP, עם קוד סטטוס 200 (OK): \

  • access_token: חובה. אסימון הגישה שהונפק על ידי שרת OAuth. GTAF מצפה שנקודת הקצה של האסימון תחזיר אסימון.
  • expires_in: חובה. משך החיים של אסימון גישה, בשניות. לדוגמה, הערך "3600" מציין שתוקף הגישה יפוג תוך שעה מרגע יצירת התגובה. אם לא תציינו אותו, שרת ה-OAuth צריך לציין את תאריך התפוגה באמצעים אחרים או לתעד את ערך ברירת המחדל.
  • token_type: חובה. סוג האסימון שהונפק. למידע נוסף על הסוגים השונים של האסימונים, ראו סעיף 7.1 ב-RFC 6749. הערך הוא לא תלוי-רישיות. GTAF תומך רק באסימונים של הדובים בזמן הכתיבה.
  • refresh_token: אופציונלי. אסימון הרענון שבו אפשר להשתמש כדי לקבל אסימוני גישה חדשים, עם אותה הרשאת גישה.
  • scope: אופציונלי, אם הוא מיושם וזהה להיקף המבוקש על ידי ה-GTAF. אחרת, הוא נדרש.

הפרמטרים כלולים בגוף הישות של תגובת ה-HTTP באמצעות התג "application/json" הפרמטרים טוריים במבנה של JavaScript Object (JSON) על ידי הוספת כל פרמטר ברמת המבנה הגבוהה ביותר. שמות של פרמטרים וערכי מחרוזת כלולים כמחרוזות JSON. ערכים מספריים כלולים כמספרי JSON. סדר הפרמטרים לא משנה והוא יכול להשתנות.

שרת ההרשאות חייב לכלול את השדה HTTP " Cache-Control" ככותרת של תגובה עם הערך "no-store" בכל תגובה שמכילה אסימונים, פרטי כניסה או מידע רגיש אחר, וגם את השדה "Pragma" בכותרת התגובה עם הערך "no-cache"

לדוגמה:

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"Bearer",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "example_parameter":"example_value"
     }

כמה נקודות חשובות שכדאי לזכור:

  • ה-GTAF מתעלם משמות של ערכים לא מזוהים בתגובה.
  • הגדלים של האסימונים והערכים האחרים שהתקבלו משרת ה-OAuth נשארים לא מוגדרים.
  • אנשי ה-GTAF צריכים להימנע מהשערות לגבי גודלי ערכים. שרת ה-OAuth צריך לתעד את הגודל של כל ערך שבו הוא נוצר.

הודעת שגיאה

אם בקשת הרשאה נכשלה מכל סיבה שהיא, למשל: חסר, לא חוקי או URI של הפניה לא תואמת.

הענקת הרשאה ב-GTAF

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

ה-GTAF משתמש בסוג המענק client_credentials. בסוג המענק client_credentials, GTAF מבקש אסימון באמצעות בקשת HTTP POST ואימות HTTP בסיסי. כל הבקשות נשלחות באמצעות TLS (כלומר, HTTPS), ו-GTAF לא יכול להשתלב עם שרת OAuth ללא אישור TLS תקין. GTAF יכול להעביר היקף של אסימונים שניתן להגדיר להעביר אותו, אם הוא לא מוגדר.

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

לפרטים נוספים על סוגי המענק השונים, קראו את סעיף 1.3 בנושא RFC 6749.

דוגמה לתגובה

נניח של-GTAF יש את התצורה הבאה עבור שרת OAuth:

URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa

הערה: ה-Client Secret ל-DPA אמיתי צריך להיות מאובטח הרבה יותר מזה שמוצג בדוגמה.

כדי להפיק את מחרוזת ההרשאה, מזהה הלקוח, ':' והסיסמה הם משורשרים ומקודדים לפי Base64. ניתן לשכפל זאת בממשק של שורת הפקודה באופן הבא:

$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==

לאחר מכן, GTAF ישלח לשרת ה-OAuth בקשת POST באמצעות פרטי הכניסה האלה, סוג המענק ל-Client_credentials וההיקף שהוגדר. בדוגמה של Google, בקשת GTAF&#39 נראית כמו הבקשה שנוצרה על ידי:

$ curl -H 'Authorization: Basic Z3RhZjpwYXNzd29yZA==' -X POST \
-d 'grant_type=client_credentials&scope=dpa' 'https://www.example.com/gettoken/'

הכותרות שנעשה בהן שימוש ב-GTAF לא יתאימו לכותרות שנשלחות על ידי Curl, אם כי כותרת ההרשאה תהיה זהה.

GTAF צפוי לקבל תשובה בפורמט הבא:

{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}

דוגמה לתגובה חוקית:

{
"access_token":"YXRudWhhZXVoLGFodWFoaGF1aG9zaHVvYWV1Cg",
"token_type": "Bearer",
"expires_in":3600
}

הערה: התגובה חייבת להיות JSON תקין.

קוד שגיאה וקוד שגיאה

אם בקשת הרשאה מ-GTAF נכשלה עקב אחת מהסיבות שצוינו בקטע 'הודעת שגיאה', שרת ה-OAuth חייב להגיב באמצעות קוד סטטוס HTTP 400 (בקשה שגויה), (אלא אם צוין אחרת) ולכלול אחד מהפרמטרים הבאים בתגובה:

למשל: \

     HTTP/1.1 400 Bad Request
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "error":"invalid_request"
     }

GTAF מצפה משרת ה-OAuth לתמוך בתגובות השגיאה הבאות:

קוד שגיאה תגובה סיבה
HTTP 400 לא חוקי_בקשה בבקשה חסר פרמטר נדרש, כולל ערך פרמטר שאינו נתמך (שאינו סוג המענק), חוזר על פרמטר, כולל פרטי כניסה מרובים, משתמש ביותר ממנגנון אחד לאימות עם GTAF או שהפורמט שלו שגוי.
HTTP 401 לא חוקי_לקוח אימות הלקוח נכשל (למשל, לקוח לא ידוע, לא הוגדר אימות לקוח או שיטת אימות שאינה נתמכת). שרת ה-OAuth יכול להחזיר קוד סטטוס HTTP 401 (לא מורשה) כדי לציין אילו סכימות אימות ב-HTTP נתמכות. אם הלקוח ניסה לבצע אימות באמצעות השדה כותרת הכותרת "Authorization" , שרת ה-OAuth חייב להגיב עם קוד סטטוס HTTP 401 (לא מורשה), ולכלול את השדה ה- "WWW-Authenticate" בהתאם לסכימת האימות שבה הלקוח משתמש.
HTTP 500 כשל בשרת OAuth

לפרטים על תגובות אחרות שיכולות לשמש לניפוי באגים, עיינו ב סעיף 5.2 של RFC 6749.