OAuth 2.0 Flow: Installed apps

Este flujo de OAuth 2.0 está diseñado para aplicaciones instaladas en un dispositivo, como un teléfono celular o una computadora. Estas aplicaciones pueden acceder a YouTube Data API mientras el usuario interactúa con la aplicación o cuando la aplicación está activa en segundo plano durante un período prolongado sin la interacción directa del usuario.

Este flujo supone que la aplicación no puede almacenar de forma segura tokens que permitirían a un usuario interactuar con YouTube Data API. También requiere que la aplicación tenga acceso al navegador del sistema o la capacidad de insertar un control de explorador. Si la solicitud no cumple con alguna de estas condiciones, haga clic en la pestaña Dispositivos arriba para consultar las instrucciones de OAuth 2.0 para dispositivos.

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. Registro de la aplicación como una aplicación instalada

    Cuando registres la aplicación, asegúrate de especificar que se trata de una aplicación instalada. Esto se traduce en un valor predeterminado diferente para el parámetro redirect_uri.

  2. 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. Al registrar una aplicación instalada, se crean automáticamente dos valores de redirect_uri: http://localhost:port y urn:ietf:wg:oauth:2.0:oob. Las siguientes descripciones pueden ayudarte a elegir el valor adecuado para la aplicación.

    http://localhost:port
    Este valor indica que el servidor de autorización de Google debe mostrar el código de autorización como un parámetro de string de consulta al servidor web del dispositivo del cliente. Es posible especificar un número de puerto sin cambiar la configuración de la Google APIs console.

    Para recibir el código de autorización en esta URL, la aplicación debe estar escuchando en el servidor web local. Si la plataforma lo admite, este es el mecanismo recomendado para obtener el código de autorización. Sin embargo, ten en cuenta que no todas las plataformas admiten este enfoque y que, incluso si la plataforma no lo admite, otros programas (por ejemplo, Firewall de Windows) pueden impedir la entrega del mensaje.

    urn:ietf:wg:oauth:2.0:oob
    Este valor indica que el servidor de autorización de Google debe mostrar el código de autorización en la barra de título del navegador. Esta opción es útil si el cliente no puede escuchar en un puerto HTTP sin realizar modificaciones importantes en el cliente. Las aplicaciones de Windows tienen esta característica.

    Si la aplicación utiliza este valor, es necesario determinar si el navegador ha cargado una respuesta del servidor de autorización. Luego, extrae el código de autorización del título de la página publicada en el navegador. Consulta el paso 4 para obtener instrucciones específicas sobre cómo analizar el token del título de la página.

    Si deseas evitar que el usuario vea la página con el código de autorización, la aplicación también debe cerrar la ventana del navegador. El mecanismo para el cierre de la ventana varía de plataforma en plataforma.
    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.
    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.

    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
    
  3. Manejo de la respuesta de Google

    Una vez que el usuario concede o niega el acceso a la aplicación, Google redirige al usuario al redirect_uri que se especificó en el paso 2 o muestra una página en el navegador del usuario.

    • Si estableces el redirect_uri en http://localhost (o alguna ruta en el servidor web local), se producirá una de estas dos situaciones:

      • Si el usuario concede el acceso a la aplicación, Google agrega un parámetro code al redirect_uri, como se muestra en la URL del ejemplo que aparece a continuación. Su valor especifica un código de autorización de un solo uso que se cambia por un token de acceso, como se describe en el paso 5.

        http://localhost/oauth2callback?code=SINGLE_USE_CODE
      • 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
    • Si estableces el redirect_uri en urn:ietf:wg:oauth:2.0:oob, el servidor de autorización de Google muestra una página en el navegador como la que aparece a continuación. Luego, la aplicación extrae el código de autorización del título de la página.

      Para extraer el token, la aplicación debe suponer que todo lo que sigue al último carácter de espacio en el título de la página es un string de parámetros cuyo formato es x=a&y=b. El código debe analizar los parámetros de ese substring y buscar una asignación code= o error= para indicar que la página contiene el string de título final y que el flujo de acceso se completó correctamente. Si el título de la página asigna un valor al parámetro code, ese valor es el token. Sin embargo, la aplicación no debe hacer suposiciones acerca de la extensión del token o la cantidad de parámetros del string de parámetros.

      Por ejemplo, la siguiente captura de pantalla muestra una página con los siguientes atributos:

      • Título de la página: Success code=4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu
      • String de parámetros: code=4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu
      • Token de autorización: 4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu

  4. 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 4 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 4.
    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
    
  5. 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.