אימות והרשאה ב-Google Data Protocol

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

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

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

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

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

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

  • ‫Google Sign-In היא דרך פשוטה לאפשר לאנשים להשתמש בפרטי הכניסה שלהם ל-Google כדי להיכנס לאתר שלכם. הוא כולל קבוצה של כלים שקל לשלב במכשירים שונים.
  • ‫OAuth 2.0 הוא פרוטוקול הרשאות לכל ממשקי Google API. ‫OAuth 2.0 מסתמך על SSL לאבטחה, במקום לדרוש מהאפליקציה לבצע חתימה קריפטוגרפית ישירות. הפרוטוקול הזה מאפשר לאפליקציה לבקש גישה לנתונים שמשויכים לחשבון Google של המשתמש.
  • התחברות באמצעות OAuth 2.0 (OpenID Connect) מאמתת משתמשים באמצעות התחברות לחשבונות Google שלהם. זוהי חלופה ל-OpenID, ומשתמשים ב-OpenID צריכים לתכנן מעבר לכניסה באמצעות OAuth 2.0.

אם האפליקציה היא גאדג'ט (לשימוש ב-iGoogle או במאגרי OpenSocial אחרים), כדאי לעיין בקטע אימות לגאדג'טים.

הערה: המסמך הזה נועד לספק סקירה כללית של כל שיטת אימות. מידע מפורט על כל שיטה מופיע במסמכי התיעוד המלאים של ממשקי Google Account Authentication API.

אפשר גם לעיין בקבוצת Google Accounts API כדי לקרוא דיונים על השימוש בממשקי Google Accounts API.

‫OAuth – הרשאה לאפליקציות אינטרנט ולאפליקציות מותקנות

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

‫Google תומכת בשתי גרסאות של OAuth לקבלת גישה מאושרת לנתוני משתמש ב-Google: ‏ OAuth 1.0 ו-OAuth 2.0. שתי הגרסאות מאפשרות גישה לאפליקציות אינטרנט ולאפליקציות מותקנות.

‫OAuth 2.0 לאפליקציות אינטרנט ולאפליקציות מותקנות

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

‫OAuth 1.0 לאפליקציות אינטרנט

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

‫OAuth 1.0 לאפליקציות מותקנות

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

שימוש ב-OAuth עם אפליקציות אינטרנט

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

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

תהליך ההרשאה של OAuth

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

באופן כללי, התהליך הוא כזה:

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

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

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

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

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

הכנות ל-OAuth

לפני שמגדירים את האפליקציה לשימוש בשירות ההרשאה של Google עם OAuth, צריך לבצע את המשימות הבאות.

החלטה אם לרשום את אפליקציית האינטרנט

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

האפליקציה צריכה לחתום על כל בקשת OAuth שהיא שולחת. אם בוחרים להשתמש בחתימת RSA-SHA1 כדי לחתום על הבקשות, צריך להעלות אישור אבטחה כחלק מתהליך ההרשמה.

אפשר גם להשתמש בחתימת HMAC-SHA1 כדי לחתום על הבקשות. לא נדרש אישור לחתימות HMAC-SHA1. במקום זאת, Google יוצרת ערך OAuth consumer secret שמוצג בדף הרישום של הדומיין אחרי הרישום.

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

קביעת היקף הנתונים שהאפליקציה שלכם תוכל לגשת אליהם

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

באופן כללי, מומלץ לבקש אסימון להיקף הצר ביותר שכולל את הנתונים שאתם צריכים. לדוגמה, אם האפליקציה שלכם דורשת גישה לפיד 'כל היומנים' של המשתמש, אתם צריכים לבקש טוקן להיקף http://www.google.com/calendar/feeds/default/allcalendars/full.

הגדרת מנגנון לניהול טוקנים של OAuth

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

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

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

הגדרת מנגנון לבקשת גישה לשירות Google

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

מידע נוסף על פורמט הבקשה המתאים לכל Google Data API מופיע במסמכי התיעוד של ה-API הזה.

הטמעה של OpenID (אופציונלי)

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

