Autenticación para GDK Glassware

Si tu Glassware de la GDK necesita autenticar a los usuarios en un servicio web, la GDK proporciona una API que permite que el usuario ingrese sus credenciales cuando instala tu Glassware.

Con el uso de esta API, proporcionas una experiencia de usuario coherente para los usuarios de Glass y evitas la sobrecarga que genera implementar tus propios esquemas de autenticación personalizados.

Nota: Actualmente, solo puedes probar y usar esta API después de que subamos tu APK a MyGlass, lo que ocurre durante el proceso de revisión.

Crea una cuenta de servicio de la API de Google

Cuando la autenticación se configura correctamente, el backend de tu app web usa la API de Mirror para enviar la información de la cuenta de los usuarios a Glass después de que se autentiquen con tu servicio.

Para acceder a esta API, crea un proyecto de la API de Google y, luego, un ID de cliente para una "cuenta de servicio" (y no una "aplicación web"). Cuando se usa una cuenta de servicio, los usuarios no tienen que otorgar permiso a tu aplicación de forma independiente para enviar sus credenciales a Glass y no se les volverá a mostrar la página de permisos de OAuth ni tu propia página de autenticación.

Para crear esta cuenta, haz lo siguiente:

1. Ve a Google Developers Console.
2. Haz clic en el botón Create Project y, luego, ingresa la información solicitada.
3. Cuando se cree el proyecto, anota el número de proyecto, que necesitarás más adelante.
4. En APIs y autenticación, haz clic en APIs y habilita la API de Google Mirror para tu proyecto nuevo.
5. En APIs y autenticación, haz clic en Credenciales y, luego, en Crear ID de cliente nuevo. Marca la casilla etiquetada como Cuenta de servicio para crear un nuevo ID de cliente de OAuth 2.0 para el proyecto.
6. Una ventana emergente te informará que la clave privada se está descargando en tu computadora y te proporcionará la contraseña correspondiente. Una vez que cierres esta ventana, no podrás descargar esta clave privada ni volver a ver la contraseña. Si alguna vez se pierden, debes crear uno nuevo.
7. Anota la dirección de correo electrónico de la cuenta de servicio, que necesitarás más adelante para realizar la llamada a la API.

Proporcionar metadatos acerca de tu Glassware

Cuando esté todo listo para enviar tu producto de vidrio, deberás proporcionar la siguiente información. Esto nos permite configurar tu Glassware para que se autentique correctamente cuando lo implementes.

• Tu URL de autenticación, a la que se redirecciona a los usuarios cuando activan Glassware en MyGlass
• El tipo de cuenta (la cadena que usarás cuando llames a las APIs de AccountManager de Android en el dispositivo Glass)
• El nombre del paquete de tu aplicación desde tu AndroidManifest.xml
• El ID numérico del proyecto de la API de Google del proyecto que creaste anteriormente
• El APK que se subirá a MyGlass Para las pruebas, solo debes proporcionar este APK una vez para controlar la descarga inicial cuando se activa Glassware desde MyGlass. Después de eso, puedes iterar y depurar de forma local si reemplazas el APK en tu dispositivo. Ten en cuenta que este APK debe cumplir con los siguientes criterios:
  • Debe estar alineado con ZIP.
  • No debes realizar ningún cambio en el nombre del paquete ni en la clave de firma privada después de esto (el administrador de paquetes de Android no permite actualizaciones si se produce alguno de estos cambios).
  • Debe tener un tamaño inferior a 50 megabytes.
  • Se debe compilar con la versión más reciente del GDK.

Implementa el flujo de autenticación

En el siguiente diagrama, se muestra el flujo de autenticación básico de Glassware de GDK:

Para implementar el flujo de autenticación, haz lo siguiente:

1. Cuando los usuarios activan tu Glassware en MyGlass, se los redirecciona a tu URL de autenticación. Estas solicitudes incluyen un parámetro de consulta llamado userToken que deberás usar más adelante.

   Advertencia: No almacenes este token de usuario. Solo los extremos de autenticación de Google pueden usarlo para asignar la solicitud al usuario que la originó solo durante esa sesión y no contiene información que se pueda usar para identificar al usuario de forma persistente. No se garantiza que el token sea el mismo si el usuario se autentica con el mismo Glassware varias veces o si el usuario se autentica con Glassware diferente del mismo desarrollador.

