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

בדף הזה מוסבר איך להוסיף תמיכה בממשק ה-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@")
    },
    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.