OAuth 2.0 para apps de escritorio y dispositivos móviles

En la descripción general, se resumen los flujos de OAuth 2.0 que admite Google, lo que puede ayudarte a asegurarte de que seleccionaste el flujo correcto 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 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.

Android

1. Selecciona el tipo de aplicación Android.
2. Ingresa un nombre para el cliente de OAuth. Este nombre se muestra en la Credentials page de tu proyecto 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 apps.
   • 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, que se incluye con Java, para imprimir información del certificado en un formato legible. Copia el valor SHA1 en la sección Certificate fingerprints del resultado de keytool. Consulta Autenticación de tu cliente en la documentación de las APIs de Google para Android para obtener más información.
5. (Opcional) Verifica la propiedad de tu aplicación para Android.
6. Haz clic en Crear.

iOS

1. Selecciona el tipo de aplicación iOS.
2. Ingresa un nombre para el cliente de OAuth. Este nombre se muestra en la Credentials page de tu proyecto para identificar al cliente.
3. Ingresa el identificador de paquete de tu app. Este ID es el valor de la clave CFBundleIdentifier en el archivo de recursos de lista de propiedades de información de tu app (info.plist). El valor se muestra con mayor frecuencia 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 de información general de la página de información de la app en el sitio de App Store Connect de Apple.
4. (opcional)

   Ingrese el ID de la aplicación en App Store si esta está publicada en el App Store de Apple. El ID de la tienda es una cadena 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 símbolo de 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 tu ID de equipo. Consulta Cómo encontrar tu ID de equipo en la documentación de la cuenta de desarrollador de Apple para obtener más información.

6. Haz clic en Crear.

UWP

1. Selecciona el tipo de aplicación Universal Windows Platform.
2. Ingresa un nombre para el cliente de OAuth. Este nombre se muestra en la Credentials page de tu proyecto 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. Haz clic en Crear.

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

Esquema de URI personalizado (Android, iOS, UWP)

Los esquemas de URI personalizados son una forma de vinculación directa que usa un esquema definido de forma personalizada para abrir tu app.

Importante: Los esquemas de URI personalizados ya no se admiten en las nuevas apps de Chrome y están inhabilitados de forma predeterminada en los nuevos clientes de Android debido al riesgo de robo de identidad de apps.

Alternativa al uso de esquemas de URI personalizados en Android

Usa el SDK de Acceso con Google para Android, que entrega la respuesta de OAuth 2.0 directamente a tu app y elimina la necesidad de un URI de redireccionamiento.

Cómo migrar al SDK de Acceso con Google para Android

Si actualmente usas un esquema personalizado para tu integración de OAuth en Android, deberás completar las siguientes acciones a fin de migrar por completo al SDK recomendado de Acceso con Google para Android:

1. Actualiza tu código para usar el SDK de Acceso con Google.
2. Inhabilitar la compatibilidad con el esquema personalizado en la Consola de API de Google

Nota: Para evitar que los usuarios reciban un mensaje de error de invalid_request cuando intenten usar tu app, debes completar e implementar las actualizaciones de código (ten en cuenta el tiempo de adopción en toda la base de usuarios o dispositivos más antiguos) antes de inhabilitar la compatibilidad con esquemas personalizados en la Consola de APIs de Google.

Sigue estos pasos para migrar al SDK de Android de Acceso con Google:

1. Actualiza tu código para usar el SDK de Android de Acceso con Google:
   1. Examina tu código para identificar dónde envías una solicitud al servidor de OAuth 2.0 de Google. Si usas un esquema personalizado, tu solicitud se vería como se muestra a continuación:

        https://accounts.google.com/o/oauth2/v2/auth?
        scope=<SCOPES>&
        response_type=code&
        &state=<STATE>&
        redirect_uri=com.example.app:/oauth2redirect&
        client_id=<CLIENT_ID>
        

      com.example.app:/oauth2redirect es el URI de redireccionamiento del esquema personalizado del ejemplo anterior. Consulta la definición del parámetro redirect_uri para obtener más detalles sobre el formato del valor del esquema de URI personalizado.
   2. Toma nota de los parámetros de solicitud scope y client_id que necesitarías para configurar el SDK de Acceso con Google.
      Nota: Si usas una biblioteca de terceros, revisa el archivo de configuración de la biblioteca para encontrar esta información.
   3. Sigue las instrucciones de Comienza a integrar el Acceso con Google en tu app para Android a fin de configurar el SDK. Puedes omitir el paso Obtén el ID de cliente de OAuth 2.0 del servidor de backend, ya que volverías a usar el client_id que recuperaste del paso anterior.
   4. Sigue las instrucciones para habilitar el acceso a la API del servidor. Esto incluye los siguientes pasos:
      1. Usa el método getServerAuthCode a fin de recuperar un código de Auth para los permisos para los que solicitas permiso.
      2. Envía el código de Auth al backend de tu app para intercambiarlo por un token de acceso y actualización.
      3. Usa el token de acceso recuperado para realizar llamadas a las APIs de Google en nombre del usuario.
      Nota: Si tu aplicación no requiere acceso sin conexión, sigue estas instrucciones para solicitar acceso a la API del cliente.
