OAuth 2.0 para apps de escritorio y dispositivos móviles

2

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 mantiene la privacidad de sus nombres de usuario, contraseñas y otra información. Por ejemplo, una aplicación puede usar OAuth 2.0 para obtener el permiso de los usuarios y, así, 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:

Requisitos previos

Habilita las API para tu proyecto.

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

Sigue estos pasos para habilitar una API en tu proyecto:

  1. Open the API Library en Google API Console.
  2. If prompted, select a project, or create a new one.
  3. El elemento API Library enumera todas las APIs disponibles, agrupadas por familia de productos y popularidad. 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. 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 de OAuth 2.0 de Google. En los siguientes pasos, se explica cómo crear credenciales para tu proyecto. Luego, las aplicaciones pueden usar las credenciales para acceder a las APIs que habilitaste 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 que se recomienda para tu aplicación, asígnale un nombre a tu cliente de OAuth y configura los demás 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 el 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> del archivo de manifiesto de la 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 Cómo autenticar 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 el 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 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 aparece en la sección de información general de la página de información de la app en el sitio de Apple App Store Connect.
  4. (opcional)

    Ingresa el ID de App Store de tu aplicación si está publicada en la 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 Encuentra 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 el Credentials page de tu proyecto para identificar al cliente.
  3. Ingresa el ID de 12 caracteres de tu app de Microsoft Store. 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 manera personalizada para abrir tu app.

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 utilizas un esquema personalizado para la integración de OAuth en Android, deberás completar las siguientes acciones a fin de migrar por completo al uso recomendado del Acceso con Google para el SDK de Android:

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

Sigue los pasos que se indican a continuación para migrar al SDK de Android de Acceso con Google:

  1. Actualiza el código para usar el SDK de Android de Acceso con Google:
    1. Examina tu código para identificar dónde estás envíando una solicitud al servidor de OAuth 2.0 de Google. Si usas un esquema personalizado, tu solicitud se vería de la siguiente manera:
        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.
    3. Sigue las instrucciones de Comienza a integrar Acceso con Google en tu app para Android para configurar el SDK. Puedes omitir el paso Obtén el ID de cliente de OAuth 2.0 de tu servidor de backend, ya que volverías a usar el client_id que recuperaste del paso anterior.
    4. Sigue las instrucciones para habilitar la API del servidor. Esto incluye los siguientes pasos:
      1. Usa el método getServerAuthCode para 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.
  2. Inhabilita la compatibilidad con el esquema personalizado en la Consola de APIs 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 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.

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

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. Se deben cumplir los siguientes requisitos para que la verificación sea exitosa:

  • 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 para Android para el que completas 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 Verificar la propiedad de la app del cliente de Android, haz clic en el botón Verificar propiedad para completar el proceso de verificación.

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

Para corregir una verificación fallida, haz lo siguiente:

  • Asegúrate de que la app que verificas 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, se deben cumplir 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 completas la verificación.
  • Debes ser publicador del elemento de Chrome Web Store. Obtén más información sobre la administración del acceso en el Panel del desarrollador de Chrome Web Store.

En la sección Verificar la propiedad de la app del cliente de la extensión de Chrome, haz clic en el botón Verificar propiedad 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 el éxito del proceso. De lo contrario, se mostrará un mensaje de error.

Para corregir una verificación fallida, haz 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 completas la verificación.
  • Asegúrate de ser 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 grupos, verifica que la lista de membresías de publicadores de grupos esté sincronizada en el Panel del desarrollador de Chrome Web Store. Obtén más información para sincronizar tu lista de membresías de publicadores.

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

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, debe responder mostrando una página HTML que 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 de formulario Configura el tipo de aplicación como App de escritorio.

Copiar y pegar manualmente

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 permisos solicitados y la probabilidad de obtener el consentimiento del usuario.

Antes de que comiences a implementar la autorización de OAuth 2.0, te recomendamos identificar los permisos a los que tu app necesitará permiso para acceder.

