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

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

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

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

תהליך ההרשאה הזה דומה לתהליך ההרשאה אפליקציות בשרת האינטרנט. ההבדל העיקרי הוא האפליקציות המותקנות חייבות לפתוח את דפדפן המערכת ולספק URI של הפניה אוטומטית לטיפול תגובות משרת ההרשאות של 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. הקטעים הבאים מתארים את סוגי הלקוחות ואת שיטות ההפניה מחדש ששרת ההרשאות תומך בכך. צריך לבחור את סוג הלקוח המומלץ ייתן שם ללקוח 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 תומכת במפתח הוכחה עבור 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: קוד ההרשאה של Exchange לרענון וגישה אסימונים

כדי להחליף קוד הרשאה באסימון גישה, קוראים אל 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

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

כדי לרענן אסימון גישה, האפליקציה שולחת כתובת URL מסוג HTTPS מסוג POST לשרת האימות של 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"
}

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

ביטול אסימון

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

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

קריאה נוספת

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