‫Users API לחבילות שירותים מדור קודם

מזהה אזור

‫REGION_ID הוא קוד מקוצר ש-Google מקצה על סמך האזור שבוחרים כשיוצרים את האפליקציה. הקוד לא תואם למדינה או למחוז, למרות שחלק ממזהי האזורים עשויים להיראות דומים לקודים נפוצים של מדינות ומחוזות. באפליקציות שנוצרו אחרי פברואר 2020, REGION_ID.r נכלל בכתובות URL של App Engine. באפליקציות קיימות שנוצרו לפני התאריך הזה, מזהה האזור הוא אופציונלי בכתובת ה-URL.

מידע נוסף על מזהי אזורים

אישור

Go Java PHP Python

ממשק ה-API של המשתמשים מאפשר לאפליקציה:

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

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

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

אימות משתמשים

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

אפשר לבדוק אם המשתמש מחובר ולקבל את כתובת האימייל שלו באמצעות servlet API רגיל, עם השיטה getUserPrincipal() של אובייקט הבקשה. אתם יכולים להשתמש ב-User service API כדי ליצור כתובות URL לכניסה ויציאה.

package com.example.appengine.users;

import com.google.appengine.api.users.UserService;
import com.google.appengine.api.users.UserServiceFactory;
import java.io.IOException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

// With @WebServlet annotation the webapp/WEB-INF/web.xml is no longer required.
@WebServlet(
    name = "UserAPI",
    description = "UserAPI: Login / Logout with UserService",
    urlPatterns = "/userapi"
)
public class UsersServlet extends HttpServlet {

  @Override
  public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    UserService userService = UserServiceFactory.getUserService();

    String thisUrl = req.getRequestURI();

    resp.setContentType("text/html");
    if (req.getUserPrincipal() != null) {
      resp.getWriter()
          .println(
              "<p>Hello, "
                  + req.getUserPrincipal().getName()
                  + "!  You can <a href=\""
                  + userService.createLogoutURL(thisUrl)
                  + "\">sign out</a>.</p>");
    } else {
      resp.getWriter()
          .println(
              "<p>Please <a href=\"" + userService.createLoginURL(thisUrl) + "\">sign in</a>.</p>");
    }
  }
}

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

אכיפת כניסה וגישת אדמין באמצעות web.xml

אם יש לכם דפים שהמשתמש לא אמור להיות מסוגל לגשת אליהם אלא אם הוא מחובר לחשבון, אתם יכולים להגדיר אילוצי אבטחה לדפים האלה בקובץ התיאור של הפריסה (קובץ web.xml). אם משתמש ניגש לכתובת URL עם הגבלת אבטחה והוא לא מחובר, App Engine מפנה אותו באופן אוטומטי לדף הכניסה (לאימות של חשבונות Google או Google Workspace), ואז מפנה אותו בחזרה לכתובת ה-URL אחרי שהוא נכנס או נרשם בהצלחה.

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

כדי ללמוד איך מגדירים אילוצי אבטחה לכתובות URL, אפשר לעיין במאמר The Deployment Descriptor: Security and Authentication (מתאר הפריסה: אבטחה ואימות) של web.xml.

אפשרויות אימות

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

• חשבון Google.
• חשבון בדומיין שלכם ב-Google Workspace

בחירת אפשרות אימות

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

כניסה לחשבון ויציאה ממנו

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

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

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

ה-Users API כולל שיטה ליצירת כתובת URL ליציאה מהאפליקציה. כתובת ה-URL ליציאה מבטלת את האימות של המשתמש באפליקציה, ואז מפנה אותו חזרה לכתובת ה-URL של האפליקציה בלי להציג דבר.

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

גישה לפרטי החשבון

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

האפליקציה יכולה גם לקבוע אם המשתמש הנוכחי הוא אדמין באפליקציה. משתמש אדמין הוא כל משתמש שיש לו תפקיד של צפייה, עריכה, בעלים או אדמין ב-App Engine. אתם יכולים להשתמש בתכונה הזו כדי ליצור תכונות ניהול לאפליקציה, גם אם אתם לא מאמתים משתמשים אחרים. ממשקי ה-API של Go, ‏ Java, ‏ PHP ו-Python מאפשרים להגדיר כתובות URL כ'למנהלים בלבד'.

הערה: לכל משתמש יש את אותו מזהה משתמש בכל האפליקציות של App Engine. אם האפליקציה שלכם משתמשת במזהה המשתמש בנתונים ציבוריים, למשל על ידי הכללתו בפרמטר של כתובת URL, אתם צריכים להשתמש באלגוריתם גיבוב עם ערך 'מלח' שנוסף כדי להסתיר את המזהה. חשיפה של מזהים גולמיים עלולה לאפשר למישהו לשייך את הפעילות של משתמש באפליקציה אחת לפעילות שלו באפליקציה אחרת, או לקבל את כתובת האימייל של המשתמש על ידי אילוץ המשתמש להיכנס לאפליקציה אחרת.

משתמשים ו-Datastore

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

חשבונות Google ושרת הפיתוח

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

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

באופן דומה, Users API מחזיר כתובת URL ליציאה שמבטלת את הכניסה המזויפת.