Autenticazione per GDK Glassware

Se il tuo Glassware GDK deve autenticare gli utenti in base a un servizio web, il GDK fornisce un'API che consente all'utente di inserire le proprie credenziali quando installa il tuo Glassware.

Utilizzando questa API, offri un'esperienza utente coerente agli utenti di Glass ed eviti il sovraccarico di implementare i tuoi schemi di autenticazione personalizzati.

Creazione di un account di servizio API di Google

Quando l'autenticazione è configurata correttamente, il back-end della tua app web utilizza l'API Mirror per inviare i dati dell'account degli utenti a Glass dopo che si sono autenticati con il tuo servizio.

Per accedere a questa API, crea un progetto API Google e poi crea un ID client per un "account di servizio" (e non un'"applicazione web"). Utilizzando un account di servizio, gli utenti non devono concedere separatamente l'autorizzazione all'applicazione per eseguire il push delle loro credenziali a Glass e non visualizzeranno più la pagina delle autorizzazioni OAuth e la tua pagina di autenticazione.

Per creare questo account:

  1. Vai a Google Developers Console.
  2. Fai clic sul pulsante Crea progetto e inserisci le informazioni richieste.
  3. Una volta creato il progetto, prendi nota del numero del progetto, che ti servirà in seguito.
  4. In API e autenticazione, fai clic su API e abilita l'API Google Mirror per il nuovo progetto.
  5. In API e autenticazione, fai clic su Credenziali e poi su Crea nuovo ID client. Seleziona la casella Account di servizio per creare un nuovo ID client OAuth 2.0 per il progetto.
  6. Una finestra popup ti informerà che la chiave privata è in fase di download sul tuo computer e ti fornisce la password per quella chiave privata. Una volta chiusa questa finestra, non potrai più scaricare la chiave privata o visualizzare di nuovo la password. Se li perdi, devi crearne uno nuovo.
  7. Prendi nota dell'indirizzo email dell'account di servizio, che ti servirà più tardi per effettuare la chiamata all'API.

Fornire metadati sulla tua attrezzatura Glassware

Quando è tutto pronto per inviare i tuoi prodotti per la casa, dovrai fornire le seguenti informazioni. In questo modo possiamo configurare Glassware in modo che venga autenticato correttamente quando lo implementi.

  • Il tuo URL di autenticazione, a cui gli utenti vengono reindirizzati quando attivano i tuoi Glassware in MyGlass.
  • Il tipo di account (la stringa che utilizzerai quando chiamerai le API Android AccountManager sul dispositivo Glass)
  • Il nome del pacchetto della tua applicazione da AndroidManifest.xml
  • L'ID progetto numerico dell'API Google del progetto che hai creato sopra
  • L'APK da caricare su MyGlass. Per i test, devi fornire questo APK solo una volta per gestire il download iniziale quando la tua app per Glass viene attivata da MyGlass. Dopodiché, puoi eseguire l'iterazione e il debug localmente sovrascrivendo l'APK sul dispositivo. Tieni presente che questo APK deve soddisfare i seguenti criteri:
    • Deve essere allineato a ZIP.
    • Dopodiché non devi apportare modifiche al nome del pacchetto o alla chiave di firma privata (il gestore pacchetti Android non consente gli upgrade se vengono apportate queste modifiche).
    • Deve avere dimensioni inferiori a 50 megabyte.
    • Deve essere compilato utilizzando la versione più recente del GDK.

Implementazione del flusso di autenticazione

Il seguente diagramma mostra il flusso di autenticazione di base per GDK Glassware:

Per implementare il flusso di autenticazione:

  1. Quando gli utenti attivano la tua app Glassware in MyGlass, vengono reindirizzati al tuo URL di autenticazione. Queste richieste includono un parametro di query denominato userToken che dovrai utilizzare in un secondo momento.

  2. L'utente inserisce le proprie credenziali nella pagina di autenticazione.

  3. Il server convalida le credenziali dell'utente. Se le credenziali sono valide, effettua una chiamata all'API Mirror al metodo mirror.accounts.insert. Questo metodo richiede di specificare l'ambito https://www.googleapis.com/auth/glass.thirdpartyauth quando crei l'oggetto servizio Mirror. Gli esempi di esecuzione di questa chiamata API utilizzando HTTP non elaborato o Java sono riportati negli esempi di creazione dell'account.

    I parametri e il corpo della richiesta forniti di seguito rappresentano le stesse informazioni che forniresti a AccountManager di Android se crei l'account direttamente sul dispositivo.

    Nome proprietà Valore Descrizione
    features[] Elenco di stringhe Un elenco di funzionalità (vedi AccountManager.hasFeatures).
    password stringa La password dell'account (vedi AccountManager.getPassword). Ti consigliamo di non archiviare la password effettiva dell'utente in questo campo, ma di utilizzarla per archiviare dati privati di lunga durata, come un token di aggiornamento.
    userData[] elenco di oggetti Una o più coppie di dati utente associati all'account (vedi AccountManager.getUserData).
    userData[].key stringa La chiave associata a una determinata coppia chiave-valore dei dati utente.
    userData[].value stringa Il valore associato a una determinata coppia chiave-valore dei dati utente.
    authTokens[] elenco di oggetti Uno o più token di autenticazione associati all'account (vedi AccountManager.getAuthToken).
    authTokens[].type stringa Il tipo di token di autenticazione.
    authTokens[].authToken stringa Il token di autenticazione.

  4. Al ricevimento della richiesta mirror.account.insert, l'API Mirror spinge l'account sui dispositivi Glass dell'utente, dove ora puoi accedervi utilizzando la classe AccountManager.

Segui queste linee guida per implementare un flusso di autenticazione facile da usare:

  • Ottimizza il flusso per i dispositivi mobili.
  • Se il flusso ha un ambito e l'utente lo annulla, devi avere un messaggio di errore ben progettato.
  • Assicurati che gli ambiti richiesti vengano effettivamente utilizzati in Glassware.
  • Se è possibile collegare un account utente, assicurati di farlo.
  • Ove possibile, è consigliabile eseguire il backup dei dati utente sul cloud.

Per mantenere la coerenza nell'autenticazione di Glassware, utilizza uno dei seguentiflussi di autenticazione:

Mirror o ibrido senza un account

  1. Dopo aver attivato la funzionalità in MyGlass, l'URL di autenticazione si apre in una finestra popup.
  2. Questo invia direttamente l'utente agli ambiti da accettare.
  3. Dopo che l'utente accetta o annulla gli ambiti, chiudi il popup.

Eseguire il mirroring con un account

  1. Dopo aver attivato la funzionalità in MyGlass, l'URL di autenticazione si apre in una finestra popup.
    • Se l'utente ha già eseguito l'accesso al tuo servizio, indirizzalo direttamente agli ambiti.
    • Se l'utente non ha eseguito l'accesso, mostra i campi di accesso, consentigli di accedere al tuo servizio e poi indirizzalo agli ambiti.
    • Se l'utente non dispone di un account, fornisci un link per crearne uno. Gli utenti devono avere la possibilità di creare un account nell'ambito della procedura di flusso di installazione.
  2. L'utente accetta gli ambiti.
    • Se il tuo Glassware ha impostazioni configurabili, indirizza l'utente alla pagina delle impostazioni con i valori predefiniti ragionevoli selezionati.
    • Se il prodotto Glassware non dispone di impostazioni configurabili, indirizza l'utente a una pagina di conferma. Chiudi il popup se non occorre alcuna configurazione aggiuntiva.

Ibrido con un account

  1. Dopo l'attivazione in MyGlass, l'URL di autenticazione si aprirà in un popup.
    • Se l'utente ha già eseguito l'accesso al tuo servizio, indirizzalo direttamente agli ambiti.
    • Se l'utente non ha eseguito l'accesso, mostra i campi di accesso, consentigli di accedere e poi invialo agli ambiti.
    • Se l'utente non ha un account, fornisci un link per crearne uno.
  2. L'utente accetta gli ambiti.
  3. Invia una richiesta all'API Mirror per inserire l'account GDK.
    • Invia l'utente alla pagina delle impostazioni con i valori predefiniti ragionevoli selezionati.
    • Invia all'utente una pagina di conferma. Chiudi il popup se non è richiesta alcuna configurazione aggiuntiva.

Mirror o ibrida con un account e ambiti personalizzati

  1. Dopo aver attivato la funzionalità in MyGlass, l'URL di autenticazione si apre in una finestra popup.
    • Se l'utente ha già eseguito l'accesso al tuo servizio, indirizzalo ai tuoi ambiti interni
    • Se l'utente non ha eseguito l'accesso, mostra i campi di accesso, consentigli di accedere e poi indirizzalo ai tuoi ambiti interni
    • Se l'utente non dispone di un account, fornisci un link per crearne uno.
  2. Quando l'utente accetta i tuoi ambiti personalizzati, indirizzalo agli ambiti di Google.
  3. Invia una richiesta all'API Mirror per inserire l'account GDK.
    • Invia l'utente alla pagina delle impostazioni con i valori predefiniti ragionevoli selezionati.
    • Invia all'utente una pagina di conferma. Chiudi il popup se non è richiesta alcuna configurazione aggiuntiva.

Mirroring o ibrido con un'app per Android/iPhone

  1. Dopo aver attivato la funzionalità in MyGlass, l'URL di autenticazione si apre in una finestra popup.
  2. Questo invia direttamente l'utente agli ambiti da accettare.
  3. Dopo che l'utente accetta gli ambiti:
    • Se l'utente ha l'app complementare ed è autenticato, chiudi la finestra popup.
    • In caso contrario, indirizza l'utente a un annuncio interstitial che lo invita a scaricare l'app dal Google Play Store o dallo store iOS
  4. Dopo aver installato l'app e aver eseguito l'autenticazione, chiudi la finestra popup

GDK e nessun account

Per questo flusso è sufficiente attivare Glassware in MyGlass.

GDK con un account

  1. Dopo aver attivato la funzionalità in MyGlass, l'URL di autenticazione si apre in una finestra popup.
    • Se l'utente ha già eseguito l'accesso al tuo servizio, indirizzalo alla schermata di conferma.
    • Se l'utente non ha eseguito l'accesso, mostra i campi di accesso, consentigli di accedere e poi indirizzalo alla schermata di conferma.
    • Se l'utente non ha un account, fornisci un link per crearne uno.
  2. L'utente accetta gli ambiti.
  3. Invia una richiesta all'API Mirror per inserire l'account GDK.
  4. Mostra la schermata di conferma e chiudila dopo averla mostrata per un breve periodo di tempo.

Esempi di creazione di account

Utilizza le librerie client per l'API Mirror, se possibile. In questo modo è più facile chiamare mirror.accounts.insert per creare l'account.

Esempio di HTTP non elaborato

L'esempio seguente mostra solo l'URL della richiesta e un esempio del corpo JSON previsto. Rendere le richieste HTTP non elaborate per conto di un account di servizio è molto più complicato (vedi Utilizzo di OAuth 2.0 per le applicazioni server-server per informazioni dettagliate), quindi, se possibile, ti consigliamo di utilizzare una delle librerie client dell'API di Google per semplificare questa operazione.

Metodo di richiesta e URL:

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

Corpo della richiesta:

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

Sostituisci {userToken} nell'URL della richiesta con il token passato al tuo URL di autenticazione nel passaggio 1 di Implementazione del flusso di autenticazione.

Esempio Java

Questo esempio mostra come utilizzare la libreria client Java per chiamare 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();
  }
}

Recupero di account su Glass

Il recupero e l'utilizzo degli oggetti Account su Glass è simile all'utilizzo di AccountManager su Android standard.

  1. Dichiara le seguenti autorizzazioni manifest nel file AndroidManifest.xml:

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

  2. Recupera gli account di 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. Recupera un token di autenticazione da 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);