2. Inhabilita la compatibilidad con el esquema personalizado en la Consola de API de Google:
   1. Ve a la lista de credenciales de OAuth 2.0 y selecciona tu cliente de Android.
   2. Navega a la sección Configuración avanzada, desmarca la casilla de verificación Habilitar el esquema de URI personalizado y haz clic en Guardar para inhabilitar la compatibilidad con el esquema de URI personalizado.

Habilita el esquema de URI personalizado

Si la alternativa recomendada no funciona en tu caso, puedes habilitar los esquemas de URI personalizados para tu cliente de Android siguiendo las instrucciones que se indican a continuación:

1. Ve a la lista de credenciales de OAuth 2.0 y selecciona tu cliente de Android.
2. Navega a la sección Configuración avanzada, marca la casilla de verificación Habilitar el esquema de URI personalizado y haz clic en Guardar para habilitar la compatibilidad con el esquema de URI personalizado.

Alternativa al uso de esquemas de URI personalizados en apps de Chrome

Usa la API de Chrome Identity, que entrega la respuesta de OAuth 2.0 directamente a la app y elimina la necesidad de un URI de redireccionamiento.

Cómo verificar la propiedad de la app (Android y Chrome)

Puedes verificar la propiedad de tu aplicación para reducir el riesgo de robo de identidad.

Android

Nota: Por el momento, la verificación de la propiedad de una app para Android solo está disponible en apps de Google Play.

Para completar el proceso de verificación, puedes usar tu cuenta de desarrollador de Google Play si tienes una y tu app está registrada en Google Play Console. Para que la verificación se complete correctamente, debes cumplir los siguientes requisitos:

• Debes tener una aplicación registrada en Google Play Console con el mismo nombre de paquete y la misma huella digital del certificado de firma SHA-1 que el cliente de OAuth de Android para el que deseas completar la verificación.
• Debes tener permiso de Administrador para la app en Google Play Console. Obtén más información sobre la administración de accesos en Google Play Console.

En la sección Verify App Ownership del cliente de Android, haz clic en el botón Verify Ownership para completar el proceso de verificación.

Si la verificación se realiza correctamente, se mostrará una notificación para confirmar que el proceso se realizó correctamente. De lo contrario, se mostrará un mensaje de error.

Para corregir una verificación con errores, prueba lo siguiente:

• Asegúrate de que la app que quieres verificar esté registrada en Google Play Console.
• Asegúrate de tener permiso de Administrador para la app en Google Play Console.

Chrome

Para completar el proceso de verificación, usa tu cuenta de desarrollador de Chrome Web Store. Para que la verificación se complete correctamente, debe cumplir con los siguientes requisitos:

• Debes tener un elemento registrado en el Panel del desarrollador de Chrome Web Store con el mismo ID de elemento que el cliente de OAuth de la extensión de Chrome para el que deseas completar la verificación.
• Debes ser publicador del elemento de Chrome Web Store. Obtén más información sobre la administración de accesos en el Panel del desarrollador de Chrome Web Store.

En la sección Verify App Ownership del cliente de la extensión de Chrome, haz clic en el botón Verify Ownership para completar el proceso de verificación.

Nota: Espera unos minutos antes de completar el proceso de verificación después de otorgar acceso a tu cuenta.

Si la verificación se realiza correctamente, se mostrará una notificación para confirmar que el proceso se realizó correctamente. De lo contrario, se mostrará un mensaje de error.

Para corregir una verificación con errores, prueba lo siguiente:

• Asegúrate de que haya un elemento registrado en el Panel del desarrollador de Chrome Web Store con el mismo ID de elemento que el cliente de OAuth de la extensión de Chrome para el que deseas completar la verificación.
• Asegúrate de ser el publicador de la app, es decir, debes ser el publicador individual de la app o un miembro del publicador del grupo de la app. Obtén más información sobre la administración de accesos en el Panel del desarrollador de Chrome Web Store.
• Si acabas de actualizar la lista de publicadores de grupo, verifica que la lista de membresías de publicadores de grupo esté sincronizada en el Panel del desarrollador de Chrome Web Store. Obtén más información para sincronizar tu lista de membresías del editor.

