OAuth 2.0 para apps de escritorio y dispositivos móviles

. En el resumen, se resumen los flujos de OAuth 2.0 que admite Google, lo que puede ayudarte a garantizar que hayas seleccionado el flujo adecuado para tu aplicación.

En este documento, se explica cómo las aplicaciones instaladas en dispositivos como teléfonos, tablets y computadoras usan los extremos de OAuth 2.0 de Google para autorizar el acceso a las API de Google.

OAuth 2.0 permite a los usuarios compartir datos específicos con una aplicación al mismo tiempo que mantienen privados sus nombres de usuario, contraseñas y otra información. Por ejemplo, una aplicación puede usar OAuth 2.0 a fin de obtener permiso de los usuarios para almacenar archivos en sus unidades de Google Drive.

Las apps instaladas se distribuyen a dispositivos individuales y se supone que estas apps no pueden conservar secretos. Pueden acceder a las API de Google mientras el usuario está presente en la app o se está ejecutando en segundo plano.

Este flujo de autorización es similar al que se usa para las aplicaciones del servidor web. La principal diferencia es que las apps instaladas deben abrir el navegador del sistema y proporcionar un URI de redireccionamiento local para manejar las respuestas del servidor de autorización de Google.

Alternativas

En el caso de las apps para dispositivos móviles, es posible que prefieras usar el Acceso con Google en Android o iOS. Las bibliotecas cliente de Acceso con Google controlan la autenticación y la autorización del usuario, y pueden ser más fáciles de implementar que el protocolo de nivel inferior descrito aquí.

En el caso de las apps que se ejecutan en dispositivos que no admiten un navegador del sistema o que tienen capacidades de entrada limitadas, como TVs, consolas de juegos, cámaras o impresoras, consulta OAuth 2.0 para TVs y dispositivos o Acceso en TVs y dispositivos de entrada limitados.

Bibliotecas y muestras

Recomendamos las siguientes bibliotecas y muestras para ayudarte a implementar el flujo de OAuth 2.0 que se describe en este documento:

• Biblioteca AppAuth para Android
• Biblioteca AppAuth para iOS
• OAuth para apps: muestras de Windows

Prerequisites

Habilita las API para tu proyecto.

Cualquier aplicación que llame a las API de Google debe habilitar esas API en el API Console.

Para habilitar una API en tu proyecto, sigue estos pasos:

1. Open the API Library en Google API Console
2. If prompted, select a project, or create a new one.
3. API Library enumera todas las API disponibles, agrupadas por familia y popularidad del producto. Si la API que quieres habilitar no está visible en la lista, usa la búsqueda para encontrarla o haz clic en Ver todo en la familia de productos a la que pertenece.
4. Seleccione la API que desea habilitar y, luego, haga clic en el botón Habilitar.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

Crea credenciales de autorización

Todas las aplicaciones que usen OAuth 2.0 para acceder a las API de Google deben tener credenciales de autorización que identifiquen la aplicación al servidor de OAuth 2.0 de Google. En los siguientes pasos, se explica cómo crear credenciales para tu proyecto. Tus aplicaciones pueden usar las credenciales a fin de acceder a las API que hayas habilitado para ese proyecto.

1. Go to the Credentials page.
2. Haz clic en Crear credenciales > ID de cliente de OAuth.
3. En las siguientes secciones, se describen los tipos de clientes y los métodos de redireccionamiento que admite el servidor de autorización de Google. Elige el tipo de cliente recomendado para tu aplicación, asigna un nombre a tu cliente de OAuth y configura los otros campos en el formulario que corresponda.

Esquema de URI personalizado (Android, iOS, UWP)

Se recomienda un esquema de URI personalizado para las apps para Android, las apps para iOS y las apps de la plataforma universal de Windows (UWP).

Android

1. Selecciona el tipo de aplicación Android.
2. Ingresa un nombre para el cliente de OAuth. Este nombre se muestra en el proyecto Credentials page para identificar al cliente.
3. Ingresa el nombre del paquete de tu app para Android. Este valor se define en el atributo package del elemento <manifest> en el archivo de manifiesto de tu app.
4. Ingresa la huella digital del certificado de firma SHA-1 de la distribución de la app.
   • Si tu app usa la firma de apps de Google Play, copia la huella digital SHA-1 de la página de firma de apps de Play Console.
   • Si administras tu propio almacén de claves y claves de firma, usa la utilidad keytool incluida con Java para imprimir la información del certificado en un formato legible. Copia el valor SHA1 en la sección Certificate fingerprints del resultado de keytool. Consulta Cómo autenticar tu cliente en la documentación de las API de Google para Android si quieres obtener más información.
