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

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

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

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

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

ספריות לקוח

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

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

ספריות לקוח של Google API עבור אפליקציות בצד השרת זמינות בשפות הבאות:

דרישות מוקדמות

הפעלת ממשקי API בפרויקט שלך

כל אפליקציה שיוצרת קריאה ל-Google APIs צריכה להפעיל את ממשקי ה-API האלה ב- API Console.

כדי להפעיל ממשק API בפרויקט:

  1. Open the API Library ב Google API Console.
  2. If prompted, select a project, or create a new one.
  3. ברשימה API Library מופיעים כל ממשקי ה-API הזמינים, מקובצים לפי משפחת מוצרים ופופולריות. אם ממשק ה-API שרוצים להפעיל לא מופיע ברשימה, משתמשים בחיפוש כדי למצוא אותו או לוחצים על הצגת הכול במשפחת המוצרים שאליה הוא שייך.
  4. בוחרים ב-API שרוצים להפעיל ולוחצים על הלחצן הפעלה.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

יצירת פרטי כניסה להרשאה

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

  1. Go to the Credentials page.
  2. לוחצים על Create credentials > OAuth client ID (יצירת פרטי כניסה > מזהה לקוח ב-OAuth).
  3. בוחרים בסוג האפליקציה אפליקציית אינטרנט.
  4. ממלאים את הטופס ולוחצים על יצירה. באפליקציות שנעשה בהן שימוש בשפות ובמסגרות כמו PHP, Java, Python, Ruby ו-NET .צריך לציין כתובות URI מורשות. ה-URIs של הפניות מחדש הם נקודות הקצה שאליהן שרת OAuth 2.0 יכול לשלוח תגובות. נקודות הקצה האלו חייבות לעמוד בכללי האימות של Google.

    לצורך בדיקה, אפשר לציין כתובות URI שמתייחסות למכונה המקומית, למשל http://localhost:8080. לאור זאת, חשוב לזכור שכל הדוגמאות במסמך הזה משתמשות ב-http://localhost:8080 כ-URI של ההפניה האוטומטית.

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

אחרי שיוצרים את פרטי הכניסה, מורידים את הקובץ client_secret.json מה- API Console. יש לאחסן את הקובץ באופן מאובטח במיקום שבו רק האפליקציה שלך יכולה לגשת.

זיהוי היקפי גישה

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

לפני הטמעת הרשאת OAuth 2.0, מומלץ לזהות את היקפי ההרשאות שהאפליקציה שלך צריכה עבורם הרשאת גישה.

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

המסמך היקפי ההרשאות של OAuth 2.0 API מכיל רשימה מלאה של היקפים שניתן להשתמש בהם כדי לגשת ל-Google APIs.

דרישות ספציפיות לשפה

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

PHP

כדי להפעיל את הדוגמאות של קוד ה-PHP במסמך הזה, צריך:

  • PHP 5.6 ומעלה עם ממשק שורת הפקודה (CLI) ותוסף JSON מותקנים.
  • כלי לניהול יחסי תלות של מלחין.

  • ספריית הלקוח של Google APIs ל-PHP:

    composer require google/apiclient:^2.10

Python

כדי להפעיל את דוגמאות הקוד של Python במסמך הזה, יש צורך ב:

  • Python
  • הכלי Pip לניהול חבילות.
  • ספריית הלקוח של Google APIs ל-Python: 
    pip install --upgrade google-api-python-client
  • ההרשאות google-auth, google-auth-oauthlib וכן google-auth-httplib2 להרשאות משתמשים. 
    pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
  • המסגרת של אפליקציית האינטרנט של Flask Python. 
    pip install --upgrade flask
  • ספריית requests ב-HTTP. 
    pip install --upgrade requests

Ruby

כדי להריץ את דוגמאות הקוד של Ruby במסמך הזה, צריך:

  • Ruby 2.2.2 ומעלה

  • ספריית הלקוח של APIs של Google עבור Ruby:

    gem install google-api-client

  • המסגרת של אפליקציית האינטרנט סינה רובי.

    gem install sinatra

Node.js

כדי להריץ את דוגמאות הקוד של Node.js במסמך, תצטרכו:

  • ה-LTS לתחזוקה, LTS פעיל או גרסה נוכחית של Node.js.

  • לקוח Node.js של ממשקי ה-API של Google:

    npm install googleapis

HTTP/REST

אין צורך להתקין ספריות כדי לבצע קריאה ישירה לנקודות הקצה של OAuth 2.0.

קבלת אסימוני גישה ל-OAuth 2.0

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

הרשימה הבאה מסכמת בקצרה את השלבים הבאים:

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

שלב 1: הגדרת פרמטרים של הרשאה

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

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

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

PHP

קטע הקוד שלמטה יוצר אובייקט Google\Client(), שמגדיר את הפרמטרים בבקשת ההרשאה.

האובייקט הזה משתמש במידע מהקובץ client_secret.json כדי לזהות את האפליקציה שלך. (מידע נוסף על הקובץ הזה זמין במאמר יצירת פרטי כניסה לשימוש בהרשאה). האובייקט גם מזהה את ההיקפים שהאפליקציה שלך מבקשת עבורם הרשאה לגשת ואת כתובת ה-URL של נקודת הקצה לאימות של האפליקציה שלך. כך נוכל לטפל בתגובה משרת ה-OAuth 2.0 של Google. לבסוף, הקוד מגדיר את הפרמטרים האופציונליים access_type ו-include_granted_scopes.

לדוגמה, הקוד הזה מבקש גישה לקריאה בלבד, במצב אופליין, ל-Google Drive של המשתמש: 

$client = new Google\Client();
$client->setAuthConfig('client_secret.json');
$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');
// offline access will give you both an access and refresh token so that
// your app can refresh the access token without user interaction.
$client->setAccessType('offline');
// Using "consent" ensures that your application always receives a refresh token.
// If you are not using offline access, you can omit this.
$client->setApprovalPrompt('consent');
$client->setIncludeGrantedScopes(true);   // incremental auth

הבקשה מציינת את הפרטים הבאים:

פרמטרים
client_id נדרש

מזהה הלקוח של האפליקציה שלך. אפשר למצוא את הערך הזה ב API Console Credentials page.

ב-PHP, קוראים לפונקציה setAuthConfig כדי לטעון פרטי כניסה להרשאה מקובץ client_secret.json.

$client = new Google\Client();
$client->setAuthConfig('client_secret.json');
redirect_uri נדרש

המדיניות הזו קובעת איפה שרת ה-API מפנה את המשתמש אחרי שהוא מסיים את תהליך ההרשאה. הערך חייב להתאים בדיוק לאחד ממזהי ה-URI המורשים של לקוח OAuth 2.0, שמוגדר ב- API Console Credentials pageשל הלקוח. אם הערך לא תואם ל-URI מורשה של כתובת אתר להפניה מחדש עבור client_id שסופק, תתקבל שגיאת redirect_uri_mismatch.

לתשומת ליבך: הסכימה, הפנייה או הקו הנטוי שלhttp או https ('/') חייבות להיות תואמות.

כדי להגדיר את הערך הזה ב-PHP, צריך לקרוא לפונקציה setRedirectUri. לתשומת לבך, עליך לציין URI חוקי של הפניה מחדש עבור client_id שצוינו.