Dirección IP de bucle invertido (en macOS, Linux y Windows)

Importante: La opción de redireccionamiento de dirección IP de bucle invertido no está disponible para los tipos de cliente de OAuth para Android, iOS y Android. Consulta la guía de migración de direcciones IP de bucle invertido para obtener instrucciones sobre cómo migrar a una alternativa compatible.

Para recibir el código de autorización con esta URL, la aplicación debe estar escuchando en el servidor web local. Esto 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 mejorar la usabilidad, esta debe mostrar una página HTML que le indique al usuario que cierre el navegador y vuelva a tu app.

Uso recomendado	Apps de escritorio de macOS, Linux y Windows (pero no para la plataforma universal de Windows)
Valores del formulario	Configura 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, aunque no todos, permiten la comunicación de bucle invertido.

Copiar y pegar manualmente

Importante: Ya no se admite la opción de copiar y pegar manual, también conocida como método de redireccionamiento fuera de banda (OOB). Consulta la guía de migración de OOB a fin de obtener instrucciones para migrar a una alternativa segura.

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.

Nota: No se admite la autorización incremental para apps o dispositivos instalados.

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.

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

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.

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 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:

Parámetros
client_id	Obligatorio El ID de cliente de tu aplicación. Puedes encontrar este valor en API Console Credentials page.
redirect_uri	Obligatorio Determina cómo el servidor de autorización de Google envía una respuesta a tu app. Existen varias opciones de redireccionamiento disponibles para las apps instaladas, y tendrás que configurar tus credenciales de autorización con un método de redireccionamiento en particular en mente. El valor debe coincidir exactamente con uno de los URI de redireccionamiento autorizados para el cliente OAuth 2.0, que configuraste en la API Console Credentials pagede tu cliente. Si este valor no coincide con un URI autorizado, obtendrás un error redirect_uri_mismatch. En la siguiente tabla, se muestra el valor del parámetro redirect_uri apropiado 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 DNS inversa de un dominio bajo tu control. El esquema personalizado debe contener un punto para ser válido. com.googleusercontent.apps.123 es la notación DNS inversa del ID de cliente. redirect_uri_path es un componente opcional de la ruta de acceso, como /oauth2redirect. Ten en cuenta que la ruta de acceso debe comenzar con una sola barra, que es diferente de las URL HTTP normales. Nota : Los esquemas de URI personalizados ya no son compatibles con las apps de Chrome y están inhabilitados de forma predeterminada en Android. Obtén más información sobre las alternativas de esquemas personalizados para las apps de Android y Chrome. Dirección IP de bucle invertido http://127.0.0.1:port o http://[::1]:port Consulta tu plataforma para obtener la dirección IP de bucle invertido relevante y, luego, inicia un objeto de escucha de HTTP en un puerto aleatorio disponible. Sustituye port por el número de puerto real en el que escucha tu app. Ten en cuenta que la compatibilidad con la opción de redireccionamiento de la dirección IP de bucle invertido en las apps para dispositivos móviles no está disponible.
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 tu aplicación podría acceder en nombre del usuario. Estos valores informan la pantalla de consentimiento que Google muestra al usuario. Los permisos permiten que tu 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 tu aplicación. Por lo tanto, existe una relación inversa entre la cantidad de alcances solicitados y la probabilidad de obtener el consentimiento del usuario.
code_challenge	Se recomienda Especifica un code_verifier codificado que se usará como desafío del servidor durante el intercambio de código de autorización. Consulta la sección anterior Cómo crear un desafío de código 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 de código de autorización. Este parámetro debe usarse con el parámetro code_challenge descrito anteriormente. El valor predeterminado de code_challenge_method es 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 tu aplicación usa para mantener el estado entre la 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 redirect_uri después de que el usuario da su consentimiento o rechaza la solicitud de acceso de tu aplicación. Puedes usar este parámetro para varios fines, como dirigir al usuario al recurso correcto en tu aplicación, enviar nonces y mitigar la falsificación de solicitudes entre sitios. Como tu redirect_uri puede adivinarse, usar un valor state puede aumentar la seguridad de que una conexión entrante sea 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 captura el estado del cliente, puedes validar la respuesta para garantizar, además, 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 está intentando autenticar, 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 previamente el campo de correo electrónico en el formulario de acceso o seleccionando la sesión de acceso múltiple adecuada. Establece el valor del parámetro en una dirección de correo electrónico o un identificador sub, que equivale al ID de Google del usuario.

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

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.