5. Haga clic en Crear.

iOS

1. Seleccione el tipo de aplicación para iOS.
2. Ingresa un nombre para el cliente de OAuth. Este nombre se muestra en el proyecto Credentials page para identificar al cliente.
3. Ingresa el identificador del paquete para tu app. El ID del paquete es el valor de la clave CFBundleIdentifier en el archivo de recursos de la lista de propiedades de información de tu app (info.plist). Por lo general, el valor se muestra en el panel General o en el panel Signing &Capabilities del editor de proyectos de Xcode. El ID del paquete también se muestra en la sección Información general de la página Información de apps de la app en el sitio de App Store de Apple.
4. (Opcional)

   Ingresa el ID de la app en App Store si está publicada en la App Store de Apple. El ID de tienda es una string numérica incluida en cada URL de la App Store de Apple.

   1. Abre la app de App Store de Apple en tu dispositivo iOS o iPadOS.
   2. Busca tu app.
   3. Selecciona el botón Compartir (cuadrado y flecha hacia arriba).
   4. Selecciona Copiar vínculo.
   5. Pega el vínculo en un editor de texto. El ID de App Store es la parte final de la URL.

      Ejemplo: https://apps.apple.com/app/google/id284815942

5. (Opcional)

   Ingresa el ID de tu equipo. Para obtener más información, consulta Cómo encontrar tu ID de equipo en la documentación de la cuenta de desarrollador de Apple.

6. Haga clic en Crear.

UWP

1. Seleccione el tipo de aplicación Universal Windows Platform.
2. Ingresa un nombre para el cliente de OAuth. Este nombre se muestra en el proyecto Credentials page para identificar al cliente.
3. Ingresa el ID de Microsoft Store de 12 caracteres de tu app. Puedes encontrar este valor en el Centro de socios de Microsoft en la página Identidad de la app en la sección Administración de apps.
4. Haga clic en Crear.

En el caso de las aplicaciones de UWP, el esquema de URI personalizado no puede tener más de 39 caracteres.

Nota: Consulta la definición del parámetro redirect_uri para obtener detalles sobre el formato del valor del esquema de URI personalizado. Además, las bibliotecas y las muestras demuestran algunas implementaciones específicas de la plataforma de los redireccionamientos del esquema de URI personalizado.

Dirección IP de bucle invertido (macOS, Linux, computadora de escritorio con Windows)

Importante: La opción de redireccionamiento de la dirección IP de bucle invertido es OBSOLETO en las apps para dispositivos móviles. Puedes considerar una dirección IP de bucle invertido para aplicaciones de escritorio, incluidas las aplicaciones web. Considera un esquema de URI personalizado de apps para dispositivos móviles.

Para recibir el código de autorización con esta URL, tu aplicación debe escuchar en el servidor web local. Eso es posible en muchas plataformas, pero no en todas. Sin embargo, si tu plataforma lo admite, este es el mecanismo recomendado para obtener el código de autorización.

Cuando tu app recibe la respuesta de autorización, para ofrecer una mejor usabilidad, debe mostrar una página HTML que le indique al usuario que cierre el navegador y regrese a tu app.

Uso recomendado	Apps de macOS, Linux y Windows para escritorio (pero no para la Plataforma universal de Windows)
Valores del formulario	Configure el tipo de aplicación como Aplicación de escritorio.

Nota: Consulta la definición del parámetro redirect_uri para obtener más información sobre la dirección IP de bucle invertido. También es posible usar localhost en lugar de la IP de bucle invertido, pero esta configuración puede causar problemas con los firewalls del cliente. La mayoría de los firewalls, pero no todos, permiten la comunicación de bucle invertido.

Copiar y pegar manualmente

Importante: La opción de copiar y pegar manualmente, también conocida como método de redireccionamiento fuera de banda (OOB), es OBSOLETO. Puedes considerar un esquema de URI personalizado para apps para dispositivos móviles o una dirección IP de bucle invertido para aplicaciones de escritorio, incluidas las aplicaciones web.

