OAuth 2.0 para aplicaciones web del cliente

Extremos de OAuth 2.0

Genera una URL para solicitar acceso al extremo de OAuth 2.0 de Google en https://accounts.google.com/o/oauth2/v2/auth. Se puede acceder a este extremo mediante HTTPS. Se rechazan las conexiones HTTP simples.

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

Redireccionamiento de muestra 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, redirecciona al usuario a ella.

Código de muestra de JavaScript

En el siguiente fragmento de JavaScript, se muestra cómo iniciar el flujo de autorización en JavaScript sin usar 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 entre dominios (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();
}

Extremos de OAuth 2.0

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

Si el usuario aprueba la solicitud, la respuesta contendrá un token de acceso. Si el usuario no aprueba la solicitud, la respuesta contendrá un mensaje de error. El token de acceso o el mensaje de error se muestra en el fragmento de 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 del parámetro access_token, la string del fragmento también contiene el parámetro token_type, que siempre se establece en Bearer, y el parámetro expires_in, que especifica la vida útil del token, en segundos. Si se especificó el parámetro state en la solicitud del token de acceso, su valor también se incluye en la respuesta.

• Una respuesta de error:

  https://oauth2.example.com/callback#error=access_denied

Respuesta del servidor OAuth 2.0 de muestra

Para probar este flujo, haz clic en la siguiente URL de muestra, que solicita acceso de solo lectura a fin de ver los metadatos de los archivos de tu 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, se te redireccionará a http://localhost/oauth2callback. Esa URL generará un error 404 NOT FOUND, a menos que tu máquina local entregue un archivo en esa dirección. En el siguiente paso, se proporciona más detalles sobre la información que se muestra en el URI cuando se redirecciona al usuario de vuelta a tu aplicación.

Extremos de OAuth 2.0

Una vez que tu aplicación obtenga un token de acceso, puedes usarlo para realizar llamadas a una API de Google en nombre de una cuenta de usuario determinada si se otorgaron los permisos de acceso que requiere la API. Para ello, incluye el token de acceso en una solicitud a la API mediante la inclusión de un parámetro de consulta access_token o un valor Bearer de encabezado HTTP Authorization. Cuando es posible, se prefiere el encabezado HTTP, ya que las strings de consulta tienden a ser visibles en los registros del servidor. En la mayoría de los casos, puedes usar una biblioteca cliente para configurar tus llamadas a las API de Google (por ejemplo, cuando llames a la API de Drive Files).

Puedes probar todas las API de Google y ver sus alcances en el Playground de OAuth 2.0.

Ejemplos de HTTP GET

Es posible que una llamada al extremo drive.files (la API de Drive Files) con el encabezado HTTP Authorization: Bearer se vea de la siguiente manera. Ten en cuenta que debes especificar tu propio token de acceso:

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

Esta es una llamada a la misma API para el usuario autenticado con el parámetro de string de consulta access_token:

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

curl ejemplos

Puedes probar estos comandos con la aplicación de línea de comandos de curl. A continuación, te mostramos un ejemplo en el que se usa la opción de encabezado HTTP (opción preferida):

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

Como alternativa, la opción de parámetro de string de consulta:

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

Código de muestra de JavaScript

En el siguiente fragmento de código, se muestra cómo usar CORS (uso compartido de recursos entre dominios) para enviar una solicitud a una API de Google. En este ejemplo, no se usa la biblioteca cliente de las API de Google para JavaScript. Sin embargo, incluso si no usas la biblioteca cliente, es posible que la guía de compatibilidad con CORS de la documentación de esa biblioteca te ayude a comprender mejor estas solicitudes.

En este fragmento de código, la variable access_token representa el token que obtuviste para realizar solicitudes a la API en nombre del usuario autorizado. En el ejemplo completo, se muestra cómo almacenar ese token en el almacenamiento local del navegador y recuperarlo cuando se realiza una solicitud a la 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);

Extremos de OAuth 2.0

En esta muestra de código, se muestra cómo completar el flujo de OAuth 2.0 en JavaScript sin usar la biblioteca cliente de las API de Google para JavaScript. El código es de una página HTML que muestra un botón para probar una solicitud a la API. Si haces clic en el botón, el código verifica si la página almacenó un token de acceso a la API en el almacenamiento local del navegador. Si es así, ejecuta la solicitud a la 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. Dirige al usuario al servidor OAuth 2.0 de Google, que solicita acceso al permiso https://www.googleapis.com/auth/drive.metadata.readonly.
2. Después de otorgar (o rechazar) el acceso a uno o más permisos solicitados, el usuario se redirecciona a la página original, que analiza el token de acceso de la string de identificador del fragmento.

3. La página usa el token de acceso para realizar la solicitud a la API de muestra.

   La solicitud a la API llama al método about.get de la API de Drive 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.

Puedes revocar el acceso a la app desde la página Permisos de tu Cuenta de Google. La app aparecerá como OAuth 2.0 Demo for Google API Docs (Demostración de OAuth 2.0 para los documentos de la API de Google).

A fin de ejecutar este código de forma local, debes establecer valores para las variables YOUR_CLIENT_ID y YOUR_REDIRECT_URI que correspondan a tus credenciales de autorización. La variable YOUR_REDIRECT_URI debe establecerse en la misma URL en la que se entrega la página. El valor debe coincidir exactamente con uno de los URI de redireccionamiento autorizados para el cliente de OAuth 2.0, que configuraste en el API Console Credentials page. Si este valor no coincide con un URI autorizado, se mostrará el error redirect_uri_mismatch. El proyecto también debe tener habilitada la API correspondiente 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>

Extremos de OAuth 2.0

Para agregar permisos a un token de acceso existente, incluye el parámetro include_granted_scopes en tu solicitud al servidor de OAuth 2.0 de Google.

En el siguiente fragmento de código, se muestra cómo hacerlo. En el fragmento, se supone que almacenaste los permisos para los que es válido el token de acceso en el almacenamiento local del navegador. (En el código de ejemplo completo, se almacena una lista de los permisos para los que es válido el token de acceso mediante la configuración de la propiedad oauth2-test-params.scope en el almacenamiento local del navegador).

El fragmento compara los permisos para los que el token de acceso es válido con el permiso que deseas usar en una consulta en particular. Si el token de acceso no cubre ese alcance, se inicia el flujo de OAuth 2.0. Aquí, la función oauth2SignIn es la misma que se proporcionó en el paso 2 (y se brinda 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.
}

Extremos de OAuth 2.0

Para revocar un token de manera programática, la aplicación realiza una solicitud a 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}

Puede ser un token de acceso o de actualización. Si es un token de acceso y tiene un token de actualización correspondiente, este último también se revocará.

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

En el siguiente fragmento de JavaScript, se muestra cómo revocar un token en JavaScript sin usar la biblioteca cliente de las API de Google para JavaScript. Dado que el extremo de OAuth 2.0 de Google para revocar tokens no admite el uso compartido de recursos entre dominios (CORS), el código crea un formulario y lo envía al extremo, en lugar de usar el método XMLHttpRequest() a fin de publicar 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();
}