OAuth 2.0 para apps de escritorio y dispositivos móviles

En este documento, se explica cómo las aplicaciones instaladas en dispositivos como teléfonos, tablets y computadoras usan los extremos 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 y, al mismo tiempo, mantener la privacidad de sus nombres de usuario, contraseñas y demás información. Por ejemplo, una aplicación puede usar OAuth 2.0 a fin de obtener el 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 no pueden guardar secretos. Pueden acceder a las APIs de Google mientras el usuario está presente en la app o cuando esta se ejecuta en segundo plano.

Este flujo de autorización es similar al que se usa para las aplicaciones de servidor web. La diferencia principal 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 para Android o iOS. Las bibliotecas cliente de Acceso con Google administran la autenticación y la autorización de usuarios, y es posible que sean más fáciles de implementar que el protocolo de nivel inferior que se describe 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 implementar el flujo de OAuth 2.0 que se describe en este documento:

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

Requisitos previos

Habilita las API para tu proyecto.

Cualquier aplicación que llame a las APIs de Google debe habilitarlas en la API Console.

Para habilitar una API en tu proyecto, haz lo siguiente:

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 APIs disponibles, agrupadas por familia de productos y popularidad. Si la API que quieres habilitar no está 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. Selecciona la API que deseas habilitar y, luego, haz 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

Cualquier aplicación que use OAuth 2.0 para acceder a las APIs de Google debe tener credenciales de autorización que identifiquen la aplicación para el servidor OAuth 2.0 de Google. En los siguientes pasos, se explica cómo crear credenciales para tu proyecto. Luego, tus aplicaciones pueden usar las credenciales con el objetivo de acceder a las APIs 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 cliente 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, asígnale un nombre a tu cliente de OAuth y configura los otros campos del formulario según corresponda.

Identifica los permisos de acceso

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

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

En el documento Alcances de la API de OAuth 2.0, se incluye una lista completa de los alcances que puedes usar para acceder a las API de Google.

Obtén tokens de acceso de OAuth 2.0

En los siguientes pasos, se muestra cómo interactúa tu aplicación con el servidor de OAuth 2.0 de Google a fin de obtener el consentimiento de un usuario para realizar una solicitud a la API en su nombre. 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 de código y un desafío

Google admite el protocolo de prueba de clave 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", 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 criptográfica aleatoria de alta entropía que usa caracteres sin reservar: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", con una longitud mínima de 43 caracteres y una longitud máxima de 128 caracteres.

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

Cómo crear el desafío de código

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

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

Paso 2: Envía una solicitud al servidor de 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 sesión activa, autentica al usuario y obtiene su consentimiento. Solo se puede acceder al extremo a través de SSL y rechaza las conexiones HTTP (no SSL).

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

Ejemplos de URL de autorización

En las siguientes pestañas se muestran ejemplos de URL de autorización para las diferentes opciones de URI de redireccionamiento.

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

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 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

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 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 otorga a tu aplicación el acceso solicitado. En esta etapa, Google muestra una ventana de consentimiento que muestra el nombre de tu aplicación y los servicios de la API de Google a los que solicita permiso de acceso con las credenciales de autorización del usuario, así como un resumen de los permisos de acceso que se otorgarán. Luego, el usuario puede otorgar acceso a uno o más alcances solicitados por la aplicación, o rechazar la solicitud.

Tu aplicación no necesita realizar ninguna acción en esta etapa, ya que espera la respuesta del servidor OAuth 2.0 de Google que indique si se otorgó algún acceso. Esa respuesta se explica en el siguiente paso.

Paso 4: Controla la respuesta del servidor de OAuth 2.0

La forma en que tu aplicación recibe la respuesta de autorización depende del esquema de URI de redireccionamiento que usa. Independientemente del 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 la 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 el código de autorización por 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:

En el siguiente fragmento, se muestra una solicitud de ejemplo:

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://127.0.0.1:9004&
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:

En el siguiente fragmento, se muestra una respuesta de muestra:

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

Llama a las APIs de Google

Después de que la aplicación obtiene 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 del encabezado HTTP Authorization. Siempre que sea posible, se prefiere el encabezado HTTP, ya que las cadenas 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 llamas a la API de Archivos de Drive).

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

Ejemplos de HTTP GET

Una llamada al extremo drive.files (la API de Archivos de Drive) 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 con el parámetro de cadena 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. En el siguiente ejemplo, 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 cadena 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 vencen periódicamente y se dejan de ser 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 HTTPS al servidor de autorización de Google (https://oauth2.googleapis.com/token) que incluye los siguientes parámetros:

En el siguiente fragmento, se muestra una solicitud de ejemplo:

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 una respuesta de ejemplo:

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

Ten en cuenta que existen límites para la cantidad de tokens de actualización que se emitirán: uno por combinación de cliente y usuario, y otro por usuario para todos los clientes. Debes guardar los tokens de actualización en un almacenamiento a largo plazo y seguir usándolos mientras sean válidos. Si tu aplicación solicita demasiados tokens de actualización, podría alcanzar estos límites, en cuyo caso los tokens de actualización más antiguos dejarán de funcionar.

Revoca un token

En algunos casos, es posible que el usuario desee revocar el acceso otorgado a una aplicación. El usuario puede revocar el acceso a través de la Configuración de la cuenta. Para obtener más información, consulta el documento de asistencia Cómo quitar el acceso a sitios o apps de Sitios y apps de terceros con acceso a tu cuenta.

También es posible que una aplicación revoque de forma programática el acceso que se le otorgó. La revocación programática es importante en los casos en que un usuario anula la suscripción, quita una aplicación o si los recursos de la API que requiere una app 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, tu aplicación envía 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 de acceso o de actualización. Si se trata de un token de acceso y tiene un token de actualización correspondiente, el token de actualización 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.

Material de lectura adicional

En la práctica actual recomendada de IETF, OAuth 2.0 para apps nativas establece muchas de las prácticas recomendadas documentadas aquí.