$client->setRedirectUri('https://oauth2.example.com/code');
scope נדרש

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

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

כדי להגדיר את הערך הזה ב-PHP, מפעילים את הפונקציה addScope:

$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);

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

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

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

כדי להגדיר את הערך הזה ב-PHP, מפעילים את הפונקציה setAccessType:

$client->setAccessType('offline');
state מומלץ

המדיניות הזו קובעת את ערך המחרוזת שמשמש את האפליקציה כדי לשמור על המצב בין בקשת ההרשאה שלך לבין התגובה של שרת ההרשאות. השרת מחזיר את הערך המדויק ששלחת כזוג name=value ברכיב השאילתה של כתובת האתר (?) של redirect_uri לאחר שהמשתמש מסכים לבקשת הגישה של האפליקציה או דוחה אותה.

אפשר להשתמש בפרמטר הזה לכמה מטרות, למשל הפניית המשתמש למשאב הנכון באפליקציה, שליחת מחרוזות ופתרון זיוף של בקשה בין אתרים. אפשר לנחש את הערך redirect_uri, לכן שימוש בערך state יכול לתת לך הבטחה לכך שהחיבור הנכנס הוא תוצאה של בקשת אימות. אם יוצרים מחרוזת אקראית או מקודדים גיבוב (hash) של קובץ cookie או כל ערך אחר שמתעד את מצב הלקוח, ניתן לאמת את התגובה כדי לוודא שהבקשה ותגובה התקבלו באותו דפדפן, וכך לספק הגנה מפני מתקפות כמו זיוף בקשות באתרים שונים. במסמכי התיעוד OpenID Connect מוצגת דוגמה ליצירה ולאישור של אסימון state.

כדי להגדיר את הערך הזה ב-PHP, מפעילים את הפונקציה setState:

$client->setState($sample_passthrough_value);
include_granted_scopes אופציונלי

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

כדי להגדיר את הערך הזה ב-PHP, מפעילים את הפונקציה setIncludeGrantedScopes:

$client->setIncludeGrantedScopes(true);
login_hint אופציונלי

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

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

כדי להגדיר את הערך הזה ב-PHP, מפעילים את הפונקציה setLoginHint:

$client->setLoginHint('None');
prompt אופציונלי

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

כדי להגדיר את הערך הזה ב-PHP, מפעילים את הפונקציה setApprovalPrompt:

$client->setApprovalPrompt('consent');

הערכים האפשריים הם:

none אין להציג מסכי אימות או הסכמה. לא ניתן לציין אותו עם ערכים אחרים.
consent תוצג למשתמשים בקשת הסכמה.
select_account הצגת בקשה למשתמש לבחור חשבון.

Python

קטע הקוד הבא משתמש במודול google-auth-oauthlib.flow כדי ליצור את בקשת ההרשאה.

הקוד בונה אובייקט Flow שמזהה את האפליקציה שלך באמצעות מידע מהקובץ client_secret.json שהורדת אחרי יצירת פרטי כניסה להרשאה. אובייקט זה מזהה גם את ההיקפים שהאפליקציה שלך מבקשת עבורם הרשאה, ואת כתובת ה-URL של נקודת הקצה לאימות של האפליקציה שלך. כך נוכל לטפל בתגובה משרת ה-OAuth 2.0 של Google. לבסוף, הקוד מגדיר את הפרמטרים האופציונליים access_type ו-include_granted_scopes.

לדוגמה, הקוד הזה מבקש גישה לקריאה בלבד, במצב אופליין, ל-Google Drive של המשתמש: 

import google.oauth2.credentials
import google_auth_oauthlib.flow

# Use the client_secret.json file to identify the application requesting
# authorization. The client ID (from that file) and access scopes are required.
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'])

# Indicate where the API server will redirect the user after the user completes
# the authorization flow. The redirect URI is required. The value must exactly
# match one of the authorized redirect URIs for the OAuth 2.0 client, which you
# configured in the API Console. If this value doesn't match an authorized URI,
# you will get a 'redirect_uri_mismatch' error.
flow.redirect_uri = 'https://www.example.com/oauth2callback'

# Generate URL for request to Google's OAuth 2.0 server.
# Use kwargs to set optional request parameters.
authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

הבקשה מציינת את הפרטים הבאים:

פרמטרים
client_id נדרש

מזהה הלקוח של האפליקציה שלך. אפשר למצוא את הערך הזה ב API Console Credentials page.

ב-Python, קוראים לשיטה from_client_secrets_file כדי לאחזר את מזהה הלקוח מקובץ client_secret.json. (ניתן גם להשתמש בשיטה from_client_config שמעבירה את תצורת הלקוח כפי שהיא הופיעה במקור בקובץ סודות של לקוח, אך אינה ניגשת לקובץ עצמו).

flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'])
redirect_uri נדרש

המדיניות הזו קובעת איפה שרת ה-API מפנה את המשתמש אחרי שהוא מסיים את תהליך ההרשאה. הערך חייב להתאים בדיוק לאחד ממזהי ה-URI המורשים של לקוח OAuth 2.0, שמוגדר ב- API Console Credentials pageשל הלקוח. אם הערך לא תואם ל-URI מורשה של כתובת אתר להפניה מחדש עבור client_id שסופק, תתקבל שגיאת redirect_uri_mismatch.

לתשומת ליבכם: http או https הסכימה, האות והקו הנטוי שאחרי ('/') חייבים להתאים לכולם.

כדי להגדיר את הערך הזה ב-Python, מגדירים את מאפיין redirect_uri של האובייקט flow:

flow.redirect_uri = 'https://oauth2.example.com/code'
scope נדרש

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

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

ב-Python, משתמשים בשיטה שבה משתמשים כדי להגדיר את client_id כדי לציין את רשימת ההיקפים. 

flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'])

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

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

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

ב-Python, מגדירים את הפרמטר access_type על ידי ציון access_type כארגומנט של מילת מפתח כשמפעילים את השיטה flow.authorization_url:

authorization_url, state = flow.authorization_url(
    access_type='offline',
    include_granted_scopes='true')
state מומלץ

המדיניות הזו קובעת את ערך המחרוזת שמשמש את האפליקציה כדי לשמור על המצב בין בקשת ההרשאה שלך לבין התגובה של שרת ההרשאות. השרת מחזיר את הערך המדויק ששלחת כצמד name=value ברכיב השאילתה של כתובת ה-URL (?) של ה-redirect_uri, לאחר שהמשתמש מסכים או דוחה את בקשת הגישה של האפליקציה שלך.

אפשר להשתמש בפרמטר הזה לכמה מטרות, למשל הפניית המשתמש למשאב הנכון באפליקציה, שליחת מחרוזות ופתרון זיוף של בקשה בין אתרים. אפשר לנחש את הערך redirect_uri, לכן שימוש בערך state יכול לתת לך הבטחה לכך שהחיבור הנכנס הוא תוצאה של בקשת אימות. אם יוצרים מחרוזת אקראית או מקודדים גיבוב (hash) של קובץ cookie או כל ערך אחר שמתעד את מצב הלקוח, ניתן לאמת את התגובה כדי לוודא שהבקשה ותגובה התקבלו באותו דפדפן, וכך לספק הגנה מפני מתקפות כמו זיוף בקשות באתרים שונים. אפשר להיעזר במאמר OpenID Connect כדי לקבל דוגמה ליצירה ולאישור של אסימון state.

