OAuth 2.0 para aplicaciones web del lado del cliente

Este documento explica cómo implementar la autorización OAuth 2.0 para acceder a las API de Google desde una aplicación web JavaScript. OAuth 2.0 permite a los usuarios compartir datos específicos con una aplicación mientras mantienen la privacidad de sus nombres de usuario, contraseñas y otra información. Por ejemplo, una aplicación puede usar OAuth 2.0 para obtener permiso de los usuarios para almacenar archivos en sus Google Drives.

Este flujo de OAuth 2.0 se llama el flujo subvención implícita. Está diseñado para aplicaciones que acceden a las API solo mientras el usuario está presente en la aplicación. Estas aplicaciones no pueden almacenar información confidencial.

En este flujo, su aplicación abre una URL de Google que usa parámetros de consulta para identificar su aplicación y el tipo de acceso a la API que la aplicación requiere. Puede abrir la URL en la ventana actual del navegador o en una ventana emergente. El usuario puede autenticarse con Google y otorgar los permisos solicitados. Luego, Google redirige al usuario a su aplicación. El redireccionamiento incluye un token de acceso, que su aplicación verifica y luego usa para realizar solicitudes de API.

Prerrequisitos

Habilite las API para su proyecto

Cualquier aplicación que llama a las API de Google necesita para que estas APIs en la API Console.

Para habilitar una API para su proyecto:

  1. Open the API Library en el Google API Console.
  2. If prompted, select a project, or create a new one.
  3. El API Library listas de todas las APIs disponibles, agrupados por familias de productos y popularidad. Si la API desea activar no es visible en la lista, el uso de búsqueda para encontrarlo, o haga clic en Ver todos en la familia de productos al que pertenece.
  4. Seleccione la API que desea activar, a continuación, haga clic en el botón de activación.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

Crear credenciales de autorización

Cualquier aplicación que use OAuth 2.0 para acceder a las API de Google debe tener credenciales de autorización que identifiquen la aplicación en el servidor OAuth 2.0 de Google. Los siguientes pasos explican cómo crear credenciales para su proyecto. Luego, sus aplicaciones pueden usar las credenciales para acceder a las API que haya habilitado para ese proyecto.

  1. Go to the Credentials page.
  2. Haga clic en Crear credenciales> OAuth ID de cliente.
  3. Seleccionar el tipo de aplicación aplicación web.
  4. Completa el formulario. Las aplicaciones que utilizan JavaScript para hacer autorizado orígenes Google solicitudes de la API de JavaScript debe especificar autorizados. Los orígenes identifican los dominios desde los cuales su aplicación puede enviar solicitudes al servidor OAuth 2.0. Estos orígenes deben cumplir con las reglas de validación de Google .

Identificar ámbitos de acceso

Los ámbitos permiten que su aplicación solo solicite acceso a los recursos que necesita, al mismo tiempo que permite a los usuarios controlar la cantidad de acceso que otorgan a su aplicación. Por lo tanto, puede haber una relación inversa entre el número de alcances solicitados y la probabilidad de obtener el consentimiento del usuario.

Antes de comenzar a implementar la autorización OAuth 2.0, le recomendamos que identifique los ámbitos a los que su aplicación necesitará permiso para acceder.

El Scopes 2.0 API de OAuth documento contiene una lista completa de los alcances que puede utilizar el acceso a las API de Google.

Obtención de tokens de acceso de OAuth 2.0

Los siguientes pasos muestran cómo su aplicación interactúa con el servidor OAuth 2.0 de Google para obtener el consentimiento de un usuario para realizar una solicitud de API en su nombre. Su aplicación debe tener ese consentimiento antes de poder ejecutar una solicitud de API de Google que requiere la autorización del usuario.

Paso 1: configurar el objeto de cliente

Si está utilizando la biblioteca cliente de API de Google para JavaScript para manejar el flujo de OAuth 2.0, el primer paso consiste en configurar los gapi.auth2 y gapi.client objetos. Estos objetos permiten que su aplicación obtenga la autorización del usuario y realice solicitudes de API autorizadas.

El objeto de cliente identifica los ámbitos a los que su aplicación solicita permiso para acceder. Estos valores informan la pantalla de consentimiento que Google muestra al usuario.

Biblioteca cliente JS

La biblioteca cliente de JavaScript simplifica numerosos aspectos del proceso de autorización:

  1. Crea la URL de redireccionamiento para el servidor de autorización de Google y proporciona un método para dirigir al usuario a esa URL.
  2. Maneja la redirección desde ese servidor a su aplicación.
  3. Valida el token de acceso devuelto por el servidor de autorización.
  4. Almacena el token de acceso que el servidor de autorización envía a su aplicación y lo recupera cuando su aplicación posteriormente realiza llamadas API autorizadas.

El fragmento de código a continuación es un extracto del ejemplo completo se muestra más adelante en este documento. Este código inicializa el gapi.client objeto, que su aplicación utilizaría más adelante para hacer llamadas a la API. Cuando se crea ese objeto, el gapi.auth2 objeto, que la aplicación utiliza para comprobar y supervisar el estado de autorización del usuario, también se ha inicializado.

