OAuth 2.0 Flow: Client-side web apps

Este flujo de OAuth 2.0 está diseñado para permitir a las aplicaciones web basadas en JavaScript enviar solicitudes autorizadas de la API de Google. Estas aplicaciones no pueden mantener el estado en el tiempo; es decir, la aplicación accede a YouTube Data API mientras el usuario está presente en la aplicación. Este flujo supone que la aplicación no puede almacenar información confidencial.

Important: You need to obtain authorization credentials in the Google Developers Console to be able to use OAuth 2.0 authorization.

This document contains the following sections:

Obtaining OAuth 2.0 access tokens

Este flujo tiene los siguientes pasos:

  1. Cómo obtener un token de acceso

    Nota: Las solicitudes al servidor de autorización de Google deben usar https en lugar de http porque solo se puede acceder al servidor a través de SSL (HTTPs) y rechaza las conexiones HTTP.

    Cuando un usuario intenta realizar por primera vez una acción que requiere autenticación de API, es necesario dirigirlo al servidor de autorización de Google en https://accounts.google.com/o/oauth2/auth. En la tabla siguiente se identifican los parámetros de la solicitud que se deben (o pueden) incluir en la URL. Ten en cuenta que el URI de solicitud que crees debe contener los valores de los parámetros URL de escape adecuados.

    Parámetros
    client_id Obligatorio. El ID de cliente de OAuth 2.0 para la aplicación. Puedes encontrar este valor en la APIs Console.
    redirect_uri Obligatorio. Un redirect_uri registrado para tu ID de cliente. Registra los URI de redirección válidos para tu aplicación en la APIs Console.
    response_type Obligatorio. Determina si el criterio de valoración de OAuth 2.0 de Google muestra un código de autorización. Las aplicaciones JavaScript deben establecer el valor del parámetro en token. Esto indica al servidor de autorización de Google que muestre el token de acceso como un par name=value del fragmento hash (#) del URI de redirección que muestra el servidor.
    scope Obligatorio. Una lista delimitada por espacios de los alcances que identifican los recursos a los que la aplicación podría acceder en nombre del usuario. Estos valores determinan qué permisos se mostrarán en la página de consentimiento que Google muestra al usuario.

    The YouTube Data API supports the following scopes:

    Scopes
    https://www.googleapis.com/auth/youtube.force-ssl Manage your YouTube account. This scope requires communication with the API server to happen over an SSL connection.
    https://www.googleapis.com/auth/youtube Manage your YouTube account. This scope is functionally identical to the youtube.force-ssl scope listed above because the YouTube API server is only available via an HTTPS endpoint. As a result, even though this scope does not require an SSL connection, there is actually no other way to make an API request.
    https://www.googleapis.com/auth/youtube.readonly View your YouTube account.
    https://www.googleapis.com/auth/youtube.upload Upload YouTube videos and manage your YouTube videos.
    https://www.googleapis.com/auth/youtubepartner-channel-audit Retrieve the auditDetails part in a channel resource.
    approval_prompt Opcional. Este parámetro indica si se le pedirá al usuario que permita a la aplicación acceder a la cuenta cada vez que intente realizar una acción en particular. El valor predeterminado es auto, lo que indica que el usuario sólo tendría que conceder el acceso la primera vez que se intente acceder a un recurso protegido.

    Establece el valor del parámetro en force para dirigir al usuario a una página de consentimiento, incluso si ya se ha concedido el acceso a la aplicación para un conjunto determinado de alcances.
    state Opcional. Un string que la aplicación utiliza para mantener el estado entre la solicitud y la respuesta de redirección. El valor exacto que envíes se muestra como un par name=value en el fragmento de hash (#) del redirect_uri después de que el usuario aprueba o niega la solicitud de acceso de la aplicación. Puedes utilizar este parámetro para varios propósitos, tales como dirigir al usuario al recurso correcto en la aplicación, enviar valores de seguridad y mitigar la falsificación de solicitudes entre sitios.
    login_hint Opcional. Si la aplicación sabe qué usuario está intentando autenticar, puede utilizar este parámetro para proporcionar una sugerencia al servidor de autenticación de Google. El servidor utiliza la sugerencia para simplificar el flujo de acceso, ya sea llenando previamente el campo de correo electrónico en el formulario de acceso a la cuenta o seleccionando la sesión de accesos múltiples correspondiente.

    La dirección URL de ejemplo a continuación muestra un URI del servidor de autorización de Google que solicita permiso para que una aplicación muestre solicitudes de YouTube Data API en nombre del usuario. Ten en cuenta que los valores de los parámetros deben contener URL con los caracteres de escape adecuados.

    https://accounts.google.com/o/oauth2/auth?
      client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
      redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
      scope=https://www.googleapis.com/auth/youtube&
      response_type=token
    
  2. Manejar la respuesta de Google

    Una vez que el usuario haya aceptado o rechazado otorgar acceso a la aplicación, Google lo redirige al redirect_uri que se especificó en el paso 1.

    • Si el usuario concedió el acceso a la aplicación, Google agrega un token de acceso de corta duración en el fragmento de hash del URI de redirección, como se muestra en el URI de ejemplo a continuación. La respuesta también incluye los parámetros expires_in y token_type. Estos parámetros describen la vida útil del token en segundos y el tipo de token que se muestra, respectivamente. Por último, la respuesta incluye el parámetro state si un parámetro state se incluyó en la solicitud original que se envió al servidor de autorización.

      http://localhost/oauth2callback#access_token=1/QbIbRMWW&token_type=Bearer&expires_in=3600

      Nota: La aplicación también debe permitir que se incluyan otros parámetros en el fragmento de hash de la respuesta. El párrafo anterior describe el conjunto mínimo de pares de nombre y valor que se muestran en el redirect_uri.

      El código JavaScript que esté activo en tu página puede capturar el token de acceso del valor window.location.hash y almacenar el token en una cookie o POST en un servidor.

    • Si el usuario se negó a permitir el acceso a la aplicación, Google incluirá el mensaje de error access_denied en el fragmento hash de redirect_uri:

      http://localhost/oauth2callback#error=access_denied
  3. Validar el token del usuario

    Si el usuario concedió el acceso a la aplicación, es necesario validar explícitamente el token que aparece en el redirect_uri . Mediante la validación o verificación del token, se asegura de que su aplicación no sea vulnerable a la falsificación de solicitud entre sitios.

    Para validar el token, envía una solicitud a https://www.googleapis.com/oauth2/v1/tokeninfo y configura el token como el valor del parámetro access_token. Esa URL acepta y muestra la información sobre el token, como la aplicación para la cual se emitió, el usuario asociado al token, el alcance del acceso que autorizó el usuario y el tiempo para que el token caduque.

    La dirección URL de ejemplo a continuación muestra dónde se debería enviar una solicitud de validación de token:

    https://www.googleapis.com/oauth2/v1/tokeninfo?access_token=ACCESS_TOKEN
  4. Procesar la respuesta de validación del token

    En respuesta a una solicitud de validación del token, el servidor de autorización de Google muestra un objeto JSON que describe el token o contiene un mensaje de error.

    • Si el token es válido, el objeto JSON incluye las siguientes propiedades:

      Campos
      audience La aplicación que corresponde al usuario previsto del token de acceso.

      Importante: antes de usar el token, es necesario verificar que el valor de este campo coincida exactamente con el Client ID en la Google APIs console. Esta verificación garantiza que la aplicación no sea vulnerable a la falsificación de solicitud entre sitios.
      expires_in La cantidad de segundos restantes para que el token caduque.
      scope Una lista delimitada por espacios de los alcances a los que el usuario concedió acceso. La lista debe coincidir con los alcances especificados en la solicitud de autorización del paso 1.
      userid Este valor permite correlacionar la información de perfil desde múltiples API de Google. Solo está presente en la respuesta si se incluye el alcance https://www.googleapis.com/auth/userinfo.profile en la solicitud del paso 1. El valor del campo es un identificador inmutable para el usuario conectado que se puede utilizar para crear y administrar sesiones de usuario en la aplicación.

      A continuación se muestra una respuesta de ejemplo:

      {
        "audience":"8819981768.apps.googleusercontent.com",
        "user_id":"123456789",
        "scope":"https://www.googleapis.com/auth/youtube",
        "expires_in":436
      }
      
    • Si el token caducó, se ha manipulado o tenía sus permisos revocados, el servidor de autorización de Google muestra un mensaje de error en el objeto JSON. Este se muestra como un error 400 y un cuerpo de JSON en el formato que se muestra a continuación.

      {"error":"invalid_token"}

      La ausencia de información adicional en cuanto a la razón de la falla es deliberada.

      Nota: En la práctica, un error 400 suele indicar que el formato de la dirección URL de solicitud de token de acceso es incorrecto, a menudo debido al escape incorrecto de la dirección URL.

Invocación de YouTube Data API

Tras obtener un token de acceso para un usuario, la aplicación puede utilizar ese token para enviar solicitudes autorizadas de API en nombre de ese usuario. La API permite especificar un token de acceso de dos maneras:

  1. Especifique el token de acceso como el valor del encabezado de solicitud HTTP de Authorization: Bearer. Este es el método recomendado.

    GET /youtube/v3/channels?part=id&mine=true HTTP/1.1
    Host: www.googleapis.com
    Authorization: Bearer ACCESS_TOKEN
    ...
    

    Para probar este método, puedes usar cURL con el siguiente comando:

    curl -H "Authorization: Bearer ACCESS_TOKEN" https://www.googleapis.com/youtube/v3/channels?part=id&mine=true
    
  2. Especifica el token de acceso como el valor del parámetro de consulta de access_token:

    https://www.googleapis.com/youtube/v3/channels?part=id&mine=true&access_token=ACCESS_TOKEN

    Para probar este método, puedes usar cURL con el siguiente comando:

    curl https://www.googleapis.com/youtube/v3/channels?part=id&mine=true&access_token=ACCESS_TOKEN
    

La API muestra un código de respuesta HTTP 401 (Unauthorized) si envías una solicitud para acceder a un recurso protegido con un token de acceso caduco, falso, de alcance incorrecto o no válido por cualquier otra razón.

Si la API muestra un código de respuesta HTTP 403, la aplicación no se puede registrar. Muchas API establecen un límite de consultas-volumen de 0 para aplicaciones no registradas y muestran un código de respuesta 403 cuando se excede este límite.

La siguiente sección explica cómo actualizar un token de acceso.

Actualización de un token de acceso

Los tokens de acceso caducan periódicamente. Cuando esto sucede, es necesario actualizarlos. La aplicación puede usar un token de actualización para obtener un nuevo token de acceso válido cuando el anterior haya caducado o en cualquier otro momento. Las aplicaciones web del servidor, las aplicaciones instaladas y los dispositivos obtienen tokens de actualización durante el proceso de autorización.

Para actualizar un token de acceso, la aplicación envía una solicitud de POST al servidor de autorización de Google que especifica el ID de cliente, el secreto de cliente y el token de actualización para el usuario. Además, la solicitud establece el valor del parámetro grant_type en refresh_token. A continuación se muestra un ejemplo de solicitud:

POST /o/oauth2/token HTTP/1.1
Host: accounts.google.com
Content-Type: application/x-www-form-urlencoded

client_id=21302922996.apps.googleusercontent.com&
client_secret=XTHhXh1SlUNgvyWGwDk1EjXB&
refresh_token=1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ&
grant_type=refresh_token

El servidor de autorización muestra un objeto JSON que contiene un nuevo token de acceso:

{
  "access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in":3920,
  "token_type":"Bearer"
}

Ten en cuenta que existen límites en la cantidad de tokens de actualización que se emitirán; un límite por combinación cliente-usuario y otro por usuario a través de todos los clientes. Guarda los tokens de actualización en un almacenamiento a largo plazo y sigue usándolos mientras sean válidos. Si la aplicación solicita demasiados tokens de actualización, podría llegar a estos límites, en cuyo caso los tokens de actualización antiguos dejarán de funcionar.

Revocación de un token

Existen dos formas para revocar un token de acceso:

  • Un usuario puede revocar el acceso dado a una solicitud a través de la siguiente URL y revocar explícitamente el acceso:

    https://accounts.google.com/b/0/IssuedAuthSubTokens

    Los siguientes pasos explican cómo llegar a esta página:

    1. Haz clic en la imagen del usuario en la barra de Google y en el vínculo Cuenta, o bien, desplázate de alguna otra forma a la página Vista general de la cuenta de la cuenta de Google del usuario.
    2. Sigue el vínculo para la página de configuración de Seguridad.
    3. Haz clic en el botón para administrar el acceso a las aplicaciones y sitios web conectados que pueden acceder y utilizar los detalles de la cuenta de Google del usuario.

  • Una aplicación puede revocar su propio acceso de manera programática. Este tipo de revocación es importante en los casos en que un usuario cancela la suscripción o elimina una aplicación, en la que una solicitud de la API para eliminar los permisos concedidos a la aplicación debe ser parte del proceso de eliminación.

    Para revocar un token de manera programática, la aplicación envía una solicitud a https://accounts.google.com/o/oauth2/revoke e incluye el token como parámetro:

    curl https://accounts.google.com/o/oauth2/revoke?token={token}

    El token especificado puede ser un token de acceso o de actualización. Si se trata de un token de acceso y tiene un token de actualización correspondiente, este último también se revoca.

    Si la revocación se realiza correctamente, el código de estado de la respuesta es 200. Si se produce un error, el código de estado de respuesta es 400 y la respuesta también contiene un código de error.

Bibliotecas cliente

Acceder a Google

Nota: Si pretendes proporcionar una característica de acceso con Google, te recomendamos que utilices Google+ Sign-in, que ofrece el mecanismo de autenticación OAuth 2.0 junto con un acceso adicional a las características sociales de Google+.

Puedes usar las bibliotecas cliente a continuación para implementar OAuth 2.0 en tu aplicación. Recomendamos usar una biblioteca de cliente en lugar de escribir tu propio código. El uso de estas bibliotecas de cliente estándar es importante para la seguridad y la seguridad de los usuarios y tu aplicación.

También puedes seguir las instrucciones en la sección Invocación de YouTube Data API para modificar el código y así configurar correctamente los valores de token de OAuth 2.0.