אימות ל-GDK Glassware

אם GDK Glassware צריך לאמת משתמשים מול שירות אינטרנט, ה-GDK מספק ממשק API שמאפשר למשתמש להזין את פרטי הכניסה שלו כשהוא מתקין את ה-Glassware.

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

יצירת חשבון שירות של Google API

כשהאימות מוגדר בצורה נכונה, הקצה העורפי של אפליקציית האינטרנט משתמש ב-Mirror API כדי לדחוף את פרטי החשבון של המשתמשים ל-Glass אחרי שהם מבצעים אימות באמצעות השירות שלכם.

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

כדי ליצור את החשבון הזה:

  1. עוברים אל Google Developers Console.
  2. לוחצים על הלחצן Create Project ומזינים את המידע הנדרש.
  3. אחרי שיוצרים את הפרויקט, רושמים בצד את Project Number (מספר הפרויקט) שתצטרכו לעשות בהמשך.
  4. בקטע APIs & auth, לוחצים על APIs ומפעילים את Google Mirror API בפרויקט החדש.
  5. בקטע APIs & auth, לוחצים על Credentials ואז על Create New Client ID. מסמנים את התיבה חשבון שירות כדי ליצור מזהה לקוח חדש ב-OAuth 2.0 לפרויקט.
  6. יופיע חלון קופץ עם הודעה על כך שהמפתח הפרטי מתחיל להורדה למחשב, ועם הסיסמה למפתח הפרטי הזה. לאחר סגירת החלון, לא תוכלו להוריד את המפתח הפרטי הזה או לראות שוב את הסיסמה. אם איבדתם את המפתחות, תצטרכו ליצור מפתחות חדשים.
  7. רושמים בצד את כתובת האימייל של חשבון השירות. תצטרכו להשתמש בה מאוחר יותר כדי לשלוח את הקריאה ל-API.

איך מספקים מטא-נתונים על אפליקציות Glassware

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

  • כתובת ה-URL לאימות, שאליה המשתמשים מופנים כשהם מפעילים את אפליקציית Glassware ב-MyGlass.
  • סוג החשבון (המחרוזת שבה תשתמשו כשתקראו לממשקי ה-API של Android‏ AccountManager במכשיר Glass)
  • שם החבילה של האפליקציה מ-AndroidManifest.xml
  • המזהה המספרי של הפרויקט ב-Google API שיצרתם למעלה
  • קובץ ה-APK להעלאה ב-MyGlass. לצורך בדיקה, צריך לספק את קובץ ה-APK הזה רק פעם אחת כדי לטפל בהורדה הראשונית כשאפליקציית Glassware מופעלת מ-MyGlass. לאחר מכן, אפשר לבצע איטרציות ולפתור באגים באופן מקומי על ידי החלפת קובץ ה-APK במכשיר. חשוב לזכור שה-APK צריך לעמוד בקריטריונים הבאים:
    • הוא חייב להיות מיושר ב-zip.
    • לאחר מכן אסור לבצע שינויים בשם החבילה או במפתח החתימה הפרטי (מנהל החבילות של Android לא מאפשר שדרוגים אם מתבצעים שינויים כאלה).
    • הגודל המרבי המותר הוא 50 מגה-בייט.
    • צריך לקמפל אותו באמצעות הגרסה האחרונה של GDK.

הטמעת תהליך האימות

התרשים הבא מציג את תהליך האימות הבסיסי של GDK Glassware:

כדי להטמיע את תהליך האימות:

  1. כשמשתמשים מפעילים את אפליקציית Glassware ב-MyGlass, הם מופנים לכתובת ה-URL לאימות. הבקשות האלה כוללות פרמטר שאילתה בשם userToken שבו תצטרכו להשתמש בהמשך.

  2. המשתמש מזין את פרטי הכניסה שלו בדף האימות.

  3. השרת מאמת את פרטי הכניסה של המשתמש. אם פרטי הכניסה תקינים, מבצעים קריאה ל-Mirror API ל-method‏ mirror.accounts.insert. באמצעות השיטה הזו צריך לציין את ההיקף https://www.googleapis.com/auth/glass.thirdpartyauth כשמפתחים את אובייקט השירות Mirror. דוגמאות ליצירת חשבון כוללות דוגמאות לקריאה ל-API הזו באמצעות HTTP גולמי או Java.

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

    שם הנכס ערך תיאור
    features[] רשימת מחרוזות רשימת התכונות (לפרטים, אפשר לעיין ב- AccountManager.hasFeatures).
    password מחרוזת סיסמת החשבון (ראו AccountManager.getPassword). מומלץ לא לשמור את הסיסמה האמיתית של המשתמש בשדה הזה, אלא להשתמש בה כדי לאחסן נתונים פרטיים לטווח ארוך, כמו אסימון רענון.
    userData[] רשימת אובייקטים לפחות זוג אחד של נתוני משתמש שמשויכים לחשבון (ראו AccountManager.getUserData).
    userData[].key מחרוזת המפתח שמשויך לצמד מפתח/ערך ספציפי של נתוני משתמש.
    userData[].value מחרוזת הערך שמשויך לצמד מפתח/ערך של נתוני משתמש ספציפי.
    authTokens[] רשימת אובייקטים אסימוני אימות אחד או יותר שמשויכים לחשבון (ראו AccountManager.getAuthToken).
    authTokens[].type מחרוזת הסוג של אסימון האימות.
    authTokens[].authToken מחרוזת טוקן האימות.

  4. לאחר קבלת הבקשה mirror.account.insert, Mirror API דוחף את החשבון למכשירי Glass של המשתמש, שם תוכלו לגשת אליו באמצעות המחלקה AccountManager.

כדי להטמיע תהליך אימות ידידותי למשתמש, יש לפעול לפי ההנחיות הבאות:

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

כדי לשמור על עקביות באימות של Glassware, צריך להשתמש באחד מתהליכי האימות הבאים:

שיקוף או היברידי ללא חשבון

  1. אחרי שמפעילים את MyGlass, כתובת ה-URL לאימות תיפתח בחלון קופץ.
  2. הפעולה הזו תשלח את המשתמש ישירות להיקפי ההרשאות כדי לאשר אותן.
  3. אחרי שהמשתמש מאשר או מבטל את ההיקפים, סוגרים את החלון הקופץ.

שיקוף באמצעות חשבון

  1. אחרי שמפעילים את האפשרות ב-MyGlass, כתובת ה-URL לאימות נפתחת בחלון קופץ.
    • אם המשתמש כבר מחוברים לשירות, שולחים אותו ישירות להיקפי הגישה.
    • אם המשתמש לא מחובר לחשבון, מציגים את שדות הכניסה, מאפשרים לו להיכנס לחשבון בשירות ואז שולחים אותו להיקפי הרשאות הגישה.
    • אם למשתמש אין חשבון, מספקים קישור ליצירת חשבון. המשתמשים צריכים שתהיה להם אפשרות ליצור חשבון כחלק מתהליך ההתקנה.
  2. המשתמש מקבל היקפים.
    • אם ל-Glassware יש הגדרות שניתנות להגדרה, שולחים את המשתמש לדף ההגדרות עם ברירות מחדל סבירות שנבחרו.
    • אם ל-Glassware אין הגדרות שניתן לשנות, שולחים את המשתמש לדף אישור. סוגרים את החלון הקופץ אם לא נדרשות הגדרות נוספות.

היברידי עם חשבון

  1. אחרי שמפעילים את האפשרות ב-MyGlass, כתובת ה-URL לאימות נפתחת בחלון קופץ.
    • אם המשתמש כבר מחובר לשירות, צריך להעביר אותו ישירות להיקפי ההרשאות.
    • אם המשתמש לא מחובר לחשבון, מציגים את שדות הכניסה, מאפשרים לו להיכנס ואז שולחים אותם להיקפי ההרשאות.
    • אם למשתמש אין חשבון, מספקים קישור ליצירת חשבון.
  2. המשתמש מאשר את ההיקפים.
  3. שולחים בקשה ל-Mirror API כדי להוסיף את חשבון GDK.
    • שולחים את המשתמש לדף ההגדרות עם הגדרות ברירת מחדל סבירות שנבחרו.
    • שולחים למשתמש דף אישור. סוגרים את החלון הקופץ אם לא נדרשת הגדרה נוספת.