2. El usuario ingresa sus credenciales en tu página de autenticación.

3. Tu servidor valida las credenciales del usuario. Si las credenciales son válidas, realiza una llamada a la API de Mirror al método mirror.accounts.insert. Este método requiere que especifiques el alcance de https://www.googleapis.com/auth/glass.thirdpartyauth cuando compilas tu objeto de servicio de Mirror. En los ejemplos de creación de cuentas, se muestran ejemplos de cómo realizar esta llamada a la API con HTTP sin procesar o Java.

   Los parámetros y el cuerpo de la solicitud que proporcionas a continuación representan la misma información que le proporcionarías a AccountManager de Android si crearas la cuenta directamente en el dispositivo.

   Nombre de la propiedad	Valor	Descripción
   features[]	lista de cadenas	Una lista de funciones (consulta AccountManager.hasFeatures).
   password	string	La contraseña de la cuenta (consulta AccountManager.getPassword). Te recomendamos que no almacenes la contraseña real del usuario en este campo, sino que la uses para almacenar datos privados de larga duración, como un token de actualización.
   userData[]	lista de objetos	Uno o más pares de datos del usuario asociados con la cuenta (consulta AccountManager.getUserData).
   userData[].key	string	Es la clave asociada con un par clave-valor de datos del usuario en particular.
   userData[].value	string	Es el valor asociado con un par clave-valor de datos del usuario en particular.
   authTokens[]	lista de objetos	Uno o más tokens de autenticación asociados con la cuenta (consulta AccountManager.getAuthToken).
   authTokens[].type	string	El tipo de token de autenticación.
   authTokens[].authToken	string	El token de autenticación

4. Cuando recibe la solicitud mirror.account.insert, la API de Mirror envía la cuenta a los dispositivos Glass del usuario, a los que ahora puedes acceder con la clase AccountManager.

Flujos de autenticación recomendados

Sigue estos lineamientos para implementar un flujo de autenticación fácil de usar:

• Optimiza tu flujo para dispositivos móviles.
• Si tu flujo tiene un alcance y el usuario lo cancela, debes tener un mensaje de error bien diseñado.
• Asegúrate de que los permisos que solicitas se estén usando en tu Glassware.
• Si se puede conectar una cuenta de usuario, asegúrate de hacerlo.
• Siempre que sea posible, se debe crear una copia de seguridad de los datos del usuario en la nube.

Nota: Instala tu Glassware al menos una vez a través de MyGlass para asegurarte de que el flujo de autenticación se realice correctamente. Siempre que lo hayas hecho una vez, puedes instalarlo mediante sideloading para realizar pruebas.

Si deseas mantener la coherencia en la autenticación de Glassware, usa uno de los siguientes flujos de autenticación:

Conexión espejo o híbrida sin una cuenta

1. Después de activar y desactivar en MyGlass, la URL de autenticación se abre en una ventana emergente.
2. Esto envía directamente al usuario a los permisos que debe aceptar.
3. Después de que el usuario acepte o cancele los permisos, cierra la ventana emergente.

Cómo duplicar con una cuenta

1. Después de activar la opción en MyGlass, se abrirá tu URL de autenticación en una ventana emergente.
   • Si el usuario ya accedió a tu servicio, envíalo directamente a los alcances.
   • Si el usuario no accedió, muestra los campos de acceso, permítele acceder a tu servicio y, luego, envíalo a los permisos.
   • Si el usuario no tiene una cuenta, proporciona un vínculo para crear una. Los usuarios deben tener una forma de crear una cuenta como parte del proceso del flujo de instalación.
2. El usuario acepta permisos.
   • Si tu Glassware tiene parámetros de configuración configurables, dirige al usuario a la página de configuración con parámetros predeterminados razonables seleccionados.
   • Si tu Glassware no tiene parámetros de configuración configurables, envía al usuario a una página de confirmación. Cierra la ventana emergente si no se requiere ninguna configuración adicional.

Híbrido con una cuenta

