Autenticación de usuarios

Los protocolos de autenticación web usan funciones HTTP, pero las Apps de Chrome se ejecutan dentro del contenedor de la app. No se cargan a través de HTTP y no pueden realizar redireccionamientos ni establecer cookies.

Usa la API de Chrome Identity para autenticar usuarios: getAuthToken para los usuarios que accedieron a su Cuenta de Google y launchWebAuthFlow para los usuarios que accedieron a cuentas ajenas a Google. Si tu app usa su propio servidor para autenticar usuarios, deberás usar este último.

Cómo funciona

Los usuarios de las Apps de Chrome tienen una Cuenta de Google asociada a su perfil. Las apps pueden obtener tokens de OAuth2 para estos usuarios mediante la API de getAuthToken.

Las apps que deseen realizar una autenticación con proveedores de identidad ajenos a Google deben llamar a launchWebAuthFlow. Este método usa una ventana emergente del navegador para mostrar las páginas del proveedor y captura los redireccionamientos a los patrones de URL específicos. Las URLs de redireccionamiento se pasan a la app, que extrae el token de la URL.

Autenticación de la Cuenta de Google

Estos son los cinco pasos que debes completar:

  1. Agrega permisos a tu manifiesto y sube la app.
  2. Copia la clave del archivo manifest.json instalado en tu manifiesto de origen para que el ID de aplicación se mantenga constante durante el desarrollo.
  3. Obtén un ID de cliente de OAuth2 para tu app de Chrome.
  4. Actualiza tu manifiesto para incluir el ID de cliente y los alcances.
  5. Obtén el token de autenticación.

Agrega permisos y sube la app

Debes asegurarte de que el permiso de identidad esté en tu manifiesto. Luego, puedes subir tu app a la página de administración de apps y extensiones (consulta Publicar).

"permissions": [
  "identity"
]

Copiar la clave en tu manifiesto

Cuando registres tu aplicación en la consola de OAuth de Google, deberás proporcionar el ID de la aplicación, que se verificará durante las solicitudes de token. Por lo tanto, es importante tener un ID de aplicación coherente durante el desarrollo.

Para mantener constante el ID de aplicación, debes copiar la clave del manifest.json instalado en el manifiesto de origen. No es la tarea más elegante, pero aquí te explicamos cómo:

  1. Ve al directorio de datos del usuario. Ejemplo en macOS: ~/Library/Application\ Support/Google/Chrome/Default/Extensions
  2. Enumera las apps y extensiones instaladas, y haz coincidir el ID de tu app en la página de administración de apps y extensiones con el mismo ID aquí.
  3. Ve al directorio de la app instalada (esta será una versión dentro del ID de la app). Abre el manifest.json instalado (pico es una forma rápida de abrir el archivo).
  4. Copia la "clave" del archivo manifest.json instalado y pégala en el archivo de manifiesto de origen de tu app.

Obtén tu ID de cliente de OAuth2

Debes registrar tu aplicación en la Consola de APIs de Google para obtener el ID de cliente:

  1. Accede a la Consola de APIs de Google con la misma Cuenta de Google que usaste para subir la app a Chrome Web Store.
  2. Para crear un proyecto nuevo, expande el menú desplegable de la esquina superior izquierda y selecciona el elemento de menú Crear....
  3. Una vez que hayas creado y nombrado, ve al elemento del menú de navegación "Servicios" y activa los servicios de Google que necesite tu app.
  4. Ve al elemento de menú de navegación “Acceso a la API” y haz clic en el botón azul Crear un ID de cliente de OAuth 2.0....
  5. Ingresa la información de desarrollo de la marca solicitada y selecciona el tipo Aplicación instalada.
  6. Selecciona Aplicación de Chrome y, luego, ingresa el ID de aplicación (el mismo que se muestra en la página de administración de apps y extensiones).

Actualiza tu manifiesto con los permisos y el ID de cliente de OAuth2

Debes actualizar tu manifiesto para incluir el ID de cliente y los alcances. Este es el ejemplo de "oauth2" para la muestra de gdrive:

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

Obtén tokens de acceso

Ahora, estás listo para obtener el token de autenticación con una llamada a identity.getAuthToken.

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

Interacción del usuario

