גוגל מחויבת לקידום הון גזעי לקהילות שחורות. תראה איך.
דף זה תורגם על ידי Cloud Translation API.
Switch to English

OpenID Connect

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

השג אישורי OAuth 2.0

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

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

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

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

הגדר URI להפניה מחדש

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

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

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

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

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

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

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

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

גישה לשירות

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

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

אימות המשתמש

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

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

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

זרימת שרתים

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

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

1. צור אסימון נגד זיוף

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

ג'אווה

עליך להוריד את ספריית הלקוחות של ממשקי ה- API של Google כדי להשתמש ב- 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);

פִּיתוֹן

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

השלב הבא הוא יצירת בקשת 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 בסיסית צריך להיות openid email . (קרא עוד scope .)
  • redirect_uri אמורה להיות נקודת הקצה HTTP בשרת שלך שתקבל את התגובה מגוגל. הערך חייב להתאים במדויק לאחד מ- URI המפנים להפניה מחדש עבור לקוח OAuth 2.0, שהגדרת ב API Console Credentials page. אם ערך זה אינו תואם URI מורשה, הבקשה תיכשל עם שגיאת redirect_uri_mismatch .
  • state צריכה לכלול את הערך של אסימון ההפעלה הייחודי למניעת זיוף, כמו גם כל מידע אחר הדרוש לשחזור ההקשר כאשר המשתמש חוזר ליישום שלך, למשל, כתובת האתר ההתחלתית. (קרא עוד state .)
  • nonce הוא ערך אקראי שנוצר על ידי האפליקציה שלך ומאפשר הגנה על הפעלה חוזרת כשהוא קיים.
  • login_hint יכול להיות כתובת הדוא"ל של המשתמש או מחרוזת sub , המקבילה לזהות המשתמש של Google. אם אינך מספק login_hint והמשתמש מחובר כעת, מסך ההסכמה כולל בקשה לאישור לשחרור כתובת הדוא"ל של המשתמש לאפליקציה שלך. (קרא עוד ב- login_hint .)
  • השתמש בפרמטר hd כדי לייעל את זרימת OpenID Connect למשתמשים בתחום G Suite מסוים. (קרא עוד ב- 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);
}

ג'אווה

עליך להוריד את ספריית הלקוחות של 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.");
}

פִּיתוֹן

עליך להוריד את ספריית הלקוחות של 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 , קוד הרשאה חד פעמי שהשרת שלך יכול להחליף עבור אסימון גישה ואסימון מזהה. השרת שלך מבצע את ההחלפה על ידי שליחת בקשת HTTPS POST . בקשת ה- POST נשלחת לנקודת הקצה של האסימון, אותה עליך לאחזר ממסמך Discovery באמצעות ערך המטא נתונים של token_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 אסימון שניתן לשלוח ל- API של גוגל.
expires_in משך החיים שנותר של אסימון הגישה בשניות.
id_token JWT המכיל מידע זהות אודות המשתמש החתום דיגיטלית על ידי גוגל.
scope היקפי הגישה המוענקים על ידי ה- access_token מבוטאים כרשימה של מחרוזות תוחמות-שטח, access_token רישיות.
token_type מזהה את סוג האסימון שהוחזר. בשלב זה, השדה הזה תמיד יש את הערך Bearer .
refresh_token (אופציונאלי)

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

5. השג פרטי משתמש מסימן הזיהוי

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

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

מטען של אסימון תעודת זהות

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

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

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

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

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

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

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

6. אמת את המשתמש

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

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

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

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

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

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

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

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

שיקולים:

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

למידע נוסף, ראה רענון אסימון גישה (גישה לא מקוונת) .

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

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

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

הטבלה הבאה מציגה תיאורים מלאים יותר של הפרמטרים המקובלים ב- API לאימות OAuth 2.0 של גוגל.

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

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

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

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

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

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

state (אופציונלי, אך מומלץ בחום)

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

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

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

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

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

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

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

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

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

  • consent

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

  • select_account

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

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

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

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

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

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

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

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

אימות של אסימון מזהה דורש מספר שלבים:

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

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

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

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

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

השגת מידע על פרופיל משתמש

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

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

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

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

מסמך Discovery

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

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

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

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

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