שימוש ב-OAuth עם ממשקי ה-API של נתוני Google

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

מבוא

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

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

Audience

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

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

הסברים מעטים

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

  1. "ריקוד OAuth"

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

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

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

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

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

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

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

    אלה כתובות ה-URI הנדרשות לאימות אפליקציה ולהשגת אסימון גישה. לשלושה יש שלושה שלבים בסך הכול – אחד לכל שלב בתהליך ה-OAuth. נקודות הקצה (endpoints) של 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 היא MCA.

  6. (OAuth) צרכן

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

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

תחילת העבודה

הרשמה

כדי להתחיל להשתמש ב-OAuth עם ממשקי ה-API של נתוני Google, נדרשת הגדרה קצרה. מכיוון שכל בקשות ה-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 הבסיסית בקידוד של כתובת ה-URL: http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull.
  • ה-oauth_token מקודד פעמיים.

הערות בכותרת 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

מטרה

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

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

מה יקרה?

  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 לדומיין הרשום והזנת המפתח הפרטי שלך על ידי לחיצה על 'השתמש במפתח הפרטי שלך'. יש להשתמש רק במפתח פרטי בדיקה.

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

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

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

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

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

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

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

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

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

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

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

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

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

לסיום, לוחצים על הלחצן 'אסימון גישה' בתיבה 'קבלת האסימון'.

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

אם אתם רוצים לקבל אסימון חדש, לחצו על 'התחלה מחדש' כדי להתחיל מחדש את ריקוד ה-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. משנים את התפריט הנפתח של שיטת HTTP ל-PUT.
  4. יש ללחוץ על "הזנת נתוני פוסט" מתחת לתפריט הנפתח הזה ולהדביק את קובץ ה-XML של <entry> בחלון הקופץ.
  5. לוחצים על הלחצן "ביצוע".

השרת יגיב באמצעות 200 OK.

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

סיכום

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

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

משאבים