חיבור OpenID

ניתן להשתמש בממשקי ה-API של OAuth 2.0 לאימות ולהרשאה. מסמך זה מתאר את יישום OAuth 2.0 שלנו לאימות, שתואם למפרט OpenID Connect, והוא אישור OpenID. המסמכים שמופיעים בקטע שימוש ב-OAuth 2.0 לגישה ל-API של Google חלים גם על השירות הזה. אם ברצונך לבדוק את הפרוטוקול הזה באופן אינטראקטיבי, אנחנו ממליצים על מגרש המשחקים של Google OAuth 2.0. לקבלת עזרה בנושא Stack Overflow, אפשר לתייג את השאלות בדומיין 'google-oauth'

הגדרת OAuth 2.0

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

קבלת פרטי כניסה של OAuth 2.0

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

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

לחלופין, צפה בזיהוי הלקוח ובסוד הלקוח שלך מדף האישורים ב API Console :

  1. Go to the Credentials page.
  2. לחץ על שם האישור שלך או על סמל העיפרון ( ). קוד זיהוי הלקוח וסודך נמצאים בראש העמוד.

הגדרת URI של הפניה אוטומטית

ה-URI של ההפניה האוטומטית שהגדרת ב- API Console קובע ש-Google שולחת תגובות לבקשות האימות שלך.

כדי ליצור, להציג או לערוך את כתובות ה- URI להפניה מחדש עבור אישור נתון OAuth 2.0, בצע את הפעולות הבאות:

  1. Go to the Credentials page.
  2. בקטע מזהי לקוח OAuth 2.0 בדף, לחץ על אישור.
  3. הצגה או עריכה של קבצי ה- URI המפנים מחדש.

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

התאמה אישית של מסך הסכמת משתמש

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

במסך הסכמת המשתמש מוצגים גם פרטי מיתוג כמו שם המוצר, הלוגו וכתובת ה-URL של דף הבית. אפשר לשלוט בפרטי המיתוג ב API Console.

כדי לאפשר את מסך ההסכמה של הפרויקט שלך:

  1. פתח את Consent Screen page ב- Google API Console .
  2. If prompted, select a project, or create a new one.
  3. מלא את הטופס ולחץ על שמור .

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

צילום מסך של דף ההסכמה

גישה לשירות

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

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

מתבצע אימות של המשתמש

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

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

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

זרימת שרת

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

  1. יצירת אסימון למצב מניעת זיוף
  2. שליחת בקשת אימות ל-Google
  3. אישור אסימון מצב מניעת זיוף
  4. Exchange code עבור אסימון גישה ואסימון מזהה
  5. קבלת פרטי משתמש מאסימון המזהה
  6. אימות המשתמש

1. יצירת אסימון למצב מניעת זיוף

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

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

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

PHP

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

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
$state = bin2hex(random_bytes(128/8));
$app['session']->set('state', $state);
// Set the client ID, token state, and application name in the HTML while
// serving it.
return $app['twig']->render('index.html', array(
    'CLIENT_ID' => CLIENT_ID,
    'STATE' => $state,
    'APPLICATION_NAME' => APPLICATION_NAME
));

Java

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

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
String state = new BigInteger(130, new SecureRandom()).toString(32);
request.session().attribute("state", state);
// Read index.html into memory, and set the client ID,
// token state, and application name in the HTML before serving it.
return new Scanner(new File("index.html"), "UTF-8")
    .useDelimiter("\\A").next()
    .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
    .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)
    .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}",
    APPLICATION_NAME);

Python

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

# Create a state token to prevent request forgery.
# Store it in the session for later validation.
state = hashlib.sha256(os.urandom(1024)).hexdigest()
session['state'] = state
# Set the client ID, token state, and application name in the HTML while
# serving it.
response = make_response(
    render_template('index.html',
                    CLIENT_ID=CLIENT_ID,
                    STATE=state,
                    APPLICATION_NAME=APPLICATION_NAME))

2. שליחת בקשת אימות ל-Google

השלב הבא הוא יצירת בקשת HTTPS GET עם הפרמטרים המתאימים של URI. לתשומת ליבך, השימוש ב-HTTPS במקום ב-HTTP בכל השלבים של התהליך הזה. אין תמיכה בחיבורי HTTP. יש לאחזר את ה-URI הבסיסי ממסמך ה-Discovery באמצעות ערך המטא-נתונים authorization_endpoint. בדיון הבא ההנחה היא שה-URI הבסיסי הוא https://accounts.google.com/o/oauth2/v2/auth.

