OAuth 2.0 לאפליקציות לנייד ולמחשב

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

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

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

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

חלופות

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

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

ספריות ודוגמאות

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

• ספריית AppAuth ל-Android
• ספריית AppAuth ל-iOS
• OAuth לאפליקציות: Windows דוגמאות

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

הפעלת ממשקי 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. בדף ספרייה אפשר למצוא את ממשק YouTube Data API ולהפעיל אותו. צריך לחפש ממשקי API אחרים שהאפליקציה תשתמש בהם ולהפעיל גם אותם.

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

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

1. Go to the Credentials page.
2. לוחצים על Create credentials > מזהה לקוח OAuth.
3. הקטעים הבאים מתארים את סוגי הלקוחות ואת שיטות ההפניה האוטומטית שבהן תומך שרת ההרשאות של Google. בוחרים את סוג הלקוח המומלץ לאפליקציה, נותנים שם ללקוח OAuth ומגדירים את שאר השדות בטופס לפי הצורך.

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

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

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

ממשק YouTube Data API v3 משתמש בהיקפים הבאים:

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

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

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

שלב 1: יוצרים מאמת קוד ואתגר

Google תומכת בפרוטוקול Proof Key for Code Exchange (PKCE) כדי לשפר את האבטחה של זרימת האפליקציה המותקנת. לכל בקשת הרשאה נוצר מאמת קוד ייחודי, והערך שלו, שנקרא "code_challenge", נשלח לשרת ההרשאות כדי לקבל את קוד ההרשאה.

יצירה של מאמת הקוד

code_verifier היא מחרוזת אקראית קריפטוגרפית עם אנטרופיה גבוהה שמורכבת מתווים לא שמורים: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", באורך מינימלי של 43 תווים ובאורך מקסימלי של 128 תווים.

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

יוצרים את אתגר הקוד

יש תמיכה בשתי שיטות ליצירת אתגר הקוד.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

שלב 2: שליחת בקשה לשרת OAuth 2.0 של Google

כדי לקבל הרשאה למשתמש, צריך לשלוח בקשה לשרת האימות של Google בכתובת https://accounts.google.com/o/oauth2/v2/auth. נקודת הקצה (endpoint) הזו מטפלת בחיפוש פעיל בסשן, מאמתת את המשתמש ומקבלת את הסכמת המשתמשים. ניתן לגשת לנקודת הקצה רק באמצעות SSL, והיא דוחה חיבורי HTTP (לא SSL).

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

דוגמאות לכתובות URL של הרשאות

הכרטיסיות הבאות מציגות כתובות URL של הרשאות לדוגמה עבור האפשרויות השונות של כתובות URI להפניה מחדש.

כתובות ה-URL זהות, מלבד הערך של הפרמטר redirect_uri. כתובות ה-URL מכילות גם את הפרמטרים הנדרשים response_type ו-client_id, וגם את הפרמטר האופציונלי state. כל כתובת URL כוללת מעברי שורה ורווחים כדי לשפר את הקריאוּת.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

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

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

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

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

האופן שבו האפליקציה מקבלת את תגובת ההרשאה תלוי בסכימת ה-URI להפניה אוטומטית שבה היא משתמשת. בלי קשר לסכימה, התשובה תכיל קוד הרשאה (code) או שגיאה (error). לדוגמה, error=access_denied מציין שהמשתמש דחה את הבקשה.

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

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

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

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

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=http://127.0.0.1:9004&
grant_type=authorization_code

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

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

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

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

קריאה ל-Google APIs

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

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

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

דוגמאות ל-HTTP GET

קריאה לנקודת הקצה ( youtube.channels) (YouTube Data API) באמצעות כותרת ה-HTTP Authorization: Bearer עשויה להיראות כך. שימו לב שתצטרכו לציין אסימון גישה משלכם:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

curl דוגמאות

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

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

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

רענון של אסימון גישה

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

כדי לרענן אסימון גישה, האפליקציה שולחת בקשת POST מסוג HTTPS לשרת ההרשאות של Google (https://oauth2.googleapis.com/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, כדי להבטיח שההרשאות שניתנו בעבר לאפליקציה יוסרו.

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

קריאה נוספת

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