OpenID Connect

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

הגדרת OAuth 2.0

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

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

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

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

אפשר גם לראות את מזהה הלקוח ואת הסוד של הלקוח בדף Clients ב-Cloud Console:

1. עוברים אל דף הלקוחות.
2. לוחצים על שם הלקוח או על סמל העריכה (create). מזהה הלקוח והסוד שלו מופיעים בחלק העליון של הדף.

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

ה-URI של ההפניה האוטומטית שמוגדר ב-Cloud Console קובע לאן Google שולחת תגובות לבקשות האימות שלכם.

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

1. עוברים אל דף הלקוחות.
2. לוחצים על הלקוח.
3. צפייה ב-URI של ההפניה או עריכה שלו.

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

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

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

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

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

1. פותחים את הדף Branding במסוף Google Cloud.
2. אם מתבקשים, בוחרים פרויקט או יוצרים פרויקט חדש.
3. ממלאים את הטופס ולוחצים על שמירה.

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

גישה לשירות

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

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

אימות המשתמש

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

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

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

תהליך העבודה של השרת

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

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

1. יצירת טוקן למניעת זיוף

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

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

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

// 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
));

// 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);

# 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, שאפשר לקבל מתוך Cloud Console דף הלקוחות .
• ‫response_type, שבבקשה בסיסית להרשאה באמצעות קוד צריך להיות code. (מידע נוסף זמין בכתובת response_type).
• ‫scope, שבבקשה בסיסית צריך להיות openid email. (מידע נוסף זמין בכתובת scope).
• ‫redirect_uri צריכה להיות נקודת הקצה של HTTP בשרת שלכם שתקבל את התגובה מ-Google. הערך חייב להיות זהה לאחד מכתובות ה-URI המורשות להפניה אוטומטית של לקוח OAuth 2.0, שהגדרתם בדף 'אמצעי אימות' במסוף Cloud. אם הערך הזה לא תואם ל-URI מורשה, הבקשה תיכשל ותוצג השגיאה redirect_uri_mismatch.
• state צריך לכלול את הערך של טוקן הסשן הייחודי למניעת זיוף, וגם כל מידע אחר שנדרש לשחזור ההקשר כשהמשתמש חוזר לאפליקציה, למשל כתובת ה-URL של ההתחלה. (מידע נוסף זמין בכתובת state).
• ‫nonce הוא ערך אקראי שנוצר על ידי האפליקציה ומאפשר הגנה מפני שידור חוזר, אם הוא קיים.
• login_hint יכול להיות כתובת האימייל של המשתמש או המחרוזת sub, ששווה למזהה Google של המשתמש. אם לא מספקים login_hint והמשתמש מחובר לחשבון, במסך ההסכמה מוצגת בקשה לאישור שחרור כתובת האימייל של המשתמש לאפליקציה. (מידע נוסף זמין במאמר login_hint).
• משתמשים בפרמטר hd כדי לבצע אופטימיזציה של תהליך OpenID Connect למשתמשים בדומיין מסוים שמשויך לארגון Google Workspace או 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//developers.google.com/oauthplayground&
 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://developers.google.com/oauthplayground?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

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

הקוד הבא מדגים איך מאשרים את טוקני הסשן שיצרתם בשלב 1:

// 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);
}

// 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.");
}

# 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, קוד הרשאה חד-פעמי שהשרת יכול להמיר לטוקן גישה ולטוקן מזהה. השרת שלכם מבצע את ההחלפה הזו על ידי שליחת בקשת HTTPS‏ POST. בקשת POST נשלחת לנקודת הקצה של האסימון, שאותה צריך לאחזר ממסמך Discovery באמצעות ערך המטא-נתונים token_endpoint. בדיון הבא אנחנו מניחים שנקודת הקצה היא https://oauth2.googleapis.com/token. הבקשה חייבת לכלול את הפרמטרים הבאים בגוף POST:

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

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//developers.google.com/oauthplayground&
grant_type=authorization_code

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

5. קבלת מידע על המשתמש מאסימון המזהה

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

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

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

טוקן ID הוא אובייקט 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 עשויים להכיל את השדות הבאים (שנקראים claims):

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

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

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

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

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

גישה ל-Google APIs אחרים

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

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

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

שיקולים:

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

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

בקשת הסכמה מחדש

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

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

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

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

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

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

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

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

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

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

כדי לאמת אסימון מזהה, צריך לבצע כמה שלבים:

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

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

השלב הראשון מורכב יותר וכולל בדיקה של חתימה קריפטוגרפית. למטרות ניפוי באגים, אפשר להשתמש בנקודת הקצה tokeninfo של Google כדי להשוות לעיבוד מקומי שהוטמע בשרת או במכשיר. נניח שהערך של אסימון המזהה הוא XYZ123. אחר כך מבטלים את ההפניה של ה-URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. אם החתימה של הטוקן תקינה, התגובה תהיה המטען הייעודי (payload) של ה-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 לנקודת הקצה userinfo, שאותה צריך לאחזר ממסמך Discovery באמצעות ערך המטא-נתונים userinfo_endpoint. התגובה של userinfo כוללת מידע על המשתמש, כפי שמתואר בOpenID Connect Standard Claims ובערך המטא-נתונים claims_supported של מסמך Discovery. משתמשים או הארגונים שלהם יכולים לבחור אם לספק שדות מסוימים או לא, ולכן יכול להיות שלא תקבלו מידע לגבי כל שדה בהיקפי הגישה המורשים שלכם.

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

{
  "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 round-trip על ידי שמירת הערכים במטמון ממסמך Discovery. נעשה שימוש בכותרות סטנדרטיות של HTTP לצורך שמירה במטמון, וצריך להתייחס אליהן.

ספריות לקוח

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

• Google APIs Client Library for Java
• ספריית הלקוח של Google APIs ל-Python
• ספריית הלקוח של Google APIs ל-‎ .NET
• ספריית הלקוח של Google APIs ל-Ruby
• ספריית הלקוח של Google APIs ל-PHP
• ספריית OAuth 2.0 ל-Google Web Toolkit
• Google Toolbox for Mac OAuth 2.0 Controllers

תאימות ל-OpenID Connect

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