Probabilmente sei qui perché Google Sign-In avrebbe dovuto essere un'integrazione rapida, e invece ti trovi di fronte a una schermata di credenziali che ti fa domande sul perché un tipo di app ti dà un segreto client e un altro no. Quella confusione è normale, soprattutto se stai costruendo con Capacitor, Ionic, Electron o una pila mista web e nativa.
La parte che più guide trascurano è quella che rompe le implementazioni reali: I Denti Client Google sono specifici per piattaforma, e i tipi di applicazione non web spesso non hanno un segreto client di progetto. Se crei il credenziale sbagliata solo per forzare un segreto nel flusso, di solito finisci con un setup OAuth rotto che è più difficile da debuggare di quanto dovrebbe essere.
Elenco dei contenuti
- Collega la tua app al Google Ecosystem
- Cos'è un ID Client Google
- Come creare e visualizzare il tuo ID Client
- Configurazioni di ID del client per piattaforma
- Proteggere le tue credenziali Google API
- Risolvere gli errori comuni di ID del client
Connettere la tua app all'ecosistema Google
Molti team colpiscono questo problema nello stesso momento. Hanno bisogno Accedi con Google, o vogliono un accesso approvato dagli utenti a qualcosa come Drive o Calendario, e una chiave API improvvisamente non è più sufficiente.
Questo è perché l'accesso degli utenti e l'accesso delegato passano attraverso OAuth. Google ha bisogno di una via per identificare l'applicazione, non solo la API in esecuzione. Il credenziale che fa questo è il Google Client ID.
Se si lavora in un codice cross-platform, la confusione peggiora rapidamente. Potreste avere un frontend web, un shell Android, un'app iOS e forse un build Electron per desktop. Possono condividere la branding del prodotto e la logica del backend, ma non dovrebbero condividere un'identità OAuth.
Una configurazione OAuth pratica si riduce a poche domande di implementazione:
- Qual tipo di applicazione creare
- Se si ha bisogno di un segreto del client
- Quali URIs di reindirizzamento o origini devono corrispondere esattamente
- Come collegare i flussi mobili e web senza mescolare le credenziali
- Why un flusso che funziona nel browser fallisce all'interno di un wrapper nativo
Regola pratica: Se la tua app richiede il permesso dell'utente o l'accesso, inizia pensando ai tipi di client OAuth, non ai API chiavi.
Questa distinzione salva tempo inizialmente. Inoltre, evita l'errore comune di creare un flusso di accesso mobile basato su un credenziale web solo perché il console mostrava più campi. Se stai implementando questo in un'app Capacitor, questa guida su OAuth2 nelle app Capacitor è un utile compagno per il flusso dell'app.
Cosa è un ID client di Google
Un ID client OAuth 2.0 di Google è l'identificatore pubblico per la tua applicazione nel sistema di autenticazione di Google. Google lo descrive come l'username unico per un'applicazione quando richiede token di accesso dai punti di fine di autenticazione di Google, e nota che è distinto dalle API chiavi perché viene utilizzato nei flussi OAuth per verificare l'identità dell'app durante l'interscambio di token, come spiegato in la documentazione dei client di Cloud di Google.
The mental model semplice
Pensa al ID client Google gli issue come il tuo app’s username pubblico.
Dice a Google, 'questa richiesta proviene da questo'applicazione registrata.' Ciò è importante durante l'accesso, il consenso, l'interscambio di token e qualsiasi flusso in cui il tuo app chiede di agire in nome di un utente. L'ID client è destinato a essere riferito sia dal tuo app che dai server di autenticazione di Google.
Ciò che confonde le persone è che questo credenziale si trova accanto a due altri concetti che non sono intercambiabili.
ID client identifica l'app in OAuth.
API key identifica un progetto per certe API chiamate che non coinvolgono l'autorizzazione degli utenti delegati.
Segreto client is il controparte confidenziale utilizzato solo nei flussi e nei tipi di app che possono sicuramente conservare segreti.
Un gran numero di integrazioni rotte iniziano quando qualcuno tratta questi come variazioni della stessa cosa. Non lo sono.
Dove l'ID del client Google si inserisce nella pratica
Se hai bisogno Accedi con Google o Un solo tocco, l'ID del client è il valore che il tuo frontend utilizza per avviare il negoziato di autenticazione. La documentazione di Google nota anche che l'app deve essere registrata in un progetto Cloud Console dedicato prima che il credenziale possa essere generato, e che le app web richiedono origine JavaScript autorizzata configurata o URIs di reindirizzamento con schema e hostname completi.
È per questo che la configurazione sembra più rigorosa della generazione di una semplice chiave. Google non sta solo abilitando l'accesso. Sta legando la richiesta di autenticazione a un'identità di app nota.
Per le squadre che stanno costruendo app ibride, il modello mentale più sicuro è questo:
- Utilizza l'ID del client per identificare l'app
- Utilizza lo schermo di consenso per rappresentare l'app all'utente
- Usa il tipo di app corretto per determinare se un segreto appartiene al flusso
Se desideri una panoramica più ampia su come l'identità dell'app e l'accesso delegato si integrano a vicenda, questa guida all'autorizzazione dell'app è un buon rinfrescamento.
Come creare e visualizzare il tuo ID client
La cartella del console è cambiata abbastanza da far pensare ai developer che si trovino nel posto sbagliato. Di solito non è così. Google esporre attualmente due percorsi di navigazione per questi credenziali: il nuovo Google Auth Platform > Clienti percorso e l'antico APIs & Services > Credenziali percorso, come descritto in la documentazione di configurazione di Google.
Avvia nell'area del console corretta
Apri il Google Cloud Console e seleziona o crea il progetto che gestirà la configurazione delle credenziali di autenticazione. Non disperdere le credenziali di autenticazione in progetti random. Ciò rende l'audit e il supporto dolorosi in seguito.
Dal lì, vai in uno dei seguenti luoghi:
- Piattaforma di autenticazione di Google > Client
- Credenziali > API e servizi
Se il tuo team vede etichette di navigazione diverse, ciò è previsto. Google ha separato la configurazione dell'identità dalla superficie delle credenziali di API.
Crea la credenziale senza limitarti
Quando si crea un nuovo client OAuth, la decisione più importante è il tipo di applicazione. Google ti chiede di scegliere un tipo specifico come ad esempio Web, Android, iOSo o Desktop. La scelta non è estetica. Definisce come l'app viene identificata e quali configurazioni di supporto sono richieste.
Per un'app web, si prevede di inserire:
- Origini JavaScript autorizzate
- URI di reindirizzamento autorizzati
Quei valori devono essere esatti. Per un credenziale web, Google aspetta il pieno schema e il nome host, ad esempio https://www.example.com, piuttosto che un concetto di dominio lassista.
Per piattaforme mobili, la forma è diversa. La registrazione Android richiede identità e verifica di proprietà a livello di pacchetto, mentre iOS utilizza i propri identificatori di piattaforma. Se si sta combinando l'autenticazione Google con un'altra layer di autenticazione, questo Capacitor setup di accesso sociale con Supabase è un esempio utile di come questi pezzi si adattano spesso l'uno all'altro.
This walkthrough is a decent visual reference if you want to compare the UI while you click through:
Dove trovarlo in seguito
Dopo la creazione, l'ID del client appare nella lista delle credenziali del progetto. Lo stesso spazio del progetto è anche dove le squadre abilitano le API e visualizzano come l'identità OAuth si connette alla schermata di consenso. Il nome dell'applicazione registrata è quello che gli utenti vedono durante la richiesta di autorizzazione, il che è una delle ragioni per cui nominare l'app con precisione è importante.
Google mantiene queste credenziali gestibili nel tempo. Puoi tornare alla dashboard per copiare l'ID del client, esaminare le impostazioni e, ove applicabile, gestire il segreto del client associato a quella credenziale.
La schermata di consenso non è solo decorativa. È parte del confine di fiducia. Gli utenti vedono il nome dell'applicazione lì, non il nickname del progetto interno.
Configurazioni degli ID del client specifiche per piattaforma
La via più veloce per rompere un setup di accesso Google è assumere che un ID del client possa coprire ogni piattaforma. Non può. Per le app multi-piattaforma, ogni piattaforma deve registrare il proprio ID del client OAuth 2.0 distinto, e la configurazione di Android richiede in particolare il fingerprint SHA1 per verificare la proprietà, come riportato in Questo riferimento di configurazione per piattaforma.
Perché un'app necessita di ID del client multipli
La tua prodotto può essere un'app per l'utente, ma è un client OAuth multipli per Google.
A app webe an costruzione di Androide an costruzione di iOSe un applicazione desktop non presentano le stesse proprietà di sicurezza. Non dimostrano l'identità nello stesso modo e non conservano tutti i credenziali in un ambiente affidabile. Google gestisce questo aspetto fornendo a ogni piattaforma il proprio modello di registrazione dell'applicazione.
Questa separazione è un buon igiene della sicurezza. Se la configurazione dei credenziali di una piattaforma è compromessa o configurata in modo errato, le altre non sono automaticamente esposte.
Ecco lo split pratico da seguire:
- Web utilizza un ID del client web e un matching di origine e URI di reindirizzamento rigoroso.
- Android utilizza un ID del client Android legato all'identità del pacchetto e alla firma SHA1.
- IOS utilizza un ID del client iOS legato all'identità del bundle dell'applicazione.
- Desktop o Electron spesso utilizza un modello OAuth di stile installato o desktop piuttosto che un flusso di browser basato su una chiave segreta.
Tipi di ID del client Google confrontati
| Tipo di applicazione | Identificatore principale | Fornisce segreto del client? | Caso d'uso principale |
|---|---|---|---|
| Web | Origini JavaScript autorizzate e URIs di reindirizzamento | Sì, di solito | Applicazioni del browser e OAuth assistite da backend |
| Android | Identità del pacchetto più impronta SHA1 | No, di solito | Accedi con Android nativo |
| iOS | Identità del bundle dell'app | No, di solito | Accedi con iPhone e iPad nativo |
| Desktop | Identità dell'app installata | Spesso no | Applicazioni desktop, comprese le flussi native di stile Electron |
Il paradosso del segreto del client per mobile e desktop
Questo è il punto in cui molti tutorial sbagliano.
I sviluppatori di mobile e desktop spesso aspettano che ogni client OAuth venga fornito con entrambi un ID del client e un segreto del client. Poi creano un credenziale di Applicazione Web perché è l'unico modo in cui possono vedere un segreto nella console. Il flusso sembra più completo, quindi continuano. In seguito, l'autenticazione si rompe in modi confusi.
Secondo questa spiegazione della disallineamento delle credenziali mobili, i tipi di applicazione non web, come Android, iOS e applicazioni installate, ricevono spesso un ID client ma nessun segreto client intenzionalmente, perché Google non vuole che un segreto confidenziale sia inserito nel software di client-side dove gli utenti possono estrarlo.
Quella scelta di progettazione è corretta. Un'app mobile o un pacchetto Electron non è un magazzino di segreti sicuro.
Ciò che funziona: Flussi OAuth nativi o client-side progettati per client pubblici.
Ciò che non funziona: La creazione di una credenziale web per un'app mobile solo per costringere un segreto nell'implementazione.
Per Capacitor team, questo si manifesta spesso in uno dei due cattivi pattern:
- L'app avvia un flusso basato su browser utilizzando un client web e poi cerca di comportarsi come un server confidenziale.
- L'app invia un segreto del client da code integrato, che sconfessa l'obiettivo di avere un segreto.
L'approccio migliore è trattare le app mobili e desktop come client pubblici. In OAuth moderno, ciò significa generalmente utilizzare un flusso che non dipende da un segreto nascosto all'interno del client. Se il tuo backend è coinvolto, mantieni le operazioni riservate sul backend e limita l'app nativa a ciò che un client pubblico dovrebbe fare.
Un altro punto sottile ha importanza per l'accesso Android Firebase. In quel setup, l'ID del tipo di applicazione web è utilizzato come ID del client OAuth del server backend, mentre l'app Android mantiene la propria identità specifica per piattaforma. Quel divario confonde le squadre perché vedono sia una credenziale web che una credenziale mobile nello stesso progetto e suppongono che una sostituisca l'altra. Non è così. Servono ruoli diversi. Se ricordi una regola, utilizza questa: scegli il tipo di client che corrisponde a dove si esegue __CAPGO_KEEP_0__, non la forma della credenziale che vorresti avere
Credenziali Google __CAPGO_KEEP_0__ Sicure choose the client type that matches where the code runs, not the credential shape you wish you had.
Securing Your Google API Credentials
from bundled __CAPGO_KEEP_0__, which defeats the point of having a secret.
La guida di Google per OAuth sottolinea che gli ID client e i segreti devono essere trattati come dati privati, e per gli app web l'ID client è impostato contro le URI di reindirizzamento pre-registrate. Se l'URI di reindirizzamento non corrisponde esattamente, Google rifiuta la richiesta. Quella vincolazione di origine fa parte della protezione contro l'intercettazione di token, come descritto in La guida di registrazione del client di OAuth.com.
Cosa bloccare immediatamente
Se fai solo poche cose al meglio, fai queste:
- Non spedire mai un segreto client in app code. I pacchetti web, i binari mobili e i pacchetti Electron sono ispezionabili dagli utenti.
- Registra URI di reindirizzamento esatte. Basta non è abbastanza. Google verifica match stretti per flussi web.
- Tieni le origini strette. Non autorizzare domini ampi solo per superare la frizione di configurazione.
- Separare le credenziali delle piattaforme. Don’t lasciare che la comodità spinga Android, iOS e web in un singolo credenziale.
Un dettaglio operativo è facile da perdere. Google consente alle squadre di generare nuovi segreti per un ID client esistente e disabilitare quelli vecchi. Ciò conta quando un segreto è stato esposto o quando si sta stringendo il proprio processo di distribuzione.
Ciò che fanno le squadre sicure
Gli sviluppatori che evitano problemi trattano i credenziali OAuth come ogni altro segreto di produzione.
Tengono i segreti dei client web sul backend, li iniettano attraverso la gestione dell'ambiente e controllano chi ha accesso alla console. Se si sta pulendo il proprio pipeline di rilascio, questa guida sul gestione dei segreti nei pipeline CI/CD è anche utile per la configurazione di autenticazione.
Rivisitano anche i metadati, non solo le chiavi. Lo schermo di consenso OAuth è legato all'identità del client che gli utenti vedono. Se il nome dell'applicazione è vago o ingannevole, gli utenti sono più propensi a non fidarsi della richiesta o a approvare l'applicazione sbagliata.
La sicurezza non riguarda solo il nascondimento di un segreto. Si tratta anche di assicurarsi che l'identità dell'app corretta, i target di reindirizzamento e lo schermo di approvazione si allineino ogni volta.
Risolvere gli errori comuni degli ID client
La maggior parte degli errori di autenticazione OAuth di Google deriva da un piccolo insieme di errori di configurazione. Il testo dell'errore non è sempre gentile, ma l'errore sottostante è solitamente chiaro una volta che si sa dove cercare.
Il fix che risolve la maggior parte degli errori
redirect_uri_mismatch
Il tuo app sta inviando un URI di reindirizzamento che non corrisponde esattamente a quanto registrato per quel client web. Controlla lo schema, l'host, la path e qualsiasi differenza finale. Per OAuth web, il matching esatto fa parte del modello di sicurezza.
invalid_client
Ciò significa spesso che l'app sta inviando il ID client sbagliato, il segreto sbagliato per quel client, o sta mescolando le credenziali tra piattaforme. Un esempio comune è un flusso Android o iOS che accidentalmente utilizza le credenziali web nel posto sbagliato.
invalid_request
Questo è ampio, ma nei casi di app cross-platform spesso indica parametri di autenticazione malformati o un flusso che non si adatta al tipo di client. Controlla se l'app sta cercando di includere un segreto dove non dovrebbe, o se il flusso OAuth selezionato aspetta un tipo di client diverso.
Google Sign-In funziona su web ma fallisce su mobile
La prima cosa da controllare è il tipo di client. La fonte più comune di errore per i developer di mobile è creare un ID client di applicazione web solo per ottenere un segreto client, quando dovrebbero utilizzare tipi Android o iOS che spesso omettono il segreto intenzionalmente, come spiegato in questa spiegazione del mismatch del segreto clientSe la tua implementazione include il lavoro di ciclo di vita dei token dopo l'accesso, quella guida di revoca è utile anche.
L'accesso Android fallisce dopo la creazione delle credenziali
Controlla nuovamente la fingerprint SHA1 attaccata al client Android. Se l'identità di firma non corrisponde a quanto Google aspetta, l'app non dimostrerà la proprietà correttamente.
La schermata di consenso sembra sbagliata
Verifica il nome dell'applicazione e la marca legata alla configurazione OAuth nel console. Gli utenti autorizzano ciò che vedono lì, quindi i metadati errati creano sia problemi di fiducia che rumore di supporto.
Ordine di debug pratico è semplice: controlla il tipo di client in primo luogo, poi le impostazioni di reindirizzamento, poi gli identificatori di piattaforma, poi se un segreto appartiene al flusso in generale.
Se il tuo team invia Capacitor o app Electron, i bug di autenticazione raramente restano isolati. Solitamente emergono insieme alla pressione di rilascio, alle esigenze di rollback e alle correzioni specifiche dell'ambiente. Capgo aiuta le squadre a inviare aggiornamenti mirati alle app code e agli asset senza dover aspettare la revisione della store, il che rende molto più facile correggere i flussi di accesso, la gestione dei callback e gli issue di autenticazione client-side quando finiscono in produzione.
