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 APIs de Google.
OAuth 2.0 permite que los usuarios compartan datos específicos con una aplicación y, al mismo tiempo, mantengan 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 permiso de los usuarios para almacenar archivos en sus unidades de Google Drive.
Las apps instaladas se distribuyen a dispositivos individuales y se supone que estas apps no pueden 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 controlar las respuestas del servidor de autorización de Google.
Alternativas
En el caso de las aplicaciones para dispositivos móviles, te recomendamos que uses Acceder con Google para Android o iOS. Las bibliotecas cliente de Acceso con Google controlan la autenticación y la autorización del usuario, y pueden ser más fáciles de implementar que el protocolo de nivel inferior 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 limitada.
Bibliotecas y muestras
Te recomendamos las siguientes bibliotecas y muestras para ayudarte a 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 API Console.
Para habilitar una API en tu proyecto, sigue estos pasos:
- Open the API Library en Google API Console.
- If prompted, select a project, or create a new one.
- En la API Library , se enumeran 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.
- Selecciona la API que deseas habilitar y, luego, haz clic en el botón Habilitar.
- If prompted, enable billing.
- 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 podrán usar las credenciales para acceder a las APIs que habilitaste para ese proyecto.
- Go to the Credentials page.
- Haz clic en Crear credenciales > ID de cliente de OAuth.
- En las siguientes secciones, se describen los tipos de clientes 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
- Selecciona el tipo de aplicación Android.
- Ingresa un nombre para el cliente de OAuth. Este nombre se muestra en el Credentials page de tu proyecto para identificar al cliente.
- Ingresa el nombre del paquete de tu app para Android. Este valor se define en el
atributo
packagedel elemento<manifest>en el archivo de manifiesto de tu app. - Ingresa la huella digital del certificado de firma SHA-1 de la distribución de la app.
- Si tu app usa la firma de apps de Google Play, copia la huella digital SHA-1 de la página de firma de apps de Play Console.
- Si administras tu propio almacén de claves y claves de firma, usa la utilidad keytool incluida en Java para imprimir la información del certificado en un formato legible por humanos. Copia el valor de
SHA1en la secciónCertificate fingerprintsdel 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.
- Verifica la propiedad de tu aplicación para Android (opcional).
- Haz clic en Crear.
iOS
- Selecciona el tipo de aplicación iOS.
- Ingresa un nombre para el cliente de OAuth. Este nombre se muestra en el Credentials page de tu proyecto para identificar al cliente.
- Ingresa el identificador de paquete de tu app. El ID del paquete es el valor de la clave
CFBundleIdentifier
en el archivo de recursos de la lista de propiedades de información de tu app (info.plist). Por lo general, el valor se muestra en el panel General o en el panel Signing & Capabilities del editor de proyectos de Xcode. El ID del paquete también se muestra en la sección Información general de la página Información de la app en el sitio de App Store Connect de Apple.
Confirma que estás usando el ID de paquete correcto para tu app, ya que no podrás cambiarlo si usas la función de Verificación de aplicaciones.
- (Opcional)
Ingresa el ID de la app en App Store si la app se publicó en la App Store de Apple. El ID de la tienda es una cadena numérica que se incluye en cada URL de la App Store de Apple.
- Abre la app de Apple App Store en tu dispositivo iOS o iPadOS.
- Busca tu app.
- Selecciona el botón Compartir (cuadrado y símbolo de flecha hacia arriba).
- Selecciona Copiar vínculo.
- Pega el vínculo en un editor de texto. El ID de la tienda de aplicaciones es la parte final de la URL.
Ejemplo:
https://apps.apple.com/app/google/id284815942
- (Opcional)
Ingresa el ID de tu equipo. Consulta Cómo ubicar el ID de tu equipo en la documentación de la cuenta de desarrollador de Apple para obtener más información.
Nota: El campo ID de equipo es obligatorio si habilitas la Verificación de aplicaciones para tu cliente. - (Opcional)
Habilita la Verificación de aplicaciones para tu app para iOS. Cuando habilitas esta función, se usa el servicio de App Attest de Apple para verificar que las solicitudes de OAuth 2.0 que provienen de tu cliente de OAuth sean genuinas y provengan de tu app. Esto ayuda a reducir el riesgo de suplantación de identidad de apps. Obtén más información para habilitar la Verificación de aplicaciones en tu app para iOS.
- Haz clic en Crear.
UWP
- Selecciona el tipo de aplicación Universal Windows Platform.
- Ingresa un nombre para el cliente de OAuth. Este nombre se muestra en el Credentials page de tu proyecto para identificar al cliente.
- Ingresa el ID de Microsoft Store de 12 caracteres de tu app. Puedes encontrar este valor en Microsoft Partner Center, en la página Identidad de la app, en la sección Administración de apps.
- Haz clic en Crear.
En el caso de las apps para UWP, el esquema de URI personalizado no puede tener más de 39 caracteres.
Identifica los permisos de acceso
Los alcances permiten que la aplicación solo solicite acceso a los recursos que necesita, al tiempo que permiten a los usuarios controlar el nivel 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 alcances para los que la aplicación necesitará permiso de acceso.
El documento Alcances de la API de OAuth 2.0 contiene una lista completa de los permisos que puedes usar para acceder a las APIs de Google.
Obtén tokens de acceso de OAuth 2.0
En los siguientes pasos, se muestra cómo tu aplicación interactúa 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 autorización del usuario.
Paso 1: Genera un verificador de códigos y un desafío
Google admite el protocolo de clave de prueba para el intercambio de código (PKCE) para que el flujo de apps instaladas 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 cadena aleatoria criptográfica 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ódigos debe tener suficiente entropía para que sea poco práctico adivinar el valor.
Crea el desafío de programación
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) | La verificación de código es el hash SHA256 codificado en Base64URL (sin padding) del verificador de código.
|
| plain | El desafío de código es el mismo valor que el verificador de código que se generó anteriormente.
|
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 sesiones activas, autentica al usuario y obtiene su consentimiento. Solo se puede acceder al extremo a través de SSL, y se rechazan 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 el archivo 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 habrás configurado tus credenciales de autorización teniendo en cuenta un método de redireccionamiento en particular. El valor debe coincidir exactamente con uno de los URIs de redireccionamiento autorizados para el cliente de OAuth 2.0, que configuraste en el API Consolede tu cliente Credentials page. Si este valor no coincide con un URI autorizado, recibirás un error En la siguiente tabla, se muestra el valor apropiado del parámetro
|
||||||
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 |
||||||
scope |
Obligatorio
Es una lista de permisos delimitados por espacios que identifican los recursos a los que puede acceder tu aplicación en nombre del usuario. Estos valores informan la pantalla de consentimiento que Google muestra al usuario. Los alcances permiten que la aplicación solo solicite acceso a los recursos que necesita, al tiempo que permiten a los usuarios controlar el nivel 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 |
Recomendado
Especifica un |
||||||
code_challenge_method |
Recomendado
Especifica qué método se usó para codificar un |
||||||
state |
Recomendado
Especifica cualquier valor de cadena que use tu aplicación para mantener el estado entre tu solicitud de autorización y la respuesta del servidor de autorización.
El servidor muestra el valor exacto que envías como un par 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. Dado que se puede adivinar tu |
||||||
login_hint |
Opcional
Si tu aplicación sabe qué usuario intenta autenticarse, puede usar este parámetro para proporcionar una sugerencia al servidor de autenticación de Google. El servidor usa la sugerencia para simplificar el flujo de acceso, ya sea completando 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 |
||||||
URLs de autorización de muestra
En las siguientes pestañas, se muestran URLs de autorización de ejemplo 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 state opcional. 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 le solicita consentimiento al usuario
En este paso, el usuario decide si otorgarle 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 para acceder con las credenciales de autorización del usuario, y un resumen de los permisos de acceso que se otorgarán. Luego, el usuario puede consentir otorgar acceso a uno o más permisos solicitados por tu aplicación o rechazar la solicitud.
Tu aplicación no necesita hacer nada en esta etapa, 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
Es posible que las solicitudes al extremo de autorización de OAuth 2.0 de Google muestren mensajes de error para el usuario en lugar de los flujos de autenticación y autorización esperados. A continuación, se indican los códigos de error comunes y las resoluciones sugeridas.
admin_policy_enforced
La Cuenta de Google no puede autorizar uno o más permisos solicitados debido a las políticas de su administrador de Google Workspace. Consulta el artículo de ayuda del Administrador 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 forma explícita a tu ID de cliente de OAuth.
disallowed_useragent
El extremo de autorización se muestra dentro de un usuario-agente incorporado que no está permitido por las Políticas de OAuth 2.0 de Google.
Android
Es posible que los desarrolladores de Android encuentren este mensaje de error cuando abran solicitudes de autorización en android.webkit.WebView.
En su lugar, los desarrolladores deben usar bibliotecas de Android, como Acceso con Google para Android o AppAuth para Android de la OpenID Foundation.
Es posible que los desarrolladores web encuentren 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 los 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
Es posible que los desarrolladores de iOS y macOS encuentren este error cuando abran solicitudes de autorización en WKWebView.
En su lugar, los desarrolladores deben usar bibliotecas de iOS, como Acceso con Google para iOS o AppAuth para iOS de OpenID Foundation.
Es posible que los desarrolladores web encuentren 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 los 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 forma parte de un proyecto que limita el acceso a las Cuentas de Google en una organización de Google Cloud específica. Para obtener más información sobre esta opción de configuración, consulta la sección Tipo de usuario en el artículo de ayuda Cómo configurar tu pantalla de consentimiento de OAuth.
invalid_grant
Si usas un verificador de código y un desafío, el parámetro code_callenge no es válido o falta. Asegúrate de que el parámetro code_challenge esté configurado correctamente.
Cuando se actualiza un token de acceso, es posible que el token haya caducado o que 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 tu aplicación esté configurada correctamente y de que uses los tokens y parámetros correctos en tu solicitud. De lo contrario, es posible que se haya borrado o inhabilitado la cuenta de usuario.
redirect_uri_mismatch
El redirect_uri que se pasó 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 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 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 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 para Chrome o El esquema de URI personalizado no está habilitado para tu cliente de Android, significa que estás usando un esquema de URI personalizado que no es compatible con las apps para Chrome y que está inhabilitado de forma predeterminada en Android. Obtén 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 tu aplicación, puedes intercambiar el código de autorización por un token de acceso y un token de actualización, como se describe en el siguiente paso.
Paso 5: Intercambia 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 establece 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ódigos que creaste en el paso 1. |
grant_type |
Como se define en la especificación de OAuth 2.0, el valor de este campo debe establecerse en authorization_code. |
redirect_uri |
Uno de los URIs de redireccionamiento que se enumeran para tu proyecto en el API Console
Credentials page para el client_id determinado. |
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
Google responde a esta solicitud mostrando 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 tu aplicación para autorizar una solicitud a la API de Google. |
expires_in |
Es la vida útil restante del token de acceso en segundos. |
id_token |
Nota: Esta propiedad solo se muestra si tu solicitud incluyó un alcance de identidad, como openid, profile o email. El valor es un token web JSON (JWT) que contiene información de identidad firmada digitalmente sobre el usuario. |
refresh_token |
Es un token que puedes usar para obtener un nuevo token de acceso. Los tokens de actualización son válidos hasta que el usuario revoca el acceso. Ten en cuenta que los tokens de actualización siempre se devuelven para las aplicaciones instaladas. |
scope |
Los permisos de acceso que otorga access_token expresados como una lista de cadenas delimitadas por espacios y que distinguen mayúsculas de minúsculas. |
token_type |
Es el tipo de token que se muestra. En este momento, el valor de este campo siempre se establece en Bearer. |
En el siguiente fragmento, se muestra una respuesta de ejemplo:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Paso 6: Verifica qué permisos otorgaron los usuarios
Cuando solicites varios permisos a la vez, es posible que los usuarios no otorguen todos los permisos que solicita tu app. Tu app siempre debe verificar qué permisos otorgó el usuario y controlar cualquier denegación de permisos inhabilitando las funciones relevantes. Consulta Cómo controlar los permisos detallados para obtener más información.
Para verificar si el usuario otorgó a tu aplicación acceso a un alcance en particular, examina el campo scope en la respuesta del token de acceso. Los permisos de acceso que otorga el access_token expresados como una lista de cadenas separadas por espacios y sensibles a mayúsculas y minúsculas.
Por ejemplo, la siguiente respuesta de muestra del token de acceso indica que el usuario le otorgó a tu aplicación acceso a los permisos de eventos de Calendario y actividad de solo lectura de Drive:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Cómo llamar a las APIs de Google
Una vez que tu aplicación obtenga un token de acceso, podrás 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 con un parámetro de consulta access_token o un valor Bearer de encabezado HTTP Authorization. Cuando sea posible, se prefiere el encabezado HTTP, ya que las cadenas de consulta suelen 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 APIs de Google y ver sus permisos en OAuth 2.0 Playground.
Ejemplos de HTTP GET
Una llamada al extremo
drive.files (la API de Files de Drive) 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 con el parámetro de cadena de consulta access_token:
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 curl. A continuación, se muestra un ejemplo que usa la opción de encabezado HTTP (preferida):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
O bien, 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 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 alcances asociados con el token.
Para actualizar un token de acceso, tu 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
(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 se muestra después del 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 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 https://www.googleapis.com/auth/calendar.readonly", "token_type": "Bearer" }
Ten en cuenta que hay límites en la cantidad de tokens de actualización que se emitirán: un límite por combinación de cliente/usuario y otro por usuario en todos los clientes. Debes guardar los tokens de actualización en el almacenamiento a largo plazo y seguir usándolos mientras sigan siendo válidos. Si tu aplicación solicita demasiados tokens de actualización, es posible que se encuentre con estos límites, en cuyo caso los tokens de actualización más antiguos dejarán de funcionar.
Cómo revocar un token
En algunos casos, es posible que un usuario desee revocar el acceso otorgado a una aplicación. Un usuario puede revocar el acceso en Configuración de la cuenta. Consulta la sección Cómo quitar el acceso de un sitio o una app del documento de asistencia Sitios y apps de terceros con acceso a tu cuenta para obtener más información.
También es posible que una aplicación revoque de forma programática el acceso que se le otorgó. La revocación programática es importante en los casos en que un usuario cancela su suscripción, quita una aplicación o los recursos de la API que requiere una app cambiaron de forma 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 y, además, incluye el token como parámetro:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}El token puede ser un token de acceso o un token de actualización. Si el token es 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.
Métodos de redireccionamiento de apps
Esquema de URI personalizado (Android, iOS y UWP)
Los esquemas de URI personalizados son una forma de vinculación directa que usa un esquema definido por el usuario para abrir tu app.
Alternativa al uso de esquemas de URI personalizados en Android
Usa el SDK de Acceso con Google para Android, que envía la respuesta de OAuth 2.0 directamente a tu app, lo que elimina la necesidad de un URI de redireccionamiento.
Cómo migrar al SDK de Acceso con Google para Android
Si usas un esquema personalizado para tu integración de OAuth en Android, deberás completar las siguientes acciones para migrar por completo al uso del SDK recomendado de Acceso con Google para Android:
- Actualiza tu código para usar el SDK de Acceso con Google.
- Inhabilita la compatibilidad con el esquema personalizado en la Consola de APIs de Google.
Sigue estos pasos para migrar al SDK de Acceso a Google para Android:
-
Actualiza tu código para usar el SDK de Android de Acceder con Google:
-
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á 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:/oauth2redirectes el URI de redireccionamiento del esquema personalizado en el ejemplo anterior. Consulta la definición del parámetroredirect_uripara obtener más detalles sobre el formato del valor del esquema de URI personalizado. -
Anota los parámetros de solicitud
scopeyclient_idque necesitarás para configurar el SDK de Acceder con Google. -
Sigue las instrucciones de
Comienza a integrar el 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 reutilizarás el
client_idque recuperaste en el paso anterior. -
Sigue las instrucciones de
Cómo habilitar el acceso a la API del servidor. Esto incluye los siguientes pasos:
-
Usa el método
getServerAuthCodepara recuperar un código de autorización para los alcances para los que solicitas permiso. - Envía el código de autenticación al backend de tu app para intercambiarlo por un token de acceso y actualización.
- Usa el token de acceso recuperado para realizar llamadas a las APIs de Google en nombre del usuario.
-
Usa el método
-
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á de la siguiente manera:
-
Inhabilita la compatibilidad con el esquema personalizado en la Consola de API de Google:
- Ve a la lista de credenciales de OAuth 2.0 y selecciona tu cliente de Android.
- 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.
Habilitar el esquema de URI personalizado
Si la alternativa recomendada no funciona, puedes habilitar esquemas de URI personalizados para tu cliente de Android siguiendo las instrucciones que se indican a continuación:- Ve a la lista de credenciales de OAuth 2.0 y selecciona tu cliente de Android.
- 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 para Chrome
Usa la API de Chrome Identity, que envía la respuesta de OAuth 2.0 directamente a tu app, lo que elimina la necesidad de un URI de redireccionamiento.
Dirección IP de bucle invertido (computadoras de escritorio con macOS, Linux o Windows)
Para recibir el código de autorización con esta URL, tu aplicación debe estar escuchando en el servidor web local. Eso es posible en muchas plataformas, pero no en todas. Sin embargo, si tu plataforma lo admite, este es el mecanismo recomendado para obtener el código de autorización.
Cuando tu app recibe la respuesta de autorización, para una mejor usabilidad, debe mostrar una página HTML que le indique al usuario que cierre el navegador y regrese a tu app.
| Uso recomendado | Aplicaciones para computadoras de escritorio (pero no para la plataforma universal de Windows) de macOS, Linux y Windows |
| Valores del formulario | Configura el tipo de aplicación como App de escritorio. |
Copiar y pegar manual (obsoleto)
Protege tus apps
Verifica la propiedad de la app (Android y Chrome)
Puedes verificar la propiedad de tu aplicación para reducir el riesgo de suplantación 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 se realice correctamente:
- 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, aparecerá una notificación para confirmar el éxito del proceso de verificación. De lo contrario, se mostrará un mensaje de error.
Para corregir una verificación fallida, prueba 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, debes usar tu cuenta de desarrollador de Chrome Web Store. Para que la verificación se realice 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 de acceso 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, aparecerá una notificación para confirmar el éxito del proceso de verificación. De lo contrario, se mostrará un mensaje de error.
Para corregir una verificación fallida, 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 estás completando 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 tu lista de publicadores del grupo, verifica que la lista de membresías de publicadores del grupo esté sincronizada en el panel de desarrollador de Chrome Web Store. Obtén más información para sincronizar tu lista de membresías de publicadores.
Verificación de aplicaciones (solo para iOS)
La función Verificación de aplicaciones ayuda a proteger tus aplicaciones para iOS del uso no autorizado mediante el servicio de App Attest de Apple para verificar que las solicitudes que se realizan a los extremos de OAuth 2.0 de Google provengan de tus aplicaciones auténticas. Esto ayuda a reducir el riesgo de suplantación de identidad de apps.
Habilita la Verificación de aplicaciones para tu cliente de iOS
Se deben cumplir los siguientes requisitos para habilitar correctamente la Verificación de aplicaciones para tu cliente de iOS:- Debes especificar un ID de equipo para tu cliente para iOS.
- No debes usar un comodín en el ID de paquete, ya que puede resolverse en más de una app. Esto significa que el ID de paquete no debe incluir el símbolo de asterisco (*).
Después de habilitar la Verificación de aplicaciones, comenzarás a ver métricas relacionadas con las solicitudes de OAuth de tu cliente en la vista de edición del cliente de OAuth. Las solicitudes de fuentes no verificadas no se bloquearán hasta que apliques la Verificación de aplicaciones. La información de la página de supervisión de métricas puede ayudarte a determinar cuándo comenzar la aplicación forzosa.
Es posible que veas errores relacionados con la función de Verificación de apps cuando habilites esta función para tu app para iOS. Para solucionar estos errores, haz lo siguiente:
- Verifica que el ID del paquete y el ID del equipo que especificaste sean válidos.
- Verifica que no uses un comodín para el ID del paquete.
Aplica la Verificación de aplicaciones para tu cliente de iOS
Si habilitas la Verificación de aplicaciones para tu app, no se bloquearán automáticamente las solicitudes no reconocidas. Para aplicar esta protección, ve a la vista de edición de tu cliente para iOS. Allí, verás las métricas de la Verificación de aplicaciones a la derecha de la página, en la sección Google Identity para iOS. Las métricas incluyen la siguiente información:- Cantidad de solicitudes verificadas: Son las solicitudes que tienen un token válido de la Verificación de aplicaciones. Después de habilitar la aplicación forzosa de la Verificación de aplicaciones, solo se ejecutarán de manera correcta las solicitudes de esta categoría.
- Cantidad de solicitudes no verificadas: solicitudes de cliente probablemente desactualizadas: Solicitudes a las que les falta un token de la Verificación de aplicaciones. Estas solicitudes pueden provenir de una versión anterior de tu app que no incluye una implementación de la Verificación de aplicaciones.
- Cantidad de solicitudes no verificadas: Solicitudes de origen desconocido: Solicitudes a las que les falta un token de Verificación de aplicaciones y que no parecen provenir de tu app.
- Cantidad de solicitudes no verificadas: solicitudes no válidas: Solicitudes con un token no válido de Verificación de aplicaciones, que puede provenir de un cliente falso que intenta hacerse pasar por tu app, o bien de entornos emulados.
Para aplicar la Verificación de aplicaciones, haz clic en el botón ENFORCE y confirma tu elección. Una vez que la aplicación forzosa esté activa, se rechazarán todas las solicitudes no verificadas de tu cliente.
Nota: Después de habilitar la aplicación forzosa, los cambios pueden tardar hasta 15 minutos en aplicarse.
Anula la aplicación de la Verificación de aplicaciones para tu cliente de iOS
Si anulas la aplicación de la Verificación de aplicaciones para tu app, se detendrá la aplicación y se permitirán todas las solicitudes de tu cliente a los extremos de OAuth 2.0 de Google, incluidas las solicitudes no verificadas.
Para inhabilitar la Verificación de aplicaciones en tu cliente para iOS, navega a la vista de edición del cliente para iOS, haz clic en el botón INHABILITAR y confirma tu elección.
Nota: Después de inhabilitar la Verificación de apps, los cambios pueden tardar hasta 15 minutos en aplicarse.
Inhabilita la Verificación de aplicaciones para tu cliente de iOS
Si inhabilitas la Verificación de aplicaciones en tu app, se detendrá toda la supervisión y aplicación forzosa de esta. Considera anular la Verificación de aplicaciones para que puedas seguir supervisando las métricas de tu cliente.
Para inhabilitar la Verificación de aplicaciones en tu cliente para iOS, navega a la vista de edición del cliente para iOS y desactiva el botón de activación Protege tu cliente de OAuth contra abusos con la Verificación de aplicaciones de Firebase.
Nota: Después de inhabilitar la Verificación de apps, los cambios pueden tardar hasta 15 minutos en aplicarse.
Lecturas adicionales
La práctica recomendada actual del IETF OAuth 2.0 para apps nativas establece muchas de las prácticas recomendadas que se documentan aquí.
Implementa la Protección integral de la cuenta
Un paso adicional que debes seguir para proteger las cuentas de tus usuarios es implementar la Protección entre cuentas con el servicio de Protección entre cuentas de Google. Este servicio te permite suscribirte a notificaciones de eventos de seguridad que proporcionan información a tu aplicación sobre cambios importantes en la cuenta de usuario. Luego, puedes usar la información para tomar medidas según cómo decidas responder a los eventos.
Estos son algunos ejemplos de los tipos de eventos que el servicio de Protección entre cuentas 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 página Protege las cuentas de usuario con la Protección integral de la cuenta para obtener más información sobre cómo implementar la Protección integral de la cuenta y ver la lista completa de eventos disponibles.