OAuth 2.0 para apps de escritorio y dispositivos móviles

Nota: Si eres nuevo en OAuth 2.0, te recomendamos que leas el Descripción general de OAuth 2.0 antes de comenzar El se resumen los flujos de OAuth 2.0 que admite Google, lo que puede ayudarte a garantizar que Seleccionaste el flujo adecuado para tu aplicación.

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

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

Las apps instaladas se distribuyen a los dispositivos individuales y se supone que estas apps no puede guardar secretos. Pueden acceder a las APIs de Google mientras el usuario está presente en la app o cuando La app se ejecuta en segundo plano.

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

Alternativas

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

Para apps que se ejecutan en dispositivos que no son compatibles con un navegador del sistema o que tienen entradas 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 ejemplos 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 aplicaciones: Windows Ejemplos

Requisitos previos

Habilita las API para tu proyecto.

Cualquier aplicación que llame a las APIs de Google debe habilitarlas en el 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. El elemento API Library enumera todas las APIs disponibles, agrupadas por producto familia y popularidad. Si la API que quieres habilitar no está en la lista, usa la búsqueda para la encontrarás 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 utilice OAuth 2.0 para acceder a las APIs de Google debe tener credenciales de autorización que identifican la aplicación en el servidor OAuth 2.0 de Google. Los siguientes pasos explican cómo crear credenciales para tu proyecto. Así, tus aplicaciones pueden usar las credenciales para 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 clientes y los métodos de redireccionamiento que utiliza Google de autorización de Google. Elige el tipo de cliente recomendado para tu aplicación, asignar un nombre a tu cliente de OAuth y establecer los demás campos del formulario como lo que sea apropiado.

Android

1. Selecciona el tipo de aplicación para Android.
2. Ingresa un nombre para el cliente de OAuth. Este nombre se muestra en el bucket de tu proyecto Credentials page para identificar al cliente.
3. Ingrese el nombre del paquete de su aplicación para Android. Este valor se define en el Atributo package del elemento <manifest> en el archivo de manifiesto de tu app.
4. Ingresa la huella digital del certificado de firma SHA-1 de la distribución de la app.
   • Si tu app usa firma de apps de Google Play, copia el hash SHA-1 huella digital desde 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 incluyen en Java para imprimir información del certificado en un formato en lenguaje natural. Copia el valor SHA1 en la sección Certificate fingerprints de la keytool. Consulta Autenticación de tu cliente en la Puedes obtener más información en la documentación de las APIs de Google para Android.
5. (Opcional) Verifica la propiedad de tu dispositivo Android y mantener la integridad de su aplicación.
6. Haz clic en Crear.

iOS

1. Selecciona el tipo de aplicación para iOS.
2. Ingresa un nombre para el cliente de OAuth. Este nombre se muestra en el bucket de tu proyecto Credentials page para identificar al cliente.
3. Ingresa el identificador de paquete de tu app. El ID del paquete es el valor del CFBundleIdentifier en el archivo de recursos de la lista de propiedades de la información de tu app (info.plist). El valor se muestra con mayor frecuencia en el panel General o en el panel Signing & Panel de capacidades del Editor del proyecto de Xcode. El ID del paquete también se muestra en la sección Información general de la página Información de la app en Sitio de App Store Connect de Apple.
4. (Opcional)

   Ingresa el ID de tu app, si esta se publicó en App Store de Apple. El ID de tienda es una cadena numérica incluida en cada URL de la App Store de Apple.

   1. Abre el App de Apple App Store 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 bucket de tu proyecto Credentials page para identificar al cliente.
3. Ingresa el ID de Microsoft Store de 12 caracteres de tu app. Puedes encontrar este valor en Centro de socios de Microsoft en la Identidad de las apps en la sección Administración de aplicaciones.
4. Haz clic en Crear.

En el caso de las apps 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 se inhabilitado de forma predeterminada en clientes de Android nuevos debido al riesgo de robo de identidad de la app.

