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 la chose qui brise les implémentations réelles : Les identifiants de client Google sont spécifiques à la plateformeet les types d'applications non web le sont souvent ne pas
d'obtenir un secret client par conception. 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
- Connexion de votre application à l'écosystème Google
- Où l'identifiant client Google s'insère en pratique
- Configurations de l'ID du client spécifique à la plateforme
- Sécuriser vos API identifiants Google
- Dépannage des erreurs d'ID de client courantes
Connexion de votre application à l'écosystème Google
Beaucoup d'équipes rencontrent ce problème en même temps. Elles ont besoin Se connecter avec Google, ou ils veulent un accès approuvé par l'utilisateur à quelque chose comme Drive ou Agenda, et une clé API soudainement cesse d'être suffisante.
C'est parce que 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 application, et non juste la API qui est appelée. Le jeton d'authentification qui fait cela est le ID client Google.
Si vous travaillez dans un codebase multiplateforme, la confusion s'accroît rapidement. Vous pourriez avoir un frontend web, une coquille 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 mobile et web sans mélanger les jetons d'authentification
- Why a flux qui fonctionne dans le navigateur échoue à l'intérieur d'un enveloppe native
Règle pratique : Si votre application demande la permission de l'utilisateur ou la connexion, commencez par penser aux types de clients OAuth, pas aux API clés.
Cette distinction économise du temps en amont. Elle empêche également l'erreur commune 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 Google OAuth 2.0 est l'identifiant public de votre application dans le système d'authentification Google. Google le décrit comme l'identifiant unique d'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 clés car il est utilisé dans les flux OAuth pour vérifier l'identité de l'application lors de l'échange de jetons, comme expliqué dans la documentation du client OAuth de Cloudflare.
The simple mental model
Pensez à la identifiant client Google les problèmes comme les autorisations de votre application nom d'utilisateur public.
Cela dit à Google : « Cette requête provient de cette application enregistrée. » Cela compte lors de la connexion, de l'accord, de l'échange de jeton 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'authentification de Google.
Ce qui fait chuter les gens, c'est que ce credencial se trouve à côté de deux autres concepts qui ne sont pas interchangeables.
Identifiant client identifie l'application dans OAuth.
API clé identifie un projet pour certains appels API qui ne concernent pas l'autorisation déléguée de l'utilisateur.
Identifiant secret du client is le contrepartie confidentielle utilisée uniquement dans les flux et les types d'application qui peuvent sécuriser les secrets.
Un grand nombre d'intégrations brisées commencent lorsque quelqu'un traite ces choses comme des variations de la même chose. Ce n'est pas le cas.
Où l'identifiant client Google s'insère en pratique
Si vous avez besoin Se connecter avec Google ou Un seul coup, l'identifiant client est la valeur que votre frontend utilise pour initier la main de jeu d'authentification. La documentation de Google note également que l'application doit être enregistrée dans un projet Cloud Console dédié avant que les informations d'identification ne puissent être générées, 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 lié à la demande d'authentification à une identité d'application connue.
Pour les équipes qui construisent 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
- Utilisez le type d'application correct pour déterminer si une clé se trouve dans le flux
Si vous souhaitez une introduction plus large sur la manière dont l'identité des applications et l'accès délégué s'associent, ce guide à l'autorisation des applications 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 la mauvaise place. 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 > Credentials chemin, comme décrit dans la documentation de configuration de Google.
Commencez dans la bonne zone de console
Ouvrez le Google Cloud Console 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 ultérieurement.
À partir de là, allez dans l'un de ces endroits :
- Google Auth Platform > Clients
- APIs & Services > Credentials
If your team sees different navigation labels, that’s expected. Google has been separating identity setup from the rest of the API credential surface.
Créez le crédit sans vous enfermer
Lorsque vous créez un nouveau client OAuth, la plus grande décision est le type d'application. Google vous demande de choisir un type spécifique tel que Web, Android, iOSou 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.
Pour une application web, 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.
Pour les plateformes mobiles, la forme est différente. La registration 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.
This walkthrough is a decent visual reference if you want to compare the UI while you click through:
Où le trouver plus tard
Après la création, l'ID client apparaît dans la liste des informations de sécurité du projet. Cette même espace de projet est également où les équipes activent les API et consultent comment l'identité OAuth se connecte à l'écran de consentement. Le nom de l'application enregistrée est celui que les utilisateurs voient lors de 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 sécurité de manière à les rendre gérables sur le long terme. Vous pouvez retourner sur le tableau de bord pour copier l'ID client, examiner les paramètres et, le cas échéant, gérer le secret client associé à cette information.
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 de l'ID client spécifiques à la plateforme
La façon la plus rapide de casser une configuration de connexion Google est de supposer que l'un seul ID client peut couvrir toutes les plateformes. C'est impossible. 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 la mise à jour de l'empreinte SHA1 pour vérifier la propriété, comme indiqué dans Pourquoi une 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 Pourquoi une application nécessite plusieurs ID clientsne 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 pas tous les identifiants dans un environnement fiable. la construction d'une application Androidne 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 pas tous les identifiants dans un environnement fiable. et une application de bureaune 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 pas tous les identifiants dans un environnement fiable. Google gère cela en fournissant à 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 identifiants d'une plateforme est compromise ou mal configurée, les autres ne sont pas automatiquement exposés.
Voici la séparation pratique à suivre :
Web
- utilise un identifiant de client web et un matching d'origine et d'URI de redirection strict. Android
- iOS build utilise un identifiant de client Android lié à l'identité du package et à la empreinte SHA1.
- IOS utilise un identifiant de client iOS lié à l'identité du bundle de l'application.
- Bureau ou Electron utilise souvent un modèle OAuth de style installé ou de bureau plutôt qu'un flux de navigateur basé sur un secret.
Types d'identifiant de client Google comparés
| Type d'application | Identifiant principal | fournit un secret de client? | Utilisation clé |
|---|---|---|---|
| Web | Origines JavaScript autorisées et URIs de redirection | Généralement oui | Applications de navigateur et OAuth assistées par un serveur web |
| Android | Identité du package plus empreinte SHA1 | Souvent non | Connexion d'authentification Android native |
| iOS | Identité du bundle d'applications | Souvent non | Connexion d'authentification native iPhone et iPad |
| Desktop | Identité de l'application installée | Souvent non | Les applications de bureau, y compris les flux natifs Electron-style |
Le paradoxe du secret client pour les appareils mobiles et de bureau
C'est là où de nombreuses tutoriels se trompent.
Les développeurs de mobiles et de bureau attendent souvent que chaque client OAuth vienne avec les deux un ID client et un secret client . Ils créent ensuite unCredential d'Application Web car c'est la seule façon dont ils peuvent voir un secret dans la console. Le flux semble plus complet, donc ils continuent. Plus tard, l'authentification se brise de manière confuse. Selon
__CAPGO_KEEP_0__ explication de la désynchronisation des crédentiels mobilesLes 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 choix de conception est correct. Une application mobile ou un bundle 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 crédentiel 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 essaie ensuite de se comporter comme un serveur confidentiel.
- L'application envoie un secret client de l'code embarqué, ce qui détruit l'intérêt d'avoir un secret.
L'approche plus efficace consiste à considérer les applications mobiles et de bureau comme 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 backend est impliqué, gardez les opérations confidentielles sur le backend et limitez 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, l' ID du client de l'application web est utilisé comme ID du client OAuth du serveur backend, tandis que l'application Android garde 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'endroit où s'exécute l'code, pas la forme de credencial que vous souhaitez avoir.
Sécuriser vos identifiants Google API
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.
La documentation d'authentification Google met l'accent sur le fait que les identifiants et les secrets des clients doivent être traités comme des données privées, et pour les applications web, l'identifiant du 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 documentation de l'enregistrement du client de OAuth.com.
Ce que vous devez sécuriser immédiatement
Si vous faites seulement quelques choses correctement, faites-les :
- Ne jamais expédier un secret de client dans l'application code. Les bundles web, les binaires mobiles et les packages Electron sont inspectables par les utilisateurs.
- Enregistrer des URIs de redirection exactes. Proche ne suffit pas. Google valide des correspondances strictes pour les flux web.
- Gardez les origines serrées. N'autorisez pas des domaines larges juste pour passer la friction de configuration.
- Séparez les informations de plateforme. Don’t let convenience pousser Android, iOS, et web dans une seule identité de connexion.
Un détail opérationnel est facile à manquer. Google permet aux équipes de générer de nouveaux secrets pour un ID 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 backend, les injectent à travers la gestion de l’environnement, et audittent 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é de l’application 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é n’est pas seulement à cacher un secret. C’est aussi s’assurer que l’identité de l’application, les cibles de redirection et l’écran d’approbation s’alignent à chaque fois.
Résoudre les erreurs courantes liées aux ID de client
La plupart des échecs de l’authentification Google OAuth proviennent d’un petit ensemble 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
__CAPGO_KEEP_0__
__CAPGO_KEEP_0__
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, la route 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 les appareils mobiles
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 omittent souvent le secret intentionnellement, comme expliqué dans ce guide de décomposition de 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 la 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 marque associés à 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, puis les paramètres de redirection, puis les identifiants de plateforme, puis si un secret appartient au flux en question.
Si votre équipe expédie des applications Capacitor ou Electron, les bugs d'authentification sont rarement isolés. Ils surgissent 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.
