שימוש ב-OAuth עם Google Data APIs

אריק בידלמן, צוות Google Data APIs
ספטמבר 2008

מבוא

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

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

קהל

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

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

הסברים על המונחים

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

  1. ‫"OAuth dance"

    המונח הלא רשמי שלי לתיאור תהליך האימות וההרשאה המלא של OAuth.

  2. (OAuth) אסימון בקשה

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

  3. אסימון גישה (OAuth)

    השלב האחרון בתהליך הוא המרת טוקן הבקשה המאושר לטוקן גישה. אחרי שהאפליקציה מקבלת את הטוקן, המשתמש לא צריך לעבור שוב את תהליך OAuth, אלא אם הטוקן בוטל.

    דמיון ל-AuthSub:
    אסימון גישה ל-OAuth הוא אותו דבר כמו אסימון מאובטח של סשן AuthSub.

  4. נקודות קצה (OAuth)

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

    קבלת טוקן בקשה:https://www.google.com/accounts/OAuthGetRequestToken
    מאשרים את טוקן הבקשה:https://www.google.com/accounts/OAuthAuthorizeToken
    שדרוג לטוקן גישה:https://www.google.com/accounts/OAuthGetAccessToken

    דמיון ל-AuthSub:
    החלפת טוקן בקשה מאושר בטוקן גישה דומה לשדרוג טוקן AuthSub חד-פעמי לטוקן סשן לטווח ארוך בכתובות https://www.google.com/accounts/AuthSubRequestToken ו-https://www.google.com/accounts/AuthSubSessionToken, בהתאמה. ההבדל הוא שב-AuthSub אין מושג של טוקן בקשה ראשוני. במקום זאת, המשתמש מתחיל את תהליך האסימון מדף ההרשאה AuthSubRequestToken.

  5. ספק שירות (OAuth)

    במקרה של Google Data APIs, הספק הוא Google. באופן כללי, ספק השירות משמש לתיאור האתר או שירות האינטרנט שמספק את נקודות הקצה של OAuth. דוגמה נוספת לספק שירות OAuth היא MySpace.

  6. צרכן (OAuth)

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

הערה: למרות שפרוטוקול OAuth תומך בתרחיש השימוש באפליקציות שמותקנות במחשב, Google תומכת ב-OAuth רק באפליקציות אינטרנט.

תחילת העבודה

הרשמה

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

בקשות לחתימה

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

דוגמה לבקשה

GET רשימה של יומני Google של המשתמש בכתובת http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime

פורמט מחרוזת הבסיס base_string = http-method&base-http-request-url&normalized-string-of-oauth_parameters
דוגמה למחרוזת בסיס GET&http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull&oauth_consumer_key%3Dexample.com%26oauth_nonce%3D4572616e48616d6d%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D137131200%26oauth_token%3D1%252Fab3cd9j4ks73hf7g%26oauth_version%3D1.0%26orderby%3Dstarttime
דוגמה לבקשת HTTP 
GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: OAuth oauth_token="1%2Fab3cd9j4ks73hf7g", oauth_signature_method="RSA-SHA1", oauth_signature="wOJIO9AvZbTSMK%2FPY%3D...", oauth_consumer_key="example.com", oauth_timestamp="137131200", oauth_nonce="4572616e48616d6d", oauth_version="1.0"

הערה: זוהי רק דוגמה. ה-oauth_signature יהיה ארוך יותר.

הערות לגבי מחרוזת הבסיס:

  • פרמטר השאילתה orderby=starttime ממוין יחד עם שאר הפרמטרים oauth_* לפי סדר לקסיקוגרפי של ערכי בייטים.
  • המחרוזת הזו לא מכילה את התו '?'.
  • החלק base-http-request-url מכיל רק את כתובת הבסיס המקודדת בפורמט URL: http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull.
  • הפרמטר oauth_token מקודד פעמיים בכתובת ה-URL.