Cuando llamas a getAuthToken, puedes pasar una marca ('interactive': true en el ejemplo anterior) que indica si deseas que se llame a la API en modo interactivo o silencio. Si invocas la API en modo interactivo, el usuario verá una IU de acceso o aprobación cuando sea necesario, como se muestra en la siguiente captura de pantalla:

Captura de pantalla que muestra la IU cuando una app usa la API de Identity para autenticar una Cuenta de Google

Si invocas la API en modo silencioso, la API solo mostrará un token si es posible producir uno sin mostrar ninguna IU. Esto es útil cuando, por ejemplo, una app realiza el flujo durante su inicio o, en general, cuando no hay gestos del usuario involucrados.

La práctica recomendada que sugerimos es usar el modo silencioso cuando no hay gestos del usuario involucrados, y usar el modo interactivo si hay un gesto del usuario (por ejemplo, si el usuario hizo clic en el botón Acceder en tu app). Ten en cuenta que no imponemos ningún requisito de gestos.

Almacenamiento en caché

Chrome tiene una caché de tokens de acceso en la memoria, por lo que puedes llamar a getAuthToken cada vez que necesites usar un token. La caché controla automáticamente el vencimiento del token.

Puedes ver el estado actual de la caché del token en chrome://identity-internals.

En algunos casos, como cuando el usuario cambia su contraseña, los tokens de acceso no vencidos dejarán de funcionar. Las llamadas a la API que usen el token comenzarán a mostrarse con el código de estado HTTP 401. Si detectas que esto ha ocurrido, puedes quitar el token no válido de la caché de Chrome llamando a identity.removeCachedAuthToken.

Ejemplo 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);
      }
    });
  }
}

Autenticación con cuentas ajenas a Google

Estos son los tres pasos que debes completar:

  1. Regístrate con el proveedor.
  2. Agrega permisos para los recursos del proveedor a los que accederá tu app.
  3. Obtén el token de autenticación.

Regístrate con el proveedor

Debes registrar un ID de cliente de OAuth2 con el proveedor y configurarlo como un sitio web. Para que se ingrese el URI de redireccionamiento durante el registro, usa la URL del formulario: https://<extension-id>.chromiumapp.org/<anything-here>

Por ejemplo, si el ID de tu app es abcdefghijklmnopqrstuvwxyzabcdef y quieres que provider_cb sea la ruta de acceso para distinguirlo de los URI de redireccionamiento de otros proveedores, debes usar lo siguiente: https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb

Agregar permisos para el proveedor

Para realizar XHR de origen cruzado a los extremos de la API del proveedor, debes incluir en la lista de entidades permitidas los patrones adecuados en los permisos:

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

Obtén el token

Para obtener el token, haz lo siguiente:

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

El elemento <url-to-do-auth> es la URL que se usa para autenticar la identidad del proveedor desde un sitio web. Por ejemplo, supongamos que estás realizando un flujo OAuth2 con un proveedor, registraste tu app con el ID de cliente 123456789012345 y quieres acceder a las fotos del usuario en el sitio web del proveedor: 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

El proveedor realizará la autenticación y, si corresponde, le mostrará al usuario la IU de acceso o aprobación. Luego, se redireccionará a https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb#authToken=<auth-token>

Chrome lo capturará e invocará la devolución de llamada de la app con la URL de redireccionamiento completa. La app debe extraer el token de la URL.

Modo interactivo frente a modo silencioso

Cuando llamas a launchWebAuthFlow, puedes pasar una marca ('interactive': true en el ejemplo anterior) que indica si deseas que se llame a la API en modo interactivo o no (también conocido como modo silencioso). Si invocas la API en modo interactivo, el usuario verá la IU, si es necesario, para obtener el token (IU de acceso o IU de aprobación; o, en ese caso, cualquier IU específica del proveedor).

Si invocas la API en modo silencioso, la API solo mostrará un token si el proveedor puede proporcionarlo sin mostrar ninguna IU. Esto es útil en casos en los que una app está realizando el flujo durante el inicio, por ejemplo, o, en general, cuando no hay gestos del usuario involucrados.

La práctica recomendada que sugerimos es usar el modo silencioso cuando no hay gestos del usuario involucrados, y usar el modo interactivo si hay un gesto del usuario (por ejemplo, si el usuario hizo clic en el botón Acceder en tu app). Ten en cuenta que no aplicamos el requisito de gestos.