La llamada a gapi.client.init especifica los siguientes campos:

  • Los apiKey y clientId valores especifican las credenciales de autorización de la aplicación. Como se discutió en la credenciales de autorización creación de sección, estos valores se pueden obtener en el API Console. Tenga en cuenta que la clientId es necesario si su aplicación hace que las solicitudes de API autorizados. Las aplicaciones que solo realizan solicitudes no autorizadas solo pueden especificar una clave API.
  • El scope campo especifica una lista delimitada por espacios de acceso de ámbitos que corresponden a los recursos que su aplicación podría acceder en nombre del usuario. Estos valores informan la pantalla de consentimiento que Google muestra al usuario.

    Recomendamos que su aplicación solicite acceso a los ámbitos de autorización en contexto siempre que sea posible. Al solicitar el acceso a los datos del usuario en un contexto, a través de la autorización incrementales , ayuda a los usuarios a entender más fácilmente por las que su aplicación necesita el acceso que está solicitando.

  • Los discoveryDocs campo identifica una lista de documentos de la API de descubrimiento que utiliza su aplicación. Un documento de Discovery describe la superficie de una API, incluidos sus esquemas de recursos, y la biblioteca cliente de JavaScript usa esa información para generar métodos que las aplicaciones pueden usar. En este ejemplo, el código recupera el documento de descubrimiento para la versión 3 de la API de Google Drive.

Después de los gapi.client.init ultima llamada, el código establece el GoogleAuth variable para identificar el objeto de autenticación Google. Por último, el código establece un oyente que llama a una función cuando cambia el estado de inicio de sesión del usuario. (Esa función no está definida en el fragmento).

var GoogleAuth; // Google Auth object.
function initClient() {
  gapi.client.init({
      'apiKey': 'YOUR_API_KEY',
      'clientId': 'YOUR_CLIENT_ID',
      'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly',
      'discoveryDocs': ['https://www.googleapis.com/discovery/v1/apis/drive/v3/rest']
  }).then(function () {
      GoogleAuth = gapi.auth2.getAuthInstance();

      // Listen for sign-in state changes.
      GoogleAuth.isSignedIn.listen(updateSigninStatus);
  });
}

Extremos de OAuth 2.0

Si accede directamente a los puntos finales de OAuth 2.0, puede continuar con el siguiente paso.

Paso 2: Redirigir al servidor OAuth 2.0 de Google

Para solicitar permiso para acceder a los datos de un usuario, redirigir al usuario al servidor OAuth 2.0 de Google.

Biblioteca cliente JS

Llame a la GoogleAuth.signIn() método para dirigir al usuario al servidor de autorización de Google.

GoogleAuth.signIn();

En la práctica, la aplicación podría establecer un valor booleano para determinar si se debe llamar a la signIn() método antes de intentar realizar una llamada a la API.

El fragmento de código a continuación demuestra cómo iniciaría el flujo de autorización del usuario. Tenga en cuenta los siguientes puntos sobre el fragmento:

  • El GoogleAuth objeto referenciado en el código es la misma que la variable global se define en el fragmento de código en el paso 1 .

  • El updateSigninStatus función es un oyente que escucha los cambios en el estado de autorización del usuario. Su papel como oyente también se definió en el fragmento de código en el paso 1:
    GoogleAuth.isSignedIn.listen(updateSigninStatus);
  • El fragmento define dos variables globales adicionales:

    • isAuthorized es una variable booleana que indica si el usuario ya ha iniciado sesión. Este valor se puede ajustar cuando se carga la aplicación y actualiza si el usuario dentro o fuera de la aplicación.

      En este fragmento, el sendAuthorizedApiRequest función comprueba el valor de la variable para determinar si la aplicación debe intentar una solicitud de API que requiera autorización o mensaje al usuario para autorizar la aplicación.

    • currentApiRequest es un objeto que almacena los detalles acerca de la última petición de la API de que el usuario ha intentado. El valor del objeto se establece cuando la aplicación llama a la sendAuthorizedApiRequest función.

      Si el usuario ha autorizado la aplicación, la solicitud se ejecuta de inmediato. De lo contrario, la función redirige al usuario para iniciar sesión. Después el usuario inicia sesión, el updateSignInStatus función llama sendAuthorizedApiRequest , pasando por la misma solicitud que se intentó antes de que comenzara el flujo de autorización.

var isAuthorized;
var currentApiRequest;

/**
 * Store the request details. Then check to determine whether the user
 * has authorized the application.
 *   - If the user has granted access, make the API request.
 *   - If the user has not granted access, initiate the sign-in flow.
 */
function sendAuthorizedApiRequest(requestDetails) {
  currentApiRequest = requestDetails;
  if (isAuthorized) {
    // Make API request
    // gapi.client.request(requestDetails)

    // Reset currentApiRequest variable.
    currentApiRequest = {};
  } else {
    GoogleAuth.signIn();
  }
}

/**
 * Listener called when user completes auth flow. If the currentApiRequest
 * variable is set, then the user was prompted to authorize the application
 * before the request executed. In that case, proceed with that API request.
 */
function updateSigninStatus(isSignedIn) {
  if (isSignedIn) {
    isAuthorized = true;
    if (currentApiRequest) {
      sendAuthorizedApiRequest(currentApiRequest);
    }
  } else {
    isAuthorized = false;
  }
}

Extremos de OAuth 2.0

Generar una URL para solicitar acceso de OAuth 2.0 punto final de Google en https://accounts.google.com/o/oauth2/v2/auth . Se puede acceder a este punto final a través de HTTPS; Se rechazan las conexiones HTTP simples.

El servidor de autorización de Google admite los siguientes parámetros de cadena de consulta para aplicaciones de servidor web:

Parámetros
client_id Requerido

El ID de cliente de su aplicación. Puede encontrar este valor en el API ConsoleCredentials page.

redirect_uri Requerido