הערות על הכותרת Authorization:

  • הסדר של הפרמטרים oauth_* לא משנה בכותרת Authorization.
  • הכותרת לא כוללת את orderby=starttime כמו מחרוזת הבסיס. פרמטר השאילתה הזה נשמר כחלק מכתובת ה-URL של הבקשה.

למידע נוסף על חתימה על בקשות באמצעות OAuth, ראו חתימה על בקשות OAuth.

ההבדל מ-AuthSub:
לשם השוואה, הנה אותה דוגמה באמצעות AuthSub מאובטח:

פורמט מחרוזת הבסיס base_string = http-method http-request-URL timestamp nonce
דוגמה למחרוזת בסיס 
GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d
דוגמה לבקשת HTTP 
GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: AuthSub token="GD32CMCL25aZ-v____8B" data="GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime 137131200 4572616e48616d6d" sig="MCwCFrV93K4agg==..." sigalg="rsa-sha1"

מידע נוסף על חתימה על בקשות באמצעות AuthSub זמין במאמר חתימה על בקשות AuthSub.

כלי OAuth Playground

מטרה

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

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

מה יקרה?

  1. האיור מציג את תהליך האימות של OAuth: אחזור של טוקן בקשה, אישור הטוקן ושדרוג שלו לטוקן גישה.
  2. המחרוזת הבסיסית הנכונה לחתימה מוצגת לכל בקשה.
  3. הכותרת הנכונה Authorization מוצגת לכל בקשה.
  4. הדגמה של שימוש ב-oauth_token לאינטראקציה עם פיד נתונים מאומת של Google. אפשר לראות נתונים של GET/POST/PUT/DELETE.
  5. אפשר לראות פיד מאומת ישירות בדפדפן.
  6. מאפשר לבדוק את oauth_consumer_key (הדומיין הרשום) ואת המפתח הפרטי.
  7. אילו שירותי פידים של נתונים מ-Google זמינים ל-oauth_token.

הדגמה

שלב 1: בוחרים את ההיקפים

קודם כל, מחליטים באילו ממשקי API רוצים להשתמש על ידי בחירה של היקף אחד או יותר. בהדגמה הזו, אני מבקש טוקן שיפעל עם Blogger ועם אנשי הקשר מחשבון Google.

דמיון ל-AuthSub:
גם ב-AuthSub נדרש הפרמטר scope כדי לשלוט בטווח הנתונים שאסימון יכול לגשת אליהם. ‫Google הטמיעה את הפרמטר הזה כמו שמוצע במפרט OAuth.

שלב 2: שינוי הפרמטרים וההגדרות של OAuth

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

הערה: רק השדות oauth_signature_method ו-oauth_consumer_key ניתנים לעריכה כאן. המערכת תיצור עבורכם באופן אוטומטי את oauth_timestamp, oauth_nonce ו-oauth_token.

בנוסף ל-RSA-SHA1, אפשר להשתמש ב-HMAC-SHA1 בשביל oauth_signature_method. במקרה כזה, ב-Playground יוצגו תיבות נוספות שבהן תצטרכו להזין את oauth_consumer_key ואת הסוד של הצרכן. הערכים האלה מופיעים בדף https://www.google.com/accounts/ManageDomains של הדומיין הרשום.

ההבדל מ-AuthSub:
ב-AuthSub מאובטח, אין פרמטר להגדרה מפורשת של שם דומיין. הדומיין נכלל כחלק מפרמטר כתובת ה-URL‏ next. קיים פרמטר כזה ב-OAuth: ‏ oauth_consumer_key. מגדירים אותו לדומיין הרשום.

שלבים 3-5: קבלת אסימון הגישה

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

קודם לוחצים על הלחצן 'בקשת טוקן' בתיבה 'קבלת הטוקן'.