ב-Python, מגדירים את הפרמטר state על ידי ציון state כארגומנט של מילת מפתח כשמפעילים את השיטה flow.authorization_url:

authorization_url, state = flow.authorization_url(
    access_type='offline',
    state=sample_passthrough_value,
    include_granted_scopes='true')
include_granted_scopes אופציונלי

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

ב-Python, מגדירים את הפרמטר include_granted_scopes על ידי ציון include_granted_scopes כארגומנט של מילת מפתח כשמפעילים את השיטה flow.authorization_url:

authorization_url, state = flow.authorization_url(
    access_type='offline',
    include_granted_scopes='true')
login_hint אופציונלי

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

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

ב-Python, מגדירים את הפרמטר login_hint על ידי ציון login_hint כארגומנט של מילת מפתח כשמפעילים את השיטה flow.authorization_url:

authorization_url, state = flow.authorization_url(
    access_type='offline',
    login_hint='None',
    include_granted_scopes='true')
prompt אופציונלי

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

ב-Python, מגדירים את הפרמטר prompt על ידי ציון prompt כארגומנט של מילת מפתח כשמפעילים את השיטה flow.authorization_url:

authorization_url, state = flow.authorization_url(
      access_type='offline',
      prompt='consent',
      include_granted_scopes='true')

הערכים האפשריים הם:

none אין להציג מסכי אימות או הסכמה. לא ניתן לציין אותו עם ערכים אחרים.
consent תוצג למשתמשים בקשת הסכמה.
select_account הצגת בקשה למשתמש לבחור חשבון.

Ruby

יש להשתמש בקובץ client_secrets.json שיצרת כדי להגדיר אובייקט לקוח באפליקציה. כשמגדירים אובייקט לקוח, צריך לציין את היקפי ההרשאות שהאפליקציה צריכה לגשת אליהם, ואת כתובת ה-URL של נקודת הקצה לאימות של האפליקציה. כך היא תטופל בתגובה משרת OAuth 2.0.

לדוגמה, הקוד הזה מבקש גישה לקריאה בלבד, במצב אופליין, ל-Google Drive של המשתמש: 

require 'google/apis/drive_v2'
require 'google/api_client/client_secrets'

client_secrets = Google::APIClient::ClientSecrets.load
auth_client = client_secrets.to_authorization
auth_client.update!(
  :scope => 'https://www.googleapis.com/auth/drive.metadata.readonly',
  :redirect_uri => 'http://www.example.com/oauth2callback',
  :additional_parameters => {
    "access_type" => "offline",         # offline access
    "include_granted_scopes" => "true"  # incremental auth
  }
)

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

Node.js

קטע הקוד שלמטה יוצר אובייקט google.auth.OAuth2, שמגדיר את הפרמטרים בבקשת ההרשאה.

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

const {google} = require('googleapis');

/**
 * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI
 * from the client_secret.json file. To get these credentials for your application, visit
 * https://console.cloud.google.com/apis/credentials.
 */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for read-only Drive activity.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

// Generate a url that asks permissions for the Drive activity scope
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

הערה חשובה – refresh_token מוחזר רק בהרשאה הראשונה. פרטים נוספים כאן.

HTTP/REST

נקודת הקצה של Google OAuth 2.0 נמצאת ב-https://accounts.google.com/o/oauth2/v2/auth. נקודת הקצה הזו נגישה רק באמצעות HTTPS. חיבורי HTTP רגילים נדחות.

שרת ההרשאות של Google תומך בפרמטרים הבאים של מחרוזת שאילתה עבור אפליקציות של שרת אינטרנט:

פרמטרים
client_id נדרש

מזהה הלקוח של האפליקציה שלך. אפשר למצוא את הערך הזה ב API Console Credentials page.
redirect_uri נדרש

המדיניות הזו קובעת איפה שרת ה-API מפנה את המשתמש אחרי שהוא מסיים את תהליך ההרשאה. הערך חייב להתאים בדיוק לאחד ממזהי ה-URI המורשים של לקוח OAuth 2.0, שמוגדר ב- API Console Credentials pageשל הלקוח. אם הערך לא תואם ל-URI מורשה של כתובת אתר להפניה מחדש עבור client_id שסופק, תתקבל שגיאת redirect_uri_mismatch.

לתשומת ליבך: הסכימה, הפנייה או הקו הנטוי שלhttp או https ('/') חייבות להיות תואמות.
response_type נדרש

המדיניות קובעת אם נקודת הקצה Google OAuth 2.0 מחזירה קוד הרשאה.

צריך להגדיר את ערך הפרמטר כ-code לאפליקציות שרת אינטרנט.
scope נדרש

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

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

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

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

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

המדיניות הזו קובעת את ערך המחרוזת שמשמש את האפליקציה כדי לשמור על המצב בין בקשת ההרשאה שלך לבין התגובה של שרת ההרשאות. השרת מחזיר את הערך המדויק ששלחת כצמד name=value ברכיב השאילתה של כתובת ה-URL (?) של ה-redirect_uri, לאחר שהמשתמש מסכים או דוחה את בקשת הגישה של האפליקציה שלך.

אפשר להשתמש בפרמטר הזה לכמה מטרות, למשל הפניית המשתמש למשאב הנכון באפליקציה, שליחת מחרוזות ופתרון זיוף של בקשה בין אתרים. אפשר לנחש את הערך redirect_uri, לכן שימוש בערך state יכול לתת לך הבטחה לכך שהחיבור הנכנס הוא תוצאה של בקשת אימות. אם יוצרים מחרוזת אקראית או מקודדים גיבוב (hash) של קובץ cookie או כל ערך אחר שמתעד את מצב הלקוח, ניתן לאמת את התגובה כדי לוודא שהבקשה ותגובה התקבלו באותו דפדפן, וכך לספק הגנה מפני מתקפות כמו זיוף בקשות באתרים שונים. אפשר להיעזר במאמר OpenID Connect כדי לקבל דוגמה ליצירה ולאישור של אסימון state.
include_granted_scopes אופציונלי

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

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

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

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

הערכים האפשריים הם:

none אין להציג מסכי אימות או הסכמה. לא ניתן לציין אותו עם ערכים אחרים.
consent תוצג למשתמשים בקשת הסכמה.
select_account הצגת בקשה למשתמש לבחור חשבון.

שלב 2: הפניה אוטומטית לשרת OAuth 2.0 של Google

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

PHP

  1. יוצרים כתובת URL כדי לבקש גישה משרת OAuth 2.0 של Google: 
    $auth_url = $client->createAuthUrl();
  2. הפניית המשתמש אל $auth_url: 
    header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));

Python

בדוגמה הבאה אפשר לראות איך להפנות את המשתמש לכתובת ה-URL של ההרשאה באמצעות framework של אפליקציית האינטרנט של Flask:

return flask.redirect(authorization_url)

Ruby

  1. יוצרים כתובת URL כדי לבקש גישה משרת OAuth 2.0 של Google: 
    auth_uri = auth_client.authorization_uri.to_s
  2. הפניית המשתמש אל auth_uri.