שיקוף או שילוב עם חשבון והיקפים מותאמים אישית

  1. אחרי שמפעילים את MyGlass, כתובת ה-URL לאימות תיפתח בחלון קופץ.
    • אם המשתמש כבר נכנס לחשבון בשירות, שולחים אותו להיקפי הגישה הפנימיים
    • אם המשתמש לא מחובר לחשבון, מציגים את שדות הכניסה, מאפשרים לו להיכנס ואז שולחים אותו להיקפי הרשאה פנימיים
    • אם למשתמש אין חשבון, צריך לספק קישור כדי ליצור חשבון.
  2. כשהמשתמש מאשר את ההיקפים המותאמים אישית, שולחים אותו להיקפים של Google.
  3. שולחים בקשה ל-Mirror API כדי להוסיף את חשבון ה-GDK.
    • שולחים את המשתמש לדף ההגדרות עם הגדרות ברירת מחדל סבירות שנבחרו.
    • שולחים למשתמש דף אישור. סוגרים את החלון הקופץ אם לא נדרשות הגדרות נוספות.

שיקוף או שילוב עם אפליקציה ל-Android או ל-iPhone

  1. אחרי שמפעילים את האפשרות ב-MyGlass, כתובת ה-URL לאימות נפתחת בחלון קופץ.
  2. הפעולה הזו שולחת את המשתמש ישירות להיקפי הגישה שצריך לאשר.
  3. אחרי שהמשתמש מאשר את ההיקפים:
    • אם המשתמש התקין את האפליקציה הנלווית והוא מאומת, סוגרים את החלון הקופץ.
    • אם לא, שלחו את המשתמש למודעת מעברון שתפנה אותו להוריד את האפליקציה מחנות Google Play או מחנות iOS
  4. אחרי התקנת האפליקציה והאימות, סוגרים את החלון הקופץ.

GDK ואין חשבון

כדי לבצע את התהליך הזה, צריך רק להפעיל את Glassware ב-MyGlass.

GDK עם חשבון

  1. אחרי שמפעילים את האפשרות ב-MyGlass, כתובת ה-URL לאימות נפתחת בחלון קופץ.
    • אם המשתמש כבר נכנס לשירות, שולחים אותו למסך האישור.
    • אם המשתמש לא מחובר לחשבון, מציגים את שדות הכניסה, מאפשרים לו להיכנס לחשבון ואז שולחים אותו למסך האישור.
    • אם למשתמש אין חשבון, מספקים קישור ליצירת חשבון.
  2. המשתמש מאשר את ההיקפים.
  3. שולחים בקשה ל-Mirror API כדי להוסיף את חשבון ה-GDK.
  4. להציג את מסך האישור ולסגור את המסך אחרי שהוא מוצג למשך זמן קצר.

דוגמאות ליצירת חשבון

כשהדבר אפשרי, כדאי להשתמש בספריות הלקוח של Mirror API. כך קל יותר להתקשר למספר mirror.accounts.insert כדי ליצור את החשבון.

דוגמה ל-HTTP גולמי

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

שיטת הבקשה וכתובת ה-URL:

POST https://www.googleapis.com/mirror/v1/accounts/{userToken}/com.example.myapp/username%40email.com

גוף הבקשה:

{
    "features": ["a", "b", "c"],
    "userData": [
        { "key": "realName", "value": "Rusty Shackleford" },
        { "key": "foo", "value": "bar" }
    ],
    "authTokens": [
        { "type": "your_token_type", "authToken": "zT419Ma3X2pBr0L..." }
    ]
}

מחליפים את {userToken} בכתובת ה-URL של הבקשה באסימון שהוענק לכתובת ה-URL לאימות בשלב 1 של הטמעת תהליך האימות.

דוגמה ל-Java

