Autenticazione per GDK Glassware

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

L'utilizzo di questa API fornisce un'esperienza utente coerente per gli utenti di Glass ed evita l'overhead di implementazione dei tuoi schemi di autenticazione personalizzati.

Creazione di un account di servizio API di Google

Se l'autenticazione è configurata correttamente, il backend dell'app web utilizza l'API Mirror per eseguire il push dei dati dell'account degli utenti a Glass dopo l'autenticazione con il servizio.

Per accedere a questa API, crea un progetto API di Google, quindi crea un ID client per un "account di servizio" (e non per un'"applicazione web"). Utilizzando un account di servizio, gli utenti non devono concedere separatamente l'autorizzazione della tua applicazione per trasferire le loro credenziali a Glass e non verranno più presentate sia con la pagina delle autorizzazioni OAuth sia con la tua pagina di autenticazione.

Per creare questo account:

  1. Vai alla Google Developers Console.
  2. Fai clic sul pulsante Crea progetto e inserisci le informazioni richieste.
  3. Una volta creato il progetto, annota il numero del progetto di cui avrai bisogno in seguito.
  4. In API e autenticazione, fai clic su API e abilita l'API Google Mirror per il tuo nuovo progetto.
  5. In API e autenticazione, fai clic su Credenziali, quindi 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. Dopo aver chiuso questa finestra, non potrai scaricare questa chiave privata né visualizzare di nuovo la password. Se le perdi, dovrai crearne una nuova.
  7. Prendi nota dell'indirizzo email dell'account di servizio, che ti servirà in un secondo momento per effettuare la chiamata API.

Fornire metadati relativi al Glassware

Quando vuoi inviare il tuo Glassware, devi fornire le seguenti informazioni. In questo modo possiamo configurare l'autenticazione del tuo Glassware correttamente quando la implementi.

  • L'URL di autenticazione, a cui gli utenti vengono reindirizzati quando attivano il Glassware in MyGlass.
  • Il tipo di account (la stringa che utilizzerai quando chiami le API Android AccountManager sul dispositivo Glass)
  • Il nome del pacchetto dell'applicazione indicato in AndroidManifest.xml
  • L'ID progetto numerico dell'API di Google del progetto che hai creato sopra
  • L'APK da caricare su MyGlass. Per eseguire il test, devi fornire questo APK una sola volta per gestire il download iniziale quando Glassware è attivo da MyGlass; in seguito, potrai eseguire l'iterazione ed eseguire il debug a livello locale sovrascrivendo l'APK sul tuo dispositivo. Tieni presente che questo APK deve soddisfare i seguenti criteri:
    • Deve essere allineato in modo zip.
    • Non devi apportare modifiche al nome del pacchetto o alla chiave di firma privata in seguito (il gestore di pacchetti di Android non consente gli upgrade se una di queste modifiche).
    • Deve essere inferiore a 50 megabyte.
    • Deve essere compilato utilizzando l'ultima versione di GDK.

Implementare il 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 il tuo Glassware in MyGlass, vengono reindirizzati all'URL di autenticazione. Queste richieste includono un parametro di ricerca 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, esegui una chiamata 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 del servizio Mirror. Esempi di esecuzione di questa chiamata API tramite HTTP non valido o Java sono illustrati 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 stessi creando l'account direttamente sul dispositivo.

    Nome proprietà Valore Descrizione
    features[] elenco di stringhe Un elenco di funzionalità (vedi AccountManager.hasFeatures).
    password string 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 string La chiave associata a una determinata coppia chiave-valore dei dati utente.
    userData[].value string 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 string Il tipo di token di autenticazione.
    authTokens[].authToken string Il token di autenticazione.

  4. Dopo aver ricevuto la richiesta mirror.account.insert, l'API Mirror esegue il push dell'account ai dispositivi Glass dell'utente, dove ora puoi accedervi utilizzando la classe AccountManager.

Segui queste linee guida per implementare un flusso di autenticazione intuitivo:

  • Ottimizza il flusso per i dispositivi mobili.
  • Se il flusso ha un ambito e l'utente lo annulla, presenta un messaggio di errore ben progettato.
  • Assicurati che gli ambiti richiesti siano effettivamente utilizzati nel tuo Glassware.
  • Se è possibile connettere un account utente, assicurati di collegarlo.
  • Dove possibile, il backup dei dati utente deve essere eseguito sul cloud.

Per garantire la coerenza nell'autenticazione Glassware, utilizza uno dei seguenti flussi di autenticazione:

Mirroring o ibrido senza un account

  1. Dopo l'attivazione in MyGlass, l'URL di autenticazione si apre in un popup.
  2. In questo modo l'utente viene indirizzato direttamente agli ambiti per l'accettazione.
  3. Dopo che l'utente accetta o annulla gli ambiti, chiudi il popup.

Mirroring con un account

  1. Dopo l'attivazione in MyGlass, l'URL di autenticazione si apre 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, consenti all'utente di accedere al tuo servizio e poi invialo negli ambiti.
    • Se l'utente non dispone di un account, fornisci un link per crearne uno. Gli utenti devono avere un modo per creare un account come parte integrante della procedura di installazione.
  2. L'utente accetta gli ambiti.
    • Se il tuo Glassware ha impostazioni configurabili, indirizza l'utente alla pagina delle impostazioni con valori ragionevoli selezionati.
    • Se il tuo Glassware non ha impostazioni configurabili, indirizza l'utente a una pagina di conferma. Chiudi il popup se non sono richieste configurazioni aggiuntive.

Ibrido con account

  1. Dopo l'attivazione in MyGlass, l'URL di autenticazione si apre 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, consenti l'accesso e poi invia quest'ultimo agli ambiti.
    • Se l'utente non dispone di 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 le impostazioni predefinite ragionevoli.
    • Invia all'utente una pagina di conferma. Chiudi il popup se non sono richieste configurazioni aggiuntive.

Mirroring o ibrido con un account e ambiti personalizzati

  1. Dopo l'attivazione in MyGlass, l'URL di autenticazione si apre in un popup.
    • Se l'utente ha già eseguito l'accesso al tuo servizio, indirizzalo agli ambiti interni
    • Se l'utente non ha eseguito l'accesso, mostra i campi di accesso, consenti l'accesso e poi inviali 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 Google.
  3. Invia una richiesta all'API Mirror per inserire l'account GDK.
    • Invia l'utente alla pagina delle impostazioni con le impostazioni predefinite ragionevoli.
    • Invia all'utente una pagina di conferma. Chiudi il popup se non sono richieste configurazioni aggiuntive.

Mirroring o ibrido con un'app per Android/iPhone

  1. Dopo l'attivazione in MyGlass, l'URL di autenticazione si apre in un popup.
  2. In questo modo l'utente viene indirizzato direttamente agli ambiti per l'accettazione.
  3. Dopo che l'utente accetta gli ambiti:
    • Se l'utente ha l'app complementare e viene autenticato, chiudi la finestra popup.
    • Se non è così, indirizza l'utente a un interstitial con l'invito di scaricare l'app dal Google Play Store o dall'iOS Store
  4. Dopo aver installato l'app e aver eseguito l'autenticazione, chiudi la finestra popup

GDK e nessun account

Per attivare questo flusso è sufficiente attivare i calici in MyGlass.

GDK con un account

  1. Dopo l'attivazione in MyGlass, l'URL di autenticazione si apre in un 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, visualizza i campi di accesso, consenti l'accesso e poi invialo alla schermata di conferma.
    • Se l'utente non dispone di 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 visualizzata per un breve periodo di tempo.

Esempi di creazione dell'account

Quando possibile, utilizza le librerie client per l'API Mirror. In questo modo chiamare mirror.accounts.insert è più semplice.

Esempio di HTTP non elaborato

L'esempio seguente mostra solo l'URL della richiesta e un esempio del corpo JSON che si aspetta. Effettuare richieste HTTP non elaborate per conto di un account di servizio è molto più complicato (vedi Utilizzare OAuth 2.0 per le applicazioni Server-Server per i dettagli completi), quindi ti consigliamo di utilizzare una delle librerie client dell'API di Google, se possibile.

Metodo e URL della richiesta:

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 che è stato trasmesso all'URL di autenticazione al passaggio 1 della sezione Implementare il 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 degli account su Glass

Il recupero e l'utilizzo degli oggetti Account su Glass sono simili a quelli usati per Android standard AccountManager.

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