Node.js

  1. יש להשתמש בכתובת ה-URL שנוצרה authorizationUrl משיטת שלב 1 generateAuthUrl כדי לבקש גישה משרת OAuth 2.0 של Google.
  2. הפניית המשתמש אל authorizationUrl. 
    res.writeHead(301, { "Location": authorizationUrl });

HTTP/REST

Sample redirect to Google's authorization server

An example URL is shown below, with line breaks and spaces for readability.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 access_type=offline&
 include_granted_scopes=true&
 response_type=code&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

לאחר יצירת כתובת ה-URL של הבקשה, יש להפנות את המשתמש אליה.

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

שלב 3: Google מבקשת מהמשתמשים הסכמה

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

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

שגיאות

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

admin_policy_enforced

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

disallowed_useragent

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

Android

מפתחי Android עשויים להיתקל בהודעת השגיאה הזו בפתיחת בקשות הרשאה ב-android.webkit.WebView. במקום זאת, המפתחים צריכים להשתמש בספריות Android, כמו כניסה באמצעות חשבון Google ל-Android או AppAuth ל-Android של OpenID Foundation.

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

iOS

המפתחים של iOS ו-macOS עשויים להיתקל בשגיאה הזו כשפותחים בקשות הרשאה ב-WKWebView. במקום זאת, מפתחים צריכים להשתמש בספריות iOS, כמו כניסה באמצעות חשבון Google ל-iOS או AppAuth ל-iOS של OpenID Foundation.

מפתחי האתרים עשויים להיתקל בשגיאה הזו כשאפליקציה ל-iOS או ל-macOS פותחת קישור אינטרנט כללי בסוכן משתמש מוטמע, ומשתמש מנווט לאתר דרך נקודת הקצה של OAuth 2.0 של Google. המפתחים צריכים לאפשר לקישורים כלליים להיפתח בברירת המחדל של handlers לקישורים של מערכת ההפעלה, שכוללת את ה-handlers של Universal Links ואת אפליקציית הדפדפן שמוגדרת כברירת מחדל. גם הספרייה SFSafariViewController היא אפשרות נתמכת.
org_internal

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

invalid_client

סוד הלקוח ב-OAuth שגוי. בדיקת התצורה של לקוח OAuth, כולל מזהה הלקוח והסוד של הבקשה הזו.

invalid_grant

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

redirect_uri_mismatch

redirect_uri שהועבר בבקשת ההרשאה לא תואם ל-URI המוקצה להפניה מחדש עבור מספר הלקוח ב-OAuth. יש לבדוק את ה-URIs המותרים להפניה מחדש ב- Google API Console Credentials page.

הפרמטר redirect_uri עשוי להתייחס לזרימת OAuth מחוץ למסגרת (OOB) שהוצאה משימוש ואינה נתמכת יותר. יש לעיין במדריך להעברה כדי לעדכן את האינטגרציה שלך.

שלב 4: טיפול בתגובה של שרת OAuth 2.0

שרת OAuth 2.0 מגיב לבקשת הגישה של האפליקציה שלך באמצעות כתובת האתר שצוינה בבקשה.

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

תגובת שגיאה:

https://oauth2.example.com/auth?error=access_denied

תגובה של קוד הרשאה:

https://oauth2.example.com/auth?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7

דוגמה לתגובה של שרת OAuth 2.0

כדי לבדוק את התהליך הזה, לחצו על כתובת האתר לדוגמה הבאה, שמבקשת גישת קריאה בלבד להצגת מטא נתונים של קבצים ב-Google Drive: 

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 access_type=offline&
 include_granted_scopes=true&
 response_type=code&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

לאחר השלמת הזרימה של OAuth 2.0, המערכת תפנה אותך לכתובת http://localhost/oauth2callback, שככל הנראה תניב שגיאת 404 NOT FOUND, אלא אם המכונה המקומית תציג קובץ בכתובת הזו. השלב הבא מספק פרטים נוספים על המידע שמוחזר ב-URI כשהמשתמש מופנה בחזרה לאפליקציה.

שלב 5: מחליפים את קוד ההרשאה של אסימוני רענון וגישה

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

PHP

כדי להחליף קוד הרשאה לאסימון גישה, יש להשתמש בשיטה authenticate:

$client->authenticate($_GET['code']);

אפשר לאחזר את אסימון הגישה באמצעות השיטה getAccessToken:

$access_token = $client->getAccessToken();

Python

בדף ההתקשרות החוזרת, אפשר להשתמש בספרייה של google-auth כדי לאמת את התשובה של שרת ההרשאות. לאחר מכן, צריך להשתמש בשיטה flow.fetch_token כדי להחליף את קוד ההרשאה בתגובה הזו לאסימון גישה:

state = flask.session['state']
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'],
    state=state)
flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

authorization_response = flask.request.url
flow.fetch_token(authorization_response=authorization_response)

# Store the credentials in the session.
# ACTION ITEM for developers:
#     Store user's access and refresh tokens in your data store if
#     incorporating this code into your real app.
credentials = flow.credentials
flask.session['credentials'] = {
    'token': credentials.token,
    'refresh_token': credentials.refresh_token,
    'token_uri': credentials.token_uri,
    'client_id': credentials.client_id,
    'client_secret': credentials.client_secret,
    'scopes': credentials.scopes}

Ruby

כדי להחליף קוד הרשאה לאסימון גישה, יש להשתמש בשיטה fetch_access_token!:

auth_client.code = auth_code
auth_client.fetch_access_token!

Node.js

כדי להחליף קוד הרשאה לאסימון גישה, יש להשתמש בשיטה getToken:

const url = require('url');

// Receive the callback from Google's OAuth 2.0 server.
if (req.url.startsWith('/oauth2callback')) {
  // Handle the OAuth 2.0 server response
  let q = url.parse(req.url, true).query;

  // Get access and refresh tokens (if access_type is offline)
  let { tokens } = await oauth2Client.getToken(q.code);
  oauth2Client.setCredentials(tokens);
}

HTTP/REST

כדי להחליף קוד הרשאה לאסימון גישה, צריך לקרוא לנקודת הקצה https://oauth2.googleapis.com/token ולהגדיר את הפרמטרים הבאים:

שדות
client_id מספר הלקוח שהתקבל מ- API Console Credentials page.
client_secret סוד הלקוח שהתקבל מ- API Console Credentials page.
code קוד ההרשאה הוחזר מהבקשה הראשונית.
grant_type כפי שמוגדר במפרט OAuth 2.0, יש להגדיר את הערך של השדה הזה כ-authorization_code.
redirect_uri אחד ממזהי ה-URI שצוינו עבור הפרויקט שלך ב- API Console Credentials page של client_id הנתון.

קטע הקוד הבא מציג בקשה לדוגמה:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

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

התשובה מכילה את השדות הבאים:

שדות
access_token האסימון שהאפליקציה שלך שולחת כדי לאשר בקשת API של Google.
expires_in משך החיים הנותר של אסימון הגישה בשניות.
refresh_token אסימון שבו אפשר להשתמש כדי לקבל אסימון גישה חדש. אסימוני רענון יהיו בתוקף עד שהמשתמש יבטל את הגישה. שוב, השדה הזה יוצג בתגובה הזו רק אם הפרמטר access_type יהיה offline בבקשה הראשונית לשרת ההרשאות של Google.
scope היקפי הגישה שניתנו על ידי ה-access_token מוצגים כרשימה של מחרוזות שתלויות ברווחים ותלויות ברווחים.
token_type סוג האסימון שהוחזר. בשלב זה, הערך של השדה הזה תמיד מוגדר Bearer.