Una 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 aplicación, lo que elimina la necesidad de una URI de redireccionamiento.

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

Si actualmente usas un esquema personalizado para tu integración OAuth en Android, deberás completa las siguientes acciones para migrar por completo al uso del Acceso con Google recomendado para SDK de 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 APIs de Google.

Nota: Debes completar e implementar las actualizaciones de código (teniendo en cuenta el tiempo de adopción). en tu base de usuarios o dispositivos más antiguos) antes de inhabilitar la compatibilidad con esquemas personalizados en el Consola de APIs de Google para evitar que los usuarios obtengan una invalid_request mensaje de error cuando intentan usar tu app.

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

1. Actualiza tu código para usar el SDK de Acceso con Google para Android:
   1. Examina tu código para identificar dónde te encuentras enviar una solicitud al servidor OAuth 2.0 de Google Si usas un esquema personalizado, tu solicitud se verá 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 en el 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. Ten en cuenta los parámetros de solicitud scope y client_id, que debes configurar el SDK de Acceso con Google.
      Nota: Si usas una biblioteca de terceros, consulta las de Terraform para encontrar esa información.
   3. Sigue el Comienza a integrar el Acceso con Google en tu app para Android instrucciones para configurar el SDK. Puedes omitir el Obtén el ID de cliente de OAuth 2.0 de tu servidor de backend como lo harías en otro momento. el client_id que recuperaste del paso anterior.
   4. Sigue el Cómo habilitar el acceso a la API del servidor instrucciones. Esto incluye los siguientes pasos:
      1. Usa el método getServerAuthCode para recuperar un código de Auth para permisos para los que solicitas permiso.
      2. Envía el código de Auth al backend de tu app para intercambiarlo por un acceso. actualizar token.
      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 en lugar de solicitar acceso a la API del cliente.
2. Inhabilita la compatibilidad con el esquema personalizado en la Consola de APIs de Google:
   1. Ve a tu Credenciales de OAuth 2.0 y selecciona tu cliente de Android.
   2. Ve a la sección Configuración avanzada y desmarca la Casilla de verificación Habilitar esquema de URI personalizado y haz clic en Guardar en inhabilitar la compatibilidad con el esquema de URI personalizado.

Habilita el esquema de URI personalizado

Si la alternativa recomendada no funciona, puedes habilitar los esquemas de URI personalizados para tu Android. Para ello, sigue las instrucciones que se indican a continuación:

1. Ve a tu lista de credenciales de OAuth 2.0 y selecciona tu cliente de Android.
2. Ve a la sección Configuración avanzada y revisa el Casilla de verificación Enable Custom URI Scheme y haz clic en Save para habilitarla compatibilidad con el esquema de URI personalizado.

Una alternativa al uso de esquemas de URI personalizados en las apps de Chrome

Usa el API de Chrome Identity que entrega la respuesta de OAuth 2.0 directamente a tu aplicación, lo que elimina la necesidad de una URI de redireccionamiento.