Determina dónde el servidor de API redirige al usuario después de que el usuario completa el flujo de autorización. El valor debe coincidir exactamente con uno de los URI de redirección autorizados para el cliente de OAuth 2.0, que configuró en el de su cliente API ConsoleCredentials page. Si este valor no coincide con una URI de redireccionamiento autorizado para el proporcionado client_id obtendrá un redirect_uri_mismatch error.

Tenga en cuenta que el http o https esquema, caja y barra final ( ' / ') deben coincidir.

response_type Requerido

Aplicaciones JavaScript es necesario para establecer el valor del parámetro de token . Este valor indica al Google servidor de autorización para devolver el token de acceso como un name=value par en el identificador de fragmento de la URI ( # ) a la que se redirige al usuario después de completar el proceso de autorización.

scope Requerido

Una lista de ámbitos delimitada por espacios que identifica los recursos a los que su aplicación podría acceder en nombre del usuario. Estos valores informan la pantalla de consentimiento que Google muestra al usuario.

Los ámbitos permiten que su aplicación solo solicite acceso a los recursos que necesita, al mismo tiempo que permite a los usuarios controlar la cantidad de acceso que otorgan a su aplicación. Por tanto, existe una relación inversa entre el número de alcances solicitados y la probabilidad de obtener el consentimiento del usuario.

Recomendamos que su aplicación solicite acceso a los ámbitos de autorización en contexto siempre que sea posible. Al solicitar el acceso a los datos del usuario en un contexto, a través de la autorización incrementales , ayuda a los usuarios a entender más fácilmente por las que su aplicación necesita el acceso que está solicitando.

state Recomendado

Especifica cualquier valor de cadena que utiliza su aplicación para mantener el estado entre su solicitud de autorización y la respuesta del servidor de autorización. El servidor devuelve el valor exacto que se envía como un name=value par en el identificador de fragmento de URL ( # ) de la redirect_uri después el usuario consiente o deniega la solicitud de acceso de la aplicación.

Puede usar este parámetro para varios propósitos, como dirigir al usuario al recurso correcto en su aplicación, enviar nonces y mitigar la falsificación de solicitudes entre sitios. Debido a que su redirect_uri se puede adivinar, utilizando un state valor puede aumentar su seguridad de que una conexión entrante es el resultado de una solicitud de autenticación. Si genera una cadena aleatoria o codifica el hash de una cookie u otro valor que captura el estado del cliente, puede validar la respuesta para asegurarse adicionalmente de que la solicitud y la respuesta se originaron en el mismo navegador, brindando protección contra ataques como entre sitios. Solicitar falsificación. Ver el OpenID Conectar la documentación para un ejemplo de cómo crear y confirmar un state token.

include_granted_scopes Opcional

Permite que las aplicaciones utilicen una autorización incremental para solicitar acceso a ámbitos adicionales en contexto. Si establece el valor de este parámetro para true y la solicitud de autorización se concede, entonces el nuevo token de acceso también cubrirá los ámbitos a los que el usuario concedido anteriormente el acceso a las aplicaciones. Ver la autorización incremental de la sección de ejemplos.

login_hint Opcional

Si su aplicación sabe qué usuario está intentando autenticarse, puede utilizar este parámetro para proporcionar una pista al servidor de autenticación de Google. El servidor utiliza la sugerencia para simplificar el flujo de inicio de sesión, ya sea rellenando previamente el campo de correo electrónico en el formulario de inicio de sesión o seleccionando la sesión de inicio de sesión múltiple adecuada.

Establecer el valor del parámetro a una dirección de correo electrónico o sub identificador, lo que equivale a del usuario ID de Google.

prompt Opcional

Una lista de mensajes delimitados por espacios que distinguen entre mayúsculas y minúsculas para presentar al usuario. Si no especifica este parámetro, se le preguntará al usuario solo la primera vez que su proyecto solicite acceso. Ver Prompting re-consentimiento para más información.

Los posibles valores son:

none No muestre ninguna pantalla de autenticación o consentimiento. No debe especificarse con otros valores.
consent Solicitar al usuario su consentimiento.
select_account Solicitar al usuario que seleccione una cuenta.

Ejemplo de redireccionamiento al servidor de autorización de Google

A continuación se muestra un ejemplo de URL, con saltos de línea y espacios para facilitar la lectura.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

Después de crear la URL de la solicitud, redirija al usuario a ella.

Código de muestra de JavaScript

El siguiente fragmento de JavaScript muestra cómo iniciar el flujo de autorización en JavaScript sin utilizar la biblioteca cliente de las API de Google para JavaScript. Dado que este extremo de OAuth 2.0 no admite el uso compartido de recursos de origen cruzado (CORS), el fragmento crea un formulario que abre la solicitud a ese extremo.

/*
 * Create form to request access token from Google's OAuth 2.0 server.
 */
function oauthSignIn() {
  // Google's OAuth 2.0 endpoint for requesting an access token
  var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

  // Create <form> element to submit parameters to OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'GET'); // Send as a GET request.
  form.setAttribute('action', oauth2Endpoint);

  // Parameters to pass to OAuth 2.0 endpoint.
  var params = {'client_id': 'YOUR_CLIENT_ID',
                'redirect_uri': 'YOUR_REDIRECT_URI',
                'response_type': 'token',
                'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly',
                'include_granted_scopes': 'true',
                'state': 'pass-through value'};

  // Add form parameters as hidden input values.
  for (var p in params) {
    var input = document.createElement('input');
    input.setAttribute('type', 'hidden');
    input.setAttribute('name', p);
    input.setAttribute('value', params[p]);
    form.appendChild(input);
  }

  // Add form to page and submit it to open the OAuth 2.0 endpoint.
  document.body.appendChild(form);
  form.submit();
}

Paso 3: Google solicita el consentimiento del usuario

En este paso, el usuario decide si concede a su aplicación el acceso solicitado. En esta etapa, Google muestra una ventana de consentimiento que muestra el nombre de su aplicación y los servicios de la API de Google a los que solicita permiso para acceder con las credenciales de autorización del usuario y un resumen de los alcances de acceso que se otorgarán. Luego, el usuario puede dar su consentimiento para otorgar acceso a uno o más ámbitos solicitados por su aplicación o rechazar la solicitud.

Su aplicación no necesita hacer nada en esta etapa, ya que espera la respuesta del servidor OAuth 2.0 de Google que indica si se le otorgó acceso. Esa respuesta se explica en el siguiente paso.

Errores

Las solicitudes al extremo de autorización de OAuth 2.0 de Google pueden mostrar mensajes de error de cara al usuario en lugar de los flujos de autenticación y autorización esperados. Los códigos de error comunes y las soluciones sugeridas se enumeran a continuación.

admin_policy_enforced

La cuenta de Google no puede autorizar uno o más alcances solicitados debido a las políticas de su administrador de Google Workspace. Ver el artículo de ayuda de Google espacio de trabajo de administración de control, que terceros y aplicaciones acceder a los datos internos Google espacio de trabajo para obtener más información acerca de cómo un administrador puede restringir el acceso a todos los ámbitos o ámbitos sensibles y restringidas hasta que el acceso se concede explícitamente a su ID de cliente de OAuth.

disallowed_useragent

El criterio de valoración de autorización se muestra dentro de un agente de usuario incrustado anulado por el de Google OAuth 2.0 Políticas .

Androide

Los desarrolladores de Android pueden encontrarse con este mensaje de error al abrir solicitudes de autorización enandroid.webkit.WebView . Los desarrolladores deben utilizar en lugar bibliotecas Android, tales como acceso de Google para Android o de OpenID Fundación AppAuth para Android .

Los desarrolladores web pueden encontrar este error cuando una aplicación de Android abre un enlace web general en un agente de usuario integrado y un usuario navega al extremo de autorización OAuth 2.0 de Google desde su sitio. Los desarrolladores deben permitir enlaces generales se abran en el controlador de enlace por defecto del sistema operativo, que incluye tanto Android App Links manipuladores o la aplicación del navegador por defecto. El androide de encargo aquí biblioteca es también una opción compatible.

iOS

IOS y MacOS desarrolladores pueden encontrar este error al abrir solicitudes de autorización enWKWebView . Los desarrolladores deben utilizar en lugar bibliotecas iOS tales como acceso de Google para iOS o de OpenID Fundación AppAuth para iOS .

Los desarrolladores web pueden encontrar este error cuando una aplicación iOS o macOS abre un enlace web general en un agente de usuario integrado y un usuario navega al extremo de autorización OAuth 2.0 de Google desde su sitio. Los desarrolladores deben permitir enlaces generales se abran en el controlador de enlace por defecto del sistema operativo, que incluye tanto universal Enlaces manipuladores o la aplicación del navegador por defecto. ElSFSafariViewController biblioteca es también una opción compatible.

org_internal

El ID de cliente de OAuth en la petición es parte de un proyecto que limita el acceso a las cuentas de Google en una determinada organización de Google Cloud . Para obtener más información acerca de esta opción de configuración ver el tipo de usuario sección en el Puesta a punto del consentimiento de OAuth artículo de ayuda de la pantalla.

origin_mismatch

Es posible que el esquema, dominio y / o puerto del JavaScript que origina la solicitud de autorización no coincida con un URI de origen JavaScript autorizado registrado para el ID de cliente OAuth. Opinión autorizada orígenes de JavaScript en el Google API ConsoleCredentials page.

redirect_uri_mismatch

El redirect_uri aprobada en la solicitud de autorización no coincide con una redirección autorizado URI para el ID de cliente de OAuth. Opinión autorizada URI de redirección en el Google API Console Credentials page.

El esquema, dominio y / o puerto del JavaScript que origina la solicitud de autorización puede no coincidir con un URI de origen JavaScript autorizado registrado para el ID de cliente OAuth. Opinión autorizada orígenes de JavaScript en el Google API Console Credentials page.

Paso 4: Manejar la respuesta del servidor OAuth 2.0

Biblioteca cliente JS

La biblioteca cliente de JavaScript maneja la respuesta del servidor de autorización de Google. Si configura un oyente para monitorear los cambios en el estado de inicio de sesión del usuario actual, esa función se llama cuando el usuario otorga el acceso solicitado a la aplicación.

Extremos de OAuth 2.0

El servidor de OAuth 2.0 envía una respuesta a la redirect_uri especificado en su solicitud de token de acceso.

Si el usuario aprueba la solicitud, la respuesta contiene un token de acceso. Si el usuario no aprueba la solicitud, la respuesta contiene un mensaje de error. El token de acceso o el mensaje de error se devuelve en el fragmento hash del URI de redireccionamiento, como se muestra a continuación:

  • Una respuesta de token de acceso:

    https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600

    Además de la access_token parámetro, la cadena fragmento también contiene el token_type parámetro, que siempre se establece en Bearer , y la expires_in parámetro, que especifica el tiempo de vida de la ficha, en segundos. Si el state parámetro se ha especificado en el token de acceso petición, su valor también se incluye en la respuesta.

  • Una respuesta de error:
    https://oauth2.example.com/callback#error=access_denied

Ejemplo de respuesta del servidor OAuth 2.0

Puede probar este flujo haciendo clic en la siguiente URL de muestra, que solicita acceso de solo lectura para ver los metadatos de los archivos en su Google Drive:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

Después de completar el flujo de OAuth 2.0, que va a ser redirigido a http://localhost/oauth2callback . Que dará lugar a una URL 404 NOT FOUND de error a menos que su máquina local pasa a servir a un archivo en esa dirección. El siguiente paso proporciona más detalles sobre la información devuelta en el URI cuando se redirige al usuario a su aplicación.

Llamar a las API de Google

Biblioteca cliente JS

Una vez que su aplicación obtiene un token de acceso, puede usar la biblioteca cliente de JavaScript para realizar solicitudes de API en nombre del usuario. La biblioteca cliente administra el token de acceso por usted, y no necesita hacer nada especial para enviarlo en la solicitud.

La biblioteca cliente admite dos formas de llamar a métodos API. Si ha cargado un documento de descubrimiento, la API definirá funciones específicas del método por usted. También puede utilizar el gapi.client.request función para llamar a un método de API. Los siguientes dos fragmentos demuestran estas opciones para la unidad de API about.get método.

// Example 1: Use method-specific function
var request = gapi.client.drive.about.get({'fields': 'user'});

// Execute the API request.
request.execute(function(response) {
  console.log(response);
});


// Example 2: Use gapi.client.request(args) function
var request = gapi.client.request({
  'method': 'GET',
  'path': '/drive/v3/about',
  'params': {'fields': 'user'}
});
// Execute the API request.
request.execute(function(response) {
  console.log(response);
});

Extremos de OAuth 2.0

Una vez que su aplicación obtiene un token de acceso, puede usar el token para realizar llamadas a una API de Google en nombre de una cuenta de usuario determinada si se han otorgado los alcances de acceso requeridos por la API. Para ello, incluya el acceso de ficha en una solicitud a la API mediante la inclusión de un bien access_token parámetro de consulta o un Authorization cabecera HTTP Bearer valor. Cuando sea posible, es preferible el encabezado HTTP, porque las cadenas de consulta tienden a ser visibles en los registros del servidor. En la mayoría de los casos se puede utilizar una biblioteca de cliente para configurar sus llamadas a las API de Google (por ejemplo, al llamar a la API de archivos de la unidad ).

Puede probar todas las API de Google y ver sus alcances en el espacio OAuth 2.0 .

Ejemplos de HTTP GET

Una llamada a la drive.files punto final (la API de archivos de la unidad) utilizando la Authorization: Bearer cabecera HTTP podría parecerse a lo siguiente. Tenga en cuenta que debe especificar su propio token de acceso:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Aquí es una llamada a la misma API para el usuario autenticado mediante el access_token parámetro de cadena de consulta:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl ejemplos

Puede probar estos comandos con el curl la aplicación de línea de comandos. Aquí hay un ejemplo que usa la opción de encabezado HTTP (preferido):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

O, alternativamente, la opción de parámetro de cadena de consulta:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Código de muestra de JavaScript

El siguiente fragmento de código demuestra cómo utilizar CORS (uso compartido de recursos de origen cruzado) para enviar una solicitud a una API de Google. Este ejemplo no utiliza la biblioteca cliente de las API de Google para JavaScript. Sin embargo, incluso si no se está utilizando la biblioteca cliente, los CORS apoyan guía en la documentación de la biblioteca probablemente ayudará a comprender mejor estas solicitudes.

En este fragmento de código, la access_token variable representa el token que haya obtenido para hacer solicitudes de API en nombre del usuario autorizado. El ejemplo completo muestra cómo almacenar esa señal en el almacenamiento local del navegador y recuperar la hora de hacer una solicitud de API.

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/drive/v3/about?fields=user&' +
    'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
  console.log(xhr.response);
};
xhr.send(null);

Ejemplo completo

Biblioteca cliente JS

Demostración de código de muestra

Esta sección contiene una demostración funcional del ejemplo de código que sigue para demostrar cómo se comporta el código en una aplicación real. Después de que autoriza la aplicación, que será incluido entre las aplicaciones conectadas a su cuenta de Google . La aplicación se llama OAuth 2.0 Demo para la API de Google Docs. Del mismo modo, si revoca el acceso y actualiza esa página, esa aplicación ya no aparecerá en la lista.

Tenga en cuenta que esta aplicación solicita acceso a la https://www.googleapis.com/auth/drive.metadata.readonly alcance. El acceso se solicita solo para demostrar cómo iniciar el flujo de OAuth 2.0 en una aplicación de JavaScript. Esta aplicación no realiza ninguna solicitud de API.

Código de muestra de JavaScript

Como se muestra arriba, esta muestra de código es para una página (una aplicación) que carga la biblioteca de cliente de las API de Google para JavaScript e inicia el flujo de OAuth 2.0. La página muestra:

  • Un botón que permite al usuario iniciar sesión en la aplicación. Si el usuario no ha autorizado previamente la aplicación, la aplicación inicia el flujo de OAuth 2.0.
  • Dos botones que permiten al usuario cerrar sesión en la aplicación o revocar el acceso previamente otorgado a la aplicación. Si cierra sesión en una aplicación, no ha revocado el acceso otorgado a la aplicación. Deberá iniciar sesión nuevamente antes de que la aplicación pueda realizar otras solicitudes autorizadas en su nombre, pero no tendrá que otorgar acceso nuevamente la próxima vez que use la aplicación. Sin embargo, si revoca el acceso, debe volver a otorgarlo.

También puede revocar el acceso a la aplicación a través de la Permisos de la página de su cuenta de Google. La aplicación aparece como OAuth 2.0 Demo para la API de Google Docs.

<script>
  var GoogleAuth;
  var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly';
  function handleClientLoad() {
    // Load the API's client and auth2 modules.
    // Call the initClient function after the modules load.
    gapi.load('client:auth2', initClient);
  }

  function initClient() {
    // In practice, your app can retrieve one or more discovery documents.
    var discoveryUrl = 'https://www.googleapis.com/discovery/v1/apis/drive/v3/rest';

    // Initialize the gapi.client object, which app uses to make API requests.
    // Get API key and client ID from API Console.
    // 'scope' field specifies space-delimited list of access scopes.
    gapi.client.init({
        'apiKey': 'YOUR_API_KEY',
        'clientId': 'YOUR_CLIENT_ID',
        'discoveryDocs': [discoveryUrl],
        'scope': SCOPE
    }).then(function () {
      GoogleAuth = gapi.auth2.getAuthInstance();

      // Listen for sign-in state changes.
      GoogleAuth.isSignedIn.listen(updateSigninStatus);

      // Handle initial sign-in state. (Determine if user is already signed in.)
      var user = GoogleAuth.currentUser.get();
      setSigninStatus();

      // Call handleAuthClick function when user clicks on
      //      "Sign In/Authorize" button.
      $('#sign-in-or-out-button').click(function() {
        handleAuthClick();
      });
      $('#revoke-access-button').click(function() {
        revokeAccess();
      });
    });
  }

  function handleAuthClick() {
    if (GoogleAuth.isSignedIn.get()) {
      // User is authorized and has clicked "Sign out" button.
      GoogleAuth.signOut();
    } else {
      // User is not signed in. Start Google auth flow.
      GoogleAuth.signIn();
    }
  }

  function revokeAccess() {
    GoogleAuth.disconnect();
  }

  function setSigninStatus() {
    var user = GoogleAuth.currentUser.get();
    var isAuthorized = user.hasGrantedScopes(SCOPE);
    if (isAuthorized) {
      $('#sign-in-or-out-button').html('Sign out');
      $('#revoke-access-button').css('display', 'inline-block');
      $('#auth-status').html('You are currently signed in and have granted ' +
          'access to this app.');
    } else {
      $('#sign-in-or-out-button').html('Sign In/Authorize');
      $('#revoke-access-button').css('display', 'none');
      $('#auth-status').html('You have not authorized this app or you are ' +
          'signed out.');
    }
  }

  function updateSigninStatus() {
    setSigninStatus();
  }
</script>

<button id="sign-in-or-out-button"
        style="margin-left: 25px">Sign In/Authorize</button>
<button id="revoke-access-button"
        style="display: none; margin-left: 25px">Revoke access</button>

<div id="auth-status" style="display: inline; padding-left: 25px"></div><hr>

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<script async defer src="https://apis.google.com/js/api.js"
        onload="this.onload=function(){};handleClientLoad()"
        onreadystatechange="if (this.readyState === 'complete') this.onload()">
</script>

Extremos de OAuth 2.0

Este ejemplo de código muestra cómo completar el flujo de OAuth 2.0 en JavaScript sin utilizar la biblioteca cliente de las API de Google para JavaScript. El código es para una página HTML que muestra un botón para probar una solicitud de API. Si hace clic en el botón, el código verifica si la página ha almacenado un token de acceso a la API en el almacenamiento local de su navegador. Si es así, ejecuta la solicitud de API. De lo contrario, inicia el flujo de OAuth 2.0.

Para el flujo de OAuth 2.0, la página sigue estos pasos:

  1. Se dirige al usuario al servidor de OAuth 2.0 de Google, que solicita acceso a la https://www.googleapis.com/auth/drive.metadata.readonly alcance.
  2. Después de otorgar (o denegar) el acceso a uno o más ámbitos solicitados, el usuario es redirigido a la página original, que analiza el token de acceso de la cadena del identificador del fragmento.
  3. La página utiliza el token de acceso para realizar la solicitud de API de muestra.

    La solicitud de API llama a la unidad de API about.get método para recuperar información sobre la cuenta de Google Drive del usuario autorizado.

  4. Si la solicitud se ejecuta correctamente, la respuesta de la API se registra en la consola de depuración del navegador.

Puede revocar el acceso a la aplicación a través de la Permisos de la página de su cuenta de Google. La aplicación se mostrará como OAuth 2.0 Demo para la API de Google Docs.

Para ejecutar este código a nivel local, es necesario valores establecidos para los YOUR_CLIENT_ID y YOUR_REDIRECT_URI variables que corresponden a sus credenciales de autorización . El YOUR_REDIRECT_URI variable debe ajustarse a la misma URL donde se sirve la página. El valor debe coincidir exactamente con uno de los URI de redirección autorizados para el cliente de OAuth 2.0, que se configuró en el API Console Credentials page. Si este valor no coincide con una URI autorizado, obtendrá un redirect_uri_mismatch error. Su proyecto también debe haber habilitado la API apropiada para esta solicitud.

<html><head></head><body>
<script>
  var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
  var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';
  var fragmentString = location.hash.substring(1);

  // Parse query string to see if page request is coming from OAuth 2.0 server.
  var params = {};
  var regex = /([^&=]+)=([^&]*)/g, m;
  while (m = regex.exec(fragmentString)) {
    params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
  }
  if (Object.keys(params).length > 0) {
    localStorage.setItem('oauth2-test-params', JSON.stringify(params) );
    if (params['state'] && params['state'] == 'try_sample_request') {
      trySampleRequest();
    }
  }

  // If there's an access token, try an API request.
  // Otherwise, start OAuth 2.0 flow.
  function trySampleRequest() {
    var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
    if (params && params['access_token']) {
      var xhr = new XMLHttpRequest();
      xhr.open('GET',
          'https://www.googleapis.com/drive/v3/about?fields=user&' +
          'access_token=' + params['access_token']);
      xhr.onreadystatechange = function (e) {
        if (xhr.readyState === 4 && xhr.status === 200) {
          console.log(xhr.response);
        } else if (xhr.readyState === 4 && xhr.status === 401) {
          // Token invalid, so prompt for user permission.
          oauth2SignIn();
        }
      };
      xhr.send(null);
    } else {
      oauth2SignIn();
    }
  }

  /*
   * Create form to request access token from Google's OAuth 2.0 server.
   */
  function oauth2SignIn() {
    // Google's OAuth 2.0 endpoint for requesting an access token
    var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

    // Create element to open OAuth 2.0 endpoint in new window.
    var form = document.createElement('form');
    form.setAttribute('method', 'GET'); // Send as a GET request.
    form.setAttribute('action', oauth2Endpoint);

    // Parameters to pass to OAuth 2.0 endpoint.
    var params = {'client_id': YOUR_CLIENT_ID,
                  'redirect_uri': YOUR_REDIRECT_URI,
                  'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly',
                  'state': 'try_sample_request',
                  'include_granted_scopes': 'true',
                  'response_type': 'token'};

    // Add form parameters as hidden input values.
    for (var p in params) {
      var input = document.createElement('input');
      input.setAttribute('type', 'hidden');
      input.setAttribute('name', p);
      input.setAttribute('value', params[p]);
      form.appendChild(input);
    }

    // Add form to page and submit it to open the OAuth 2.0 endpoint.
    document.body.appendChild(form);
    form.submit();
  }
</script>

<button onclick="trySampleRequest();">Try sample request</button>
</body></html>

Reglas de validación de origen de JavaScript

Google aplica las siguientes reglas de validación a los orígenes de JavaScript para ayudar a los desarrolladores a mantener seguras sus aplicaciones. Sus orígenes de JavaScript deben cumplir con estas reglas. Véase RFC 3986 sección 3 para la definición de dominio, host y el esquema, se mencionan a continuación.

Reglas de validación
Esquema

Los orígenes de JavaScript deben utilizar el esquema HTTPS, no HTTP simple. Los URI de localhost (incluidos los URI de dirección IP de localhost) están exentos de esta regla.

Anfitrión

Los hosts no pueden ser direcciones IP sin procesar. Las direcciones IP de localhost están exentas de esta regla.

Dominio
  • TLD anfitrionas ( dominios de nivel superior ) deben pertenecer a la lista de sufijos pública .
  • Dominios de acogida no pueden ser “googleusercontent.com” .
  • Orígenes de JavaScript no pueden contener dominios acortador de URLs (por ejemplo goo.gl ) a menos que la aplicación posee el dominio.
  • Información de usuario

    Los orígenes de JavaScript no pueden contener el subcomponente userinfo.

    Sendero

    Los orígenes de JavaScript no pueden contener el componente de ruta.

    Consulta

    Los orígenes de JavaScript no pueden contener el componente de consulta.

    Fragmento

    Los orígenes de JavaScript no pueden contener el componente de fragmento.

    Caracteres Los orígenes de JavaScript no pueden contener ciertos caracteres, incluidos:
    • Los caracteres comodín ( '*' )
    • Caracteres ASCII no imprimibles
    • Codificaciones de porcentaje no válidas (cualquier codificación de porcentaje que no siga la forma de codificación de URL de un signo de porcentaje seguido de dos dígitos hexadecimales)
    • Caracteres nulos (un carácter NULL codificada, por ejemplo, %00 , %C0%80 )

    Autorización incremental

    En el protocolo OAuth 2.0, su aplicación solicita autorización para acceder a los recursos, que se identifican por alcances. Se considera una mejor práctica para la experiencia del usuario solicitar autorización para los recursos en el momento en que los necesite. Para habilitar esa práctica, el servidor de autorización de Google admite la autorización incremental. Esta función le permite solicitar ámbitos según sean necesarios y, si el usuario concede permiso para el nuevo ámbito, devuelve un código de autorización que puede intercambiarse por un token que contiene todos los ámbitos que el usuario ha concedido al proyecto.

    Por ejemplo, una aplicación que permite a las personas probar pistas de música y crear mezclas puede necesitar muy pocos recursos en el momento del inicio de sesión, tal vez nada más que el nombre de la persona que inicia sesión. Sin embargo, guardar una mezcla completa requeriría acceso a su Google Drive. . A la mayoría de las personas les resultaría natural si solo se les pidiera acceso a su Google Drive en el momento en que la aplicación realmente lo necesitaba.

    En este caso, al iniciar sesión en el tiempo la aplicación podría solicitar los openid y profile ámbitos para realizar el inicio de sesión básico, y luego solicitar la https://www.googleapis.com/auth/drive.file alcance en el momento de la primera solicitud para guardar una mezcla.

    Las siguientes reglas se aplican a un token de acceso obtenido de una autorización incremental:

    • El token se puede utilizar para acceder a los recursos correspondientes a cualquiera de los ámbitos incluidos en la nueva autorización combinada.
    • Cuando se utiliza la actualización de símbolo para la autorización combinado para obtener un token de acceso, el token de acceso representa la autorización combinado y se puede utilizar para cualquiera de los scope los valores comprendidos en la respuesta.
    • La autorización combinada incluye todos los alcances que el usuario otorgó al proyecto de API, incluso si las concesiones se solicitaron a diferentes clientes. Por ejemplo, si un usuario otorgó acceso a un alcance utilizando el cliente de escritorio de una aplicación y luego otorgó otro alcance a la misma aplicación a través de un cliente móvil, la autorización combinada incluiría ambos alcances.
    • Si revoca un token que representa una autorización combinada, el acceso a todos los alcances de esa autorización en nombre del usuario asociado se revoca simultáneamente.

    Los ejemplos de código a continuación muestran cómo agregar ámbitos a un token de acceso existente. Este enfoque permite que su aplicación evite tener que administrar varios tokens de acceso.

    Biblioteca cliente JS

    Para agregar ámbitos a un token de acceso existente, llame a la GoogleUser.grant(options) método. Las options de objeto identifica los ámbitos adicionales a los que desea conceder acceso.

    // Space-separated list of additional scope(s) you are requesting access to.
    // This code adds read-only access to the user's calendars via the Calendar API.
    var NEW_SCOPES = 'https://www.googleapis.com/auth/calendar.readonly';
    
    // Retrieve the GoogleUser object for the current user.
    var GoogleUser = GoogleAuth.currentUser.get();
    GoogleUser.grant({'scope': NEW_SCOPES});

    Extremos de OAuth 2.0

    Para agregar ámbitos a un token de acceso existente, incluya el include_granted_scopes parámetro en la petición al servidor de OAuth 2.0 de Google .

    El siguiente fragmento de código demuestra cómo hacerlo. El fragmento asume que ha almacenado los ámbitos para los que su token de acceso es válido en el almacenamiento local del navegador. (Las completas ejemplo tiendas de código una lista de ámbitos para los que el token de acceso es válida estableciendo el oauth2-test-params.scope propiedad en el almacenamiento local del navegador).

    El fragmento compara los ámbitos para los que el token de acceso es válido con el ámbito que desea usar para una consulta en particular. Si el token de acceso no cubre ese alcance, se inicia el flujo de OAuth 2.0. Aquí, el oauth2SignIn función es la misma que la que se proporcionó en el paso 2 (y que se proporciona más adelante en el ejemplo completo ).

    var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly';
    var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
    
    var current_scope_granted = false;
    if (params.hasOwnProperty('scope')) {
      var scopes = params['scope'].split(' ');
      for (var s = 0; s < scopes.length; s++) {
        if (SCOPE == scopes[s]) {
          current_scope_granted = true;
        }
      }
    }
    
    if (!current_scope_granted) {
      oauth2SignIn(); // This function is defined elsewhere in this document.
    } else {
      // Since you already have access, you can proceed with the API request.
    }

    Revocar una ficha

    En algunos casos, un usuario puede desear revocar el acceso otorgado a una aplicación. Un usuario puede revocar el acceso al visitar Configuración de la cuenta . Vea la sección de acceso Retire el sitio o aplicación de los Sitios y aplicaciones de terceros con acceso a su cuenta documento de soporte para más información.

    También es posible que una aplicación revoque mediante programación el acceso que se le ha otorgado. La revocación programática es importante en los casos en que un usuario cancela su suscripción, elimina una aplicación o los recursos de API requeridos por una aplicación han cambiado significativamente. En otras palabras, parte del proceso de eliminación puede incluir una solicitud de API para garantizar que se eliminen los permisos otorgados previamente a la aplicación.

    Biblioteca cliente JS

    Para revocar mediante programación una ficha, llamada GoogleAuth.disconnect() :

    GoogleAuth.disconnect();

    Extremos de OAuth 2.0

    Para revocar mediante programación una ficha, la aplicación realiza una solicitud al https://oauth2.googleapis.com/revoke e incluye el token como parámetro:

    curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
            https://oauth2.googleapis.com/revoke?token={token}

    El token puede ser un token de acceso o un token de actualización. Si el token es un token de acceso y tiene un token de actualización correspondiente, también se revocará el token de actualización.

    Si la revocación se procesa correctamente, entonces el código de estado HTTP de la respuesta es 200 . Para las condiciones de error, un código de estado HTTP 400 es devuelto junto con un código de error.

    El siguiente fragmento de JavaScript muestra cómo revocar un token en JavaScript sin utilizar la biblioteca cliente de las API de Google para JavaScript. Desde OAuth 2.0 punto final del Google para revocar tokens no soporta de origen cruzado de intercambio de recursos (CORS), el código crea un formulario y envía el formulario al punto final en lugar de utilizar el XMLHttpRequest() método para enviar la solicitud.

    function revokeAccess(accessToken) {
      // Google's OAuth 2.0 endpoint for revoking access tokens.
      var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke';
    
      // Create <form> element to use to POST data to the OAuth 2.0 endpoint.
      var form = document.createElement('form');
      form.setAttribute('method', 'post');
      form.setAttribute('action', revokeTokenEndpoint);
    
      // Add access token to the form so it is set as value of 'token' parameter.
      // This corresponds to the sample curl request, where the URL is:
      //      https://oauth2.googleapis.com/revoke?token={token}
      var tokenField = document.createElement('input');
      tokenField.setAttribute('type', 'hidden');
      tokenField.setAttribute('name', 'token');
      tokenField.setAttribute('value', accessToken);
      form.appendChild(tokenField);
    
      // Add form to page and submit it to actually revoke the token.
      document.body.appendChild(form);
      form.submit();
    }