לבקשה בסיסית, יש לציין את הפרמטרים הבאים:

  • client_id, שאפשר לקבל מ API Console Credentials page .
  • response_type, שבבקשה בסיסית לזרימת קוד צריך להיות code. (מידע נוסף זמין בכתובת response_type.)
  • scope, שבבקשה בסיסית צריכים להיות openid email. (מידע נוסף זמין בכתובת scope).
  • הערך redirect_uri צריך להיות נקודת הקצה (endpoint) של HTTP בשרת, שתקבל את התגובה מ-Google. הערך צריך להתאים בדיוק לאחד ממזהי ה-URI המורשים של לקוח OAuth 2.0, שהגדרת ב API Console Credentials page. אם הערך הזה לא תואם ל-URI מאושר, הבקשה תיכשל עם שגיאה של redirect_uri_mismatch.
  • state צריך לכלול את הערך של אסימון סשנים ייחודי נגד זיוף, וגם כל מידע אחר שנדרש כדי לשחזר את ההקשר כשהמשתמש חוזר לאפליקציה, למשל כתובת ה-URL להתחלה. (מידע נוסף זמין בכתובת state).
  • הערך nonce הוא ערך אקראי שנוצר על ידי האפליקציה שלך, שמאפשר הגנה מפני הפעלה מחדש.
  • login_hint יכול להיות כתובת האימייל של המשתמש או המחרוזת sub, שזהה למזהה Google של המשתמש. אם לא סיפקת login_hint והמשתמש מחובר כרגע, מסך ההסכמה כולל בקשה לאישור לשחרור כתובת האימייל של המשתמש לאפליקציה. (מידע נוסף זמין בכתובת login_hint.)
  • ניתן להשתמש בפרמטר hd כדי לבצע אופטימיזציה של תהליך OpenID Connect למשתמשים של דומיין מסוים המשויך לארגון ב-Google Cloud. (מידע נוסף זמין בכתובת hd.)

לפניכם דוגמה ל-URI מלא לאימות של OpenID Connect, עם מעברי שורה ורווחים לקריאה:

https://accounts.google.com/o/oauth2/v2/auth?
 response_type=code&
 client_id=424911365001.apps.googleusercontent.com&
 scope=openid%20email&
 redirect_uri=https%3A//oauth2.example.com/code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=jsmith@example.com&
 nonce=0394852-3190485-2490358&
 hd=example.com

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

3. אישור אסימון של מצב נגד זיוף

התגובה תישלח אל redirect_uri שציינת בבקשה. כל התגובות יוחזרו במחרוזת השאילתה, כפי שמוצג בהמשך:

https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email

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

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

PHP

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

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if ($request->get('state') != ($app['session']->get('state'))) {
  return new Response('Invalid state parameter', 401);
}

Java

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

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if (!request.queryParams("state").equals(
    request.session().attribute("state"))) {
  response.status(401);
  return GSON.toJson("Invalid state parameter.");
}

Python

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

# Ensure that the request is not a forgery and that the user sending
# this connect request is the expected user.
if request.args.get('state', '') != session['state']:
  response = make_response(json.dumps('Invalid state parameter.'), 401)
  response.headers['Content-Type'] = 'application/json'
  return response

4. החלפת code לאסימון הגישה ולאסימון המזהה

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

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

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

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

תגובה מוצלחת לבקשה הזו מכילה את השדות הבאים במערך JSON:

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

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

5. קבלת פרטי משתמש מאסימון המזהה

אסימון ID הוא JWT (JSON Web Token), כלומר אובייקט JSON מקודד עם קריפטוגרפיה. לרוב, חשוב מאוד לאמת אסימון מזהה לפני שמשתמשים בו, אבל מאחר שיוצרים קשר ישירות עם Google דרך ערוץ HTTPS ללא מתווך, ומשתמשים בסוד הלקוח לצורך אימות שלך ב-Google, אפשר להיות בטוחים שהאסימון שקיבלת אכן מגיע מ-Google והוא תקין. אם השרת יעביר את האסימון למזהה ברכיבים אחרים של האפליקציה, חשוב מאוד שהרכיבים האחרים יאמתו את האסימון לפני השימוש בו.

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

מטען ייעודי (payload) של אסימון

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

