Autenticação para Glassware GDK

Se o Glassware do GDK precisar autenticar usuários em um serviço da Web, ele vai fornecer uma API que permite que o usuário insira as credenciais ao instalar o Glassware.

Ao usar essa API, você oferece uma experiência consistente para os usuários do Glass e evita a sobrecarga da implementação de seus próprios esquemas de autenticação personalizados.

Como criar uma conta de serviço de API do Google

Quando a autenticação é configurada corretamente, o back-end do app da Web usa a API Mirror para enviar as informações da conta dos usuários para o Glass depois que eles se autenticam com seu serviço.

Para acessar essa API, crie um projeto da API do Google e um ID do cliente para uma "conta de serviço" (e não para um "aplicativo da Web"). Ao usar uma conta de serviço, os usuários não precisam conceder permissão ao app para enviar as credenciais ao Glass e não vão receber a página de permissões do OAuth e a página de autenticação novamente.

Para criar essa conta:

  1. Acesse o Google Developers Console.
  2. Clique no botão Criar projeto e insira as informações solicitadas.
  3. Depois que o projeto for criado, anote o número do projeto, que será necessário mais tarde.
  4. Em APIs e autorização, clique em APIs e ative a API Google Mirror para o novo projeto.
  5. Em APIs e autorização, clique em Credenciais e em Criar novo ID do cliente. Marque a caixa Conta de serviço para criar um novo ID do cliente OAuth 2.0 para o projeto.
  6. Uma janela pop-up informará que a chave privada está sendo baixada para seu computador e fornecerá a senha dessa chave. Depois de fechar esta janela, não será possível fazer o download desta chave privada nem conferir a senha novamente. Se eles forem perdidos, será necessário criar um novo.
  7. Anote o endereço de e-mail da conta de serviço. Você precisará dele mais tarde para fazer a chamada de API.

Como fornecer metadados sobre seus Glassware

Quando estiver tudo pronto para enviar o Glassware, você precisará fornecer as informações a seguir. Isso nos permite configurar o Glassware para ser autenticado corretamente quando você o implementar.

  • Seu URL de autenticação, para onde os usuários são redirecionados quando ativam o Glassware no MyGlass.
  • O tipo de conta (a string que você vai usar ao chamar as APIs AccountManager do Android no dispositivo Glass)
  • O nome do pacote do app no AndroidManifest.xml
  • O ID do projeto da API do Google numérico do projeto que você criou acima
  • O APK a ser enviado para o MyGlass. Para testes, você só precisa fornecer esse APK uma vez para processar o download inicial quando o Glassware for ativado no MyGlass. Depois disso, você poderá iterar e depurar localmente substituindo o APK no dispositivo. Esse APK precisa atender aos seguintes critérios:
    • Ele precisa estar alinhado ao ZIP.
    • Não faça nenhuma mudança no nome do pacote ou na chave de assinatura particular depois disso. O gerenciador de pacotes do Android não permite upgrades se uma dessas mudanças for feita.
    • Ele precisa ter menos de 50 megabytes.
    • Ele precisa ser compilado usando a versão mais recente do GDK.

Implementar o fluxo de autenticação

O diagrama a seguir mostra o fluxo de autenticação básico para GDK Glassware:

Para implementar o fluxo de autenticação:

  1. Quando os usuários ativam o Glassware no MyGlass, eles são redirecionados para o URL de autenticação. Essas solicitações incluem um parâmetro de consulta chamado userToken, que você vai precisar usar mais tarde.

  2. O usuário insere as credenciais na página de autenticação.

  3. Seu servidor valida as credenciais do usuário. Se as credenciais forem válidas, faça uma chamada da API Mirror para o método mirror.accounts.insert. Esse método exige que você especifique o escopo https://www.googleapis.com/auth/glass.thirdpartyauth ao criar seu objeto de serviço de espelho. Exemplos de como fazer essa chamada de API usando HTTP bruto ou Java são mostrados nos exemplos de criação de conta.

    Os parâmetros e o corpo da solicitação fornecidos abaixo representam as mesmas informações que você forneceria para o AccountManager do Android se estivesse criando a conta diretamente no dispositivo.

    Nome da propriedade Valor Descrição
    features[] lista de strings Uma lista de recursos (consulte AccountManager.hasFeatures).
    password string A senha da conta (consulte AccountManager.getPassword). Recomendamos não armazenar a senha real do usuário neste campo, mas usá-lo para armazenar dados particulares de longa duração, como um token de atualização.
    userData[] lista de objetos Um ou mais pares de dados do usuário associados à conta (consulte AccountManager.getUserData).
    userData[].key string A chave associada a um par de chave-valor de dados do usuário específico.
    userData[].value string O valor associado a um par de chave-valor de dados do usuário específico.
    authTokens[] lista de objetos Um ou mais tokens de autenticação associados à conta (consulte AccountManager.getAuthToken).
    authTokens[].type string O tipo do token de autenticação.
    authTokens[].authToken string O token de autenticação.

  4. Ao receber a solicitação mirror.account.insert, a API Mirror envia a conta para os dispositivos Glass do usuário, onde agora é possível acessá-la usando a classe AccountManager.

Siga estas diretrizes para implementar um fluxo de autenticação fácil de usar:

  • Otimize seu fluxo para dispositivos móveis.
  • Se o fluxo tiver um escopo e o usuário o cancelar, tenha uma mensagem de erro bem projetada.
  • Verifique se os escopos solicitados estão sendo usados no Glassware.
  • Se uma conta de usuário puder ser conectada, faça isso.
  • Sempre que possível, os dados do usuário devem ser armazenados na nuvem.

