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

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

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

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

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

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

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

הגדרת URI של הפניה

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

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

1. Go to the Clients page.
2. לוחצים על הלקוח.
3. צפייה ב-URI של ההפניה או עריכה שלו.

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

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

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

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

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

1. פותחים את Branding page ב- Google Cloud Console.
2. If prompted, select a project, or create a new one.
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.

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

חשוב לוודא שהגדרתם את האפליקציה ב- Cloud Console כדי לאפשר לה להשתמש בפרוטוקולים האלה ולאמת את המשתמשים שלכם. כשמשתמש מנסה להיכנס לחשבון באמצעות 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 הבסיסית ממסמך הגילוי באמצעות ערך המטא-נתונים authorization_endpoint. בדיון הבא נניח שכתובת ה-URI הבסיסית היא https://accounts.google.com/o/oauth2/v2/auth.

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

• ‫client_id, שאפשר לקבל מ- Cloud Console Clients page .
• ‫response_type, שבבקשה בסיסית להרשאה באמצעות קוד צריך להיות code. (מידע נוסף זמין בכתובת response_type).
• ‫scope, שבבקשה בסיסית צריך להיות openid email. (מידע נוסף זמין בכתובת scope).
• ‫redirect_uri צריכה להיות נקודת הקצה של HTTP בשרת שלכם שתקבל את התגובה מ-Google. הערך חייב להיות זהה לאחת מכתובות ה-URI המורשות להפניה אוטומטית של לקוח OAuth 2.0, שהגדרתם ב Cloud Console Credentials page. אם הערך הזה לא תואם ל-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//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:

// 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 נשלחת לנקודת הקצה של האסימון, שאותה צריך לאחזר ממסמך הגילוי באמצעות ערך המטא-נתונים 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//oauth2.example.com/code&
grant_type=authorization_code

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

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

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

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

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

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

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

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

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

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

אחד היתרונות של שימוש ב-OAuth 2.0 לאימות הוא שהאפליקציה יכולה לקבל הרשאה להשתמש בממשקי API אחרים של Google בשם המשתמש (כמו YouTube,‏ Google Drive,‏ Calendar או אנשי קשר) בו-זמנית עם אימות המשתמש. כדי לעשות את זה, צריך לכלול את ההיקפים האחרים שנדרשים בבקשת האימות ששולחים ל-Google. לדוגמה, כדי להוסיף את קבוצת הגיל של המשתמש לבקשת האימות, צריך להעביר פרמטר scope של 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. מוודאים שאסימון ה-ID חתום בצורה תקינה על ידי המנפיק. אסימונים שהונפקו על ידי Google חתומים באמצעות אחד מהאישורים שנמצאים בכתובת ה-URI שצוינה בערך המטא-נתונים jwks_uri של מסמך הגילוי.
2. מוודאים שהערך של הטענה iss בטוקן המזהה שווה ל-https://accounts.google.com או ל-accounts.google.com.
3. מוודאים שהערך של התביעה aud בטוקן המזהה שווה למזהה הלקוח של האפליקציה.
4. מוודאים שתוקף טוקן ה-ID (התביעה exp) לא פג.
5. אם ציינתם ערך של פרמטר hd בבקשה, צריך לוודא שלטוקן ה-ID יש טענה hd שתואמת לדומיין מקובל שמשויך לארגון ב-Google Cloud.

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

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

נקודת הקצה tokeninfo שימושית לניפוי באגים, אבל למטרות ייצור, צריך לאחזר את המפתחות הציבוריים של Google מנקודת הקצה של המפתחות ולבצע את האימות באופן מקומי. צריך לאחזר את כתובת ה-URI של המפתחות ממסמך הגילוי באמצעות ערך המטא-נתונים 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. את נקודת הקצה הזו צריך לאחזר ממסמך הגילוי באמצעות ערך המטא-נתונים userinfo_endpoint. התגובה userinfo כוללת מידע על המשתמש, כפי שמתואר בOpenID Connect Standard Claims ובערך המטא-נתונים claims_supported של מסמך הגילוי. משתמשים או הארגונים שלהם יכולים לבחור אם לספק מידע בשדות מסוימים או לא, ולכן יכול להיות שלא תקבלו מידע בכל השדות בהיקפי הגישה המורשים שלכם.

מסמך ה-Discovery

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

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