En el documento Permisos de la API de OAuth 2.0, encontrarás una lista completa de los permisos 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 para obtener el consentimiento de un usuario y 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 clave de prueba para el intercambio de código (PKCE) para que el flujo de la app instalada sea más seguro. Para cada solicitud de autorización, se crea un verificador de código único 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 cadena criptográfica aleatoria de alta entropía que usa los caracteres no reservados, [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 sea poco 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 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 la forma en que 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 de OAuth 2.0, que configuraste en la Credentials pagede API Consolede tu cliente. Si este valor no coincide con un URI autorizado, recibirá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 que controlas. El esquema personalizado debe contener un período para ser 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 URLs HTTP normales.
Dirección IP de bucle invertido 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. Reemplaza 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 del bucle invertido en las apps para dispositivos móviles está OBSOLETA.

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 de permisos delimitados por espacios 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, a su vez, 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 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ódigos 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 use 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 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 es posible adivinar, 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 capture el estado del cliente, puedes validar la respuesta para garantizar, además, que la solicitud y la respuesta se originen en el mismo navegador y brindar 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 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 previamente el campo de correo electrónico en el formulario de acceso o seleccionando la sesión de acceso múltiple apropiada.

Establece el valor del parámetro en una dirección de correo electrónico o un identificador sub, que sea equivalente al ID de Google del usuario.

URL de autorización de muestra

En las siguientes pestañas, se muestran ejemplos de URL de autorización para las distintas 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 le 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 y un resumen de los permisos de acceso que se otorgarán. Luego, el usuario podrá otorgar acceso a uno o más permisos solicitados por la aplicación, o rechazar la solicitud.

En esta etapa, tu aplicación no necesita realizar ninguna acción, ya que espera la respuesta del servidor de 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 del 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 de manera explícita a tu ID de cliente de OAuth.

disallowed_useragent

El extremo de autorización se muestra dentro de 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 el Acceso con Google para Android o AppAuth para Android de OpenID Foundation.

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 se abran vínculos generales en el controlador de vínculos predeterminado del sistema operativo, que incluye los controladores de Android App Links o la app del 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 para iOS, como el 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 al 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 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 sigues viendo este error, asegúrate de que la aplicación se haya configurado de forma correcta y de usar 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 pasado en la solicitud de autorización no coincide con un URI de redireccionamiento autorizado para el ID de cliente de OAuth. Revisa los URIs 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 se admite. 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 el 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 a los esquemas de URI personalizados

Paso 4: Controla la respuesta del servidor de OAuth 2.0

La manera en que la 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 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 los tokens de acceso y actualización

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 de 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 Uno de los URI de redireccionamiento enumerados para tu proyecto en la API Console Credentials page del client_id especificado.

En el siguiente fragmento, se 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://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 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 delimitadas 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 es Bearer.

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

Una vez que tu 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. Para ello, incluye un parámetro de consulta access_token o un valor Bearer del encabezado HTTP Authorization. Cuando es 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 APIs de Google (por ejemplo, cuando llamas a la API de Drive Files).

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

Ejemplos de GET HTTP

Una llamada al extremo drive.files (la API de Drive Files) con 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 que usa 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 curl. A continuación, se muestra un ejemplo en el que 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, puedes usar la opción del 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 caducan 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 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 de cliente obtenido de API Console. (El 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 debe establecerse en refresh_token.
refresh_token El token de actualización que muestra el intercambio de códigos de autorización.

En el siguiente fragmento, se 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 mostrará un objeto JSON que contiene un token de acceso nuevo. En el siguiente fragmento, se muestra una respuesta de muestra:

{
  "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: un límite por combinación de cliente y usuario, y otro por usuario para todos los clientes. Guarda los tokens de actualización en el almacenamiento a largo plazo y sigue usándolos mientras sean válidos. Si tu aplicación solicita demasiados tokens de actualización, es posible que alcance estos límites, en cuyo caso los tokens de actualización más antiguos dejarán de funcionar.

Revocación de un token

En algunos casos, es posible que el usuario quiera 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 la sección Cómo quitar el acceso a sitios o apps de la sección Sitios y apps de terceros que tienen 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 cambia de forma significativa los recursos de la API que requiere una app. 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 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 de actualización. Si se trata de un token de acceso y tiene un token de actualización correspondiente, este 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.

Lecturas adicionales

En la práctica actual recomendada de IETF OAuth 2.0 para apps nativas, se establecen muchas de las prácticas recomendadas que se documentan aquí.