Para manter a consistência na autenticação do Glassware, use um dos seguintes fluxos de autenticação:

Espelhado ou híbrido sem uma conta

  1. Depois de ativar no MyGlass, seu URL de autenticação será aberto em um pop-up.
  2. Isso envia o usuário diretamente aos escopos para aceitar.
  3. Depois que o usuário aceitar ou cancelar os escopos, feche o pop-up.

Espelhamento com uma conta

  1. Depois de ativar o recurso no MyGlass, o URL de autenticação será aberto em um pop-up.
    • Se o usuário já tiver feito login no seu serviço, envie-o diretamente para os escopos.
    • Se o usuário não estiver conectado, mostre os campos de login, permita que ele faça login no serviço e envie para os escopos.
    • Se o usuário não tiver uma conta, forneça um link para criar uma. Os usuários precisam ter uma maneira de criar uma conta como parte do fluxo de instalação.
  2. O usuário aceita os escopos.
    • Se o Glassware tiver configurações configuráveis, envie o usuário para a página de configurações com os padrões razoáveis selecionados.
    • Se o Glassware não tiver configurações configuráveis, envie o usuário para uma página de confirmação. Feche o pop-up se nenhuma configuração adicional for necessária.

Híbrido com uma conta

  1. Depois de ativar o recurso no MyGlass, o URL de autenticação será aberto em um pop-up.
    • Se o usuário já tiver feito login no seu serviço, envie-o diretamente para os escopos.
    • Se o usuário não estiver conectado, mostre os campos de login, permita que ele faça login e envie para os escopos.
    • Se o usuário não tiver uma conta, forneça um link para criar uma.
  2. O usuário aceita os escopos.
  3. Envie uma solicitação para a API Mirror para inserir a conta do GDK.
    • Enviar o usuário para a página de configurações com padrões razoáveis selecionados.
    • Enviar uma página de confirmação ao usuário. Feche o pop-up se nenhuma outra configuração for necessária.

Espelho ou híbrido com uma conta e escopos personalizados

  1. Depois de ativar o recurso no MyGlass, o URL de autenticação será aberto em um pop-up.
    • Se o usuário já tiver feito login no seu serviço, envie o usuário para seus escopos internos.
    • Se o usuário não estiver conectado, mostre os campos de login, permita que ele faça login e envie para seus escopos internos.
    • Se o usuário não tiver uma conta, forneça um link para criar uma.
  2. Quando o usuário aceitar seus escopos personalizados, direcione-o para os escopos do Google.
  3. Envie uma solicitação para a API Mirror para inserir a conta do GDK.
    • Enviar o usuário para a página de configurações com padrões razoáveis selecionados.
    • Enviar uma página de confirmação ao usuário. Feche o pop-up se nenhuma outra configuração for necessária.

Espelhamento ou híbrido com um app para Android/iPhone

  1. Depois de ativar no MyGlass, seu URL de autenticação será aberto em um pop-up.
  2. Isso envia o usuário diretamente aos escopos para aceitar.
  3. Depois que o usuário aceita os escopos:
    • Se o usuário tiver o app complementar e estiver autenticado, feche a janela pop-up.
    • Caso contrário, direcione o usuário a um intersticial que o direcione para fazer o download do app na Google Play Store ou na iOS Store.
  4. Depois de instalar o app e fazer a autenticação, feche a janela pop-up.

GDK e nenhuma conta

Ativar o Glassware no MyGlass é tudo o que é necessário para esse fluxo.

GDK com uma conta

  1. Depois de ativar no MyGlass, seu URL de autenticação será aberto em um pop-up.
    • Se o usuário já estiver conectado ao seu serviço, envie-o para a tela de confirmação.
    • Se o usuário não tiver feito login, mostre os campos de login, permita que ele faça login e envie para a tela de confirmação.
    • Se o usuário não tiver uma conta, forneça um link para criar uma.
  2. O usuário aceita os escopos.
  3. Envie uma solicitação para a API Mirror para inserir a conta do GDK.
  4. Mostre a tela de confirmação e feche-a depois de mostrá-la por um curto período.

Exemplos de criação de conta

Use as bibliotecas de cliente para a API Mirror sempre que possível. Isso facilita a chamada de mirror.accounts.insert para criar a conta.

Exemplo de HTTP bruto

O exemplo abaixo mostra apenas o URL da solicitação e um exemplo do corpo JSON que ele espera. Fazer solicitações HTTP brutas em nome de uma conta de serviço é muito mais complicado. Para saber todos os detalhes, consulte Como usar o OAuth 2.0 para aplicativos de servidor para servidor. Portanto, recomendamos que você use uma das nossas bibliotecas de cliente da API Google se possível para facilitar isso.

Método de solicitação e URL:

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

Corpo da solicitação:

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

Substitua {userToken} no URL da solicitação pelo token transmitido para o URL de autenticação na etapa 1 de Implementação do fluxo de autenticação.

Exemplo em Java

Este exemplo mostra como usar a biblioteca de cliente Java para chamar 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();
  }
}

Como recuperar contas no Glass

Extrair e usar objetos Account no Glass é semelhante ao uso do AccountManager padrão do Android.

  1. Declare as seguintes permissões de manifesto no arquivo AndroidManifest.xml:

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

  2. Extraia as contas do 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. Extraia um token de autenticação do 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);