Authentifizierung für GDK-Glassware

Wenn Ihre GDK-Glassware für einen Webdienst authentifiziert werden muss, bietet das GDK eine API, mit der Nutzer ihre Anmeldedaten bei der Installation Ihrer Glassware eingeben können.

Durch die Verwendung dieser API stellen Sie eine konsistente Nutzererfahrung für Glass-Nutzer bereit und vermeiden den Aufwand, eigene benutzerdefinierte Authentifizierungsschemas zu implementieren.

Google API-Dienstkonto erstellen

Wenn die Authentifizierung korrekt eingerichtet ist, verwendet das Back-End Ihrer Webanwendung die Mirror API, um die Kontoinformationen der Nutzer an Glass zu senden, nachdem sie sich bei Ihrem Dienst authentifiziert haben.

Für den Zugriff auf diese API müssen Sie ein Google API-Projekt und dann eine Client-ID für ein Dienstkonto (nicht für eine Webanwendung) erstellen. Wenn Sie ein Dienstkonto verwenden, müssen Nutzer Ihrer Anwendung nicht separat die Berechtigung erteilen, ihre Anmeldedaten an Glass zu senden. Außerdem werden ihnen die OAuth-Berechtigungsseite und die eigene Authentifizierungsseite nicht noch einmal angezeigt.

So erstellen Sie dieses Konto:

  1. Rufen Sie die Google Developers Console auf.
  2. Klicken Sie auf die Schaltfläche Projekt erstellen und geben Sie die erforderlichen Informationen ein.
  3. Notieren Sie sich nach der Erstellung Ihres Projekts die Projektnummer, die Sie später benötigen.
  4. Klicken Sie unter APIs und Authentifizierung auf APIs und aktivieren Sie die Google Mirror API für Ihr neues Projekt.
  5. Klicken Sie unter APIs und Authentifizierung auf Anmeldedaten und dann auf Neue Client-ID erstellen. Klicken Sie das Kästchen Dienstkonto an, um eine neue OAuth 2.0-Client-ID für das Projekt zu erstellen.
  6. In einem Pop-up-Fenster werden Sie darüber informiert, dass der private Schlüssel auf Ihren Computer heruntergeladen wird. Außerdem finden Sie dort das Passwort für den privaten Schlüssel. Nachdem Sie dieses Fenster geschlossen haben, können Sie diesen privaten Schlüssel nicht mehr herunterladen und das Passwort nicht mehr sehen. Wenn sie verloren gehen, müssen Sie ein neues erstellen.
  7. Notieren Sie sich die E-Mail-Adresse des Dienstkontos, die Sie später für den API-Aufruf benötigen.

Metadaten zu Ihrer Glassware bereitstellen

Wenn Sie Ihre Glassware einreichen möchten, müssen Sie die folgenden Informationen angeben. Dadurch können wir Ihre Glassware bei der Implementierung korrekt authentifizieren.

  • Ihre Authentifizierungs-URL, zu der Nutzer weitergeleitet werden, wenn sie Ihre Glassware in MyGlass aktivieren.
  • Der Kontotyp (der String, den Sie beim Aufrufen der Android AccountManager APIs auf dem Glass-Gerät verwenden)
  • Der Paketname Ihrer Anwendung aus Ihrem AndroidManifest.xml
  • Die numerische Google API-Projekt-ID des oben erstellten Projekts
  • Das APK, das auf MyGlass hochgeladen werden soll. Zum Testen müssen Sie dieses APK nur einmal für den ersten Download bereitstellen, wenn Ihre Glassware von MyGlass aktiviert wird. Anschließend können Sie das APK lokal iterieren und Fehler beheben, indem Sie das APK auf Ihrem Gerät überschreiben. Dieses APK muss die folgenden Kriterien erfüllen:
    • Es muss auf Zip ausgerichtet sein.
    • Danach dürfen Sie keine Änderungen am Paketnamen oder privaten Signaturschlüssel mehr vornehmen. Der Android-Paketmanager erlaubt keine Upgrades, wenn eine dieser Änderungen vorgenommen wird.
    • Sie muss kleiner als 50 Megabyte sein.
    • Er muss mit der neuesten Version des GDK kompiliert werden.

Authentifizierungsablauf implementieren

Das folgende Diagramm zeigt den grundlegenden Authentifizierungsvorgang für GDK Glassware:

So implementieren Sie den Authentifizierungsvorgang:

  1. Wenn Nutzer Ihre Glassware in MyGlass aktivieren, werden sie zur Authentifizierungs-URL weitergeleitet. Diese Anfragen enthalten einen Abfrageparameter mit dem Namen userToken, den Sie später verwenden müssen.

  2. Der Nutzer gibt seine Anmeldedaten auf der Authentifizierungsseite ein.

  3. Der Server validiert die Anmeldedaten des Nutzers. Wenn die Anmeldedaten gültig sind, führen Sie einen Mirror API-Aufruf an die mirror.accounts.insert-Methode aus. Bei dieser Methode müssen Sie beim Erstellen des Mirror-Dienstobjekts den Bereich https://www.googleapis.com/auth/glass.thirdpartyauth angeben. In den Beispielen zur Kontoerstellung finden Sie Beispiele dazu, wie Sie diesen API-Aufruf mit HTTP- oder Java-Rohdaten senden.

    Die Parameter und der Anfragetext, die du unten angibst, geben die Informationen an, die du AccountManager von Android zur Verfügung stellen würdest, wenn du das Konto direkt auf dem Gerät erstellst.

    Attributname Wert Beschreibung
    features[] Liste von Strings Eine Liste der Features (siehe AccountManager.hasFeatures).
    password String Das Kontopasswort (siehe AccountManager.getPassword). Wir empfehlen, das tatsächliche Passwort des Nutzers nicht in diesem Feld zu speichern. Stattdessen sollten Sie damit langlebige private Daten wie ein Aktualisierungstoken speichern.
    userData[] Liste der Objekte Ein oder mehrere dem Konto zugeordnete Nutzerdatenpaare (siehe AccountManager.getUserData).
    userData[].key String Der Schlüssel, der einem bestimmten Schlüssel/Wert-Paar für Nutzerdaten zugeordnet ist.
    userData[].value String Der Wert, der einem bestimmten Schlüssel/Wert-Paar für Nutzerdaten zugeordnet ist.
    authTokens[] Liste der Objekte Ein oder mehrere mit dem Konto verknüpfte Authentifizierungstokens (siehe AccountManager.getAuthToken).
    authTokens[].type String Der Typ des Authentifizierungstokens.
    authTokens[].authToken String Das Authentifizierungstoken.

  4. Nach Erhalt der mirror.account.insert-Anfrage überträgt die Mirror API das Konto an die Glass-Geräte des Nutzers. Sie können jetzt über die Klasse AccountManager darauf zugreifen.

So implementieren Sie einen nutzerfreundlichen Authentifizierungsvorgang:

  • Abläufe für Mobilgeräte optimieren
  • Wenn der Ablauf einen Umfang hat und der Nutzer ihn abbricht, sollte die Fehlermeldung gut formuliert sein.
  • Stellen Sie sicher, dass die von Ihnen angeforderten Bereiche tatsächlich in Ihrer Glassware verwendet werden.
  • Wenn ein Nutzerkonto verbunden werden kann, müssen Sie es verbinden.
  • Nutzerdaten sollten nach Möglichkeit in der Cloud gesichert werden.

Verwenden Sie einen der folgenden Authentifizierungsabläufe, um die Konsistenz der Glassware-Authentifizierung zu wahren:

Spiegeln oder hybrid ohne Konto

  1. Nach dem Wechsel in MyGlass wird die Authentifizierungs-URL in einem Pop-up-Fenster geöffnet.
  2. Der Nutzer wird dann direkt zu den zu akzeptierenden Bereichen weitergeleitet.
  3. Nachdem der Nutzer die Bereiche akzeptiert oder abgebrochen hat, schließen Sie das Pop-up.

Mit einem Konto spiegeln

  1. Nach dem Wechsel in MyGlass wird die Authentifizierungs-URL in einem Pop-up-Fenster geöffnet.
    • Wenn der Nutzer bereits bei Ihrem Dienst angemeldet ist, senden Sie ihn direkt an Bereiche.
    • Wenn der Nutzer nicht angemeldet ist, zeigen Sie die Anmeldefelder an, erlauben Sie ihm, sich bei Ihrem Dienst anzumelden, und senden Sie ihn dann an Bereiche.
    • Wenn der Nutzer kein Konto hat, geben Sie einen Link zum Erstellen eines Kontos an. Nutzer müssen im Rahmen des Installationsvorgangs ein Konto erstellen können.
  2. Der Nutzer akzeptiert Bereiche.
    • Wenn Ihre Glassware konfigurierbare Einstellungen hat, leiten Sie den Nutzer zur Einstellungsseite mit angemessenen Standardeinstellungen weiter.
    • Wenn Ihre Glassware keine konfigurierbaren Einstellungen hat, leiten Sie den Nutzer zu einer Bestätigungsseite weiter. Schließen Sie das Pop-up, wenn keine zusätzliche Konfiguration erforderlich ist.

Hybrid mit einem Konto

  1. Nach dem Wechsel in MyGlass wird die Authentifizierungs-URL in einem Pop-up-Fenster geöffnet.
    • Wenn der Nutzer bereits bei Ihrem Dienst angemeldet ist, senden Sie ihn direkt an Bereiche.
    • Wenn der Nutzer nicht angemeldet ist, zeigen Sie Anmeldefelder an, erlauben Sie ihm, sich anzumelden, und senden Sie ihn dann an Bereiche.
    • Wenn der Nutzer kein Konto hat, geben Sie einen Link zum Erstellen eines Kontos an.
  2. Der Nutzer akzeptiert Bereiche.
  3. Senden Sie eine Anfrage zum Einfügen des GDK-Kontos an die Mirror API.
    • Den Nutzer auf die Einstellungsseite weiterleiten, auf der angemessene Standardeinstellungen ausgewählt sind.
    • Senden Sie dem Nutzer eine Bestätigungsseite. Schließen Sie das Pop-up, wenn keine weitere Konfiguration erforderlich ist.