Verifica la propiedad de la app (Android, 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 las apps para Android solo está disponible en Google Play. de Google Chat.

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 el Google Play Console Lo siguiente deben cumplirse para que la verificación sea exitosa:

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

En la sección Verificar la propiedad de la aplicación del cliente de Android, haz clic en el Verificar propiedad para completar el proceso de verificación.

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

Para corregir un error en la verificación, prueba lo siguiente:

• Asegúrate de que la app que estás verificando sea una app registrada en Google Play Console.
• Asegúrate de tener permiso de Administrador para la app en la Google Play Console

Chrome

Para completar el proceso de verificación, debes usar tu cuenta de desarrollador de Chrome Web Store. Para que la verificación sea exitosa, se deben cumplir los siguientes requisitos:

• Debes tener un artículo registrado en la Panel del desarrollador de Chrome Web Store con el mismo ID de elemento que el cliente de OAuth de la extensión de Chrome, estás completando el la verificación.
• Debes ser publicador del elemento de Chrome Web Store. Más información sobre la administración de accesos en el Panel del desarrollador de Chrome Web Store.

En la sección Verificar propiedad de la aplicación del cliente de 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 que otorgue acceso a su cuenta.

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

Para corregir un error en la verificación, 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 extensión de Chrome para el que estás completando la verificación.
• Asegúrate de ser un publicador de la app, es decir, debes ser el publicador individual de la app o un miembro del publicador de grupo de la app. 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 del grupo, verifica que la membresía del publicador del grupo esté sincronizada en el Panel del desarrollador de Chrome Web Store. Más información sobre la sincronización de tu lista de miembros del editor.

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

Importante: La opción de redireccionamiento de la dirección IP de bucle invertido es OBSOLETO para los tipos de cliente de OAuth Android, iOS y App de Chrome. Revisa la IP de bucle invertido. de migración de direcciones para obtener instrucciones sobre cómo migrar a una alternativa compatible.

Para recibir el código de autorización usando esta URL, la aplicación debe estar escuchando en el servidor web local. Esto es posible en muchas de las plataformas, pero no en todas. Sin embargo, si tu plataforma es el mecanismo recomendado para obtener el código de autorización.

Cuando tu app recibe la respuesta de autorización, para lograr una mejor usabilidad, debe responder Mostrar una página HTML en la que se le indica al usuario que cierre el navegador y vuelva a tu app

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

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

Copiar y pegar manualmente

Importante: La opción manual de copiar y pegar, también conocida como de redireccionamiento fuera de banda (OOB), ya no es compatible. Revisa la guía de migración OOB. para obtener instrucciones sobre cómo 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, al tiempo que que les permite a los usuarios controlar el nivel de acceso que otorgan a tu aplicación. Por lo tanto, hay puede ser una relación inversa entre el número de alcances 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 que identifiques los alcances. a las que tu app necesitará permiso para acceder.

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

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

Si tu aplicación pública usa permisos que permiten acceder a determinados datos del usuario, debe completar un proceso de verificación. Si ves la opción Sin verificar app en la pantalla cuando pruebes la aplicación, debes enviar un solicitud de verificación para quitarlo. Obtén más información sobre apps no verificadas y obtener respuestas a preguntas frecuentes sobre la verificación de apps en el Centro de ayuda.

Obtén tokens de acceso de OAuth 2.0

Los siguientes pasos muestran cómo interactúa tu aplicación con el servidor OAuth 2.0 de Google para obtener el consentimiento de un usuario para realizar una solicitud a la API en nombre del usuario. Tu aplicación debe tener 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 la clave de prueba para el intercambio de código (PKCE) para 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 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 el parámetro caracteres [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.

Crea el desafío de código

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

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

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

Para obtener la autorización del usuario, envía una solicitud al servidor de autorización de Google a través de la página 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 aplicaciones:

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 la aplicación. Existen varias opciones de redireccionamiento disponibles para las aplicaciones instaladas, y habrá configurado tu credenciales de autorización con un método de redireccionamiento específico tener en cuenta. El valor debe coincidir exactamente con uno de los URI de redireccionamiento autorizados para OAuth 2.0. que configuraste en la cuenta de servicio API Console Credentials pageSi este valor no coincide con una 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 que tú controlas. El esquema personalizado debe contener un punto para ser válido. com.googleusercontent.apps.123 es la notación de DNS inversa de la ID de cliente. redirect_uri_path es un componente de ruta de acceso opcional, como /oauth2redirect Ten en cuenta que la ruta debe comenzar con un solo /, que es diferente de las URLs HTTP normales. Nota : Los esquemas de URI personalizados ya no son compatibles con las aplicaciones de Chrome ni están inhabilitados de forma predeterminada en Android. Más información acerca de las alternativas de esquemas personalizados para las aplicaciones 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 una solicitud HTTP en un puerto disponible aleatorio. Sustituye port por el valor número de puerto 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 dispositivos móviles apps es OBSOLETO.
response_type	Obligatorio Determina si el extremo de Google OAuth 2.0 muestra un código de autorización. Establece el valor del parámetro en code para las aplicaciones instaladas.
scope	Obligatorio R delimitado por espacios una lista de alcances que identifican los recursos a los que tu aplicación podría acceder en el 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 al mismo tiempo que permiten a los usuarios controlar el nivel de acceso que le otorgan a su y mantener la integridad de su aplicación. Por lo tanto, existe una relación inversa entre el número de alcances solicitados. y la probabilidad de obtener el consentimiento del usuario.
code_challenge	Recomendado Especifica un code_verifier codificado que se usará como servidor de verificación durante el intercambio de códigos de autorización. Consulta crear código desafío anterior para obtener más información.
code_challenge_method	Recomendado Especifica el método que se usó para codificar un code_verifier que se usará. durante el intercambio de códigos de autorización. Este parámetro debe usarse con el El parámetro code_challenge descrito anteriormente. El valor de code_challenge_method El valor predeterminado es plain si no está presente en la solicitud que incluye un code_challenge Los únicos valores admitidos para este parámetro son los siguientes: S256 o plain.
state	Recomendado Especifica cualquier valor de cadena que tu aplicación use para mantener el estado entre tus 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 los redirect_uri después de que el usuario consienta o rechace la solicitud una solicitud de acceso. Puedes usar este parámetro para varios fines, como dirigir al usuario a la el recurso correcto en tu aplicación, enviar nonces y mitigar las solicitudes entre sitios falsificación. Como tu redirect_uri se puede adivinar, usando un state valor, puedes tener más seguridad de que una conexión entrante es el resultado de una de autenticación de la organización. Si generas una cadena aleatoria o codificas el hash de una cookie o otro valor que capture el estado del cliente, puedes validar la respuesta para además de garantizar que la solicitud y la respuesta se originen en el mismo navegador brindando protección contra ataques como solicitud entre sitios falsificación. Consulta la OpenID Connect documentación de ejemplo para crear y confirmar un token state Importante: El cliente de OAuth debe evitar la CSRF, como se indica en Especificación OAuth2 Una forma de lograrlo es usar el parámetro state para mantener estado entre tu solicitud de autorización y la respuesta del servidor de autorización.
login_hint	Opcional Si la aplicación sabe qué usuario intenta autenticarse, puede usar este parámetro. para proporcionar una sugerencia al servidor de autenticación de Google. El servidor usa la sugerencia para para simplificar el flujo de acceso, ya sea completando previamente el campo de correo electrónico en el formulario de acceso o 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 es equivalente al ID de Google del usuario.

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

Ejemplos de URLs de autorización

Las pestañas a continuación muestran ejemplos de URLs 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 obligatorios response_type y client_id. como el parámetro opcional state. Cada URL contiene saltos de línea y espacios para la legibilidad.

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 otorgará a tu aplicación el acceso solicitado. En este Google muestra una ventana de consentimiento con el nombre de tu aplicación y la API de Google. servicios a los que solicita permiso para acceder con las credenciales de autorización del usuario y un resumen de los permisos de acceso que se otorgarán. El el usuario puede dar su consentimiento para otorgar acceso a uno o más alcances solicitados por tu aplicación o rechazar la solicitud.

Tu aplicación no necesita hacer nada en esta etapa mientras espera la respuesta del Servidor OAuth 2.0 de Google que indica 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 esperados de autenticación y autorización. Códigos de error comunes y sugeridos del dispositivo se enumeran a continuación.

admin_policy_enforced

La Cuenta de Google no puede autorizar uno o más alcances 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 de terceros las apps internas 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 restringidos hasta que se otorgue acceso explícitamente a tu ID de cliente de OAuth.

disallowed_useragent

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

Android

Los desarrolladores de Android pueden encontrar este mensaje de error al abrir solicitudes de autorización en android.webkit.WebView En su lugar, los desarrolladores deberían usar bibliotecas de Android, como Acceso con Google para Android o de OpenID Foundation AppAuth para Android:

Los desarrolladores web pueden encontrar este error cuando una app para Android abre un vínculo web general en una usuario-agente incorporado y un usuario navega hasta el 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 de la un sistema operativo completo, que incluye Android App Links o la app de navegador predeterminada. El Pestañas personalizadas de Android biblioteca también es una opción admitida.

iOS

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

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 los vínculos generales se abran en el controlador de vínculos predeterminado de la un sistema operativo completo, que incluye Vínculos universales o la app de navegador predeterminada. El SFSafariViewController biblioteca también es una opción admitida.

org_internal

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

invalid_grant

Si utilizas un verificador de código y desafío, el parámetro code_callenge no es válido o no se encuentra. Asegúrate de que los El parámetro code_challenge está configurado correctamente.

Cuando se actualiza un token de acceso, es posible que haya vencido o que se invalidó. Vuelve a autenticar al usuario y pídele su consentimiento para obtener tokens nuevos. Si continúas para ver este error, asegúrate de que tu aplicación se configuró correctamente y de que usando los tokens y parámetros correctos en tu solicitud. De lo contrario, es posible que la cuenta de usuario se borró o inhabilitó.

redirect_uri_mismatch

El redirect_uri pasado en la solicitud de autorización no coincide con un Es el URI de redireccionamiento para el ID de cliente de OAuth. Revisa los URI de redireccionamiento autorizados en la 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 de OAuth (OOB) que tiene quedó obsoleto y ya no es compatible. Consulta las guía de migración para actualizar tu y la integración de datos.

invalid_request

Se produjo un error con la solicitud que hiciste. Esto puede deberse a varios motivos:

• La solicitud no tenía el formato correcto
• Faltaban parámetros obligatorios en la solicitud
• La solicitud usa un método de autorización que Google no admite. Verifica tu OAuth integración usa un método de integración recomendado
• Se utiliza 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 ni el esquema de URI personalizado no está habilitado para tu cliente de Android, significa que estás usando un URI personalizado que no es compatible con las apps de Chrome y que está inhabilitado de forma predeterminada Android Más información sobre el esquema de URI personalizado alternativas

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, contendrá un código de autorización (code) o un error (error). Por ejemplo, error=access_denied indica que el usuario rechazó la solicitud.

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

Paso 5: Intercambia el código de autorización para actualizar y acceder tokens

Para intercambiar un código de autorización por un token de acceso, llama al https://oauth2.googleapis.com/token y establece 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 Paso 1:
grant_type	Como se define en OAuth 2.0, especificación, el valor de este campo se debe establecer en authorization_code.
redirect_uri	Uno de los URI de redireccionamiento que se enumeran para tu proyecto en la API Console Credentials page por el valor especificado client_id

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 acceso de corta duración y uno 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 en segundos.
id_token	Nota: Esta propiedad solo se muestra si tu solicitud incluye un permiso de identidad. como openid, profile o email. El valor es un Un token web JSON (JWT) que contiene información de identidad con firma digital acerca del usuario.
refresh_token	Un token que puedes usar para obtener un token de acceso nuevo. Los tokens de actualización son válidos hasta el el usuario revoca el acceso. Ten en cuenta que los tokens de actualización siempre se muestran para las aplicaciones instaladas.
scope	Los permisos de acceso otorgados por el access_token expresados como una lista de cadenas 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 está establecido en Bearer

Importante: La aplicación debe almacenar ambos tokens en un y una ubicación de larga duración a la que se pueda acceder entre diferentes invocaciones de tu aplicación. El un token de actualización permite que la aplicación obtenga un nuevo token de acceso y vence el período de vencimiento. 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 los campos no reconocidos que se incluyan en la respuesta.

Llama a las APIs de Google

Luego de que la aplicación obtenga un token de acceso, puedes usarlo para realizar llamadas a un servicio API en nombre de un proveedor de servicios de usuario 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 una consulta access_token o un valor de encabezado HTTP Bearer Authorization. Cuando 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 puedes usar una biblioteca cliente para configurar las llamadas a las APIs de Google (por ejemplo, cuando llamar a la API de Drive Files).

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

Ejemplos de solicitudes GET de HTTP

Un llamado a la drive.files extremo (la API de Drive Files) con el HTTP Authorization: Bearer el encabezado 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 access_token. Parámetro de cadena de consulta:

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

Ejemplos de curl

Puedes probar estos comandos con la aplicación de línea de comandos de curl. Este es un ejemplo que usa la opción de encabezado HTTP (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 caducan periódicamente y se convierten en credenciales no válidas para una solicitud a la API relacionada. Tú puede actualizar un token de acceso sin pedirle permiso al usuario (incluso cuando (inexistente) si solicitaste acceso sin conexión a los permisos asociados con el token.

Para actualizar un token de acceso, tu aplicación envía un POST HTTPS solicitud 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. (El client_secret no es aplicable a las solicitudes de clientes registrados como aplicaciones para Android, iOS o Chrome).
grant_type	Como definidas en el 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 del código 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 devuelve un objeto JSON que contiene un token de acceso nuevo. En el siguiente fragmento, se muestra un ejemplo respuesta:

{
  "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 en la cantidad de tokens de actualización que se emitirán. un límite por una combinación de cliente y usuario y otra por usuario en 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, se pueden alcanzar estos límites, en cuyo caso los tokens de actualización más antiguos dejará de funcionar.

Revoca un token

En algunos casos, es posible que el usuario desee revocar el acceso otorgado a una aplicación. Un usuario puede revocar el acceso en Configuración de la cuenta. Consulta la Quitar Acceso al sitio o la aplicación de la sección de Sitios de terceros y apps con acceso a tu cuenta para obtener más información.

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 aplicación o los recursos de API necesarios para una aplicación han cambiado considerablemente. En otras palabras, parte del proceso de eliminación pueden incluir una solicitud a la API para garantizar que los permisos previos otorgadas a la aplicación.

Para revocar un token de manera programática, la aplicación realiza una solicitud a https://oauth2.googleapis.com/revoke e incluye el token como parámetro:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

El token puede ser de acceso o de actualización. Si el token es de acceso y tiene un token de actualización correspondiente, también se revocará el token de actualización.

Si la revocación se procesa correctamente, el código de estado HTTP de la respuesta es 200 Para las condiciones de error, se muestra el código de estado HTTP 400 junto con un código de error.

Nota: Después de una respuesta de revocación exitosa, es posible que debas esperar tiempo antes de que la revocación surta efecto.

Lecturas adicionales

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

Cómo implementar la Protección integral de la cuenta

Un paso adicional que debes seguir para proteger las contraseñas de cuentas está implementando Protección con el Servicio de protección integral de la cuenta de Google Este servicio te permite suscribirse a las notificaciones de eventos de seguridad, que proporcionan información a su aplicación sobre cambios importantes en la cuenta de usuario. Luego, puedes usar la información para tomar medidas según cómo decides responder a los eventos.

Estos son algunos ejemplos de los tipos de eventos que el Servicio de Protección integral de la cuenta de Google envía a tu app:

• https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
• https://schemas.openid.net/secevent/oauth/event-type/token-revoked
• https://schemas.openid.net/secevent/risc/event-type/account-disabled

Consulta la Cómo proteger las cuentas de usuario con la página Protección integral de la cuenta para obtener más información sobre cómo implementar la Protección integral de la cuenta y consultar la lista completa de eventos disponibles.