1. Después de activar y desactivar en MyGlass, la URL de autenticación se abre en una ventana emergente.
   • Si el usuario ya accedió a tu servicio, envíalo directamente a los permisos.
   • Si el usuario no accedió, muestra los campos de acceso, permite que acceda y, luego, envíalo a los permisos.
   • Si el usuario no tiene una cuenta, proporciónale un vínculo para crearla.
2. El usuario acepta los permisos.
3. Envía una solicitud a la API de Mirror para insertar la cuenta de GDK.
   • Envía al usuario a la página de configuración con valores predeterminados razonables seleccionados.
   • Envíale al usuario una página de confirmación. Cierra la ventana emergente si no se requiere ninguna configuración adicional.

Reflejo o híbrido con una cuenta y alcances personalizados

1. Después de activar la opción en MyGlass, se abrirá tu URL de autenticación en una ventana emergente.
   • Si el usuario ya accedió a tu servicio, envíalo a tus permisos internos.
   • Si el usuario no accedió, muestra los campos de acceso, permítele acceder y, luego, envíalo a tus alcances internos.
   • Si el usuario no tiene una cuenta, proporciona un vínculo para crear una.
2. Cuando el usuario acepte tus permisos personalizados, envíalo a los permisos de Google.
3. Envía una solicitud a la API de Mirror para insertar la cuenta de GDK.
   • Envía al usuario a la página de configuración con valores predeterminados razonables seleccionados.
   • Envíale al usuario una página de confirmación. Cierra la ventana emergente si no se requiere ninguna configuración adicional.

Duplica la pantalla o usa el modo híbrido con una app para Android o iPhone

1. Después de activar la opción en MyGlass, se abrirá tu URL de autenticación en una ventana emergente.
2. Esto envía directamente al usuario a los permisos que debe aceptar.
3. Después de que el usuario acepta los permisos, ocurre lo siguiente:
   • Si el usuario tiene la app complementaria y se autenticó, cierra la ventana emergente.
   • De lo contrario, envía al usuario a un anuncio intersticial que lo dirija a descargar la app desde Google Play Store o la tienda de iOS.
4. Después de instalar la app y autenticarte, cierra la ventana emergente.

GDK y sin cuenta

Para este flujo, solo debes activar Glassware en MyGlass.

GDK con una cuenta

1. Después de activar la opción en MyGlass, se abrirá tu URL de autenticación en una ventana emergente.
   • Si el usuario ya accedió a tu servicio, envíalo a la pantalla de confirmación.
   • Si el usuario no accedió, muestra los campos de acceso, permítele acceder y, luego, envíalo a la pantalla de confirmación.
   • Si el usuario no tiene una cuenta, proporciona un vínculo para crear una.
2. El usuario acepta los permisos.
3. Envía una solicitud a la API de Mirror para insertar la cuenta de GDK.
4. Mostrar la pantalla de confirmación y cerrarla después de mostrarla durante un período breve.

Ejemplos de creación de cuentas

Usa las bibliotecas cliente para la API de Mirror cuando sea posible. Esto facilita llamar a mirror.accounts.insert para crear la cuenta.

Ejemplo de HTTP sin procesar

En el siguiente ejemplo, solo se muestra la URL de la solicitud y un ejemplo del cuerpo de JSON que espera. Hacer solicitudes HTTP sin procesar en nombre de una cuenta de servicio es mucho más complicado (consulta Cómo usar OAuth 2.0 para aplicaciones de servidor a servidor para obtener todos los detalles), por lo que te recomendamos que uses una de nuestras bibliotecas cliente de la API de Google si es posible para facilitar este proceso.

Método de solicitud y URL:

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

Cuerpo de la solicitud:

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

Reemplaza {userToken} en la URL de solicitud por el token que se pasó a tu URL de autenticación en el paso 1 de Implementación del flujo de autenticación.

Ejemplo de Java

En este ejemplo, se muestra cómo usar la biblioteca cliente de Java para llamar a 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();
  }
}

Cómo recuperar cuentas en Glass

Recuperar y usar objetos Account en Glass es similar a usar el AccountManager estándar de Android.

1. Declara los siguientes permisos de manifiesto en tu archivo AndroidManifest.xml:

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

2. Recupera las cuentas de 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 de autenticación de 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);