Autenticação para GlassD GDK

Se o GDK Glassware precisar autenticar usuários em um serviço da Web, o GDK fornecerá uma API que permitirá ao usuário inserir as credenciais ao instalar o Glassware.

Com essa API, você oferece uma experiência consistente aos usuários do Google Glass e evita a sobrecarga de implementar seus próprios esquemas de autenticação personalizados.

Observação: no momento, só é possível testar e usar essa API depois do upload do APK para o MyGlass, o que acontece durante o processo de revisão.

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

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

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

Para criar essa conta, faça o seguinte:

1. Acesse o Google Developers Console.
2. Clique no botão Create Project 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 no novo projeto.
5. Em APIs e autenticaçã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 transferida por download para o computador e fornecerá a senha dessa chave. Após fechar essa janela, não será mais possível fazer o download dessa chave privada ou ver a senha novamente. Se eles forem perdidos, crie 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 o Glassware

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

• Seu URL de autenticação, para o qual os usuários são redirecionados quando ativam seu Glassware no MyGlass.
• O tipo de conta (a string que você usará ao chamar as APIs do Android AccountManager no dispositivo Glass).
• O nome do pacote do aplicativo do AndroidManifest.xml
• O ID numérico do projeto da API do Google do projeto criado acima
• O APK a ser enviado por upload no 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, é possível iterar e depurar localmente substituindo o APK no dispositivo. Esse APK precisa atender a estes critérios:
  • Ele precisa estar alinhado no zip.
  • Não é permitido fazer mudanças no nome do pacote ou na chave de assinatura privada depois disso. O gerenciador de pacotes do Android não permite upgrades se qualquer uma dessas mudanças.
  • Ele precisa ter menos de 50 megabytes.
  • Ele precisa ser compilado usando a versão mais recente do GDK.

Como 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, faça o seguinte:

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ê precisa usar mais tarde.

   Aviso: não armazene esse token de usuário. Ele deve ser usado somente pelos endpoints de autenticação do Google para mapear a solicitação de volta ao usuário originário durante essa sessão e não contém informações que possam ser usadas para identificar o usuário de maneira persistente. Não há garantia de que o token será igual se o usuário fizer a autenticação com o mesmo Glassware várias vezes ou se o usuário fizer a autenticação com um Glassware diferente do mesmo desenvolvedor.

2. O usuário digita 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 o objeto de serviço Mirror. Veja exemplos de como fazer essa chamada de API usando HTTP ou Java brutos 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 ao AccountManager do Android se fosse 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 que você não armazene a senha real do usuário nesse campo, mas use-a 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 específico de chave-valor de dados do usuário.
   userData[].value	string	O valor associado a um par específico de chave-valor de dados do usuário.
   authTokens[]	lista de objetos	Um ou mais tokens de autenticação associados à conta (consulte AccountManager.getAuthToken).
   authTokens[].type	string	Tipo de 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 você pode acessá-la usando a classe AccountManager.

Fluxos de autenticação recomendados

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 cancelar, tenha uma mensagem de erro bem projetada.
• Verifique se os escopos solicitados estão sendo usados no seu Glassware.
• É possível conectar uma conta de usuário.
• Sempre que possível, é preciso fazer backup dos dados do usuário na nuvem.

Observação: instale o Glassware pelo menos uma vez no MyGlass para garantir que o fluxo de autenticação seja bem-sucedido. Se você tiver feito isso uma vez, poderá instalar via sideload para fins de teste.

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

Espelhamento ou trabalho híbrido sem conta

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

Espelhar com uma conta

1. Depois de alternar no MyGlass, seu URL de autenticação é aberto em um pop-up.
   • Se o usuário já tiver feito login no 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-os aos 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 processo de fluxo de instalação.
2. O usuário aceita escopos.
   • Se o Glassware tiver configurações configuráveis, direcione o usuário para a página de configurações com padrões razoáveis selecionados.
   • Se o Glassware não tiver configurações ajustáveis, envie o usuário para uma página de confirmação. Feche o pop-up se nenhuma outra configuração for necessária.

Híbrido com uma conta

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

Espelhamento ou abordagem híbrida com uma conta e escopos personalizados

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

Espelhamento ou abordagem híbrida com um app para Android/iPhone

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

GDK e sem conta

Para ativar esse fluxo, basta ativar o Glassware no MyGlass.

GDK com uma conta

1. Depois de alternar no MyGlass, seu URL de autenticação é aberto em um pop-up.
   • Se o usuário já tiver feito login no serviço, envie-o para a tela de confirmação.
   • Se o usuário não estiver conectado, exiba os campos de login, permita que eles façam login e os envie para a tela de confirmação.
   • Se o usuário não tiver uma conta, forneça um link para criar uma conta.
2. O usuário aceita escopos.
3. Envie uma solicitação à API Mirror para inserir a conta do GDK.
4. Mostre a tela de confirmação e feche-a após um curto período.

Exemplos de criação de conta

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

Exemplo de HTTP bruto

O exemplo abaixo mostra apenas o URL da solicitação e um exemplo do corpo JSON esperado. Fazer solicitações HTTP brutas em nome de uma conta de serviço é muito mais complicado. Consulte o artigo Como usar o OAuth 2.0 para aplicativos de servidor para servidor (em inglês) para mais detalhes. Portanto, recomendamos que você use uma das nossas bibliotecas de cliente da API do Google para facilitar esse processo.

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 que foi transmitido para o URL de autenticação na etapa 1 de Como implementar o fluxo de autenticação.

Exemplo de 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 Google Glass

A recuperação e o uso de objetos Account no Google Glass são semelhantes ao uso do AccountManager padrão do Android.

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

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

2. Recupere 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. Recupere 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);