איך עובדים עם טוקנים של OAuth

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

  1. קבלת טוקן בקשה לא מורשה (OAuthGetRequestToken)
  2. אישור טוקן הבקשה (OAuthAuthorizeToken)
  3. החלפת טוקן הבקשה המאושר בטוקן גישה (OAuthGetAccessToken)

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

אתם יכולים להתנסות בבקשה וקבלת טוקנים של הרשאה ב-OAuth Playground.

למאמרי עזרה מפורטים, ראו הפניית API של OAuth.

הגדרת כתובת URL לקריאה חוזרת (callback)

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

לדוגמה, כשאתם תומכים בכמה שפות, אתם יכולים לכלול פרמטר של שאילתה שמזהה את הגרסה של האפליקציה שהמשתמש צופה בה. ערך oauth_callback של http://www.yoursite.com/Retrievetoken?Lang=de יגרום להפניה אוטומטית אל http://www.yoursite.com/Retrievetoken?Lang=de&oauth_token=DQAADKEDE. ניתוח הטוקן ופרמטר השפה מבטיח שהמשתמש יופנה בחזרה לגרסה הנכונה של האתר.

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

זיהוי האפליקציה למשתמשים

בדרך כלל, Google מציגה את השם של האפליקציה כשמבקשים מהמשתמש הרשאת גישה (ראו דוגמה).

אם האפליקציה שלכם לא רשומה, צריך להשתמש בפרמטר xoauth_displayname בבקשה OAuthGetRequestToken כדי לציין את שם האפליקציה. אם הפרמטר הזה לא מצוין, Google מציגה את שם הדומיין של כתובת ה-URL שסופקה על ידי הפרמטר oauth_callback. אם לא מספקים כתובת URL של קריאה חוזרת, Google מציגה את המחרוזת anonymous.

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

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

עבודה עם דומיינים של Google Apps

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

מידע נוסף על OAuth

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

חזרה למעלה

שימוש ב-OAuth עם אפליקציות מותקנות

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

תהליך ההרשאה של OAuth

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

באופן כללי, התהליך הוא כזה:

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

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

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

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

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

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

הכנות ל-OAuth

לפני שמגדירים את האפליקציה לשימוש בשירות ההרשאה של Google עם OAuth, צריך לבצע את המשימות הבאות.

קביעת היקף הנתונים שהאפליקציה שלכם תוכל לגשת אליהם

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

באופן כללי, מומלץ לבקש אסימון להיקף הצר ביותר שכולל את הנתונים שאתם צריכים. לדוגמה, אם האפליקציה שלכם דורשת גישה לפיד 'כל היומנים' של המשתמש, אתם צריכים לבקש טוקן להיקף http://www.google.com/calendar/feeds/default/allcalendars/full.

הגדרת מנגנון לניהול טוקנים של OAuth

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

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

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

הגדרת מנגנון לבקשת גישה לשירות Google

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

מידע נוסף על פורמט הבקשה המתאים לכל Google Data API מופיע במסמכי התיעוד של ה-API הזה.

איך עובדים עם טוקנים של OAuth

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

  1. קבלת טוקן בקשה לא מורשה (OAuthGetRequestToken)
  2. אישור טוקן הבקשה (OAuthAuthorizeToken)
  3. החלפת טוקן הבקשה המאושר בטוקן גישה (OAuthGetAccessToken)

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

אתם יכולים להתנסות בבקשה וקבלת טוקנים של הרשאה ב-OAuth Playground.

למאמרי עזרה מפורטים, ראו הפניית API של OAuth.

זיהוי האפליקציה למשתמשים

בדרך כלל, Google מציגה את השם של האפליקציה כשמבקשים מהמשתמש הרשאת גישה (ראו דוגמה).

משתמשים בפרמטר xoauth_displayname בבקשת OAuthGetRequestToken כדי לציין את שם האפליקציה. אם הפרמטר הזה לא מצוין, Google מציגה את שם הדומיין של כתובת ה-URL שסופקה על ידי הפרמטר oauth_callback. אם לא מספקים כתובת URL של קריאה חוזרת, Google מציגה את המחרוזת anonymous.

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

