Probablemente estás aquí porque Sign-In de Google debería haber sido una integración rápida, y en su lugar estás frente a una pantalla de credenciales preguntándote por qué un tipo de aplicación te da un secreto de cliente y otro no. Esa confusión es normal, especialmente si estás construyendo con Capacitor, Ionic, Electron o una pila web y nativa mixta.
La parte que más guías omiten es la que rompe las implementaciones reales: Los identificadores de cliente de Google son específicos de la plataforma, y los tipos de aplicaciones no web a menudo no obtienen un secreto de cliente por diseño. Si crea la credencial equivocada solo para obligar a un secreto en el flujo, generalmente termina con un conjunto de OAuth roto que es más difícil de depurar de lo que debería ser.
Índice
- Conectar su aplicación al ecosistema de Google
- ¿Qué es un identificador de cliente de Google?
- Cómo crear y ver su identificador de cliente
- Configuraciones de ID de cliente específicas de plataforma
- Seguridad de sus credenciales de Google API
- Resolución de errores comunes de ID de cliente
Conectar su aplicación al ecosistema de Google
Muchos equipos se encuentran con este problema en el mismo momento. Necesitan Iniciar sesión con Google, o quieren acceso aprobado por el usuario a algo como Drive o Calendario, y una clave API de repente deja de ser suficiente.
Porque el inicio de sesión del usuario y el acceso delegado pasan por OAuth. Google necesita una forma de identificar su aplicación, no solo la API que se está llamando. El credencial que hace eso es el ID del cliente de Google.
Si está trabajando en un código de código de plataforma cruzada, la confusión se vuelve peor rápidamente. Puede tener una interfaz de usuario web, una caja de Android, una aplicación de iOS y tal vez una compilación de Electron para escritorio. Pueden compartir marcas de producto y lógica de backend, pero no deberían compartir una identidad OAuth.
Una configuración OAuth práctica suele reducirse a unas pocas preguntas de implementación:
- ¿Qué tipo de aplicación debe crear
- ¿Necesita un secreto del cliente
- ¿Cuáles deben coincidir exactamente los URIs de redirección o los orígenes
- ¿Cómo conectar los flujos móviles y web sin mezclar credenciales
- ¿Por qué un flujo que funciona en el navegador falla dentro de un wrapper nativo
Regla práctica: Si su aplicación solicita permiso del usuario o inicio de sesión, comience pensando en tipos de clientes OAuth, no API claves.
Esa distinción ahorra tiempo temprano. También evita el error común de crear un flujo de inicio de sesión móvil alrededor de una credencial web solo porque el consola mostró más campos. Si está implementando esto en una Capacitor aplicación, esta guía sobre OAuth2 en Capacitor aplicaciones es una compañera útil para el flujo de la aplicación.
¿Qué es un ID de cliente de Google
A Un ID de cliente de Google OAuth 2.0 es el identificador público para su aplicación en el sistema de autenticación de Google. Google lo describe como el nombre de usuario único para una aplicación cuando solicita tokens de acceso desde puntos finales de autenticación de Google, y destaca que es distinto de API claves porque se utiliza en flujos de OAuth para verificar la identidad de la aplicación durante el intercambio de tokens, como se explica en la documentación de clientes de Google Cloud sobre OAuth.
The simple mental model
Pensé en el identificador de cliente Google los problemas como la aplicación de su nombre de usuario público.
Dice a Google, “esta solicitud proviene de esta aplicación registrada.” Eso importa durante la autenticación, el consentimiento, el intercambio de tokens y cualquier flujo en el que su aplicación solicite actuar en nombre de un usuario. El identificador de cliente está destinado a ser referenciado tanto por su aplicación como por los servidores de autenticación de Google.
Lo que confunde a las personas es que este credencial se encuentra junto a dos otros conceptos que no son intercambiables.
Identificador de cliente identifica la aplicación en OAuth.
API clave identifica un proyecto para ciertas API llamadas que no involucran la autorización delegada de usuario.
Identificador secreto del cliente es el contraparte confidencial utilizada solo en flujos y tipos de aplicación que pueden mantener seguros los secretos.
Muchas integraciones rotas comienzan cuando alguien trata a estas como variaciones del mismo cosa. No lo son.
Dónde el identificador de cliente Google se ajusta en la práctica
Si necesita Iniciar sesión con Google o Un toque, el identificador de cliente es el valor que su frontend utiliza para iniciar el intercambio de autenticación. La documentación de Google también destaca que la aplicación debe estar registrada en un proyecto de Cloud Console dedicado antes de que se pueda generar la credencial, y que las aplicaciones web requieren configuradas las orígenes de JavaScript autorizados o URIs de redirección con el esquema completo y el nombre de host.
Por eso el setup siente más estricto que generar una simple clave. Google no está solo habilitando el acceso. Está vinculando la solicitud de autenticación a una identidad de aplicación conocida.
Para los equipos que están construyendo aplicaciones híbridas, el modelo mental más seguro es este:
- Usar el identificador de cliente para identificar la aplicación
- Usar la pantalla de consentimiento para representar la aplicación al usuario
- Utilice el tipo de aplicación correcto para determinar si una clave secreta pertenece al flujo.
Si desea una introducción más amplia sobre cómo la identidad de la aplicación y el acceso delegado se relacionan entre sí, esta guía sobre la autorización de la aplicación es una buena actualización.
Cómo crear y ver su ID de cliente
El camino del consola ha cambiado lo suficiente como para que los desarrolladores piensen que están en el lugar equivocado. Normalmente no lo están. Google expone actualmente dos rutas de navegación para estos credenciales: la más nueva Google Auth Platform > Clients y la más antigua APIs & Services > Credentials ruta, tal como se describe en la documentación de configuración de Google.
Comienza en el área de consola correcta
Abre la consola de Google Cloud y selecciona o crea el proyecto que será dueño de la configuración de autenticación. No disperses la autenticación en proyectos aleatorios. Esto hace que la auditoría y el soporte sean dolorosos más tarde.
Desde allí, ve a cualquiera de estos lugares:
- Plataforma de autenticación de Google > Clientes
- APIs y Servicios > Certificados
Si tu equipo ve diferentes etiquetas de navegación, eso está esperado. Google ha estado separando la configuración de identidad de la superficie de credenciales restante de API.
Crear la credencial sin limitarte a sí mismo
Cuando creas un nuevo cliente OAuth, la decisión más grande es el tipo de aplicación. Google te pide que elijas un tipo específico como Web, Android, iOS, o Desktop. Esa elección no es cosmética. Define cómo se identifica la aplicación y qué configuración de apoyo se requiere.
Para una aplicación web, espere ingresar:
- Orígenes de JavaScript autorizados
- URIs de redireccionamiento autorizados
Esos valores deben ser exactos. Para un credencial de web, Google espera el esquema completo y el nombre de host, como https://www.example.com, en lugar de un concepto de dominio suelto.
Para plataformas móviles, la forma es diferente. La inscripción de Android requiere la verificación de identidad y propiedad a nivel de paquete, mientras que iOS utiliza sus propios identificadores de plataforma. Si está combinando la autenticación de Google con otra capa de autenticación, este Capacitor setup de inicio de sesión social con Supabase es un ejemplo útil de cómo estos piezas se ajustan a menudo.
This walkthrough is a decent visual reference if you want to compare the UI while you click through:
Dónde encontrarlo más tarde
Después de la creación, el ID del cliente aparece en la lista de credenciales del proyecto. Ese mismo espacio de proyecto es también donde los equipos habilitan las API y visualizan cómo la identidad OAuth se conecta a la pantalla de consentimiento. El nombre de la aplicación registrada es lo que los usuarios ven durante la solicitud de permiso, lo que es una de las razones por las que nombrar la aplicación con precisión importa.
Google mantiene estas credenciales manejables con el tiempo. Puede regresar a la consola para copiar el ID del cliente, revisar los ajustes y, donde corresponda, gestionar el secreto del cliente asociado con esa credencial.
La pantalla de consentimiento no es decoración. Es parte de la frontera de confianza. Los usuarios ven el nombre de su aplicación allí, no su apodo de proyecto interno.
Configuraciones de ID de cliente específicas de plataforma
La forma más rápida de romper una configuración de inicio de sesión de Google es asumir que un ID de cliente puede cubrir todas las plataformas. No puede. Para aplicaciones de múltiples plataformas, cada plataforma debe registrar su propio ID de cliente OAuth 2.0 distinto, y la configuración de Android requiere específicamente la huella SHA1 para verificar la propiedad, como se indica en.
¿Por qué una aplicación necesita múltiples IDs de cliente?
Su producto puede ser una sola aplicación para el usuario, pero es múltiples clientes OAuth para Google.
A aplicación weby an compilación de Androidy an compilación de iOSy una aplicación de escritorio no presentan las mismas propiedades de seguridad. No demuestran la identidad de la misma manera, y no almacenan todas las credenciales en un entorno confiable. Google maneja eso proporcionando a cada plataforma su propio modelo de registro de aplicación.
Esta separación es una buena higiene de seguridad. Si la configuración de credenciales de una plataforma se ve comprometida o mal configurada, las otras no se ven automáticamente expuestas.
Aquí está la división práctica a seguir:
- Web usa un ID de cliente web y un origen y un URI de redireccionamiento estricto.
- Android usa un identificador de cliente Android vinculado a la identidad del paquete y la huella SHA1.
- iOS usa un identificador de cliente iOS vinculado a la identidad del paquete.
- Desktop o Electron a menudo usa un patrón de OAuth instalado o de escritorio en lugar de un flujo de navegador respaldado por una clave secreta.
Tipos de identificadores de cliente de Google comparados
| Tipo de aplicación | Identificador principal | ¿Proporciona una clave secreta? | Uso de caso principal |
|---|---|---|---|
| Web | origenes de JavaScript autorizados y URIs de redireccionamiento | Sí, generalmente | Aplicaciones de navegador y OAuth asistido por backend web |
| Android | Identidad del paquete más huella SHA1 | No, a menudo | Inicio de sesión de Android nativo |
| iOS | Identidad del paquete de aplicación | No, a menudo | Inicio de sesión nativo de iPhone e iPad |
| Desktop | Identidad de la aplicación instalada | A menudo no | Aplicaciones de escritorio, incluidos flujos nativos de estilo Electron |
El paradoja del secreto del cliente para móviles y escritorios
Esta es la parte en la que muchos tutoriales se equivocan.
Los desarrolladores de móviles y escritorios esperan a menudo que cada cliente OAuth venga con ambos un ID de cliente y un secreto del cliente. Luego crean un Credencial de aplicación web porque es la única forma en que pueden ver un secreto en la consola. El flujo parece más completo, así que siguen adelante. Más tarde, la autenticación falla de maneras confusas.
Según explicación de la incompatibilidad de credenciales móviles, tipos de aplicaciones no web como Android, iOS y aplicaciones instaladas reciben a menudo un ID de cliente pero no un secreto de cliente intencionalmente, porque Google no quiere que un secreto confidencial esté incorporado en el software del lado del cliente donde los usuarios pueden extraerlo.
Esa elección de diseño es correcta. Una aplicación móvil o un paquete de Electron no es un almacén de secretos seguro.
Lo que funciona: Flujos de OAuth nativos o diseñados para clientes públicos.
Lo que no funciona: Crear una credencial web para una aplicación móvil solo para obligar a un secreto en la implementación.
Para Capacitor equipos, esto suele aparecer en uno de dos malos patrones:
- La aplicación lanza un flujo basado en navegador utilizando un cliente web y luego intenta comportarse como un servidor confidencial.
- La aplicación envía un cliente secreto desde code empaquetado, lo que contradice el propósito de tener un secreto.
La mejor aproximación es tratar a las aplicaciones móviles y de escritorio como clientes públicos. En OAuth moderno, eso generalmente significa usar un flujo que no depende de un secreto escondido dentro del cliente. Si su servidor está involucrado, mantenga las operaciones confidenciales en el servidor y mantenga la aplicación nativa limitada a lo que debe hacer un cliente público.
Otro punto sutil importa para la autenticación de inicio de sesión de Firebase en Android. En ese escenario, el tipo de cliente de aplicación web se utiliza como el ID de cliente del servidor de OAuth del backend, mientras que la aplicación de Android mantiene su propia identidad específica de plataforma. Esa división confunde a los equipos porque ven tanto una credencial de web como una credencial móvil en el mismo proyecto y asumen que una reemplaza a la otra. No es así. Sirven roles diferentes.
Si recuerda una regla, utilice esta: elija el tipo de cliente que coincida con donde se ejecuta code, no la forma de la credencial que desearía tener.
Seguridad de las credenciales de Google API
La mayoría de los incidentes de OAuth no se deben a ataques complejos. Los equipos divulgaban credenciales, ampliaban demasiado los ajustes de redireccionamiento o ponían secretos en lugares donde nunca estaban seguros de comenzar con ellos.
La guía de OAuth de Google enfatiza que los identificadores y secretos de clientes deben tratarse como datos privados, y para aplicaciones web, el identificador de cliente se aplica contra URIs de redireccionamiento pre-registradas. Si la URI de redireccionamiento no coincide estrictamente, Google rechaza la solicitud. Esa vinculación de origen es parte de la protección contra la interceptación de tokens, como se describe en La guía de registro de clientes de OAuth.com.
¿Qué cerrar inmediatamente?
Si solo haces un par de cosas bien, haz estas:
- Jamás envíes un secreto de cliente en la aplicación code. Los paquetes de bundles web, los binarios de móviles y los paquetes de Electron son inspeccionables por los usuarios.
- Registra URIs de redireccionamiento exactas. Lo suficiente no es suficiente. Google valida coincidencias estrictas para flujos web.
- Mantén los orígenes estrechos. No autorices dominios amplios solo para superar la fricción de configuración.
- Separa credenciales de plataforma. ¿Deje que la conveniencia combine Android, iOS y web en una credencial.
Un detalle operativo es fácil de pasar por alto. Google permite a los equipos generar nuevos secretos para un ID de cliente existente y deshabilitar los antiguos. Eso importa cuando un secreto está expuesto o cuando estás ajustando tu proceso de despliegue.
¿Qué hacen los equipos seguros?
Los equipos que evitan problemas tratan las credenciales de OAuth como cualquier otro secreto de producción.
Guardan los secretos de clientes web en el backend, los inyectan a través de la gestión de entornos y auditan quién tiene acceso a la consola. Si estás limpiando tu pipeline de lanzamiento, esta guía sobre la gestión de secretos en pipelines de CI/CD también es aplicable a tu configuración de autenticación. También revisan la metadata, no solo las claves. La pantalla de consentimiento de OAuth está vinculada a la identidad del cliente que los usuarios ven. Si el nombre de la aplicación es vago o engañoso, los usuarios son más propensos a no confiar en la solicitud o aprobar la aplicación equivocada. La seguridad no solo se trata de ocultar un secreto. También se trata de asegurarse de que la identidad del app correcta, los objetivos de redirección y la pantalla de aprobación se alineen cada vez.
Solución de Problemas Comunes de Errores de ID de Cliente
La mayoría de los errores de OAuth de Google provienen de un pequeño conjunto de errores de configuración. El texto de error no siempre es amable, pero el problema subyacente suele ser claro una vez que se sabe dónde buscar.
Las soluciones que resuelven la mayoría de los errores
__CAPGO_KEEP_0__
__CAPGO_KEEP_1__
redirect_uri_mismatch
Su aplicación está enviando una URI de redirección que no coincide exactamente con lo registrado para ese cliente de la web. Verifique el esquema, el host, la ruta y cualquier diferencia de cola.
invalid_client
Esto suele significar que la aplicación está enviando el ID de cliente incorrecto, el secreto incorrecto para ese cliente o mezclando credenciales entre plataformas. Un ejemplo común es un flujo de Android o iOS que accidentalmente utiliza la credencial de la web en el lugar incorrecto.
invalid_request
Esta es una causa general, pero en aplicaciones de varias plataformas a menudo apunta a parámetros de autenticación malformados o un flujo que no se ajusta al tipo de cliente. Verifique si la aplicación está tratando de incluir un secreto donde no debería, o si el flujo de OAuth seleccionado espera un tipo de cliente diferente.
Google Sign-In funciona en la web pero falla en móviles
La primera cosa a inspeccionar es el tipo de cliente. La fuente más común de error para los desarrolladores de móviles es crear un ID de cliente de aplicación web solo para obtener un secreto de cliente, cuando deberían estar utilizando tipos de Android o iOS que a menudo omiten el secreto intencionalmente, como se explica en este análisis de la incompatibilidad del secreto de clienteSi su implementación incluye trabajo de ciclo de vida de tokens después de la autenticación, esa guía de revocación también es útil.
La autenticación de Android falla después de la creación de credenciales
Verifique con cuidado la huella SHA1 adjunta al cliente de Android. Si la identidad de firma no coincide con lo que Google espera, la aplicación no podrá demostrar la propiedad correctamente.
La pantalla de consentimiento parece incorrecta
Verifique el nombre de la aplicación y la marca asociada a la configuración de OAuth en la consola. Los usuarios autorizan lo que ven allí, por lo que los metadatos incorrectos crean problemas de confianza y ruido de soporte.
El orden de depuración práctico es simple: compruebe el tipo de cliente primero, luego los ajustes de redirección, luego los identificadores de plataforma, luego si un secreto pertenece al flujo en absoluto.
Si su equipo envía Capacitor o aplicaciones de Electron, los errores de autenticación rara vez permanecen aislados. Suele surgir junto con la presión de lanzamiento, las necesidades de devolución y las correcciones específicas del entorno. Capgo ayuda a los equipos a enviar actualizaciones dirigidas a la aplicación code y los activos sin tener que esperar a la revisión de la tienda, lo que hace mucho más fácil corregir los flujos de inicio de sesión, el manejo de llamadas de retorno y los problemas de autenticación en el lado del cliente cuando se filtran en producción.
