Vous êtes probablement ici parce que Google Sign-In devrait être une intégration rapide, et au lieu de cela, vous vous trouvez face à un écran de clés de compte 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 la plupart des guides ignorent est celle qui brise les implémentations réelles : Google Client IDs are platform-specific, et les types d'applications non-web ont souvent pas de secret client par défaut. Si vous créez le mauvais certificat juste pour forcer un secret dans le flux, vous vous retrouvez généralement avec un ensemble 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
- Qu'est-ce qu'un identifiant client Google
- Comment créer et afficher votre identifiant client
- Configurations d'identifiant client spécifiques à la plateforme
- Sécuriser vos identifiants Google API
- Dépannage des erreurs courantes d'identifiant client
Se connecter à l'écosystème Google
Beaucoup d'équipes rencontrent ce problème en même temps. Elles ont besoin de Se connecter avec GoogleOu ils veulent un accès approuvé par l'utilisateur à quelque chose comme Drive ou Agenda, et un clé API ne suffit plus soudainement.
C'est parce que l'authentification des utilisateurs et l'accès délégué passent par OAuth. Google a besoin d'une façon d'identifier your appL’API n'est pas appelé directement. C'est le jeton qui fait cela. ID Client Google.
If you’re working in a cross-platform codebase, the confusion gets worse fast. You might have a web frontend, an Android shell, an iOS app, and maybe an Electron build for desktop. They may share product branding and backend logic, but they should not all share one OAuth identity.
Une mise en œuvre OAuth pratique se résume généralement à quelques questions d'implémentation :
- Quel type d'application devriez-vous créer
- Que vous ayez besoin d'un secret client
- Quels URIs de redirection ou d'origine doivent correspondre exactement
- Comment relier les flux mobiles et web sans mélanger les informations d'identification
- Pourquoi un flux qui fonctionne dans le navigateur échoue à l'intérieur d'un wrapper natif
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'une information d'identification 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 ID client Google
Un ID client OAuth 2.0 Google est l'identifiant public de votre application dans le système d'authentification de Google. Google le décrit comme l'identifiant de nom 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'une identité 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 de l'identifiant client de Google Cloud.
Le modèle mental simple
Pensez à l' identifiant client Google comme votre identifiant d'application utilisateur public.
Ce qui vous indique à 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 dans lequel 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 surprend les gens, c'est que ce credentiel se trouve à côté de deux autres concepts qui ne sont pas interchangeables.
ID du client identifie l'application dans OAuth.
API clé identifie un projet pour certaines appels API qui ne nécessitent pas d'autorisation utilisateur déléguée.
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 cassé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'inscrit en pratique
Si vous avez besoin Se connecter avec Google ou Un seul clicLa documentation de Google note également que l'application doit être enregistrée dans un projet Cloud Console dédié avant que le credencial 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 lié à une identité d'application connue.
Pour les équipes créant des applications hybrides, le modèle mental le plus sûr est celui-ci :
- Utilisez l'ID 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 façon 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 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 Plateforme d'authentification Google > Clients et l'ancienne APIs & Services > Identifiants chemin, tel que décrit dans la documentation de configuration de Google.
Démarrez dans la bonne zone de la console
Ouvrez le console de Google Cloud et sélectionnez ou créez le projet qui possédera la configuration d'authentification. N'éparpillez pas 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 :
- Plateforme d'authentification Google > Clients
- APIs & Services > Informations d'identification
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 l'information d'identification 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 Desktop. Cette choix n'est pas esthétique. Il définit comment l'application est identifiée et quelles configurations de soutien sont requises.
Pour une application web, attendez-vous à entrer :
- Origines JavaScript autorisées
- URIs de redirection autorisées
Ces valeurs doivent être exactes. Pour un jeton de credenciaux, 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 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étrage de connexion sociale avec Supabase est un exemple utile de la façon dont ces pièces s'assemblent souvent.
Cette marche à suivre 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 crédentials du projet. Cette même espace de projet est également où les équipes activent les APIs et visualisent comment 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 nommer l'application avec précision compte.
Google gère ces informations de crédentials de manière gérable sur le long terme. Vous pouvez revenir 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é à cette information.
L'écran de consentement n'est pas une décoration. Il fait partie de la frontière de confiance. Les utilisateurs y voient le nom de votre application, et non votre surnom de projet interne.
Configurations d'ID client spécifiques aux plateformes
La meilleure façon de casser un paramétrage 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 enregistrer son propre ID client OAuth 2.0 distinct, et la mise en place Android nécessite spécifiquement le SHA1 de l'empreinte pour vérifier la propriété, comme indiqué dans Référence de configuration de la plateforme.
Why one app needs multiple client IDs
Votre produit peut être une seule application pour l'utilisateur, mais il s'agit de plusieurs clients OAuth pour Google.
A application web, une une build Android, une une build iOSet une desktop app don’t present the same security properties. They don’t prove identity in the same way, and they don’t all store credentials in a trustworthy environment. Google handles that by giving each platform its own app registration model.
C'est une bonne pratique de sécurité. Si la configuration des identifiants 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 strict d'origine et d'URI de redirection.
- Android utilise un identifiant de client Android lié à l'identité du package et à la signature SHA1.
- iOS utilise un identifiant de client iOS lié à l'identité du bundle de l'application.
- Desktop ou Electron Utilise souvent un modèl’OAuth 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 le secret client ? | Utilisation clé |
|---|---|---|---|
| Web | Origines JavaScript autorisées et URIs de redirection | Généralement oui | Applications de bureau et OAuth assisté par web avec backend |
| Android | Identité du package plus empreinte SHA1 | Souvent non | Connexion à Android native |
| iOS | Identité du bundle d'application | Souvent non | Connexion native iPhone et iPad |
| Bureau | Identité de l'application installée | Souvent non | Applications de bureau, 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 ID du client et un un secret client. Ensuite, ils créent un Application Web un jeton d'accès 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.
According to cette explication de la mésaventure des jetons de mobile , les types d'application 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 d'un secret confidentiel inséré dans un 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 : Flux OAuth côté-client conçus pour les clients publics.
Ce qui ne fonctionne pas : Créer un jeton d'accès 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 à l'aide d'un client web et tente ensuite de se comporter comme un serveur confidentiel.
- L'application envoie un secret client à partir du bundle code, ce qui contrevient à l'objectif d'avoir un secret.
L'approche plus efficace consiste à traiter les applications mobiles et de bureau comme clients publics. Dans 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 back-end est impliqué, gardez les opérations confidentielles sur le back-end et restreignez l'application native aux actions que devrait effectuer un client public.
Un autre point subtil compte pour la connexion Firebase Android. Dans ce scénario, le ID de client d'application web est utilisé comme ID de client OAuth du serveur back-end, 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.
If you remember one rule, use this one: choisissez le type de client qui correspond à l'emplacement où le code s'exécute, et non la forme de vos informations d'identification.
Sécuriser vos identifiants Google API
La plupart des incidents OAuth ne sont pas causés par des attaques complexes. Les équipes divulguent des informations d'identification, élargissent les paramètres de redirection ou mettent des secrets dans des endroits où ils n'étaient jamais sûrs.
La documentation 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 Guidance for registering a client on OAuth.com.
Ce que vous devez sécuriser immédiatement
Si vous faites juste quelques choses bien, faites celles-ci.
- Never ship a client secret in app code. Les paquets Web, les binaires mobiles et les packages Electron sont inspectables par les utilisateurs.
- Inscrivez des URIs de redirection exactes. Le proche n'est pas suffisant. Google valide des correspondances strictes pour les flux web.
- Conservez les origines serrées. N'acceptez pas les domaines larges juste pour éviter les difficultés de configuration.
- Séparez les informations de plateforme. N'abandonnez pas la sécurité pour la commodité : protégez vos identifiants Android, iOS et web.
Un détail opérationnel est facile à manquer. Google permet aux équipes de générer de nouveaux secrets pour un ID 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 problèmes traitent les informations d'authentification OAuth comme n'importe quel autre secret de production.
They keep web client secrets on the backend, inject them through environment management, and audit who has console access. If you’re cleaning up your release pipeline, this guide on Gestion des secrets dans les pipelines CI/CD is worth applying to your auth setup too.
They also review metadata, not just keys. The OAuth consent screen is tied to the client identity users see. If the application name is vague or misleading, users are more likely to mistrust the prompt or approve the wrong app.
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ésoudre les erreurs courantes de Client ID
La plupart des échecs d'authentification OAuth Google proviennent d'une petite série d'erreurs de configuration. Le texte d'erreur n'est pas toujours aimable, mais la cause sous-jacente est généralement simple à identifier une fois que vous savez où chercher.
Les corrections qui résolvent la plupart des échecs
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, 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 works on web but fails on mobile
La première chose à inspecter est le type de client. La principale source 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 Cette analyse de la mise à jour du secret clientSi votre implémentation inclut des travaux de cycle de jeton après l'inscription, ce guide de révocation est également utile.
L'inscription Android échoue après la création de la clé de crédit
Vérifiez l’empreinte SHA1 attachée à l'application 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 semble incorrect
Vérifiez le nom de l'application et la marque attachés à la configuration OAuth dans le 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 réglages, puis identifiants de plateforme, puis si un secret appartient à la chaîne d'authentification..
Si votre équipe expédie des applications Capacitor ou Electron, les bugs d'authentification sont rarement isolés. Ils se présentent 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.