קטע הקוד הבא מציג תגובה לדוגמה:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

שגיאות

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

invalid_grant

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

קריאה ל-Google APIs

PHP

משתמשים באסימון הגישה כדי להתקשר ל-Google APIs על ידי ביצוע השלבים הבאים:

  1. אם ברצונך להחיל אסימון גישה על אובייקט Google\Client חדש – לדוגמה, אם אחסנת את אסימון הגישה בסשן של משתמש מסוים, יש להשתמש בשיטה setAccessToken: 
    $client->setAccessToken($access_token);
  2. יוצרים אובייקט שירות ל-API שאליו רוצים להתקשר. כדי ליצור אובייקט שירות, צריך לספק ל-API אובייקט מורשה של Google\Client עבור ה-API שרוצים להפעיל. לדוגמה, כדי לקרוא ל-Drive API: 
    $drive = new Google\Service\Drive($client);
  3. שולחים בקשות לשירות ה-API באמצעות הממשק שסופק על ידי אובייקט השירות. לדוגמה, כדי לרשום את הקבצים ב-Google Drive של המשתמש המאומת: 
    $files = $drive->files->listFiles(array())->getItems();

Python

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

  1. יוצרים אובייקט שירות ל-API שאליו רוצים להתקשר. כדי ליצור אובייקט שירות, יש להפעיל את השיטה build של הספרייה googleapiclient.discovery באמצעות השם והגרסה של ה-API ופרטי הכניסה של המשתמש: לדוגמה, כדי לבצע קריאה לגרסה 2 של Drive API: 
    from googleapiclient.discovery import build

drive = build('drive', 'v2', credentials=credentials)
  2. שולחים בקשות לשירות ה-API באמצעות הממשק שסופק על ידי אובייקט השירות. לדוגמה, כדי לרשום את הקבצים ב-Google Drive של המשתמש המאומת: 
    files = drive.files().list().execute()

Ruby

משתמשים באובייקט auth_client כדי להפעיל את Google APIs על ידי ביצוע השלבים הבאים:

  1. יוצרים אובייקט שירות ל-API שאליו רוצים להתקשר. לדוגמה, כדי לקרוא לגרסה 2 של Drive API: 
    drive = Google::Apis::DriveV2::DriveService.new
  2. מגדירים את פרטי הכניסה בשירות: 
    drive.authorization = auth_client
  3. מגישים בקשות לשירות ה-API באמצעות ממשק שסופק על ידי אובייקט השירות. לדוגמה, כדי לרשום את הקבצים ב-Google Drive של המשתמש המאומת: 
    files = drive.list_files

אפשר גם לספק הרשאה לכל שיטה על ידי ציון השיטה options בשיטה:

files = drive.list_files(options: { authorization: auth_client })

Node.js

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

const { google } = require('googleapis');

// Example of using Google Drive API to list filenames in user's Drive.
const drive = google.drive('v3');
drive.files.list({
  auth: oauth2Client,
  pageSize: 10,
  fields: 'nextPageToken, files(id, name)',
}, (err1, res1) => {
  if (err1) return console.log('The API returned an error: ' + err1);
  const files = res1.data.files;
  if (files.length) {
    console.log('Files:');
    files.map((file) => {
      console.log(`${file.name} (${file.id})`);
    });
  } else {
    console.log('No files found.');
  }
});

HTTP/REST

אחרי שהאפליקציה מקבלת אסימון גישה, אפשר להשתמש באסימון כדי לבצע קריאות ל-Google API מטעם חשבון משתמש נתון, אם הוענקו לך רמות הגישה הנדרשות על ידי ה-API. כדי לעשות זאת, צריך לכלול את אסימון הגישה בבקשה ל-API על ידי הכללת פרמטר שאילתה של access_token או ערך Bearer של כותרת HTTP מסוג Authorization. עדיף להשתמש בכותרת HTTP, כי מחרוזות השאילתה בדרך כלל גלויות ביומני השרת. ברוב המקרים אפשר להשתמש בספריית לקוח כדי להגדיר קריאות ל-Google APIs (לדוגמה, כשמתבצעת קריאה ל-ב-Drive Files API).

אפשר לנסות את כל ממשקי ה-API של Google ולהציג את ההיקפים שלהם במגרש המשחקים של OAuth 2.0.

דוגמאות ל-HTTP GET

קריאת לנקודת הקצה drive.files (ב-Drive Files API) באמצעות כותרת ה-HTTP Authorization: Bearer עשויה להיראות כך: הערה: צריך לציין אסימון גישה משלכם:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

זוהי קריאה לאותו API עבור המשתמש המאומת באמצעות הפרמטר access_token במחרוזת השאילתה:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl דוגמאות

אפשר לבדוק את הפקודות האלה באמצעות האפליקציה של שורת הפקודה curl. הנה דוגמה לשימוש באפשרות כותרת HTTP (מועדף):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

לחלופין, אפשרות הפרמטר של מחרוזת השאילתה:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

דוגמה מלאה

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

PHP

כדי להפעיל את הדוגמה הבאה:

  1. בשדה API Console, מוסיפים את כתובת ה-URL של המכונה המקומית לרשימת כתובות ה-URL להפניה אוטומטית. לדוגמה, מוסיפים http://localhost:8080.
  2. יצירת ספרייה חדשה ושינוי שלה. לדוגמה: 
    mkdir ~/php-oauth2-example
cd ~/php-oauth2-example
  3. התקן את ספריית הלקוחות של Google API עבור PHP באמצעות מלחין: 
    composer require google/apiclient:^2.10
  4. יוצרים את הקבצים index.php ו-oauth2callback.php עם התוכן שמופיע בהמשך.
  5. מריצים את הדוגמה עם שרת אינטרנט שמוגדר להצגת PHP. אם משתמשים ב-PHP 5.6 ואילך, אפשר להשתמש בשרת האינטרנט המובנה המיועד ל-PHP: 
    php -S localhost:8080 ~/php-oauth2-example

index.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google\Client();
$client->setAuthConfig('client_secrets.json');
$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);

if (isset($_SESSION['access_token']) && $_SESSION['access_token']) {
  $client->setAccessToken($_SESSION['access_token']);
  $drive = new Google\Service\Drive($client);
  $files = $drive->files->listFiles(array())->getItems();
  echo json_encode($files);
} else {
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

oauth2callback.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google\Client();
$client->setAuthConfigFile('client_secrets.json');
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');
$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);

