OAuth ל-Data Plan Plan Agent API

מסמכים קשורים

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

סקירה כללית

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

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

האיור הבא מציג את זרימת המידע ברמה גבוהה:

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

טוקנים של גישה

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

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

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

אימות לקוח

ה-GTAF פועל כ'לקוח סודי' ויכול לשמור על בטיחות הסיסמאות. בשלב הזה, GTAF תומך רק באימות HTTP Basic כדי לבצע אימות מול 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 תומכת רק בטוקנים מסוג bearer לגישה.

היקף טוקן הגישה

נקודות הקצה של ההרשאה והאסימון מאפשרות ללקוח לציין את היקף בקשת הגישה באמצעות פרמטר הבקשה scope. בתמורה, שרת ההרשאות משתמש בפרמטר התגובה 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 מצפה שנקודת הקצה של האסימון תחזיר אסימון מסוג bearer.
• ‫expires_in: חובה. משך החיים של אסימון הגישה בשניות. לדוגמה, הערך '3600' מציין שתוקף אסימון הגישה יפוג שעה אחת אחרי שהתשובה נוצרה. אם לא מציינים את הערך הזה, שרת ה-OAuth צריך לספק את זמן התפוגה באמצעים אחרים או לתעד את ערך ברירת המחדל.
• ‫token_type: חובה. סוג הטוקן שהונפק. מידע נוסף על סוגים שונים של אסימונים זמין ב סעיף 7.1 של RFC 6749. הערך לא תלוי באותיות רישיות. בזמן כתיבת המאמר הזה, GTAF תומך רק בטוקנים מסוג bearer.
• ‫refresh_token: אופציונלי. אסימון הרענון, שבו אפשר להשתמש כדי לקבל אסימוני גישה חדשים באמצעות אותה הרשאת גישה.
• scope: אופציונלי, אם הוא מיושם וזהה להיקף שנדרש על ידי GTAF; אחרת, הוא נדרש.

הפרמטרים נכללים בגוף הישות של תגובת ה-HTTP באמצעות application/json. הפרמטרים עוברים סריאליזציה למבנה של JavaScript Object Notation ‏ (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 להפניה חסר, לא תקין או לא תואם, או אם מזהה הלקוח חסר או לא תקין, שרת OAuth צריך להגיב עם קוד סטטוס HTTP 400 (בקשה שגויה) (אלא אם צוין אחרת) ולכלול לפחות אחד מהפרמטרים שמפורטים בקטע 'תגובה וקוד שגיאה'.

מתן הרשאה ב-GTAF

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

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

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

מידע נוסף על סוגים שונים של הרשאות זמין בסעיף 1.3 של RFC 6749.

דוגמה לבקשה ולתגובה

נניח של-GTAF יש את ההגדרה הבאה לשרת OAuth:

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

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

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

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

לאחר מכן, GTAF שולח בקשת HTTPS POST לשרת OAuth באמצעות פרטי הכניסה האלה, סוג ההרשאה client_credentials וההיקף שהוגדר. בדוגמה, הבקשה של GTAF דומה לבקשה שנוצרה על ידי:

$ 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	invalid_request	בבקשה חסר פרמטר נדרש, היא כוללת ערך פרמטר לא נתמך (שאינו סוג ההרשאה), היא חוזרת על פרמטר, היא כוללת כמה פרטי כניסה, היא משתמשת ביותר ממנגנון אחד לאימות ב-GTAF או שהיא פגומה בדרך אחרת.
HTTP 401	invalid_client	אימות הלקוח נכשל (לדוגמה, לקוח לא ידוע, לא נכלל אימות לקוח או שיטת אימות לא נתמכת). שרת OAuth עשוי להחזיר קוד סטטוס HTTP 401 (לא מורשה) כדי לציין אילו סכימות אימות HTTP נתמכות. אם הלקוח ניסה לבצע אימות באמצעות שדה הכותרת של בקשת Authorization, שרת OAuth חייב להגיב עם קוד סטטוס HTTP 401 (לא מורשה) ולכלול את שדה הכותרת של התגובה WWW-Authenticate שתואם לסכימת האימות שבה השתמש הלקוח.
HTTP 500	כשל בשרת OAuth

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