Esquema de URI personalizado

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

Dirección IP de bucle invertido

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.

Errores

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 soluciones 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é aplicaciones 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 permisos sensibles y restringidos hasta que se otorgue acceso de manera explícita a tu ID de cliente de OAuth.

disallowed_useragent

El extremo de autorización se muestra en un usuario-agente incorporado no permitido por las Políticas de OAuth 2.0 de Google.

Android

Los desarrolladores de Android pueden encontrar este mensaje de error cuando abren solicitudes de autorización en android.webkit.WebView. En su lugar, los desarrolladores deben usar bibliotecas de Android, como AppAuth para Android de OpenID Foundation o Acceso con Google para Android.

Los desarrolladores web pueden encontrar este error cuando una app para Android abre un vínculo web general en un usuario-agente incorporado y un usuario navega al extremo de autorización de OAuth 2.0 de Google desde tu sitio. Los desarrolladores deben permitir que los vínculos generales se abran 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 Android Custom Tabs 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 AppAuth para iOS de OpenID Foundation o Acceso con Google para iOS.

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

org_internal

El ID de cliente de OAuth en la solicitud es 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 la pantalla de consentimiento de OAuth.

invalid_grant

Si usas un verificador y un desafío de código, el parámetro code_callenge no es válido o falta. Asegúrate de que el parámetro code_challenge esté configurado de forma correcta.

Cuando actualizas un token de acceso, es posible que este haya vencido o se haya invalidado. Vuelve a autenticar al usuario y solicita su consentimiento para obtener tokens nuevos. Si continúas viendo este error, asegúrate de que tu aplicación se haya configurado correctamente y de que estás usando los tokens y parámetros correctos en tu solicitud. De lo contrario, es posible que la cuenta de usuario se haya borrado o inhabilitado.

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 el Google API Console Credentials page.

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

El parámetro redirect_uri puede hacer referencia al flujo fuera de banda (OOB) de OAuth que dejó de estar disponible y ya no es compatible. Consulta la guía de migración para actualizar tu integración.

invalid_request

Se produjo un error con la solicitud que realizaste. Esto podría deberse a varios motivos:

• La solicitud no tenía el formato correcto
• Faltan parámetros obligatorios en la solicitud
• La solicitud usa un método de autorización que Google no admite. Verifica que tu integración de OAuth use un método de integración recomendado
• Se usa un esquema personalizado para el URI de redireccionamiento : Si ves el mensaje de error El esquema de URI personalizado no es compatible con las apps de Chrome o El esquema de URI personalizado no está habilitado para tu cliente Android, significa que estás usando un esquema de URI personalizado que no es compatible con las apps de Chrome y que está inhabilitado de forma predeterminada en Android. Más información sobre las alternativas de esquemas de URI personalizados

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:

Campos
client_id	El ID de cliente obtenido de API Console Credentials page.
client_secret	El secreto del cliente obtenido de API Console Credentials page.
code	El código de autorización que se muestra en 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 establecer en authorization_code.
redirect_uri	Se trata de uno de los URI de redireccionamiento enumerados para tu proyecto en el archivo Credentials page de API Consolecorrespondiente al client_id determinado.

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:

Campos
access_token	Es el token que envía la aplicación para autorizar una solicitud a la API de Google.
expires_in	La vida útil restante del token de acceso, expresada en segundos.
id_token	Nota: Esta propiedad solo se muestra si tu solicitud incluía un permiso 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 token de acceso nuevo. Los tokens de actualización son válidos hasta que el usuario revoque el acceso. Ten en cuenta que los tokens de actualización siempre se muestran para las aplicaciones instaladas.
scope	Los permisos de acceso que otorga access_token, expresados como una lista de strings separadas por espacios y que distinguen mayúsculas de minúsculas.
token_type	El tipo de token que se muestra. En este momento, el valor de este campo siempre se establece en Bearer.

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

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"
}

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

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:

Campos
client_id	El ID de cliente obtenido de API Console.
client_secret	El secreto del cliente obtenido de API Console. (client_secret no se aplica a las 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 de código de autorización.

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.

Nota: Después de recibir una respuesta de revocación exitosa, es posible que la revocación demore un tiempo en aplicarse por completo.

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í.