if (! isset($_GET['code'])) {
  $auth_url = $client->createAuthUrl();
  header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));
} else {
  $client->authenticate($_GET['code']);
  $_SESSION['access_token'] = $client->getAccessToken();
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

Python

הדוגמה הזו משתמשת במסגרת Flask. הוא מפעיל אפליקציית אינטרנט ב-http://localhost:8080 שמאפשרת לבדוק את זרימת OAuth 2.0. אם תעברו לכתובת ה-URL הזו, יוצגו ארבעה קישורים:

  • בדיקת בקשת API: הקישור הזה מפנה לדף שמנסה לבצע בקשת API לדוגמה. אם צריך, הוא מתחיל את תהליך ההרשאה. אם התגובה לבקשה מוצלחת, הדף יציג את תגובת ה-API.
  • בדיקה ישירה של תהליך האימות: הקישור הזה מפנה לדף שמנסה לשלוח את המשתמש דרך תהליך ההרשאה. האפליקציה מבקשת הרשאה לשלוח בקשות API מורשות מטעם המשתמש.
  • ביטול פרטי הכניסה הנוכחיים: הקישור הזה מפנה לדף שביטל הרשאות שהמשתמש כבר העניק לאפליקציה.
  • ניקוי פרטי כניסה של Flask: קישור זה מוחק פרטי כניסה של הרשאה המאוחסנים בסשן של Flask. כך אפשר לראות מה יקרה אם משתמש שכבר נתן הרשאה לאפליקציה שלכם ינסה לבצע בקשת API בסשן חדש. הוא גם מאפשר לך לראות מה הייתה תגובת ה-API שהאפליקציה שלך הייתה מקבלת אם משתמש ביטל את ההרשאות שהוענקו לאפליקציה שלך, ובכל זאת האפליקציה שלך ניסתה לאשר בקשה באמצעות אסימון גישה שבוטלה.
# -*- coding: utf-8 -*-

import os
import flask
import requests

import google.oauth2.credentials
import google_auth_oauthlib.flow
import googleapiclient.discovery

# This variable specifies the name of a file that contains the OAuth 2.0
# information for this application, including its client_id and client_secret.
CLIENT_SECRETS_FILE = "client_secret.json"

# This OAuth 2.0 access scope allows for full read/write access to the
# authenticated user's account and requires requests to use an SSL connection.
SCOPES = ['https://www.googleapis.com/auth/drive.metadata.readonly']
API_SERVICE_NAME = 'drive'
API_VERSION = 'v2'

app = flask.Flask(__name__)
# Note: A secret key is included in the sample so that it works.
# If you use this code in your application, replace this with a truly secret
# key. See https://flask.palletsprojects.com/quickstart/#sessions.
app.secret_key = 'REPLACE ME - this value is here as a placeholder.'


@app.route('/')
def index():
  return print_index_table()


@app.route('/test')
def test_api_request():
  if 'credentials' not in flask.session:
    return flask.redirect('authorize')

  # Load credentials from the session.
  credentials = google.oauth2.credentials.Credentials(
      **flask.session['credentials'])

  drive = googleapiclient.discovery.build(
      API_SERVICE_NAME, API_VERSION, credentials=credentials)

  files = drive.files().list().execute()

  # Save credentials back to session in case access token was refreshed.
  # ACTION ITEM: In a production app, you likely want to save these
  #              credentials in a persistent database instead.
  flask.session['credentials'] = credentials_to_dict(credentials)

  return flask.jsonify(**files)


@app.route('/authorize')
def authorize():
  # Create flow instance to manage the OAuth 2.0 Authorization Grant Flow steps.
  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES)

  # The URI created here must exactly match one of the authorized redirect URIs
  # for the OAuth 2.0 client, which you configured in the API Console. If this
  # value doesn't match an authorized URI, you will get a 'redirect_uri_mismatch'
  # error.
  flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

  authorization_url, state = flow.authorization_url(
      # Enable offline access so that you can refresh an access token without
      # re-prompting the user for permission. Recommended for web server apps.
      access_type='offline',
      # Enable incremental authorization. Recommended as a best practice.
      include_granted_scopes='true')

  # Store the state so the callback can verify the auth server response.
  flask.session['state'] = state

  return flask.redirect(authorization_url)


@app.route('/oauth2callback')
def oauth2callback():
  # Specify the state when creating the flow in the callback so that it can
  # verified in the authorization server response.
  state = flask.session['state']

  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES, state=state)
  flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

  # Use the authorization server's response to fetch the OAuth 2.0 tokens.
  authorization_response = flask.request.url
  flow.fetch_token(authorization_response=authorization_response)

  # Store credentials in the session.
  # ACTION ITEM: In a production app, you likely want to save these
  #              credentials in a persistent database instead.
  credentials = flow.credentials
  flask.session['credentials'] = credentials_to_dict(credentials)

  return flask.redirect(flask.url_for('test_api_request'))


@app.route('/revoke')
def revoke():
  if 'credentials' not in flask.session:
    return ('You need to <a href="/authorize">authorize</a> before ' +
            'testing the code to revoke credentials.')

  credentials = google.oauth2.credentials.Credentials(
    **flask.session['credentials'])

  revoke = requests.post('https://oauth2.googleapis.com/revoke',
      params={'token': credentials.token},
      headers = {'content-type': 'application/x-www-form-urlencoded'})

  status_code = getattr(revoke, 'status_code')
  if status_code == 200:
    return('Credentials successfully revoked.' + print_index_table())
  else:
    return('An error occurred.' + print_index_table())


@app.route('/clear')
def clear_credentials():
  if 'credentials' in flask.session:
    del flask.session['credentials']
  return ('Credentials have been cleared.<br><br>' +
          print_index_table())


def credentials_to_dict(credentials):
  return {'token': credentials.token,
          'refresh_token': credentials.refresh_token,
          'token_uri': credentials.token_uri,
          'client_id': credentials.client_id,
          'client_secret': credentials.client_secret,
          'scopes': credentials.scopes}

def print_index_table():
  return ('<table>' +
          '<tr><td><a href="/test">Test an API request</a></td>' +
          '<td>Submit an API request and see a formatted JSON response. ' +
          '    Go through the authorization flow if there are no stored ' +
          '    credentials for the user.</td></tr>' +
          '<tr><td><a href="/authorize">Test the auth flow directly</a></td>' +
          '<td>Go directly to the authorization flow. If there are stored ' +
          '    credentials, you still might not be prompted to reauthorize ' +
          '    the application.</td></tr>' +
          '<tr><td><a href="/revoke">Revoke current credentials</a></td>' +
          '<td>Revoke the access token associated with the current user ' +
          '    session. After revoking credentials, if you go to the test ' +
          '    page, you should see an <code>invalid_grant</code> error.' +
          '</td></tr>' +
          '<tr><td><a href="/clear">Clear Flask session credentials</a></td>' +
          '<td>Clear the access token currently stored in the user session. ' +
          '    After clearing the token, if you <a href="/test">test the ' +
          '    API request</a> again, you should go back to the auth flow.' +
          '</td></tr></table>')


if __name__ == '__main__':
  # When running locally, disable OAuthlib's HTTPs verification.
  # ACTION ITEM for developers:
  #     When running in production *do not* leave this option enabled.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  # Specify a hostname and port that are set as a valid redirect URI
  # for your API project in the Google API Console.
  app.run('localhost', 8080, debug=True)

Ruby

הדוגמה הזו משתמשת במסגרת Sinatra.

require 'google/apis/drive_v2'
require 'google/api_client/client_secrets'
require 'json'
require 'sinatra'

enable :sessions
set :session_secret, 'setme'