בדוגמה הזו מוצג איך להשתמש בספריית הלקוח של Java כדי לבצע קריאה ל-mirror.accounts.insert

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;
import com.google.api.services.mirror.Mirror;
import com.google.api.services.mirror.model.Account;
import com.google.api.services.mirror.model.AuthToken;
import com.google.common.collect.Lists;
...

/** Email of the Service Account */
private static final String SERVICE_ACCOUNT_EMAIL =
    "<some-id>@developer.gserviceaccount.com";

/** Path to the Service Account's Private Key file */
private static final String SERVICE_ACCOUNT_PKCS12_FILE_PATH =
    "/path/to/<public_key_fingerprint>-privatekey.p12";

/** The account type, usually based on your company or app's package. */
private static final String ACCOUNT_TYPE = "com.example.myapp";

/** The Mirror API scopes needed to access the API. */
private static final String MIRROR_ACCOUNT_SCOPES =
    "https://www.googleapis.com/auth/glass.thirdpartyauth";

/**
 * Build and returns a Mirror service object authorized with the service accounts.
 *
 * @return Mirror service object that is ready to make requests.
 */
public static Mirror getMirrorService() throws GeneralSecurityException,
    IOException, URISyntaxException {
  HttpTransport httpTransport = new NetHttpTransport();
  JacksonFactory jsonFactory = new JacksonFactory();
  GoogleCredential credential = new GoogleCredential.Builder()
      .setTransport(httpTransport)
      .setJsonFactory(jsonFactory)
      .setServiceAccountId(SERVICE_ACCOUNT_EMAIL)
      .setServiceAccountScopes(MIRROR_ACCOUNT_SCOPES)
      .setServiceAccountPrivateKeyFromP12File(
          new java.io.File(SERVICE_ACCOUNT_PKCS12_FILE_PATH))
      .build();
  Mirror service = new Mirror.Builder(httpTransport, jsonFactory, null)
      .setHttpRequestInitializer(credential).build();
  return service;
}

/**
 * Creates an account and causes it to be synced up with the user's Glass.
 * This example only supports one auth token; modify it if you need to add
 * more than one, or to add features, user data, or the password field.
 *
 * @param mirror the service returned by getMirrorService()
 * @param userToken the user token sent to your auth callback URL
 * @param accountName the account name for this particular user
 * @param authTokenType the type of the auth token (chosen by you)
 * @param authToken the auth token
 */
public static void createAccount(Mirror mirror, String userToken, String accountName,
    String authTokenType, String authToken) {
  try {
    Account account = new Account();
    List<AuthToken> authTokens = Lists.newArrayList(
        new AuthToken().setType(authTokenType).setAuthToken(authToken));
    account.setAuthTokens(authTokens);
    mirror.accounts().insert(
        userToken, ACCOUNT_TYPE, accountName, account).execute();
  } catch (IOException e) {
    e.printStackTrace();
  }
}

אחזור חשבונות ב-Glass

אחזור של אובייקטים מסוג Account ב-Glass ושימוש בהם דומים לשימוש באפליקציית AccountManager הרגילה ל-Android.

  1. מגדירים את הרשאות המניפסט הבאות בקובץ AndroidManifest.xml:

    <uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.USE_CREDENTIALS" />

  2. מאחזרים את החשבונות של Glassware:

    AccountManager accountManager = AccountManager.get(mContext);
// Use your Glassware's account type.
Account[] accounts = accountManager.getAccountsByType("com.example");

// Pick an account from the list of returned accounts.

  3. אחזור טוקן אימות מה-Account:

    // Your auth token type.
final String AUTH_TOKEN_TYPE = "oauth2:https://www.example.com/auth/login";

accountManager.getAuthToken(account, AUTH_TOKEN_TYPE, null, activity, new AccountManagerCallback<Bundle>() {
    public void run(AccountManagerFuture<Bundle> future) {
        try {
            String token = future.getResult().getString(AccountManager.KEY_AUTHTOKEN);
            // Use the token.
        } catch (Exception e) {
            // Handle exception.
        }
    }
}, null);