Vous êtes probablement ici parce que Google Sign-In aurait dû être une intégration rapide, et au lieu de cela, vous vous trouvez face à un écran de crédentials en train de vous demander pourquoi un type d'application vous donne un secret client et un autre non. Cette confusion est normale, surtout si vous construisez avec Capacitor, Ionic, Electron ou un mélange de pile web et native.
La partie que les guides ignorent la plupart du temps est celle qui casse les implémentations réelles : Les identifiants de client Google sont spécifiques à la plateforme, et les types d'applications non web ont souvent ne pas obtenir un secret de client par design. Si vous créez le mauvais certificat juste pour forcer un secret dans le flux, vous finissez généralement par avoir un ensemble de configuration OAuth cassé qui est plus difficile à déboguer qu'il ne le devrait.
Table des matières
- Se connecter à votre application à l'écosystème Google
- Qu'est-ce qu'un identifiant de client Google
- Comment créer et afficher votre identifiant de client
- Configurations de Client ID spécifiques à la plateforme
- Authentifier vos API Google avec sécurité
- Résolution des erreurs d'identifiant de client courantes
Connecter votre application à l'écosystème Google
Beaucoup d'équipes rencontrent ce problème en même temps. Elles ont besoin Se connecter avec Googleou ils veulent un accès approuvé à quelque chose comme Drive ou Agenda, et une clé API s'arrête soudainement d'être suffisante.
En effet, l'authentification de l'utilisateur et l'accès délégué passent par OAuth. Google a besoin d'une façon d'identifier votre applicationet non seulement l’API qui est appelée. Le jeton qui fait cela est l'ID Client Google Si vous travaillez dans un codebase multiplateforme, la confusion s'accroît rapidement. Vous pourriez avoir une interface web, un shell Android, une application iOS et peut-être une mise en œuvre Electron pour le bureau. Ils peuvent partager une identité de produit et une logique de backend, mais ils ne devraient pas partager tous une identité OAuth..
Une mise en œuvre OAuth pratique se réduit généralement à quelques questions d'implémentation :
Quel type d'application devez-vous créer
- Est-ce que vous avez besoin d'un secret client
- Quels URIs de redirection ou d'origine doivent correspondre exactement
- Comment brancher les flux mobiles et web sans mélanger les jetons
- Quel type d'application devez-vous créer ?
- Why a flow that works in the browser fails inside a native wrapper
Règle pratique : Si votre application demande la permission d'accès à l'utilisateur ou la connexion, commencez par penser en types de clients OAuth, pas en API.
Cette distinction économise du temps en amont. Elle empêche également l'erreur courante de construire un flux de connexion mobile autour d'un credencial web uniquement parce que la console affichait plus de champs. Si vous implémentez cela dans une application Capacitor, ce guide sur OAuth2 dans les applications Capacitor est un compagnon utile pour le flux côté application.
Qu'est-ce qu'un identifiant client Google
Un identifiant client OAuth 2.0 Google est l'identifiant public de votre application dans le système d'authentification Google. Google le décrit comme le nom d'utilisateur unique pour une application lorsqu'elle demande des jetons d'accès aux points de terminaison d'authentification Google, et note qu'il s'agit d'une clé distincte des API car elle est utilisée dans les flux OAuth pour vérifier l'identité de l'application lors de l'échange de jetons, comme expliqué dans la documentation des clients OAuth de Google Cloud.
Le modèle mental simple
Pensez à cela comme votre identifiant client Google les problèmes comme votre identifiant d'application public Ce dernier informe Google : « Cette requête provient de cette application enregistrée. » Cela compte lors de la connexion, du consentement, de l'échange de jetons et de tout flux où votre application demande d'agir au nom d'un utilisateur. L'identifiant client est destiné à être référencé par votre application et les serveurs d'autorisation de Google..
Ce qui fait chuter les gens, c'est que ce credentiel se trouve à côté de deux autres concepts qui ne sont pas interchangeables.
Identifiant client
identifie l'application dans OAuth. __CAPGO_KEEP_0__ clé
identifie un projet pour certaines appels API qui ne concernent pas l'autorisation déléguée de l'utilisateur. identifies a project for certain API calls that don’t involve delegated user authorization.
Identifiant client Google est le contrepartie confidentielle utilisée uniquement dans les flux et les types d'applications qui peuvent garder en toute sécurité des secrets.
Un grand nombre d'intégrations brisées commencent lorsque quelqu'un traite ces éléments comme des variations de la même chose. Ce n'est pas le cas.
Où l'identifiant client Google s'inscrit en pratique
Si vous avez besoin de Se connecter avec Google ou Pour les équipes créant des applications hybrides, le modèle mental le plus sûr est celui-ci :Utilisez l'identifiant client pour identifier l'application
Utilisez l'écran de consentement pour représenter l'application à l'utilisateur
Une seule touche
- la clé d'identification client est la valeur que votre frontend utilise pour initier la main de fermeture d'authentification. La documentation de Google note également que l'application doit être enregistrée dans un projet Cloud Console dédié avant que le jeton ne puisse être généré, et que les applications web nécessitent des origines JavaScript autorisées configurées ou des URIs de redirection avec le schéma et le nom d'hôte complets.
- C'est pourquoi la configuration ressent plus stricte que la génération d'une clé simple. Google n'autorise pas simplement l'accès. C'est la demande d'authentification qui est liée à une identité d'application connue.
- Utilisez le type d'application approprié pour déterminer si un secret appartient au flux.
Si vous souhaitez une introduction plus approfondie sur la manière dont l'identité de l'application et l'accès délégué s'imbriquent, ce guide à l'autorisation de l'application est un bon rappel.
Comment Créer et Afficher Votre ID Client
Le chemin de la console a changé suffisamment pour que les développeurs pensent souvent qu'ils sont dans le mauvais endroit. Ils ne le sont généralement pas. Google expose actuellement deux routes de navigation pour ces informations d'identification : la plus récente Google Auth Platform > Clients et l'ancienne APIs & Services > Identifiants chemin, comme décrit dans la documentation de configuration de Google.
Commencez dans la bonne zone de console
Ouvrez le console Google Cloud et sélectionnez ou créez le projet qui possédera la configuration d'authentification. Évitez de répandre l'authentification dans des projets aléatoires. Cela rend l'audit et le support douloureux plus tard.
À partir de là, allez dans l'un de ces endroits :
- Google Auth Platform > Clients
- APIs & Services > Credentials
Si votre équipe voit des étiquettes de navigation différentes, cela est attendu. Google a séparé la configuration d'identité de la surface de crédentials de API.
Créez le crédit sans vous enfermer
Lorsque vous créez un nouveau client OAuth, la décision la plus importante est le Type d'application. Google vous demande de choisir un type spécifique tel que Web, Android, iOS, ou Desktop. Cette choix n'est pas esthétique. Il définit comment l'application est identifiée et quels paramètres de configuration sont requis.
For a web app, attendez-vous à saisir :
- Origines JavaScript autorisées
- URIs de redirection autorisées
Ces valeurs doivent être exactes. Pour un credencial web, Google attend le schéma et le nom de domaine complets, comme https://www.example.com, plutôt qu'un concept de domaine flou.
For mobile platforms, la forme est différente. L'enregistrement Android nécessite une vérification d'identité et de propriété au niveau du package, tandis que iOS utilise ses propres identifiants de plateforme. Si vous combinez l'authentification Google avec une autre couche d'authentification, ce Capacitor exemple de connexion sociale avec Supabase est un exemple utile de la façon dont ces pièces s'assemblent souvent.
Cette étape guidée est une référence visuelle décente si vous souhaitez comparer l'interface utilisateur tout en cliquant à travers :
Où le trouver plus tard
Après la création, l'ID client apparaît dans la liste des informations de compte du projet. Cette même espace de projet est également là où les équipes activent les API et visualisent comment l'identité OAuth se connecte à l'écran de consentement. Le nom de l'application enregistrée est ce que les utilisateurs voient pendant la demande de permission, ce qui est une raison pour laquelle il est important de nommer l'application avec précision.
Google gère ces informations de compte de manière gérable sur le long terme. Vous pouvez retourner sur le tableau de bord pour copier l'ID client, examiner les paramètres et, dans la mesure du possible, gérer le secret client associé à ce certificat.
L'écran de consentement n'est pas une simple décoration. Il fait partie de la frontière de confiance. Les utilisateurs voient le nom de votre application là, et non votre surnom de projet interne.
Configurations d'ID client spécifiques à la plateforme
La meilleure façon de casser une configuration de connexion Google est de supposer que l'un seul ID client peut couvrir toutes les plateformes. Ce n'est pas possible. Pour les applications multi-plateformes, chaque plateforme doit s'enregistrer son propre ID client OAuth 2.0 distinct, et la configuration Android nécessite spécifiquement l'impression SHA1 pour vérifier la propriété, comme indiqué dans ce référentiel de configuration de la plateforme.
Pourquoi une seule application nécessite plusieurs ID clients
Votre produit peut être une seule application pour l'utilisateur, mais il s'agit de plusieurs clients OAuth pour Google.
A une application web, un une construction d'application Android, un une construction d'application iOS, et une une application de bureau ne présentent pas les mêmes propriétés de sécurité. Ils ne prouvent pas l'identité de la même manière, et ils n'enregistrent tous les crédits dans un environnement fiable. Google gère cela en donnant à chaque plateforme son propre modèle d'enregistrement d'application.
Cette séparation est une bonne hygiène de sécurité. Si la configuration des informations d'identification d'une plateforme est compromise ou mal configurée, les autres ne sont pas automatiquement exposées.
Voici la séparation pratique à suivre :
- Utilise un identifiant client web et un matching strict de l'origine et de l'URI de redirection. Utilise un identifiant client Android
- Utilise un identifiant client iOS utilise un identifiant client Android lié à l'identité du package et à la signature SHA1.
- iOS utilise un identifiant client iOS lié à l'identité de l'application.
- Desktop ou Electron utilise souvent un modèl’OAuth installé ou de style bureau plutôt qu'un flux de navigateur basé sur un secret.
Types d'identifiant client Google comparés
| Type d'application | Identifiant principal | Fournit un secret client ? | Utilisation clé |
|---|---|---|---|
| Web | Origines JavaScript autorisées et URIs de redirection | Généralement oui | Applications de navigateur et OAuth assistées par le serveur web |
| Android | Identité du package plus empreinte SHA1 | Souvent non | Connexion d'authentification Android native |
| iOS | Identité du bundle d'application | Souvent non | Connexion d'authentification iPhone et iPad native |
| Bureau | Identité de l'application installée | Souvent non | Les applications bureautiques, y compris les flux natifs Electron-style |
Le paradoxe du secret client pour mobile et bureau
C'est là où beaucoup de tutoriels se trompent.
Les développeurs de mobile et de bureau attendent souvent que chaque client OAuth vienne avec les deux un identifiant client et un un secret client . Ils créent ensuite un Application Web développeur car c'est la seule façon dont ils peuvent voir un secret dans la console. Le flux semble plus complet, ils continuent donc. Plus tard, l'authentification se brise de manière confuse.
Selon Cette explication de la désynchronisation des informations de connexion mobileLes types d'applications non-web, comme Android, iOS et les applications installées, reçoivent souvent un identifiant client mais pas de secret client intentionnellement, car Google ne veut pas que le secret confidentiel soit intégré dans le logiciel côté client où les utilisateurs peuvent l'extraire.
Cette décision de conception est correcte. Une application mobile ou un paquet Electron n'est pas un magasin de secrets sûr.
Ce qui fonctionne : Les flux OAuth côté client conçus pour les clients publics.
Ce qui ne fonctionne pas : Créer un credencial web pour une application mobile juste pour forcer un secret dans l'implémentation.
Pour les Capacitor équipes, cela se manifeste généralement par l'un des deux mauvais modèles :
- L'application lance un flux basé sur un navigateur en utilisant un client web et tente ensuite de se comporter comme un serveur confidentiel.
- L'application envoie un secret client à partir de code intégré, ce qui détruit l'intérêt d'avoir un secret.
La meilleure approche consiste à considérer les applications mobiles et de bureau comme des clients publics. Dans l'OAuth moderne, cela signifie généralement utiliser un flux qui ne repose pas sur un secret caché à l'intérieur du client. Si votre serveur backend est impliqué, gardez les opérations confidentielles sur le serveur backend et restreignez l'application native à ce que devrait faire un client public.
Un autre point subtil est important pour la connexion de signe Firebase sur Android. Dans ce cas, le ID de client de l'application web est utilisé comme ID de client OAuth du serveur backend, tandis que l'application Android conserve son propre identité spécifique au plateau. Cette division confond les équipes car elles voient à la fois un credencial web et un credencial mobile dans le même projet et supposent que l'un remplace l'autre. Ce n'est pas le cas. Ils servent des rôles différents.
Si vous vous souvenez d'une règle, utilisez celle-ci : choisissez le type de client qui correspond à l'emplacement où le code s'exécute, pas la forme de credencial que vous souhaitez avoir.
La sécurisation de vos API Google
La plupart des incidents OAuth ne sont pas causés par des attaques complexes. Les équipes divulguent des credenciaux, élargissent trop les paramètres de redirection ou mettent des secrets dans des endroits où ils n'étaient jamais sûrs d'abord.
La guidance d'OAuth de Google met l'accent sur le fait que les identifiants et les secrets de client doivent être traités comme des données privées, et pour les applications web, l'identifiant de client est appliqué contre les URIs de redirection pré-enregistrées. Si l'URI de redirection ne correspond pas strictement, Google rejette la demande. Cette liaison d'origine fait partie de la protection contre l'interception de jetons, comme décrit dans La guidance de l'enregistrement de client de OAuth.com.
Ce que vous devez sécuriser immédiatement
Si vous faites seulement quelques choses correctement, faites ces choses :
- Ne faites jamais partir un secret de client dans l'application code. Les paquets de bundles web, les binaires mobiles et les packages Electron sont inspectables par les utilisateurs.
- Enregistrez des URIs de redirection exactes. Proche n'est pas suffisant. Google valide des correspondances strictes pour les flux web.
- Concentrez-vous sur les origines. N'autorisez pas des domaines larges juste pour passer la friction de configuration.
- Séparez les informations de connexion de plateforme. Ne laissez pas la commodité faire fondre Android, iOS et web en un seul identifiant de connexion.
Un détail opérationnel est facile à manquer. Google permet aux équipes de générer de nouveaux secrets pour un identifiant de client existant et de désactiver les anciens. Cela compte lorsque un secret est exposé ou lorsque vous resserrez votre processus de déploiement.
Ce que font les équipes sécurisées
Les équipes qui évitent les ennuis traitent les jetons OAuth comme n'importe quel autre secret de production.
Ils gardent les secrets de clients web sur le serveur, les injectent à travers la gestion des environnements et vérifient qui a accès à la console. Si vous nettoyez votre pipeline de publication, ce guide sur la gestion des secrets dans les pipelines CI/CD est également utile pour votre configuration d'authentification. Ils examinent également les métadonnées, et non seulement les clés. L'écran de consentement OAuth est lié à l'identité du client que les utilisateurs voient. Si le nom de l'application est vague ou trompeur, les utilisateurs sont plus susceptibles de se méfier de la demande ou d'approuver le mauvais application. La sécurité ne consiste pas seulement à cacher un secret. Il s'agit également de s'assurer que l'identité de l'application, les cibles de redirection et l'écran d'approbation s'alignent à chaque fois.
Résolution des erreurs courantes d'identifiant de client
La plupart des échecs de l'authentification OAuth de Google proviennent d'une petite série d'erreurs de configuration. Le texte d'erreur n'est pas toujours aimable, mais la question sous-jacente est généralement simple à résoudre une fois que vous savez où chercher.
Les corrections qui résolvent la plupart des échecs
Troubleshooting Common Client ID Errors
Most Google OAuth failures come from a small set of setup mistakes. The error text isn’t always kind, but the underlying issue is usually straightforward once you know where to look.
redirect_uri_mismatch
Votre application envoie une URI de redirection qui ne correspond pas exactement à ce qui est enregistré pour ce client web. Vérifiez le schéma, l'hôte, le chemin et toute différence de fin.
invalid_client
Cela signifie généralement que l'application envoie le mauvais ID de client, le mauvais secret pour ce client ou mélange les informations d'identification entre les plateformes. Un exemple courant est un flux Android ou iOS qui utilise par erreur les informations d'identification web dans le mauvais endroit.
invalid_request
Cela est large, mais dans les applications cross-platform, cela pointe souvent vers des paramètres d'authentification mal formés ou un flux qui ne correspond pas au type de client. Vérifiez si l'application essaie d'inclure un secret où il ne devrait pas, ou si le flux OAuth sélectionné attend un type de client différent.
Google Sign-In fonctionne sur le web mais échoue sur mobile
La première chose à inspecter est le type de client. La source la plus courante d'erreur pour les développeurs mobiles est la création d'un ID de client d'application web juste pour obtenir un secret de client, alors qu'ils devraient utiliser des types Android ou iOS qui omettent souvent le secret intentionnellement, comme expliqué dans ce détail sur la différence de secret de clientSi votre implémentation inclut du travail sur la vie du jeton après l'inscription, ce guide de revocation est également utile.
L'inscription Android échoue après la création des informations d'identification
Vérifiez à nouveau l’empreinte SHA1 attachée au client Android. Si l'identité de signature ne correspond pas à ce que Google attend, l'application ne prouvera pas la propriété correctement.
L'écran de consentement a l'air faux
Vérifiez le nom de l'application et la marquage de la mise en page attaché à la configuration OAuth dans la console. Les utilisateurs autorisent ce qu'ils voient là, donc les métadonnées incorrectes créent à la fois des problèmes de confiance et du bruit de support.
L'ordre de débogage pratique est simple: Vérifiez le type de client en premier lieu, puis les paramètres de redirection, puis les identifiants de plateforme, puis si un secret appartient à la flux au tout,.
Si votre équipe expédie Capacitor ou des applications Electron, les bugs d'authentification rarement restent isolés. Ils se manifestent généralement aux côtés de la pression de livraison, des besoins de retrait et des correctifs spécifiques à l'environnement. Capgo Aide les équipes à expédier des mises à jour ciblées vers les applications code et les actifs sans attendre la revue de la boutique, ce qui rend beaucoup plus facile de corriger les flux de connexion, la gestion des appels et les problèmes d'authentification côté client lorsqu'ils glissent en production.
