Autenticação do usuário

Os protocolos de autenticação da Web utilizam recursos HTTP, mas os apps do Chrome são executados dentro do contêiner do app. Eles não são carregados por HTTP e não podem executar redirecionamentos nem definir cookies.

Use a API Chrome Identity para autenticar usuários: o getAuthToken para usuários conectados à Conta do Google e o launchWebAuthFlow para usuários conectados a uma conta que não é do Google. Se o app usar o próprio servidor para autenticar usuários, será necessário usar o segundo.

Como funciona

Os usuários dos Aplicativos do Google Chrome têm uma Conta do Google associada ao perfil. Os apps podem receber tokens OAuth2 para esses usuários usando a API getAuthToken.

Os apps que querem realizar a autenticação com provedores de identidade que não são do Google precisam chamar launchWebAuthFlow. Esse método usa um pop-up do navegador para mostrar as páginas do provedor e captura redirecionamentos para padrões de URL específicos. Os URLs de redirecionamento são transmitidos ao app, que extrai o token do URL.

Autenticação da Conta do Google

Aqui estão as cinco etapas que você precisa concluir:

  1. Adicione permissões ao manifesto e faça upload do app.
  2. Copie a chave no manifest.json instalado no manifesto de origem para que o ID do aplicativo permaneça constante durante o desenvolvimento.
  3. Receba um ID do cliente OAuth2 para seu app do Chrome.
  4. Atualize o manifesto para incluir o ID do cliente e os escopos.
  5. Receba o token de autenticação.

Adicionar permissões e fazer upload do app

Verifique se a permissão de identidade está no manifesto. Em seguida, faça upload do app na página de gerenciamento de apps e extensões (consulte Publicar).

"permissions": [
  "identity"
]

Copiar chave para o manifesto

Ao registrar seu aplicativo no console do Google OAuth, você vai fornecer o ID do aplicativo, que será verificado durante as solicitações de token. Portanto, é importante ter um ID do aplicativo consistente durante o desenvolvimento.

Para manter o ID do aplicativo constante, copie a chave no manifest.json instalado para o manifesto de origem. Essa não é a tarefa mais graciosa, mas é assim que acontece:

  1. Acesse o diretório de dados do usuário. Exemplo no macOS: ~/Library/Application\ Support/Google/Chrome/Default/Extensions
  2. Liste os apps e extensões instalados e associe o ID do app na página de gerenciamento de apps e extensões a ele.
  3. Acesse o diretório do app instalado (uma versão dentro do ID do app). Abra o manifest.json instalado (o pico é uma maneira rápida de abrir o arquivo).
  4. Copie a "chave" no manifest.json instalado e cole no arquivo de manifesto de origem do app.

Receber o ID do cliente OAuth2

Você precisa registrar seu app no Console de APIs do Google para receber o ID do cliente:

  1. Faça login no Console de APIs do Google com a mesma Conta do Google usada para fazer upload do seu aplicativo na Chrome Web Store.
  2. Para criar um novo projeto, abra o menu suspenso no canto superior esquerdo e selecione o item de menu Create....
  3. Depois de criar e nomear, acesse o item de menu de navegação "Services" e ative os serviços do Google necessários para o app.
  4. Acesse o item de menu de navegação "Acesso à API" e clique no botão azul Criar um ID de cliente OAuth 2.0....
  5. Insira as informações de marca solicitadas e selecione o tipo Aplicativo instalado.
  6. Selecione Aplicativo do Chrome e insira o ID do aplicativo (o mesmo ID exibido na página de gerenciamento de apps e extensões).

Atualizar o manifesto com o ID e os escopos do cliente OAuth2

É necessário atualizar o manifesto para incluir o ID do cliente e os escopos. Confira o exemplo "oauth2" para o exemplo do gdrive:

"oauth2": {
    "client_id": "665859454684.apps.googleusercontent.com",
    "scopes": [
      "https://www.googleapis.com/auth/drive"
    ]
  }

Receber tokens de acesso

Agora você pode receber o token de autenticação chamando identity.getAuthToken.

chrome.identity.getAuthToken({ 'interactive': true }, function(token) {
  // Use the token.
});

Interação do usuário

Ao chamar getAuthToken, é possível transmitir uma flag ('interactive': true no exemplo acima) que indica se você quer que a API seja chamada no modo interativo ou silencioso. Se você invocar a API no modo interativo, o usuário vai receber uma interface de login e/ou aprovação quando necessário, como mostrado na captura de tela abaixo:

Captura de tela mostrando a interface quando um app usa a API Identity para autenticar uma Conta do Google

Se você invocar a API no modo silencioso, ela só vai retornar um token se for possível produzir um sem mostrar nenhuma interface. Isso é útil nos casos em que um app está executando o fluxo na inicialização, por exemplo, ou em geral nos casos em que não há um gesto do usuário envolvido.