Identifica los permisos de acceso

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

Antes de comenzar a implementar la autorización OAuth 2.0, te recomendamos que identifiques los permisos para los que tu app necesitará permiso de acceso.

Nota: La autorización incremental no es compatible con apps o dispositivos instalados.

El documento Alcances de la API de OAuth 2.0 contiene una lista completa de los alcances que puedes usar para acceder a las API de Google.

Si tu aplicación pública usa permisos que permiten el acceso a ciertos datos del usuario, debe completar un proceso de verificación. Si ves app no verificada en la pantalla cuando pruebas tu aplicación, debes enviar una solicitud de verificación para quitarla. Obtén más información sobre las apps no verificadas y obtén respuestas a preguntas frecuentes sobre la verificación de apps en el Centro de ayuda.

Obtén tokens de acceso de OAuth 2.0

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

Paso 1: Genera un verificador y desafío de código

Google admite el protocolo de clave de prueba para el intercambio de código (PKCE) a fin de que el flujo de la app instalada sea más seguro. Se crea un verificador de código único para cada solicitud de autorización y su valor transformado, llamado &code_challenge_quot;, se envía al servidor de autorización para obtener el código de autorización.

Crea el verificador de código

Un code_verifier es una string aleatoria criptográfica con alta entropía que usa los caracteres sin reserva [A-Z] /[a-z] /[0-9] / "-" / "." / "_" / "~", con una longitud mínima de 43 caracteres y 2 caracteres máximos.

El verificador de código debe tener suficiente entropía para que no sea fácil adivinar el valor.

Crea el desafío de código

Se admiten dos métodos para crear el desafío de código.

Métodos de generación de desafíos de código
S256 (recomendado)	El desafío de código es el hash SHA256 codificado en Base64URL (sin relleno) del verificador de código. code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
sin formato	El desafío de código tiene el mismo valor que el verificador de código generado anteriormente. code_challenge = code_verifier

Paso 2: Envía una solicitud al servidor OAuth 2.0 de Google

Para obtener la autorización del usuario, envía una solicitud al servidor de autorización de Google en https://accounts.google.com/o/oauth2/v2/auth. Este extremo controla la búsqueda de sesiones activa, autentica al usuario y obtiene su consentimiento. Solo se puede acceder al extremo mediante SSL y se rechazan las conexiones HTTP (no SSL).

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