הפעלת דפדפן אינטרנט

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

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

מצב זיהוי אוטומטי

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

במצב הזה, צריך לספק כתובת URL של קריאה חוזרת שאליה המשתמש מופנה אחרי שהוא מאשר את בקשת הגישה. צריך לציין את כתובת ה-URL הזו כפרמטר oauth_callback של בקשת OAuthGetRequestToken, וכפרמטר verifier של בקשת OAuthGetAccessToken.

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

מידע נוסף ושיטות מומלצות זמינים במאמר בנושא זיהוי אוטומטי של אישור.

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

מצב המכשיר

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

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

מצב פיתוח

מומלץ להשתמש במצב הזה רק בשלבים הראשונים של פיתוח אפליקציה.

כמו במצב AutoDetect, האפליקציה שלכם צריכה להפעיל דפדפן, והמשתמש צריך לאשר את הבקשה שלכם. עם זאת, במקום ליצור דף אינטרנט לכתובת ה-URL של הקריאה החוזרת, אפשר להגדיר את הערך של הפרמטר oauth_callback ל-"oob" (מחוץ לפס).

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

כדי לשלוח בקשת OAuthGetAccessToken, המשתמש צריך לחזור לאפליקציה ולהזין את מספר האימות.

מידע נוסף על OAuth

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

חזרה למעלה

שימוש ב-AuthSub להרשאה

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

תהליך ההרשאה של AuthSub

ההרשאה באמצעות AuthSub כוללת רצף של אינטראקציות בין שלושה גורמים: אפליקציית האינטרנט, שירותי Google והמשתמש. בתרשים הבא מוצג הרצף:

תהליך ההרשאה

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

עבודה עם AuthSub

כדי לשלב את AuthSub באפליקציית האינטרנט שלכם, צריך לבצע את המשימות הבאות:

  1. החליטו אם לרשום את אפליקציית האינטרנט.

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

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

  2. מחליטים באיזה סוג של טוקנים להשתמש ואיך לנהל אותם.

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

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

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

  3. קובעים את ההיקף שנדרש לשירות Google שאליו רוצים לגשת.

    כל שירות של Google קובע את רמת הגישה שהוא יאפשר ואת סוג הגישה. הגישה הזו מבוטאת כערך של היקף הרשאות. היקף ההרשאות של שירות יכול להיות כתובת URL פשוטה שמזהה את השירות כולו, או שהוא יכול לציין גישה מוגבלת יותר. חלק מהשירותים מגבילים מאוד את הגישה, למשל מאפשרים גישת קריאה בלבד למידע מוגבל. כדי לראות את ההיקפים המותרים לשירות Google שרוצים לגשת אליו, אפשר לעיין במסמכי התיעוד של השירות. כדאי לבקש אסימון עם ההיקף המצומצם ביותר שאפשר. לדוגמה, אם מנסים לגשת לתכונת הפיד של Atom ב-Gmail, צריך להשתמש בהיקף 'http://www.google.com/calendar/feeds/‎' ולא בהיקף 'http://www.google.com/calendar/‎'. ההגבלות בשירותי Google על בקשות בהיקף גדול הן הרבה יותר מחמירות.

  4. הגדרת מנגנון לבקשת טוקן הרשאה ולקבלתו.

    המנגנון צריך ליצור קריאה מעוצבת היטב של AuthSubRequest, כולל ציון הערכים המתאימים של כתובות ה-URL next ו-scope (שנקבעו בשלב 3). אם אתם משתמשים באסימונים מאובטחים או מנהלים אסימונים של סשנים, הבקשה צריכה לכלול גם ערכים למשתנים האלה.

    כתובת ה-URL הבאה יכולה לכלול פרמטרים של שאילתה. לדוגמה, כשאתם תומכים בכמה שפות, כדאי לכלול פרמטר של שאילתה שמזהה את הגרסה של אפליקציית האינטרנט שהמשתמש צופה בה. הערך http://www.yoursite.com/Retrievetoken?Lang=de של next יגרום להפניה אוטומטית http://www.yoursite.com/Retrievetoken?Lang=de&token=DQAADKEDE. ניתוח האסימון והפרמטר Lang מבטיח שהמשתמש יופנה בחזרה לגרסה הנכונה של האתר.

    במקרים מסוימים, השימוש בפרמטר hd יכול לעזור לייעל את חוויית המשתמשים כשמבקשים מהם להעניק גישה באתר של חשבונות Google. ברוב המקרים, התהליך פשוט: צריך להתחבר לחשבון ולבחור אם להעניק גישה או לא. עם זאת, משתמשים שיש להם יותר מחשבון Google אחד (חשבון Gmail רגיל ו/או חשבון אחד או יותר מאירוח Google Apps) עשויים להצטרך לבצע את תהליך הכניסה האוניברסלי כדי לציין לאיזה חשבון הם רוצים לגשת. אם האפליקציה שלכם מיועדת לדומיין מנוהל מסוים, אתם יכולים להשתמש בפרמטר הזה כדי לציין את הדומיין הזה ולחסוך את השלבים הנוספים. אפשר גם להשתמש בפרמטר hd אם האפליקציה שלכם ניגשת לשירותים שלא זמינים בחשבונות מארחים. הגדרת הערך כ-'default' תגביל את ההרשאה לחשבונות רגילים בלבד. כשמגדירים את הערך hd, Google בוחרת באופן אוטומטי את החשבון הנכון לאישור.

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

  5. מגדירים מנגנונים לבקשת טוקנים של סשנים ולאחסון או לביטול שלהם, אם רלוונטי.

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

  6. הגדרת מנגנון לבקשת גישה לשירות Google.

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

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

    Authorization: AuthSub token="token"

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

    בדוגמה הבאה מוצג כותרת של בקשה לקריאה לשירות הפיד של יומן Google. הבקשה הזו מכילה טוקן לא מאובטח: 

    GET /calendar/feeds/default/private/full HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="GD32CMCL25aZ-v____8B"
