OAuth 2.0 Flow: Server-side web apps

Este flujo de OAuth 2.0 está diseñado para aplicaciones web con servidores capaces de almacenar información confidencial y mantener el estado. Estas aplicaciones pueden acceder a YouTube Data API mientras el usuario utiliza la aplicación o después de que haya salido de ella.

Esta situación se produce cuando un usuario intenta realizar una acción que requiere autorización. La aplicación redirige al usuario a una dirección URL de Google que contiene parámetros de consulta que especifican el tipo de acceso a la API que la aplicación requiere.

Google se encarga de la autenticación y el consentimiento del usuario y luego muestra un código de autorización. La aplicación utiliza ese código, junto con su client_id y client_secret para obtener un token de acceso que se puede usar para autorizar solicitudes de API en nombre del usuario. En este paso, la aplicación también puede solicitar una actualización de token, que permite a la aplicación obtener un nuevo token de acceso una vez que caduque el que se obtuvo previamente.

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. Establece el valor del parámetro en code.
    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.
    access_type Recomendado. Este parámetro indica si la aplicación puede actualizar los tokens de acceso si el usuario no está presente en el navegador. Los valores de parámetros válidos son online y offline. Establece este valor de parámetro en offline para permitir que la aplicación utilice tokens de actualización cuando el usuario no esté presente. (Este es el método para actualizar tokens de acceso descrito más adelante en este documento.)
    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=code&
      access_type=offline
    
  2. Manejar la respuesta de Google

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

    • Si el usuario concedió el acceso a la aplicación, Google añadirá un parámetro code al redirect_uri. Este valor es un código de autorización temporal que se puede cambiar por un token de acceso, como se describe en el paso 4.

      http://localhost/oauth2callback?code=4/ux5gNj-_mIu4DOD_gNZdjX9EtOFf
    • 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. Cambio del código de autorización para tokens de actualización y de acceso

    Si el usuario concedió el acceso a la aplicación, cambia el código de autorización que se obtuvo en el paso 3 por un token de actualización y un token de acceso. Para ello, envía una solicitud de POST a https://accounts.google.com/o/oauth2/token que incluya los siguientes pares de clave y valor en el cuerpo de la solicitud:

    Claves
    code El código de autorización que Google mostró en el redirect_uri en el paso 3.
    client_id El ID de cliente de OAuth 2.0 para la aplicación. Este valor aparece en la Google APIs console.
    client_secret El secreto de cliente asociado con el ID de cliente. Este valor aparece en la Google APIs console.
    redirect_uri Un redirect_uri registrado para el ID de cliente.
    grant_type Establece este valor en authorization_code.

    A continuación puede ver un ejemplo de solicitud:

    POST /o/oauth2/token HTTP/1.1
    Host: accounts.google.com
    Content-Type: application/x-www-form-urlencoded
    
    code=4/ux5gNj-_mIu4DOD_gNZdjX9EtOFf&
    client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
    client_secret=hDBmMRhz7eJRsM9Z2q1oFBSe&
    redirect_uri=http://localhost/oauth2callback&
    grant_type=authorization_code
    
  4. Respuesta del proceso y tokens de almacenamiento

    Para responder a tu solicitud de POST, Google mostrará un objeto JSON que contiene un token de acceso de corta duración y un token de actualización.

    {
      "access_token" : "ya29.AHES6ZTtm7SuokEB-RGtbBty9IIlNiP9-eNMMQKtXdMP3sfjL1Fc",
      "token_type" : "Bearer",
      "expires_in" : 3600,
      "refresh_token" : "1/HKSmLFXzqP0leUihZp2xUt3-5wkU7Gmu2Os_eBnzw74"
    }
    

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.