get '/' do
  unless session.has_key?(:credentials)
    redirect to('/oauth2callback')
  end
  client_opts = JSON.parse(session[:credentials])
  auth_client = Signet::OAuth2::Client.new(client_opts)
  drive = Google::Apis::DriveV2::DriveService.new
  files = drive.list_files(options: { authorization: auth_client })
  "<pre>#{JSON.pretty_generate(files.to_h)}</pre>"
end

get '/oauth2callback' do
  client_secrets = Google::APIClient::ClientSecrets.load
  auth_client = client_secrets.to_authorization
  auth_client.update!(
    :scope => 'https://www.googleapis.com/auth/drive.metadata.readonly',
    :redirect_uri => url('/oauth2callback'))
  if request['code'] == nil
    auth_uri = auth_client.authorization_uri.to_s
    redirect to(auth_uri)
  else
    auth_client.code = request['code']
    auth_client.fetch_access_token!
    auth_client.client_secret = nil
    session[:credentials] = auth_client.to_json
    redirect to('/')
  end
end

Node.js

כדי להפעיל את הדוגמה הבאה:

  1. בשדה API Console, יש להוסיף את כתובת ה-URL של המכונה המקומית לרשימת כתובות ה-URL להפניה אוטומטית. לדוגמה, אפשר להוסיף את http://localhost.
  2. עליך לוודא שמותקנת במכשיר שלך גרסת LTS לתחזוקה, LTS פעיל או גרסה נוכחית של Node.js.
  3. יצירת ספרייה חדשה ושינוי שלה. לדוגמה: 
    mkdir ~/nodejs-oauth2-example
cd ~/nodejs-oauth2-example
  4. Install the Google API Client Library for Node.js using npm: 
    npm install googleapis
  5. יוצרים את הקבצים main.js, שמכילים את התוכן שמופיע בהמשך.
  6. מריצים את הדוגמה הבאה: 
    node .\main.js

main.js

const http = require('http');
const https = require('https');
const url = require('url');
const { google } = require('googleapis');

/**
 * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI.
 * To get these credentials for your application, visit
 * https://console.cloud.google.com/apis/credentials.
 */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for read-only Drive activity.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

// Generate a url that asks permissions for the Drive activity scope
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

/* Global variable that stores user credential in this code example.
 * ACTION ITEM for developers:
 *   Store user's refresh token in your data store if
 *   incorporating this code into your real app.
 *   For more information on handling refresh tokens,
 *   see https://github.com/googleapis/google-api-nodejs-client#handling-refresh-tokens
 */
let userCredential = null;

async function main() {
  const server = http.createServer(async function (req, res) {
    // Example on redirecting user to Google's OAuth 2.0 server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }

    // Receive the callback from Google's OAuth 2.0 server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the OAuth 2.0 server response
      let q = url.parse(req.url, true).query;

      if (q.error) { // An error response e.g. error=access_denied
        console.log('Error:' + q.error);
      } else { // Get access and refresh tokens (if access_type is offline)
        let { tokens } = await oauth2Client.getToken(q.code);
        oauth2Client.setCredentials(tokens);

        /** Save credential to the global variable in case access token was refreshed.
          * ACTION ITEM: In a production app, you likely want to save the refresh token
          *              in a secure persistent database instead. */
        userCredential = tokens;

        // Example of using Google Drive API to list filenames in user's Drive.
        const drive = google.drive('v3');
        drive.files.list({
          auth: oauth2Client,
          pageSize: 10,
          fields: 'nextPageToken, files(id, name)',
        }, (err1, res1) => {
          if (err1) return console.log('The API returned an error: ' + err1);
          const files = res1.data.files;
          if (files.length) {
            console.log('Files:');
            files.map((file) => {
              console.log(`${file.name} (${file.id})`);
            });
          } else {
            console.log('No files found.');
          }
        });
      }
    }

    // Example on revoking a token
    if (req.url == '/revoke') {
      // Build the string for the POST request
      let postData = "token=" + userCredential.access_token;

      // Options for POST request to Google's OAuth 2.0 server to revoke a token
      let postOptions = {
        host: 'oauth2.googleapis.com',
        port: '443',
        path: '/revoke',
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded',
          'Content-Length': Buffer.byteLength(postData)
        }
      };

      // Set up the request
      const postReq = https.request(postOptions, function (res) {
        res.setEncoding('utf8');
        res.on('data', d => {
          console.log('Response: ' + d);
        });
      });

      postReq.on('error', error => {
        console.log(error)
      });

      // Post the request with data
      postReq.write(postData);
      postReq.end();
    }
    res.end();
  }).listen(80);
}
main().catch(console.error);

HTTP/REST

הדוגמה של Python משתמשת במסגרת Flask ובספרייה Requests כדי להמחיש את תהליך OAuth 2.0 באינטרנט. אנחנו ממליצים להשתמש בספריית הלקוח של Google API עבור Python עבור התהליך הזה. (הדוגמה בכרטיסייה של Python עושה שימוש בספריית הלקוח).

import json

import flask
import requests


app = flask.Flask(__name__)

CLIENT_ID = '123456789.apps.googleusercontent.com'
CLIENT_SECRET = 'abc123'  # Read from a file or environmental variable in a real app
SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly'
REDIRECT_URI = 'http://example.com/oauth2callback'


@app.route('/')
def index():
  if 'credentials' not in flask.session:
    return flask.redirect(flask.url_for('oauth2callback'))
  credentials = json.loads(flask.session['credentials'])
  if credentials['expires_in'] <= 0:
    return flask.redirect(flask.url_for('oauth2callback'))
  else:
    headers = {'Authorization': 'Bearer {}'.format(credentials['access_token'])}
    req_uri = 'https://www.googleapis.com/drive/v2/files'
    r = requests.get(req_uri, headers=headers)
    return r.text


@app.route('/oauth2callback')
def oauth2callback():
  if 'code' not in flask.request.args:
    auth_uri = ('https://accounts.google.com/o/oauth2/v2/auth?response_type=code'
                '&client_id={}&redirect_uri={}&scope={}').format(CLIENT_ID, REDIRECT_URI, SCOPE)
    return flask.redirect(auth_uri)
  else:
    auth_code = flask.request.args.get('code')
    data = {'code': auth_code,
            'client_id': CLIENT_ID,
            'client_secret': CLIENT_SECRET,
            'redirect_uri': REDIRECT_URI,
            'grant_type': 'authorization_code'}
    r = requests.post('https://oauth2.googleapis.com/token', data=data)
    flask.session['credentials'] = r.text
    return flask.redirect(flask.url_for('index'))


if __name__ == '__main__':
  import uuid
  app.secret_key = str(uuid.uuid4())
  app.debug = False
  app.run()

כללי אימות של URI של הפניה מחדש

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

כללי אימות
סכמה

כתובות אתרים להפניה מחדש חייבות להשתמש בסכימת HTTPS, ולא ב-HTTP רגיל. כתובות URI של מארח מקומי (כולל כתובות URI של כתובת URL של מארח מקומי) פטורות מהכלל הזה.
מארח