A prática recomendada é usar o modo silencioso quando não há gesto do usuário envolvido e usar o modo interativo quando há um gesto do usuário (por exemplo, o usuário clicou no botão "Fazer login" no app). Não exigimos nenhum requisito de gesto.

Armazenamento em cache

O Chrome tem um cache em memória de tokens de acesso. Assim, você pode chamar getAuthToken sempre que precisar usar um token. A expiração do token é tratada automaticamente pelo cache.

O estado atual do cache de token pode ser visto em chrome://identity-internals.

Há alguns casos, como quando o usuário muda a senha, em que os tokens de acesso não expirados deixam de funcionar. As chamadas de API que usam o token vão começar a retornar com um código de status HTTP 401. Se você detectar que isso aconteceu, poderá remover o token inválido do cache do Chrome chamando identity.removeCachedAuthToken.

Exemplo de uso de removeCachedAuthToken:

// callback = function (error, httpStatus, responseText);
function authenticatedXhr(method, url, callback) {
  var retry = true;
  function getTokenAndXhr() {
    chrome.identity.getAuthToken({/* details */},
                                 function (access_token) {
      if (chrome.runtime.lastError) {
        callback(chrome.runtime.lastError);
        return;
      }

      var xhr = new XMLHttpRequest();
      xhr.open(method, url);
      xhr.setRequestHeader('Authorization',
                           'Bearer ' + access_token);

      xhr.onload = function () {
        if (this.status === 401 && retry) {
          // This status may indicate that the cached
          // access token was invalid. Retry once with
          // a fresh token.
          retry = false;
          chrome.identity.removeCachedAuthToken(
              { 'token': access_token },
              getTokenAndXhr);
          return;
        }

        callback(null, this.status, this.responseText);
      }
    });
  }
}

Autenticação de contas que não são do Google

Aqui estão as três etapas que você precisa concluir:

  1. Faça o registro no provedor.
  2. Adicione permissões para os recursos do provedor que o app vai acessar.
  3. Receba o token de autenticação.

Registrar com o provedor

Você precisa registrar um ID do cliente OAuth2 com o provedor e configurá-lo como um site. Para que o URI de redirecionamento seja inserido durante o registro, use o URL do formulário: https://<extension-id>.chromiumapp.org/<anything-here>

Por exemplo, se o ID do app for abcdefghijklmnopqrstuvwxyzabcdef e você quiser que provider_cb seja o caminho, para diferenciá-lo com URIs de redirecionamento de outros provedores, use: https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb

Adicionar permissões para o provedor

Para fazer XHRs de origem cruzada nos endpoints da API do provedor, é necessário permitir os padrões adequados nas permissões:

"permissions": [
  ...
  "https://www.website-of-provider-with-user-photos.com/photos/*"
]

Receber o token

Para receber o token:

chrome.identity.launchWebAuthFlow(
  {'url': '<url-to-do-auth>', 'interactive': true},
  function(redirect_url) { /* Extract token from redirect_url */ });

O <url-to-do-auth> é o URL usado para autenticar o provedor a partir de um site. Por exemplo, digamos que você esteja executando o fluxo OAuth2 com um provedor e tenha registrado seu app com o ID do cliente 123456789012345 e queira acessar as fotos do usuário no site do provedor: https://www.website-of-provider-with-user-photos.com/dialog/oauth?client_id=123456789012345& redirect_uri=https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb&response_type=token&scope=user_photos

O provedor fará a autenticação e, se apropriado, mostrará a interface de login e/ou aprovação ao usuário. Ele vai redirecionar para https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb#authToken=<auth-token>

O Chrome vai capturar isso e invocar o callback do app com o URL de redirecionamento completo. O app precisa extrair o token do URL.

Modo interativo x silencioso

Ao chamar launchWebAuthFlow, você pode transmitir uma flag ('interactive': true no exemplo acima) indicando se você quer que a API seja chamada no modo interativo ou não (modo silencioso). Se você invocar a API no modo interativo, a interface do usuário será mostrada ao usuário, se necessário, para receber o token (interface de login e/ou de aprovação ou qualquer interface específica do provedor).

Se você invocar a API no modo silencioso, ela só vai retornar um token se o provedor puder fornecer um token sem mostrar nenhuma interface. Isso é útil quando um app está executando o fluxo na inicialização do app, por exemplo, ou em geral, em casos em que não há gesto do usuário envolvido.

A prática recomendada é usar o modo silencioso quando não há gesto do usuário envolvido e usar o modo interativo quando há um gesto do usuário (por exemplo, o usuário clicou no botão "Fazer login" no app). Não exigimos o gesto.