Autenticación para cristalería de GDK

Si tu Glassware GDK necesita autenticar a los usuarios en un servicio web, el GDK proporciona una API que le permite ingresar sus credenciales cuando instala el dispositivo.

Cuando usas esta API, proporcionas una experiencia del usuario coherente para los usuarios de Glass y evitas la sobrecarga de implementar tus propios esquemas de autenticación personalizados.

Crea una cuenta de servicio de la API de Google

Cuando la autenticación se configura de forma correcta, 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 autentique con el servicio.

A fin de acceder a esta API, crea un proyecto de API de Google y, luego, crea un ID de cliente para una "cuenta de servicio" (y no una "aplicación web"). Si usas una cuenta de servicio, no es necesario que los usuarios otorguen permiso por separado a tu aplicación 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:

  1. Ve a Google Developers Console.
  2. Haz clic en el botón Crear proyecto y, luego, ingresa la información solicitada.
  3. Una vez que se haya creado el proyecto, anota el número de proyecto, ya que lo necesitarás más adelante.
  4. En API y autenticación, haz clic en API y habilita la API de duplicación de Google para tu proyecto nuevo.
  5. En API y autenticación, haz clic en Credenciales y, luego, en Crear ID de cliente nuevo. Marca la casilla Cuenta de servicio a fin de crear un ID de cliente de OAuth 2.0 nuevo 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 para esa clave privada. Una vez que cierres esta ventana, no podrás descargar esta clave privada ni ver la contraseña de nuevo. Si alguna vez se pierden, debes crear una nueva.
  7. Toma nota de la dirección de correo electrónico de la cuenta de servicio, ya que la necesitarás más adelante para realizar la llamada a la API.

Proporcionar metadatos sobre su cristalería

Cuando estés listo para enviar tu Glassware, deberás proporcionar la siguiente información. Esto nos permite configurar tu Glassware para que se autentique de forma correcta cuando la implementas.

  • Tu URL de autenticación, a la que se redirecciona a los usuarios cuando activan tu Glassware en MyGlass.
  • El tipo de cuenta (la string que usarás cuando llames a las API de AccountManager para Android en el dispositivo Glass)
  • El nombre de paquete de tu aplicación de AndroidManifest.xml
  • El ID numérico del proyecto de la API de Google del proyecto que creaste antes
  • El APK que se subirá a MyGlass. Para las pruebas, solo debes proporcionar este APK una vez a fin de manejar la descarga inicial cuando tu Glassware esté activado desde MyGlass. Después de eso, para iterar y depurar de manera local, reemplaza el APK en tu dispositivo. Ten en cuenta que este APK debe cumplir con los siguientes criterios:
    • Debe estar alineado.
    • No debes realizar cambios 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 aplica alguno de estos cambios).
    • Debe ser inferior a 50 megabytes.
    • Debe compilarse con la versión más reciente de GDK.

Implementa el flujo de autenticación

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

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

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

  2. El usuario ingresa sus credenciales en la 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 duplicación al método mirror.accounts.insert. Este método requiere que especifiques el alcance https://www.googleapis.com/auth/glass.thirdpartyauth cuando compilas el objeto de servicio de duplicación. En los ejemplos de creación de cuenta, se muestran ejemplos de cómo realizar esta llamada a la API con HTTP o Java sin procesar.

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

    Nombre de la propiedad Valor Descripción
    features[] lista de strings 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 La clave asociada a un par clave-valor de datos del usuario en particular.
    userData[].value string 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 del 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 de Glass del usuario, donde ahora puedes acceder a ella mediante la clase AccountManager.

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 los cancela, muestra un mensaje de error bien diseñado.
  • Asegúrate de que los alcances que solicitas se estén usando en tu Glassware.
  • Si puedes conectar una cuenta de usuario, asegúrate de conectarla.
  • Siempre que sea posible, se debe crear una copia de seguridad de los datos del usuario en la nube.

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

Duplicado o híbrido sin una cuenta

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

Duplicar con una cuenta

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

Híbrida con una cuenta

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

Duplicado o híbrido con una cuenta y alcances personalizados

  1. Después de activarla en MyGlass, se abrirá la 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ó, muéstrale los campos de acceso, permítele acceder y, luego, envíalo a tus permisos internos
    • Si el usuario no tiene una cuenta, proporciona un vínculo para crear una.
  2. Cuando el usuario acepte tus alcances personalizados, envíalo a los alcances de Google.
  3. Envía una solicitud a la API de Mirror para insertar la cuenta de GDK.
    • Enviar al usuario a la página de configuración con los valores predeterminados razonables seleccionados.
    • Envía al usuario una página de confirmación. Cierra la ventana emergente si no se requiere ninguna configuración adicional.

Duplicación o híbrida con una app para Android o iPhone

  1. Después de activarla en MyGlass, se abrirá la URL de autenticación en una ventana emergente.
  2. Esto envía directamente al usuario a los alcances que debe aceptar.
  3. Una vez que el usuario acepta los permisos, sucede lo siguiente:
    • Si el usuario tiene la app complementaria y está autenticado, 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 iOS Store.
  4. Después de instalar la app y autenticarla, cierra la ventana emergente.

GDK y sin cuenta

Se necesita activar Glassware en MyGlass para este proceso.

GDK con una cuenta

  1. Después de activarla en MyGlass, se abrirá la 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 alcances.
  3. Envía una solicitud a la API de Mirror para insertar la cuenta de GDK.
  4. Muestra la pantalla de confirmación y ciérrala después de mostrarla durante un período breve.

Ejemplos de creación de cuenta

Usa las bibliotecas cliente para la API de Mirror siempre que sea posible. Esto facilita la llamada 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 el cuerpo de JSON que espera. Realizar solicitudes HTTP sin procesar en nombre de una cuenta de servicio es mucho más complicado (consulta Usa OAuth 2.0 para aplicaciones de servidor a servidor a fin de obtener todos los detalles), por lo que recomendamos que uses una de nuestras bibliotecas cliente de la API de Google si es posible para facilitar esta tarea.

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 la URL de autenticación en el paso 1 de Implementa el 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 AccountManager 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 Auth desde 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);