המארחים לא יכולים להיות כתובות IP גולמיות. כתובות IP של מארח מקומי פטורות מהכלל הזה.
דומיין
  • דומיינים ברמה העליונה של מארח (דומיינים ברמה עליונה) חייבים להשתייך לרשימת הסיומות הציבוריות.
  • דומיינים מארחים לא יכולים להיות “googleusercontent.com”.
  • כתובות אתרים להפניה מחדש לא יכולות להכיל דומיינים של קיצור כתובות אתרים (לדוגמה, goo.gl), אלא אם הדומיין שייך לאפליקציה. בנוסף, אם אפליקציה שבבעלותה דומיין של גורם מקוצר בוחרת להפנות לדומיין הזה, כתובת ה-URL הזו להפניה מחדש חייבת להכיל את הנתיב “/google-callback/” או להסתיים ב-“/google-callback”.
    		•
    פרטי משתמש

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

    URIs של הפניה מחדש לא יכולים לכלול מעבר נתיב (נקרא גם 'הקודם' של הספרייה), שמיוצג על ידי “/..” או “\..” או את קידוד כתובות ה-URL שלהם.
    שאילתה

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

    כתובות אתרים להפניה מחדש לא יכולות להכיל את רכיב המקטע.
    תווים כתובות אתרים להפניה מחדש לא יכולות להכיל תווים מסוימים, כולל:
    • תווים כלליים לחיפוש ('*')
    • תווי ASCII שאינם ניתנים להדפסה
    • קידוד אחוזים באחוזים לא חוקי (כל קידוד באחוזים שאינו מופיע בצורה של קידוד כתובת אתר של סימן אחוז ואחריו שתי ספרות הקסדצימליות)
    • תווי Null (תו NULL מקודד, למשל, %00, %C0%80)

    הרשאה מצטברת

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

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

    במקרה כזה, בזמן הכניסה לאפליקציה, ייתכן שהאפליקציה תבקש את ההיקפים של openid ושל profile כדי לבצע כניסה בסיסית, ובהמשך תהיה בקשה בהיקף https://www.googleapis.com/auth/drive.file בזמן הבקשה הראשונה, כדי לשמור מיקס.

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

    הכללים הבאים חלים על אסימון גישה שהושג מהרשאה מצטברת:

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

    דוגמאות הקוד הספציפיות לשפה בשלב 1: הגדרת פרמטרים של הרשאות וכתובת האתר להפניה מחדש מסוג HTTP/REST לדוגמה בשלב 2: הפניה מחדש לשרת OAuth 2.0 של Google משתמשות בהרשאה מצטברת. בדוגמאות הקוד שבהמשך מוצגים גם הקוד שצריך להוסיף כדי להשתמש בהרשאה מצטברת.

    PHP

    $client->setIncludeGrantedScopes(true);

    Python

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

    authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

    Ruby

    auth_client.update!(
  :additional_parameters => {"include_granted_scopes" => "true"}
)

    Node.js

    const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

    HTTP/REST

    GET https://accounts.google.com/o/oauth2/v2/auth?
  client_id=your_client_id&
  response_type=code&
  state=state_parameter_passthrough_value&
  scope=https%3A//www.googleapis.com/auth/drive.file&
  redirect_uri=https%3A//oauth2.example.com/code&
  prompt=consent&
  include_granted_scopes=true

    רענון של אסימון גישה (גישה במצב אופליין)

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

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

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

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

    PHP

    אם לאפליקציה שלך נדרשת גישה אופליין ל-Google API, צריך להגדיר את סוג הגישה של לקוח ה-API כ-offline:

    $client->setAccessType("offline");

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

    Python

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

    authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

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

    Ruby

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

    auth_client.update!(
  :additional_parameters => {"access_type" => "offline"}
)

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

    Node.js

    אם לאפליקציה שלך נדרשת גישה אופליין ל-Google API, צריך להגדיר את סוג הגישה של לקוח ה-API כ-offline:

    const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

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

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

    oauth2Client.on('tokens', (tokens) => {
  if (tokens.refresh_token) {
    // store the refresh_token in your secure persistent database
    console.log(tokens.refresh_token);
  }
  console.log(tokens.access_token);
});

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

    כדי להגדיר את ה-refresh_token מאוחר יותר, אפשר להשתמש בשיטה setCredentials: 

    oauth2Client.setCredentials({
  refresh_token: `STORED_REFRESH_TOKEN`
});

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

    HTTP/REST

    כדי לרענן אסימון גישה, האפליקציה שולחת בקשת HTTPS מסוג POST לשרת ההרשאות של Google (https://oauth2.googleapis.com/token) שכולל את הפרמטרים הבאים:

    שדות
    client_id מספר הלקוח שהתקבל מ- API Console.
    client_secret סוד הלקוח שהתקבל מ- API Console.
    grant_type כפי שמוגדר במפרט של OAuth 2.0, הערך של השדה הזה צריך להיות refresh_token.
    refresh_token אסימון הרענון שמוחזר מהמרת קוד ההרשאה.

    קטע הקוד הבא מציג בקשה לדוגמה:

    POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

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

    {
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

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

    ביטול אסימון

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

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

    PHP

    כדי לבטל אסימון באופן פרוגרמטי, יש להתקשר למספר revokeToken():

    $client->revokeToken();

    Python

    כדי לבטל אסימון באופן פרוגרמטי, יש להגיש בקשה ל-https://oauth2.googleapis.com/revoke שכולל את האסימון כפרמטר ולהגדיר את הכותרת Content-Type:

    requests.post('https://oauth2.googleapis.com/revoke',
    params={'token': credentials.token},
    headers = {'content-type': 'application/x-www-form-urlencoded'})

    Ruby

    כדי לבטל אסימון באופן פרוגרמטי, צריך לשלוח בקשת HTTP אל נקודת הקצה oauth2.revoke:

    uri = URI('https://oauth2.googleapis.com/revoke')
response = Net::HTTP.post_form(uri, 'token' => auth_client.access_token)

    האסימון יכול להיות אסימון גישה או אסימון רענון. אם האסימון הוא אסימון גישה ויש לו אסימון רענון תואם, אסימון הרענון גם יבוטל.

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

    Node.js

    כדי לבטל אסימון באופן פרוגרמטי, יש להגיש בקשת HTTPS POST לנקודת הקצה /revoke:

    const https = require('https');

// Build the string for the POST request
let postData = "token=" + userCredential.access_token;

// Options for POST request to Google's OAuth 2.0 server to revoke a token
let postOptions = {
  host: 'oauth2.googleapis.com',
  port: '443',
  path: '/revoke',
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Content-Length': Buffer.byteLength(postData)
  }
};

// Set up the request
const postReq = https.request(postOptions, function (res) {
  res.setEncoding('utf8');
  res.on('data', d => {
    console.log('Response: ' + d);
  });
});

postReq.on('error', error => {
  console.log(error)
});

// Post the request with data
postReq.write(postData);
postReq.end();

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

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

    HTTP/REST

    כדי לבטל אסימון באופן פרוגרמטי, האפליקציה שלך שולחת בקשה אל https://oauth2.googleapis.com/revoke וכוללת את האסימון בתור פרמטר:

    curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

    האסימון יכול להיות אסימון גישה או אסימון רענון. אם האסימון הוא אסימון גישה ויש לו אסימון רענון תואם, אסימון הרענון גם יבוטל.

    אם הביטול יעובד בהצלחה, קוד הסטטוס של התגובה של ה-HTTP יהיה 200. בתנאי שגיאה, מוחזר קוד סטטוס HTTP 400 יחד עם קוד שגיאה.