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

בדף הזה מוסבר איך להוסיף תמיכה בממשק ה-API שלכם לאימות משתמשים מאפליקציות לקוח באמצעות Cloud Endpoints Frameworks. שימו לב: כרגע יש תמיכה בלקוחות Android ו-JavaScript.

‫Endpoints Frameworks תומך באימות משתמשים מאפליקציות לקוח שמשתמשות באחת מהמתודולוגיות הבאות:

לא משנה באיזו שיטת אימות משתמשים תשתמשו, בכל שיטת API שבה תרצו לבדוק אם האימות תקין, תצטרכו לבדוק אם יש User תקף, כמו שמתואר בקטעים הבאים:

דרישות מוקדמות

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

אימות באמצעות Firebase Auth

כדי לתמוך בשיחות מלקוחות שמשתמשים ב-Firebase Auth:

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

  2. מוסיפים את הערכים הבאים ל-@Api או להערת השיטה:

    • מוסיפים פרמטר authenticators להערה, ומגדירים אותו לערך {EspAuthenticator.class}.
    • מוסיפים פרמטר issuers שמכיל @ApiIssuer שמוגדר ל-Firebase.
    • מוסיפים פרמטר issuerAudiences שמכיל @ApiIssuerAudience, ומגדירים אותו ל-Firebase ולמזהה הפרויקט.

    לדוגמה:

    @Api(
    name = "YOUR_API_NAME",
    version = "VERSION_NUMBER",
    authenticators = {EspAuthenticator.class},
    issuers = {
        @ApiIssuer(
            name = "firebase",
            issuer = "https://securetoken.google.com/YOUR_PROJECT_ID",
            jwksUri = "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com")
    },
    issuerAudiences = {
        @ApiIssuerAudience(name = "firebase", audiences = "YOUR_PROJECT_ID")
    })
    • מחליפים את YOUR_API_NAME בשם ה-API.
    • מחליפים את VERSION_NUMBER בגרסת ה-API, לדוגמה, v1.
    • מחליפים את שני המופעים של YOUR_PROJECT_ID במזהה הפרויקט ב-Firebase.

  3. בקוד ההטמעה של ה-API, מייבאים את Users:

    import com.google.api.server.spi.auth.common.User;

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

    @ApiMethod(httpMethod = ApiMethod.HttpMethod.GET)
public Email getUserEmail(User user) throws UnauthorizedException {
  if (user == null) {
    throw new UnauthorizedException("Invalid credentials");
  }

  Email response = new Email();
  response.setEmail(user.getEmail());
  return response;
}

  5. פורסים מחדש את ה-API בכל פעם שמוסיפים לקוחות חדשים.

הוספת אימות ב-Firebase ללקוח

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

אימות באמצעות Auth0

כדי לתמוך בשיחות מלקוחות שמשתמשים ב-Auth0:

  1. מוסיפים את הערכים הבאים ל-@Api או להערת השיטה:

    • מוסיפים פרמטר authenticators להערה, ומגדירים אותו לערך {EspAuthenticator.class}.
    • מוסיפים פרמטר issuers שמכיל @ApiIssuer שהערך שלו הוא Auth0.
    • מוסיפים פרמטר issuerAudiences שמכיל @ApiIssuerAudience, ומגדירים אותו ל-Auth0 ואת מזהה הלקוח שלכם ב-Auth0.

    לדוגמה:

    @Api(
    name = "YOUR_API_NAME",
    version = "VERSION_NUMBER",
    authenticators = {EspAuthenticator.class},
    issuers = {
        @ApiIssuer(
            name = "auth0",
            issuer = "https://YOUR_ACCOUNT_NAME.auth0.com/",
            jwksUri = "https://YOUR_ACCOUNT_NAME.auth0.com/.well-known/jwks.json")
     },
     issuerAudiences = {
         @ApiIssuerAudience(name = "auth0", audiences = "AUTH0_CLIENT_ID")
    })
    • מחליפים את YOUR_API_NAME בשם ה-API.
    • מחליפים את VERSION_NUMBER בגרסת ה-API, לדוגמה, v1.
    • מחליפים את YOUR_ACCOUNT_NAME בשם של חשבון Auth0 שמשמש את הלקוח.
    • מחליפים את AUTH0_CLIENT_ID במזהה שרוצים להשתמש בו עבור הלקוח.

  2. בקוד ההטמעה של ה-API, מייבאים את Users:

    import com.google.api.server.spi.auth.common.User;

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

    @ApiMethod(httpMethod = ApiMethod.HttpMethod.GET)
public Email getUserEmail(User user) throws UnauthorizedException {
  if (user == null) {
    throw new UnauthorizedException("Invalid credentials");
  }

  Email response = new Email();
  response.setEmail(user.getEmail());
  return response;
}

  4. פורסים מחדש את ה-API בכל פעם שמוסיפים לקוחות חדשים.

הוספת אימות Auth0 ללקוח

אפשר להוסיף אימות של Auth0 לקוד שלכם כמו שמתואר במסמכי התיעוד של Auth0. הלקוח צריך להיות רשום בהגדרות של מנפיק Auth0 של ה-API.

אימות באמצעות אסימונים מזהים של Google

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

  1. מקבלים מזהה לקוח של OAuth 2 לכל אפליקציית לקוח. בעל אפליקציית הלקוח צריך ליצור את מזהה הלקוח במסוף Google Cloud . הוראות מפורטות זמינות במאמר יצירת מזהי לקוח.

  2. מוסיפים רשומה של clientIds עם מזהה הלקוח לכל אפליקציית לקוח שרוצים להעניק לה גישה, וגם רשומה של audiences לכל לקוח Android, בהערת @Api.

    לדוגמה:

    @Api(
   name = "YOUR_API_NAME",
   version = "VERSION_NUMBER",
   clientIds = {"YOUR_CLIENT_ID"},
   audiences = {"YOUR_CLIENT_ID"}
)
    • מחליפים את YOUR_API_NAME בשם ה-API.
    • מחליפים את VERSION_NUMBER בגרסת ה-API, לדוגמה, v1.
    • מחליפים את YOUR_CLIENT_ID במזהה הלקוח ב-OAuth 2 שנוצר בפרויקט של אפליקציית הלקוח.

  3. בקוד ההטמעה של ה-API, מייבאים את Users:

    import com.google.api.server.spi.auth.common.User;

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

    @ApiMethod(httpMethod = ApiMethod.HttpMethod.GET)
public Email getUserEmail(User user) throws UnauthorizedException {
  if (user == null) {
    throw new UnauthorizedException("Invalid credentials");
  }

  Email response = new Email();
  response.setEmail(user.getEmail());
  return response;
}

  5. פורסים מחדש את ה-API בכל פעם שמוסיפים לקוחות חדשים.

הוספת אימות של אסימוני Google ID ללקוח

מידע על הוספת קוד אימות ללקוחות מופיע במאמרים הבאים:

שליחת JWT בלקוח

אם אתם משתמשים ב-JWT בלקוח כדי לשלוח בקשות מאומתות ל-API, ה-JWT צריך להיות בכותרת ההרשאה של בקשת HTTP. ל-JWT צריכים להיות הפרטים הנדרשים הבאים:

  • iss
  • sub
  • aud
  • iat
  • exp

המאמרים הבאים

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