Spiegeln oder kombinieren mit einem Konto und benutzerdefinierten Bereichen

  1. Nach dem Wechsel in MyGlass wird die Authentifizierungs-URL in einem Pop-up-Fenster geöffnet.
    • Wenn der Nutzer bereits bei Ihrem Dienst angemeldet ist, senden Sie ihn an Ihre internen Bereiche.
    • Wenn der Nutzer nicht angemeldet ist, zeigen Sie Anmeldefelder an, erlauben Sie ihm, sich anzumelden, und senden Sie ihn dann an Ihre internen Bereiche.
    • Wenn der Nutzer kein Konto hat, geben Sie einen Link zum Erstellen eines Kontos an.
  2. Wenn der Nutzer Ihre benutzerdefinierten Bereiche akzeptiert, senden Sie ihn an die Bereiche von Google.
  3. Senden Sie eine Anfrage zum Einfügen des GDK-Kontos an die Mirror API.
    • Den Nutzer auf die Einstellungsseite weiterleiten, auf der angemessene Standardeinstellungen ausgewählt sind.
    • Senden Sie dem Nutzer eine Bestätigungsseite. Schließen Sie das Pop-up, wenn keine weitere Konfiguration erforderlich ist.

Spiegeln oder mischen mit einer Android-/iPhone-App

  1. Nach dem Wechsel in MyGlass wird die Authentifizierungs-URL in einem Pop-up-Fenster geöffnet.
  2. Der Nutzer wird dann direkt zu den zu akzeptierenden Bereichen weitergeleitet.
  3. Nachdem der Nutzer Bereiche akzeptiert hat:
    • Wenn der Nutzer die Companion-App hat und authentifiziert ist, schließen Sie das Pop-up-Fenster.
    • Wenn nicht, leite den Nutzer an ein Interstitial weiter, das ihn dazu anweist, die App aus dem Google Play Store oder iOS Store herunterzuladen
  4. Nachdem Sie die App installiert und sich authentifiziert haben, schließen Sie das Pop-up-Fenster

BIP und kein Konto

Für diesen Vorgang ist das Ein- und Ausschalten der Glassware in MyGlass erforderlich.

GDK mit einem Konto

  1. Nach dem Wechsel in MyGlass wird die Authentifizierungs-URL in einem Pop-up-Fenster geöffnet.
    • Wenn der Nutzer bereits bei Ihrem Dienst angemeldet ist, leiten Sie ihn zum Bestätigungsbildschirm weiter.
    • Wenn der Nutzer nicht angemeldet ist, zeigen Sie die Anmeldefelder an, erlauben Sie ihm, sich anzumelden, und senden Sie ihn dann an den Bestätigungsbildschirm.
    • Wenn der Nutzer kein Konto hat, geben Sie einen Link zum Erstellen eines Kontos an.
  2. Der Nutzer akzeptiert Bereiche.
  3. Senden Sie eine Anfrage zum Einfügen des GDK-Kontos an die Mirror API.
  4. Bestätigungsbildschirm anzeigen und nach kurzer Zeit schließen.

Beispiele für die Kontoerstellung

Verwenden Sie nach Möglichkeit die Clientbibliotheken für die Mirror API. Dadurch wird das Aufrufen von mirror.accounts.insert erleichtert, um das Konto zu erstellen.

Beispiel für Roh-HTTP

Das folgende Beispiel zeigt nur die URL der Anfrage und ein Beispiel für den erwarteten JSON-Text. Reine HTTP-Anfragen für ein Dienstkonto zu erstellen, ist wesentlich komplizierter (siehe OAuth 2.0 für Server-zu-Server-Anwendungen verwenden), daher empfehlen wir, eine der Google API-Clientbibliotheken zu verwenden, um diesen Vorgang zu vereinfachen.

Anfragemethode und URL:

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

Anfragetext:

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

Ersetzen Sie {userToken} in der Anfrage-URL durch das Token, das in Schritt 1 von Authentifizierungsvorgang implementieren an Ihre Authentifizierungs-URL übergeben wurde.

Java-Beispiel

In diesem Beispiel wird gezeigt, wie Sie mit der Java-Clientbibliothek mirror.accounts.insert aufrufen.

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();
  }
}

Konten in Glass abrufen

Das Abrufen und Verwenden von Account-Objekten in Glass ähnelt dem standardmäßigen Android-AccountManager.

  1. Deklarieren Sie in Ihrer AndroidManifest.xml-Datei die folgenden Manifestberechtigungen:

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

  2. Rufen Sie die Glassware-Konten ab:

    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. Rufen Sie ein Authentifizierungstoken von Account ab:

    // 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);