Parámetros
client_id	Obligatorio El ID de cliente de tu aplicación. Puedes encontrar este valor en Credentials pagede API Console.
redirect_uri	Obligatorio Determina cómo el servidor de autorización de Google envía una respuesta a tu app. Hay varias opciones de redireccionamiento disponibles para las apps instaladas y debes configurar tus credenciales de autorización con un método de redireccionamiento en mente. 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 Consolede tu cliente Credentials page. Si este valor no coincide con un URI autorizado, verás un error redirect_uri_mismatch. En la siguiente tabla, se muestra el valor de parámetro redirect_uri adecuado para cada método: Valor redirect_uri Esquema de URI personalizado com.example.app:redirect_uri_path o com.googleusercontent.apps.123:redirect_uri_path com.example.app es la notación de DNS inversa de un dominio bajo tu control. El esquema personalizado debe contener un punto para que sea válido. com.googleusercontent.apps.123 es la notación de DNS inversa del ID de cliente. redirect_uri_path es un componente de ruta de acceso opcional, como /oauth2redirect. Ten en cuenta que la ruta de acceso debe comenzar con una sola barra, que es diferente de las URL HTTP normales. Dirección IP de bucle http://127.0.0.1:port o http://[::1]:port Consulta a tu plataforma para obtener la dirección IP de bucle invertido relevante y, luego, inicia un objeto de escucha HTTP en un puerto disponible aleatorio. Sustituye port por el número real de puertos que escucha la app. Ten en cuenta que la compatibilidad con la opción de redireccionamiento de dirección IP de bucle invertido en apps para dispositivos móviles es OBSOLETO.
response_type	Obligatorio Determina si el extremo de Google OAuth 2.0 muestra un código de autorización. Establece el valor del parámetro en code para las aplicaciones instaladas.
scope	Obligatorio Una lista delimitada por espacios de los permisos que identifican los recursos a los que podría acceder tu aplicación en nombre del usuario. Estos valores informan a la pantalla de consentimiento que Google muestra al usuario. Los permisos permiten que la aplicación solo solicite acceso a los recursos que necesita y, al mismo tiempo, permiten que los usuarios controlen la cantidad de acceso que otorgan a la aplicación. Por lo tanto, existe una relación inversa entre la cantidad de permisos solicitados y la probabilidad de obtener el consentimiento del usuario.
code_challenge	Se recomienda Especifica un code_verifier codificado que se usará como un desafío del servidor durante el intercambio de código de autorización. Consulta la sección anterior sobre el desafío del código de creación para obtener más información.
code_challenge_method	Se recomienda Especifica qué método se usó para codificar un code_verifier que se usará durante el intercambio del código de autorización. Este parámetro se debe usar con el parámetro code_challenge descrito anteriormente. El valor de code_challenge_method se establece de forma predeterminada en plain si no está presente en la solicitud que incluye un code_challenge. Los únicos valores admitidos para este parámetro son S256 o plain.
state	Se recomienda Especifica cualquier valor de string que utilice tu aplicación para mantener el estado entre tu solicitud de autorización y la respuesta del servidor de autorización. El servidor muestra el valor exacto que envías como un par name=value en el identificador de fragmento de URL (#) de la redirect_uri después de que el usuario acepta o rechaza la solicitud de acceso a la aplicación. Puedes usar este parámetro para varios propósitos, como dirigir al usuario al recurso correcto en tu aplicación, enviar nonces y mitigar la falsificación de solicitudes entre sitios. Como se puede adivinar tu redirect_uri, usar un valor de state puede aumentar la certeza de que una conexión entrante es el resultado de una solicitud de autenticación. Si generas una string aleatoria o codificas el hash de una cookie o algún otro valor que capture el estado del cliente, puedes validar la respuesta para asegurarte de que la solicitud y la respuesta se hayan originado en el mismo navegador, lo que brinda protección contra ataques, como la falsificación de solicitudes entre sitios. Consulta la documentación de OpenID Connect para ver un ejemplo de cómo crear y confirmar un token state.
login_hint	Opcional Si tu aplicación sabe qué usuario intenta autenticarse, puede usar este parámetro para proporcionar una sugerencia al servidor de autenticación de Google. El servidor usa la sugerencia para simplificar el flujo de acceso, ya sea completando el campo de correo electrónico en el formulario de acceso o seleccionando la sesión apropiada de acceso múltiple. Establece el valor del parámetro en una dirección de correo electrónico o en un identificador sub, que es equivalente al ID de Google del usuario.

Nota: No se admite la autorización incremental para apps instaladas debido a que el cliente no puede mantener la confidencialidad de client_secret.

Ejemplo de URL de autorización

Las pestañas a continuación muestran URL de autorización de muestra para las diferentes opciones de URI de redireccionamiento.

Las URL son idénticas, excepto por el valor del parámetro redirect_uri. Las URL también contienen los parámetros obligatorios response_type y client_id, así como el parámetro opcional state. Cada URL contiene saltos de línea y espacios para facilitar la lectura.

Esquema de URI personalizado

https://accounts.google.com/o/oauth2/v2/auth?
 scope=&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

Dirección IP de bucle invertido

https://accounts.google.com/o/oauth2/v2/auth?
 scope=&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

Paso 3: Google solicita el consentimiento del usuario

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

No es necesario que tu aplicación haga nada en esta etapa mientras espera la respuesta del servidor de OAuth 2.0 de Google para indicar si se le otorgó acceso. Esa respuesta se explica en el siguiente paso.

Errors

Las solicitudes al extremo de autorización de OAuth 2.0 de Google pueden mostrar mensajes de error para el usuario en lugar de los flujos de autenticación y autorización esperados. A continuación, se indican los códigos de error comunes y las resoluciones sugeridas.

admin_policy_enforced

La Cuenta de Google no puede autorizar uno o más permisos solicitados debido a las políticas de su administrador de Google Workspace. Consulta el artículo de ayuda para administradores de Google Workspace Controla qué apps internas y de terceros acceden a los datos de Google Workspace para obtener más información sobre cómo un administrador puede restringir el acceso a todos los permisos o a los permisos sensibles y restringidos hasta que se otorgue acceso explícitamente a tu ID de cliente de OAuth.

disallowed_useragent

El extremo de autorización se muestra dentro de un usuario-agente incorporado que no permite las Políticas de OAuth 2.0 de Google.

Android

Es posible que los desarrolladores de Android encuentren este mensaje de error cuando abran solicitudes de autorización en android.webkit.WebView. En su lugar, los desarrolladores deben usar bibliotecas de Android, como Acceso con Google para Android o AppAuth para Android, de OpenID Foundation.

Es posible que los desarrolladores web experimenten este error cuando una app de Android abre un vínculo web general en un usuario-agente incorporado y un usuario navega hacia el extremo de autorización de OAuth 2.0 de Google desde tu sitio. Los desarrolladores deben permitir que se abran vínculos generales en el controlador de vínculos predeterminado del sistema operativo, que incluye controladores de Android App Links o la app de navegador predeterminada. La biblioteca de pestañas personalizadas de Android también es una opción compatible.

iOS

Los desarrolladores de iOS y macOS pueden encontrar este error cuando abren solicitudes de autorización en WKWebView. En su lugar, los desarrolladores deben usar bibliotecas de iOS, como Acceso con Google para iOS o AppAuth para iOS de OpenID Foundation.

Los desarrolladores web pueden encontrar este error cuando una app para iOS o macOS abre un vínculo web general en un usuario-agente incorporado y un usuario navega hacia el extremo de autorización de OAuth 2.0 de Google desde tu sitio. Los desarrolladores deben permitir que se abran vínculos generales en el controlador de vínculos predeterminado del sistema operativo, que incluye controladores de Universal Links o la app de navegador predeterminada. La biblioteca SFSafariViewController también es una opción compatible.

org_internal

El ID de cliente de OAuth de la solicitud forma parte de un proyecto que limita el acceso a las Cuentas de Google en una Organización de Google Cloud específica. Para obtener más información sobre esta opción de configuración, consulta la sección Tipo de usuario en el artículo de ayuda Configura tu pantalla de consentimiento de OAuth.

redirect_uri_mismatch

El redirect_uri que se pasa en la solicitud de autorización no coincide con un URI de redireccionamiento autorizado para el ID de cliente de OAuth. Revisa los URI de redireccionamiento autorizados en Google API Console Credentials page.

Es posible que el redirect_uri pasado no sea válido para el tipo de cliente.

Paso 4: Controla la respuesta del servidor OAuth 2.0

La manera en la que tu aplicación recibe la respuesta de autorización depende del esquema de URI de redireccionamiento que usa. Sin importar el esquema, la respuesta contendrá un código de autorización (code) o un error (error). Por ejemplo, error=access_denied indica que el usuario rechazó la solicitud.

Si el usuario otorga acceso a tu aplicación, puedes intercambiar el código de autorización por un token de acceso y un token de actualización como se describe en el siguiente paso.

Paso 5: Intercambia código de autorización para tokens de actualización y acceso

Para intercambiar un código de autorización por un token de acceso, llama al extremo https://oauth2.googleapis.com/token y configura los siguientes parámetros:

Campos
client_id	Es el ID de cliente obtenido de API Console Credentials page.
client_secret	El secreto de cliente obtenido de API ConsoleCredentials page.
code	El código de autorización que muestra la solicitud inicial
code_verifier	El verificador de código que creaste en el Paso 1
grant_type	Como se define en la especificación de OAuth 2.0, el valor de este campo se debe configurar como authorization_code.
redirect_uri	Uno de los URI de redireccionamiento enumerados para tu proyecto en el API ConsoleCredentials page de la client_id determinada.

El siguiente fragmento muestra una solicitud de muestra:

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

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http%3A//127.0.0.1%3A9004&
grant_type=authorization_code

Para responder a esta solicitud, Google muestra un objeto JSON que contiene un token de acceso de corta duración y un token de actualización.

La respuesta contiene los siguientes campos:

Campos
access_token	El token que envía tu aplicación para autorizar una solicitud a la API de Google.
expires_in	El ciclo de vida restante del token de acceso en segundos.
id_token	Nota: Esta propiedad solo se muestra si tu solicitud incluyó un alcance de identidad, como openid, profile o email. El valor es un token web JSON (JWT) que contiene información de identidad con firma digital sobre el usuario.
refresh_token	Un token que puedes usar para obtener un nuevo token de acceso. Los tokens de actualización son válidos hasta que el usuario revoca el acceso. Ten en cuenta que siempre se muestran tokens de actualización para las aplicaciones instaladas.
scope	Los permisos de acceso otorgados por access_token, expresados como una lista de strings delimitadas por espacios y mayúsculas de minúsculas,
token_type	El tipo de token que se muestra. En este momento, el valor de este campo siempre es Bearer.

Importante: La aplicación debe almacenar ambos tokens en un lugar seguro y de larga duración al que se pueda acceder entre diferentes invocaciones de la aplicación. El token de actualización permite que tu aplicación obtenga un nuevo token de acceso si vence. Por lo tanto, si la aplicación pierde el token de actualización, el usuario deberá repetir el flujo de consentimiento de OAuth 2.0 para que pueda obtener un nuevo token de actualización.

En el siguiente fragmento, se muestra un ejemplo de respuesta:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Nota: Tu aplicación debe ignorar cualquier campo no reconocido que se incluya en la respuesta.

Cómo llamar a las API de Google

Una vez que tu aplicación obtenga un token de acceso, puedes usarlo para hacer 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 incluyendo un parámetro de búsqueda 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, al llamar a la API de Drive Files).

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