{
  "iss": "https://accounts.google.com",
  "azp": "1234987819200.apps.googleusercontent.com",
  "aud": "1234987819200.apps.googleusercontent.com",
  "sub": "10769150350006150715113082367",
  "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
  "hd": "example.com",
  "email": "jsmith@example.com",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

אסימוני Google ID עשויים להכיל את השדות הבאים (המכונים תלונות):

תבע בעלות מוגדרים תיאור
aud תמ הקהל שבשבילו אסימון המזהה הזה מיועד. הוא חייב להיות אחד ממזהי הלקוח ב-OAuth 2.0 של האפליקציה שלך.
exp תמ אחרי תאריך התפוגה, אין לקבל את אסימון המזהה. מיוצגת באמצעות זמן יוניקס (מספר שלם).
iat תמ השעה שבה התעודה המזהה הונפקה. מיוצגת בזמן Unix (מספר שלם).
iss תמ מזהה המנפיק של המנפיק של התגובה. תמיד https://accounts.google.com או accounts.google.com לאסימוני Google ID.
sub תמ המזהה של המשתמש, שהוא ייחודי לכל חשבונות Google ולעולם לא נעשה בו שימוש חוזר. לחשבון Google אחד יכולות להיות מספר כתובות אימייל בנקודות זמן שונות, אבל הערך של sub לא משתנה אף פעם. צריך להשתמש באפליקציה sub כמפתח המזהה הייחודי של המשתמש. אורך מקסימלי של 255 תווי ASCII תלויי אותיות רישיות.
at_hash גיבוב (Hash) של אסימון הגישה. המדיניות הזו מאמתת שאסימון הגישה מקושר לאסימון הזהות. אם אסימון המזהה הונפק עם ערך access_token בתהליך השרת, התלונה הזו תמיד כלולה. ניתן להשתמש בתלונה הזו כמנגנון חלופי להגנה מפני מתקפות זיוף של בקשות בין אתרים, אבל אם מבצעים את שלב 1 ושלב 3, אין צורך לאמת את אסימון הגישה.
azp client_id של הנציג המורשה. התלונה הזו נדרשת רק כשהגורם המבקש את אסימון המזהה אינו זהה לקהל של אסימון המזהה. זה יכול לקרות במקרה של אפליקציות היברידיות באפליקציות היברידיות, שבהן לאפליקציית אינטרנט ולאפליקציית Android יש OAuth 2.0 client_id שונה, אבל אותו פרויקט Google APIs משותף.
email כתובת האימייל של המשתמש. הערך הזה לא יכול להיות ייחודי למשתמש הזה, והוא לא מתאים לשימוש כמפתח ראשי. האפשרות הזאת סופקה רק אם ההיקף כולל את היקף הemail.
email_verified הערך הזה נכון אם כתובת האימייל של המשתמש אומתה, אחרת False.
family_name שמות המשפחה של המשתמשים או שמות המשפחה. אפשר לציין אם יש name תלונה.
given_name שמות או שמות פרטיים של משתמשים. אפשר לציין אם יש name תלונה.
hd הדומיין המשויך לארגון של המשתמש ב-Google Cloud. מסופק רק אם המשתמש שייך לארגון ב-Google Cloud.
locale הלוקאל של המשתמש&, מיוצג על ידי תג שפה של BCP 47. אפשר לציין אם יש תלונה name.
name השם המלא של המשתמש, בצורה הניתנת לתצוגה. אפשר לציין זאת במקרים הבאים:
  • היקף הבקשה כלל את המחרוזת "profile"
  • אסימון המזהה מוחזר מרענון אסימון

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

nonce הערך של nonce שסופק על ידי האפליקציה שלך בבקשת האימות. יש לך אפשרות לאכוף את ההגנה מפני תקיפות הפעלה מחדש. לשם כך, יש לוודא שהיא מוצגת פעם אחת בלבד.
picture כתובת ה-URL של תמונת הפרופיל של המשתמש. אפשר לציין זאת במקרים הבאים:
  • היקף הבקשה כלל את המחרוזת "profile"
  • אסימון המזהה מוחזר מרענון אסימון

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

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

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

6. אימות המשתמש

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

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

נושאים מתקדמים

הקטעים הבאים מתארים בפירוט רב יותר את Google OAuth 2.0 API. המידע הזה מיועד למפתחים עם דרישות מתקדמות לגבי אימות והרשאה.

גישה לממשקי API אחרים של Google

אחד מהיתרונות של שימוש ב-OAuth 2.0 לאימות הוא שהאפליקציה שלכם יכולה לקבל הרשאה להשתמש בממשקי API אחרים של Google בשם המשתמש (כמו YouTube, Google Drive, יומן או אנשי קשר) באותו זמן שבו אתם מאמתים את המשתמש. לשם כך, צריך לכלול את היקפי ההרשאות האחרים שנחוצים לבקשת האימות ששולחים ל-Google. לדוגמה, כדי להוסיף את קבוצת הגיל של המשתמש לבקשת האימות, צריך להעביר את הפרמטר של היקף ההרשאות openid email https://www.googleapis.com/auth/profile.agerange.read. המשתמש מתבקש להופיע במסך ההסכמה. אסימון הגישה שקיבלת מ-Google מאפשר לגשת לכל ממשקי ה-API הקשורים להיקפי הגישה שביקשת, והוענקה לך גישה.

רענון האסימונים

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

שיקולים:

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

מידע נוסף זמין במאמר רענון של אסימון גישה (גישה אופליין).

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

מידע נוסף על הפרמטר prompt זמין בטבלה prompt בטבלה פרמטרים של URI לאימות.

פרמטרים של URI לאימות

בטבלה הבאה מפורטים תיאורים מלאים יותר של הפרמטרים שאושרו על ידי Google's API.

פרמטר נדרש תיאור
client_id (נדרש) מחרוזת ה-Client-ID שמקבלים מה- API Console, Credentials page, כפי שמתואר בקבלת פרטי כניסה של OAuth 2.0.
nonce (נדרש) ערך אקראי שנוצר על ידי האפליקציה שלכם ומאפשר הגנה מפני הפעלה מחדש.
response_type (נדרש) אם הערך הוא code, יופעל תהליך של קוד אימות בסיסי, וכדי להגיע לאסימונים האלה יהיה צורך ב-POST לנקודת הקצה של האסימון. אם הערך הוא token id_token או id_token token, מופעל זרימה משתמעת, שדורשת שימוש ב-JavaScript ב-URI ההפניה האוטומטית כדי לאחזר אסימונים ממזהה URI #fragment.
redirect_uri (נדרש) קובע לאן נשלחת התגובה. הערך של הפרמטר הזה צריך להיות תואם בדיוק לאחד מערכי ההפניה האוטומטית שהגדרת ב- API Console Credentials page (כולל סכימת ה-HTTP או ה-HTTPS, ובסוף #39;/' אם יש).
scope (נדרש)

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

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

אם ערך ההיקף של email קיים, אסימון המזהה כולל email ו-email_verified תלונות.

בנוסף להיקפי ההרשאות הספציפיים האלה של OpenID, ארגומנט ההיקף יכול לכלול גם ערכי היקף אחרים. כל ערכי ההיקף חייבים להיות מופרדים ברווחים. לדוגמה, אם רוצים לקבל גישה לכל קובץ ב-Google Drive של משתמש, הפרמטר של ההיקף יכול להיות openid profile email https://www.googleapis.com/auth/drive.file.

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

state (אופציונלי, אבל מומלץ מאוד)

מחרוזת אטומה שמעוגלת בפרוטוקול. כלומר, היא מוחזרת כפרמטר URI בתהליך הבסיסי, ובמזהה ה-URI #fragment בתהליך המשתמע.

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

access_type (אופציונלי) הערכים המותרים הם offline ו-online. ההשפעה מתועדת בגישה אופליין. אם התבקש אסימון גישה, הלקוח לא יקבל אסימון רענון, אלא אם צוין ערך offline.
display (אופציונלי) ערך מחרוזת ASCII לצורך ציון האופן שבו שרת ההרשאות מציג את דפי ממשק המשתמש לאימות ולהסכמה. הערכים הבאים צוינו, ומקובלים על ידי שרתי Google, אבל אין להם השפעה על ההתנהגות שלהם: page, popup, touch וwap.
hd (אופציונלי)

ייעול תהליך ההתחברות בחשבונות שבבעלות ארגון ב-Google Cloud. אפשר לכלול את הדומיין של הארגון של Google Cloud (לדוגמה, mycollege.edu) כדי לציין שממשק המשתמש לבחירת חשבון יותאם לאותו דומיין. כדי לבצע אופטימיזציה לחשבונות ארגוניים של Google Cloud באופן כללי במקום בדומיין אחד של Google Cloud, צריך להגדיר כוכבית (*): hd=*.

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

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

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

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

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

  • consent

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

  • select_account

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

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

אימות אסימון מזהה

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

המצבים הבאים עשויים לגרום לשליחת אסימוני מזהה לשרת:

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

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

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

יש כמה שלבים לאימות אסימון זיהוי:

  1. צריך לוודא שמנפיק המזהה חתום כראוי על ידי המנפיק. האסימונים שהונפקו על ידי Google חתומים באמצעות אחד מהאישורים שנמצאו ב-URI שצוין בערך המטא-נתונים של jwks_uri במסמך ה-Discovery.
  2. יש לאמת שהערך של התלונה iss באסימון המזהה שווה ל-https://accounts.google.com או ל-accounts.google.com.
  3. יש לוודא שהערך של תלונה aud באסימון המזהה זהה למזהה הלקוח של האפליקציה שלך.
  4. יש לוודא שמועד התפוגה (תלונה אחת (exp)) של אסימון המזהה לא עבר.
  5. אם ציינת ערך פרמטר hd בבקשה, צריך לוודא שלאסימון המזהה יש הצהרת hd שתואמת לדומיין קביל המשויך לארגון ב-Google Cloud.

השלבים 2 עד 5 כוללים השוואות של מחרוזות ותאריכים שהם פשוטים למדי, ולכן לא נפרט אותם כאן.

השלב הראשון הוא מורכב יותר, וכולל בדיקות חתימה קריפטוגרפיות. למטרות ניפוי באגים, ניתן להשתמש בנקודת הקצה של tokeninfo ב-Google כדי להשוות בין העיבוד המקומי שהוטמע בשרת או במכשיר. נניח שהערך של אסימון הזיהוי שלך הוא XYZ123. לאחר מכן, יש לציין את ה-URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. אם חתימת האסימון חוקית, התגובה תהיה מטען ייעודי של JWT בצורת אובייקט JSON מפוענח.

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

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

המערכת משיגה את פרטי הפרופיל של המשתמש

כדי לקבל מידע נוסף על המשתמש, אפשר להשתמש באסימון הגישה שהאפליקציה מקבלת (במהלך תהליך האימות) ובתקן OpenID Connect:

  1. כדי לעמוד בדרישות של OpenID, עליך לכלול את ערכי openid profile בבקשת האימות.

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

    scope=openid%20profile%20email
  2. יש להוסיף את אסימון הגישה לכותרת ההרשאה ולשלוח בקשת HTTPS GET לנקודת הקצה (endpoint) של פרטי המשתמש. צריך לאחזר אותה ממסמך ה-Discovery באמצעות ערך המטא-נתונים userinfo_endpoint. תגובת פרטי המשתמש כוללת מידע על המשתמש, כפי שמתואר בדף OpenID Connect Standard Claims ובערך המטא-נתונים של claims_supported במסמך Discovery. משתמשים או ארגונים שלהם יכולים לבחור אם לספק או למנוע שדות מסוימים, כך שייתכן שלא יתקבל מידע לגבי כל שדה עבור היקפי הגישה המורשים שלך.

מסמך הגילוי

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

כדי לפשט את ההטמעה ולהגדיל את הגמישות, OpenID Connect מאפשר להשתמש במסמך "מודעת Discovery,"מסמך JSON שנמצא במיקום ידוע המכיל צמדי מפתח/ערך שמספקים פרטים על התצורה של ספק OpenID Connect, כולל מזהי ה-URI של נקודות הקצה, האסימון, הביטול, פרטי המשתמש ומפתחות ציבוריים. ניתן לאחזר את מסמך Discovery של שירות OpenID Connect של Google מהמקומות הבאים:

https://accounts.google.com/.well-known/openid-configuration

כדי להשתמש בשירותי OpenID Connect של Google, עליך לקודד בתוך הקוד לאפליקציה שלך את ה-URI של מסמך Discovery https://accounts.google.com/.well-known/openid-configuration. האפליקציה מאחזרת את המסמך, מפעילה כללי שמירה במטמון בתגובה ולאחר מכן מאחזרת מזהי URI של נקודת הקצה לפי הצורך. לדוגמה, כדי לאמת משתמש, הקוד יאחזר את ערך המטא-נתונים של authorization_endpoint (https://accounts.google.com/o/oauth2/v2/auth בדוגמה שלמטה) בתור ה-URI הבסיסי של בקשות האימות שנשלחות אל Google.

הנה דוגמה למסמך כזה; שמות השדות הם אלה המפורטים ב-OpenID Connect Discovery 1.0 (יש לעיין במסמך במשמעות שלהם). הערכים הם להמחשה בלבד, ועשויים להשתנות. עם זאת, הם מועתקים מגרסה עדכנית של מסמך Google Discovery בפועל:

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token",
    "none"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "claims_supported": [
    "aud",
    "email",
    "email_verified",
    "exp",
    "family_name",
    "given_name",
    "iat",
    "iss",
    "locale",
    "name",
    "picture",
    "sub"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

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

ספריות לקוח

ספריות הלקוחות הבאות עוזרות להטמיע את OAuth 2.0 בשילוב עם מסגרות פופולריות:

תאימות של OpenID Connect

מערכת האימות OAuth 2.0 של Google תומכת בתכונות הנדרשות במפרט של OpenID Connect Core. כל לקוח שמיועד לפעול עם OpenID Connect צריך לפעול במשותף עם שירות זה (למעט אובייקט בקשת OpenID).