חלק מהשדות יתמלאו בנתונים.

  • המחרוזת הבסיסית של החתימה מציגה את הצורה הנכונה של המחרוזת הבסיסית שמשמשת ליצירת הפרמטר oauth_signature.
  • בקטע 'כותרת הרשאה' מוצגת כותרת Authorization המתאימה לבקשה.
  • התיבה 'שינוי פרמטרים של OAuth' מלאה בערכים oauth_nonce ו-oauth_timestamp שנשלחו בבקשה.
  • השדה oauth_token אוכלס בערך המתאים שמוחזר בגוף התגובה. בארגז החול מוצג גם סוג ה-oauth_token שיש לנו כרגע. בשלב הזה, זהו טוקן בקשה.

לאחר מכן, לוחצים על הלחצן 'הרשאה' בתיבה 'קבלת הטוקן'.

בדף ההרשאה הזה, לוחצים על הלחצן Grant Access (מתן גישה) כדי לאשר את טוקן הבקשה, ואז מועברים חזרה אל OAuth Playground.

דמיון ל-AuthSub:
דף ההרשאה הזה זהה ל-AuthSub.

ההבדל מ-AuthSub:
הפרמטר של כתובת ה-URL‏ next ב-AuthSub מקביל לפרמטר oauth_callback. ההבדל הוא שב-OAuth, הפרמטר oauth_callback הוא אופציונלי. אחרי שהמשתמש לוחץ על הלחצן 'מתן גישה', טוקן הבקשה מקבל אישור, ואפשר לבצע את שדרוג הטוקן ל-https://www.google.com/accounts/OAuthGetAccessToken באופן אסינכרוני.

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

לבסוף, לוחצים על הלחצן 'Access token' (אסימון גישה) בתיבה 'Get the Token' (קבלת האסימון).

הפעולה הזו משדרגת את אסימון הבקשה המורשה (כפי שמצוין בתווית האדומה access token).

אם רוצים לאחזר טוקן חדש, לוחצים על 'התחלה מחדש' כדי להפעיל מחדש את תהליך OAuth.

עכשיו אפשר לעשות משהו מעניין!

שימוש בטוקן הגישה

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

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

דוגמה לשאילתה: GET http://www.blogger.com/feeds/1982051675575479214/posts/default?max-results=3

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

דוגמה: איך מעדכנים פוסט

  1. בפוסט שרוצים לעדכן, מאתרים את רכיב <link> עם rel="edit". הוא אמור להיראות כך: 
    <link rel="edit" href="http://www.blogger.com/feeds/1982051675575479214/posts/default/8138973184593279875"/>

    מדביקים את כתובת ה-URL של href בשדה 'הזנת פיד נתונים של Google'.

  2. מעתיקים את ה-XML של הרשומה הקיימת על ידי לחיצה על 'הצגת טקסט פשוט' בחלק העליון של החלונית עם ההדגשה של התחביר. העתקה רק של גוף התגובה, ולא של הכותרות.
  3. משנים את התפריט הנפתח של ה-method של ה-HTTP ל-PUT.
  4. לוחצים על 'הזנת נתוני פוסט' מתחת לתפריט הנפתח ומדביקים את קוד ה-<entry> XML בחלון הקופץ.
  5. לוחצים על הלחצן 'הפעלה'.

השרת יגיב עם 200 OK.

טיפ: במקום להעתיק ידנית את הקישור edit, אפשר לבטל את הסימון בתיבת הסימון 'הדגשת תחביר?'. אחרי השאילתה, תוכלו ללחוץ על הקישורים בגופי התגובה של ה-XML.

סיכום

טכנולוגיות כמו AtomPub/Atom Publishing Protocol (פרוטוקול הבסיס של Google Data APIs) ו-OAuth עוזרות לקדם את האינטרנט. ככל שיותר אתרים יתחילו לאמץ את התקנים האלה, כך נרוויח אנחנו, המפתחים. פתאום, יצירת אפליקציה מצליחה נראית פחות מאיימת.

אם יש לכם שאלות או הערות לגבי OAuth Playground או לגבי שימוש ב-OAuth עם Google APIs, אתם מוזמנים לבקר בפורום התמיכה של G Suite APIs ו-Marketplace APIs.

משאבים