User-Agent: Java/1.5.0_06
Host: www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

מידע נוסף על AuthSub

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

חזרה למעלה

שימוש ב-ClientLogin להרשאה

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

אימות לאפליקציות מותקנות: ClientLogin

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

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

תהליך ההרשאה של ClientLogin

הרשאה באמצעות ClientLogin כוללת רצף של אינטראקציות בין שלוש ישויות: האפליקציה המותקנת, שירותי Google והמשתמש. בתרשים הבא מוצג הרצף:

תהליך ההרשאה

  1. כשאפליקציית צד שלישי צריכה לגשת לשירות Google של משתמש, היא מאחזרת את שם הכניסה והסיסמה של המשתמש.
  2. אחרי כן, האפליקציה של הצד השלישי שולחת קריאה ל-ClientLogin לשירות ההרשאות של Google.
  3. אם שירות ההרשאה של Google מחליט שנדרש אימות נוסף, הוא מחזיר תגובת כשל עם טוקן ואתגר CAPTCHA, בצורה של כתובת URL לתמונה של CAPTCHA.
  4. אם מתקבל אתגר CAPTCHA, האפליקציה של הצד השלישי מציגה למשתמש את תמונת ה-CAPTCHA ומבקשת ממנו תשובה.
  5. אם מתבקשים, המשתמשים שולחים תשובה לאתגר ה-CAPTCHA.
  6. האפליקציה של הצד השלישי מבצעת קריאה חדשה ל-ClientLogin, והפעם היא כוללת את התשובה ל-CAPTCHA ואת הטוקן (שהתקבלו עם תגובת הכשל).
  7. בניסיון כניסה מוצלח (עם או בלי אתגר CAPTCHA), שירות ההרשאה של Google מחזיר טוקן לאפליקציה.
  8. האפליקציה יוצרת קשר עם שירות Google עם בקשה לגישה לנתונים, תוך הפניה לאסימון שהתקבל משירות ההרשאות של Google.
  9. אם שירות Google מזהה את האסימון, הוא מספק גישה לנתונים המבוקשים.

