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 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
- Connexion de votre application à l'écosystème Google
- Où l'identifiant de client Google s'insère en pratique
- Configurations de l'ID du client spécifique au plateforme
- Sécurisation de vos informations de compte Google API
- Dépannage des erreurs courantes d'ID de client
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 Googleou ils veulent un accès approuvé par l'utilisateur à quelque chose comme Drive ou Agenda, et une clé API s'arrête soudainement d'être suffisante.
C'est parce que l'inscription 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 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 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
- Why a flow that works in the browser fails inside a native wrapper
Règle pratique : Si votre application demande la permission de l'utilisateur ou la connexion, commencez par penser en types de clients OAuth, pas en API.
Cette distinction économise du temps dès le début. 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
A L'identifiant client OAuth 2.0 de Google est l'identifiant public de votre application dans le système d'authentification de Google. Google le décrit comme l'identifiant d'utilisateur unique pour une application lorsqu'elle demande des jetons d'accès aux points de terminaison d'authentification de Google, et note qu'il s'agit d'un identifiant distinct des API 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 des clients OAuth de Google Cloud.
The simple mental model
Pensez à la identifiant client Google les problèmes comme votre application’s nom d'utilisateur public.
Cela dit à Google, « cette demande 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 credencial se trouve à côté de deux autres concepts qui ne sont pas interchangeables.
Identifiant client identifie l'application dans OAuth.
API key identifie un projet pour certains appels API qui ne concernent pas l'autorisation déléguée de l'utilisateur.
Identifiant secret client est le contrepartie confidentielle utilisée uniquement dans les flux et les types d'applications qui peuvent sécuriser les secrets.
Beaucoup 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 clic, l'identifiant client est la valeur que votre frontend utilise pour initier la main de mise à jour 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 de compte 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'applications 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 un secret appartient au 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 Identifiant 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 chemin et l'ancien 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édential 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, iOS, ou DesktopCette option n'est pas esthétique. Elle détermine comment l'application est identifiée et quelles configurations de soutien sont requises.
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 mise en registration d'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 paramètre 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 là où les équipes activent les API et consultent la manière dont l'identité OAuth se connecte à l'écran de consentement. Le nom de l'application enregistrée est celui 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 sécurité de manière efficace au fil du temps. 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 de l'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. 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 l'impression 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 clients. Votre produit peut être une seule application pour l'utilisateur, mais il s'agit de plusieurs clients OAuth pour Google., un une construction d'application Android, un une construction d'application iOS, et une une application 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 pas tous les crédentiels 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 :
- Web utilise un identifiant de client web et un matching d'origine et d'URI de redirection strict.
- Android utilise un identifiant de client Android lié à l'identité du package et à la trace SHA1.
- IOS utilise un identifiant de client iOS lié à l'identité du bundle de l'application.
- Desktop 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 | D'habitude oui | Applications de navigateur et OAuth assistées par un serveur backend |
| Android | Identité du package plus empreinte SHA1 | D'habitude non | Connexion d'authentification native Android |
| iOS | Identité du bundle d'applications | D'habitude non | Connexion d'authentification native iPhone et iPad |
| Bureau | Identité de l'application installée | Souvent non | Les applications de bureau, y compris les flux natifs d'Electron |
Le paradoxe du secret client pour les appareils mobiles et de bureau
C'est là où beaucoup de 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 un secret client. Ils créent ensuite un Application Web des informations d'identification 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 explication de la non-conformité des informations de crédit mobile, les types d'applications non-web comme Android, iOS et les applications installées reçoivent souvent un ID client mais pas de secret client intentionnellement, car Google ne veut pas que un secret confidentiel soit intégré dans un logiciel côté client où les utilisateurs peuvent l'extraire.
Ce choix de conception est correct. 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 crédit 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 appropriée 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 aux seules actions que devrait effectuer un client public.
Un autre point subtil est important pour la connexion de signe Firebase sur Android. Dans ce scénario, l' ID du client de l'application web est utilisé comme ID du 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ù 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 credenciales, élargissent les paramètres de redirection de manière excessive ou insèrent des secrets dans des endroits où ils n'étaient jamais sûrs.
La documentation d'OAuth de 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 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. Le 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 plateforme. N'empêchez pas la commodité de pousser Android, iOS et web vers un seul credencial.
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 credenciaux OAuth comme tout autre secret de production.
Elles gardent les secrets de clients web sur le serveur, les injectent à travers la gestion de l'environnement 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. Elles 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é 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ésolution des erreurs courantes liées aux ID de client
La plupart des échecs de l'authentification Google OAuth 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 Troubleshooting Guide
redirect_uri_mismatch
Votre application envoie une URI de redirection qui ne correspond pas exactement à celle enregistrée 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 de plateforme croisée, 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 mise en œuvre 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 marque 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 ou non.
Si votre équipe expédie des applications Capacitor ou Electron, les bugs d'authentification rarement restent 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.