Ejemplos de HTTP GET

Una llamada al extremo drive.files (la API de Drive Files) mediante el encabezado HTTP Authorization: Bearer podría verse 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 mediante 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, se muestra un ejemplo que 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, puedes usar la opción del parámetro de string de consulta:

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

Actualización de un token de acceso

Los tokens de acceso se vencen periódicamente y se convierten en credenciales no válidas para una solicitud a la API relacionada. Puedes actualizar un token de acceso sin solicitarle permiso al usuario (incluso cuando no está presente) si solicitaste acceso sin conexión a los permisos asociados con el token.

Para actualizar un token de acceso, la aplicación envía una solicitud POST de HTTPS al servidor de autorización de Google (https://oauth2.googleapis.com/token) que incluye los siguientes parámetros:

Campos
client_id	Es el ID de cliente obtenido de API Console.
client_secret	El secreto de cliente obtenido de API Console. (client_secret no se aplica a solicitudes de clientes registrados como aplicaciones para Android, iOS o Chrome).
grant_type	Como se define en la especificación de OAuth 2.0, el valor de este campo se debe establecer en refresh_token.
refresh_token	El token de actualización que se muestra en el intercambio del código de autorización.

El siguiente fragmento muestra una solicitud de muestra:

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

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Siempre que el usuario no haya revocado el acceso otorgado a la aplicación, el servidor de tokens muestra un objeto JSON que contiene un token de acceso nuevo. En el siguiente fragmento, se muestra un ejemplo de respuesta:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

Ten en cuenta que hay 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 para todos los clientes. Debes guardar los tokens de actualización en el almacenamiento a largo plazo y continuar usándolos mientras sean válidos. Si tu aplicación solicita demasiados tokens de actualización, es posible que se alcance a estos límites. En ese caso, los tokens de actualización más antiguos dejarán de funcionar.

Revoca un token

En algunos casos, un usuario podría querer revocar el acceso otorgado a una aplicación. Un usuario puede revocar el acceso desde la Configuración de la cuenta. Consulta la sección Cómo quitar el acceso a un sitio o app del documento de asistencia de sitios y apps de terceros con acceso a tu cuenta para obtener más información.

También es posible que una aplicación revoque de manera programática el acceso otorgado. La revocación programática es importante en los casos en los que un usuario anula la suscripción, quita una aplicación o los recursos de la API que requiere una aplicación cambiaron de manera significativa. En otras palabras, parte del proceso de eliminación puede incluir una solicitud a la API para garantizar que se quiten los permisos otorgados anteriormente a la aplicación.

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}

El token puede ser un token de acceso o un token de actualización. Si el token es 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, 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.

Nota: Si se realiza una respuesta de revocación correcta, es posible que la revocación demore un poco en aplicarse.

Material de lectura adicional

La práctica recomendada actual de IETF: OAuth 2.0 para aplicaciones nativas, establece muchas de las prácticas recomendadas que se documentan aquí.