שימוש ב-ClientLogin

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

כדי לשלב את ClientLogin באפליקציה, צריך לבצע את המשימות הבאות:

  1. יוצרים רכיב בממשק המשתמש כדי לתעד את נתוני הכניסה של המשתמש.

    ממשק המשתמש צריך לבקש שם משתמש (כתובת אימייל כולל הדומיין) וסיסמה. ממשק המשתמש צריך גם להיות מסוגל להציג תמונת CAPTCHA באמצעות כתובת ה-URL שמתקבלת מ-Google, אם נדרשת כזו, ולבקש מהמשתמש תשובה נכונה. מומלץ שממשק המשתמש יכלול קישור לדף הכניסה לחשבונות Google (https://www.google.com/accounts/Login), למקרה שהמשתמש יצטרך להירשם לחשבון חדש או לבצע פעולות אחרות לניהול החשבון.

  2. כותבים קוד ליצירת בקשת HTTPS POST ClientLogin תקינה ומשדרים אותה.

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

  3. טיפול בתשובות מ-Google.

    יש ארבע תגובות אפשריות לבקשת התחברות:

    • הצלחה (HTTP 200)
    • נכשלת (HTTP 403) עם קוד שגיאה שמסביר את הבעיה
    • בקשה לא חוקית, בדרך כלל כתוצאה מבקשה שגויה
    • כשל באתגר CAPTCHA

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

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

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

  4. איך פותרים אתגר CAPTCHA מ-Google

    כדי לפתור את האתגר, האפליקציה צריכה להציג את תמונת ה-CAPTCHA ולבקש מהמשתמש תשובה. כדי להציג את תמונת ה-CAPTCHA, צריך להשתמש בערך של CaptchaUrl שמוחזר עם תגובת הכשל, ולהוסיף לפניו את כתובת ה-URL של חשבונות Google: "http://www.google.com/accounts/". אחרי שהמשתמש מספק תשובה, האפליקציה צריכה לשלוח מחדש את בקשת הכניסה, הפעם כולל טוקן ה-CAPTCHA ‏ (logintoken) והתשובה של המשתמש (logincaptcha). ‏ Google מאמתת את התשובה של המשתמש לפני שהיא מאשרת גישה לחשבון.

    יש חלופה למפתחים שלא רוצים לנהל את התהליכים של קבלת תגובת CAPTCHA של משתמש והעברתה. בתגובה לאתגר CAPTCHA, האפליקציה יכולה להפנות את המשתמש לדף שמתארח ב-Google: ‏https://www.google.com/accounts/DisplayUnlockCaptcha. אחרי שהמשתמש עונה בהצלחה לאתגר, שרת Google נותן אמון במחשב שבו נעשה שימוש. לאחר מכן, האפליקציה יכולה לשלוח מחדש את בקשת הכניסה המקורית כדי לקבל את טוקן ההרשאה.

    5. הערה: Google לא מאמתת את ניסיון הכניסה לפני שהיא מציגה אתגר CAPTCHA. המשמעות היא שניסיון התחברות עלול להיכשל גם אחרי אתגר CAPTCHA.

‫* CAPTCHA הוא סימן מסחרי של אוניברסיטת קרנגי מלון

חזרה למעלה

אימות לגאדג'טים

שרת proxy של OAuth

אם אתם יוצרים גאדג'ט באמצעות Gadgets API הרגיל, אתם יכולים להשתמש בתכונה של פלטפורמת הגאדג'טים שנקראת OAuth Proxy כדי לגשת אל Google Data APIs. פרוטוקול OAuth (שמתואר למעלה) הוא תקן אימות שמאפשר למשתמשים לגשת לנתונים הפרטיים שלהם בשירות אירוח גאדג'טים כמו iGoogle,‏ MySpace או Orkut, או לשתף את הנתונים שלהם עם אתר או גאדג'ט אחרים. ה-OAuth Proxy נועד להקל על מפתחי גאדג'טים את תהליך הפיתוח, על ידי הסתרת פרטים רבים של אימות OAuth. ה-Proxy מבוסס על פרויקט קוד פתוח שנקרא Shindig, שהוא הטמעה של מפרט הגאדג'טים.

הערה: פרוקסי OAuth נתמך רק בגאדג'טים שמשתמשים ב-API‏ gadgets.* ופועלים במאגרי OpenSocial. הוא לא נתמך ב-legacy gadgets API.

תהליך האימות

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

  1. הגאדג'ט נטען בפעם הראשונה ומנסה לגשת לנתוני המשתמש באמצעות אחד מ-Google Data APIs.
  2. הבקשה נכשלת כי המשתמש לא העניק גישה. אובייקט התגובה מכיל כתובת URL (ב-response.oauthApprovalUrl) לדף האישור של OAuth. הגאדג'ט צריך לספק שיטה להפעלת חלון חדש עם כתובת ה-URL הזו.
  3. בדף האישור, המשתמש בוחר אם לאשר או לדחות את הגישה לגאדג'ט. אם הפעולה תצליח, המשתמש יועבר לדף oauth_callback שציינתם. כדי ליהנות מחוויית המשתמש הטובה ביותר, מומלץ להשתמש ב-http://oauth.gmodules.com/gadgets/oauthcallback.
  4. לאחר מכן המשתמש סוגר את החלון הקופץ. כדי להודיע לגאדג' שהמשתמש אישר, אפשר להשתמש בhandler של חלון קופץ כדי לזהות את סגירת חלון האישור. לחלופין, הווידג'ט יכול להציג קישור (למשל, אישרתי את הגישה) שהמשתמש יכול ללחוץ עליו אחרי שהחלון הזה ייסגר.
  5. הגאדג'ט מנסה לגשת ל-Google Data API בפעם השנייה על ידי שליחת בקשה חוזרת לנתוני המשתמש. הניסיון הזה הצליח.
  6. הגאדג'ט מאומת ויכול להתחיל לפעול כרגיל.

הגדרת הגאדג'ט

כדי לגשת לאחד או יותר מממשקי Google Data API, קודם צריך להגדיר את הווידג'ט לשימוש ב-OAuth כשיטת האימות. מוסיפים רכיב <OAuth> בקטע <ModulePrefs> של קובץ ה-XML של הגאדג'ט:

<ModulePrefs>
...
<OAuth>
  <Service name="google">
    <Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" />
    <Request url="https://www.google.com/accounts/OAuthGetRequestToken?
                  scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" />
    <Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
                        oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" />
  </Service>
</OAuth>
...
</ModulePrefs>

בקטע הזה, משנים רק את הפרמטרים הבאים של השאילתה:

scope
‫
פרמטר נדרש בכתובת ה-URL של הבקשה. הגאדג'ט יכול לגשת לנתונים מscope שמוגדרים בפרמטר הזה. בדוגמה הזו, הגאדג'ט יכול לגשת לנתונים של Blogger ושל היומן. גאדג'ט יכול לבקש נתונים להיקף אחד או לכמה היקפים, כמו בדוגמה הזו.
oauth_callback
פרמטר אופציונלי בכתובת ה-URL של ההרשאה. דף האישור של OAuth מפנה לכתובת ה-URL הזו אחרי שהמשתמש אישר גישה לנתונים. כדי לספק את חוויית המשתמש הטובה ביותר כשמשתמשים מתקינים את הגאדג'ט שלכם, צריך להגדיר את הפרמטר הזה לערך http://oauth.gmodules.com/gadgets/oauthcallback. בדף הזה מופיע קטע קוד JavaScript שסוגר אוטומטית את החלון הקופץ. לחלופין, אפשר להגדיר את הפרמטר הזה כך שיצביע על דף משלכם שאושר, או פשוט להשאיר את הפרמטר ריק.

גישה לפיד מאומת של Google Data API

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

מידע נוסף על גאדג'טים

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

חזרה למעלה