Flusso utente per l'autenticazione

Panoramica

Lo scopo del flusso di autenticazione è identificare e autenticare l'utente presso l'integratore dei pagamenti (integratore).

L'autenticazione è un input per altri metodi. In particolare per associateAccount e capture. Ciò significa che la prova di autenticazione viene utilizzata come input (parametro) per questi due metodi.

Per verificare un utente, Google può anche utilizzare il flusso di autenticazione in modalità autonoma. In questo caso, non viene utilizzato come input per un altro flusso, ma solo per verificare che un utente sia in grado di autenticare questa identità.

Tieni presente che durante l'onboarding, Google collaborerà con te per scegliere il meccanismo di autenticazione più adatto al tuo prodotto.

Come funziona il flusso

Esistono due modi per autenticare un utente, ciascuno con un proprio flusso. Al momento dell'integrazione, l'integratore deve determinare quale utilizzare.

  1. Autenticazione reindirizzamento
  2. Autenticazione OTP SMS-MT

Autenticazione reindirizzamento

Un utente Google che richiede l'autenticazione può essere reindirizzato all'app o al sito web dell'integratore per la verifica dell'identità. Ecco una breve panoramica dei passaggi di questa procedura:

  1. Google reindirizza l'utente all'app web o Android dell'integratore dove può essere autenticato.
  2. Per l'autenticazione, come prova dell'autenticazione viene utilizzata l'autenticazione requestId (da AuthenticationRequest).
  3. Questo genera una risposta firmata, chiamata AuthenticationResponse.
  4. Dopodiché, l'app o il sito web reindirizzano l'utente a Google.

L'autenticazione del reindirizzamento utilizza un metodo GET HTTP, con parametri codificati nell'URL di un'applicazione web. Utilizza un intent Android per l'autenticazione di un'applicazione Android. Per ulteriori dettagli sulla codifica, consulta Autenticazione web e, per i parametri intent di Android, consulta Autenticazione Android.

Il risultato di ciascuno di questi meccanismi di autenticazione è una risposta firmata denominata AuthenticationResponse. Questo intent deve includere la risposta criptata e codificata dell'autenticazione pagamenti standard di Google (gspAuthenticationResponse) per comunicare un'autenticazione riuscita. Se utilizzata in modalità autonoma, gspResult e la firma vengono usati per determinare l'autenticazione riuscita.

Il seguente diagramma di sequenza mostra l'interazione tra il browser dell'utente, Google e l'applicazione web dell'integratore:

Flusso di autenticazione web di reindirizzamento

Flusso di autenticazione web

Ecco un elenco degli oggetti e di ciò che rappresentano:

  • Utente: si tratta della persona che vuole aggiungere un metodo di pagamento al proprio Account Google.
  • UI di Google: in questo caso, l'interfaccia web di Google, dove il cliente inizia a configurare un metodo di pagamento.
  • Server Google: il server di backend di Google che esegue il controllo dell'autenticazione, insieme ad altre attività di autenticazione.
  • Web integratore di pagamenti: il sito web dell'integratore in cui l'utente ha un account.

Per questo flusso di autenticazione, supponiamo già che l'utente si trovi sul sito web di Google (UI di Google) e stia cercando di aggiungere un metodo di pagamento. Da qui inizia tutto.

  1. L'interfaccia utente di Google crea un URL di autenticazione che viene inviato al server di Google (backend). È questo che attiva il processo di autenticazione.
  2. Il server di Google crea una richiesta di autenticazione (AuthenticationRequest).
  3. La richiesta di autenticazione inviata all'interfaccia utente di Google.
  4. L'utente riceve la richiesta di autenticazione del proprio ID con l'integratore.
  5. L'utente risponde di voler eseguire l'autenticazione, il che invia il messaggio al sito web dell'integratore.
  6. Il sito web dell'integratore dei pagamenti richiede la verifica dell'identità dell'utente.
  7. L'utente fornisce una prova della propria identità, che viene inviata al sito web dell'integratore dei pagamenti.
  8. L'integratore crea una risposta (authenticationResponse) alle prove fornite (con il codice authenticationResponse codificato nel messaggio).
  9. Questo URL di risposta viene inviato all'utente.
  10. L'URL della risposta viene inviato immediatamente dall'utente alla UI di Google.
  11. La UI di Google invia la risposta al server di Google.
  12. Il server di Google interpreta la risposta come verificata.

Il prossimo diagramma di sequenza mostra l'interazione tra lo smartphone dell'utente, Google e l'applicazione Android dell'integratore:

Flusso di autenticazione delle app per Android di reindirizzamento

Flusso di autenticazione delle app per Android

Ecco gli oggetti e ciò che rappresentano:

  • Utente: si tratta della persona che vuole aggiungere un metodo di pagamento al proprio Account Google.
  • UI di Google: in questo caso, l'interfaccia dell'app, in cui il cliente inizia a configurare un metodo di pagamento.
  • Server Google: il server di backend di Google che esegue il controllo dell'autenticazione, insieme ad altre attività di autenticazione.
  • APK dell'integratore dei pagamenti: l'app dell'integratore in cui l'utente ha accesso al proprio account di integratore.
  • Server integratore dei pagamenti: il server di backend dell'integratore in cui vengono archiviate le informazioni dell'utente.

Poiché si tratta di un flusso di autenticazione, supponiamo già che l'utente stia utilizzando un'app (UI di Google) e stia cercando di aggiungere un metodo di pagamento. È qui che inizia l'inizializzazione.

  1. La UI di Google crea una chiamata di autenticazione che viene inviata al server di Google (backend).
  2. Il server di Google crea una richiesta di autenticazione (AuthenticationRequest).
  3. Il server di Google invia un APK di chiamata all'interfaccia utente Google (app) per richiedere l'autenticazione.
  4. La UI di Google invia le informazioni dell'utente all'APK dell'integratore dei pagamenti (AUTHENTICATE_V1(authReq)).
  5. L'APK dell'integratore dei pagamenti invia la richiesta (authReq) al server dell'integratore dei pagamenti.
  6. Il server dell'integrazione dei pagamenti invia una richiesta di verifica all'APK dell'integratore dei pagamenti.
  7. L'APK dell'integratore dei pagamenti invia la verifica all'utente.
  8. L'utente fornisce una prova della propria identità, che viene inviata all'APK dell'integratore dei pagamenti.
  9. che viene quindi inviata al server di integrazione dei pagamenti.
  10. Il server crea una authenticationResponse firmata.
  11. La risposta di autenticazione ha esito positivo e viene inviato un messaggio authResp all'APK dell'integratore dei pagamenti.
  12. Il messaggio di operazione riuscita (authResp) viene inviato dall'APK dell'integratore dei pagamenti alla UI di Google.
  13. La UI di Google invia la risposta al server di Google.
  14. Il server di Google interpreta la risposta corretta.

Autenticazione OTP SMS-MT

Un altro metodo di autenticazione è: Short Message Service, Mobile Terminated, One-Time Password (SMS-MT OTP). Questo meccanismo utilizza il numero di telefono dell'utente per inviare una password monouso per l'autenticazione. Google chiede all'integratore di inviare una OTP al numero di telefono dell'utente e, dopo che un utente lo riceve e lo inserisce nell'interfaccia di Google, l'utente viene verificato.

A tale scopo, procedi nel seguente modo:

  1. L'interfaccia utente (UI) di Google richiede all'utente di inserire il numero di telefono, che è già registrato presso l'integratore.
  2. L'utente inserisce un numero di telefono nella UI di Google.
  3. Google attiva l'integratore (chiama il metodo sendOtp) per inviare una password monouso (OTP) all'utente.
  4. L'utente riceve l'SMS con l'OTP.
  5. L'utente inserisce quindi l'OTP (utilizzata come input per capture, associateAccount e verifyOtp) che ha ricevuto nell'interfaccia di Google, autenticando l'utente. Questa è una prova di autenticazione.

In modalità autonoma, per verificare il valore OTP verrà chiamato solo il metodo verifyOtp.

Il seguente diagramma di sequenza mostra l'interazione tra il telefono dell'utente, Google e l'integratore durante l'invio di una OTP:

Flusso di autenticazione telefonica (invio OTP)

Flusso di autenticazione telefonica (OTP)

Ecco un elenco degli oggetti nel diagramma e di ciò che rappresentano:

  • Utente: si tratta della persona che vuole aggiungere un metodo di pagamento al proprio Account Google.
  • UI di Google: in questo caso, un sito web o un'app per telefono Google in cui il cliente inizia a configurare un metodo di pagamento. Nota: se la UI di Google è un'app per telefoni, i primi due passaggi verranno ignorati perché il telefono conosce già il numero di telefono dell'utente.
  • Server Google: il server di backend di Google che esegue il controllo dell'autenticazione, insieme ad altre attività di autenticazione.
  • Server integratore dei pagamenti: il server di backend dell'integratore in cui vengono archiviate le informazioni dell'utente.

Poiché si tratta di un flusso di autenticazione OTP, supponiamo già che l'utente stia utilizzando un'app telefonica o un sito web di Google (UI Google) e stia cercando di aggiungere un metodo di pagamento. È qui che inizia l'inizializzazione.

  1. L'interfaccia utente di Google (telefono o sito web) richiede all'utente il numero di telefono.
  2. L'utente inserisce il proprio numero di telefono nell'interfaccia utente di Google.
  3. La UI di Google invia il numero (sendChallenge(phoneNum)) al server di Google.
  4. Il server di Google invia una richiesta al server dell'integrazione dei pagamenti (SendOtp(phoneNum)) per inviare una password monouso.
  5. Il server di integrazione dei pagamenti invia una password monouso (OTP) all'utente.
  6. Il server di integrazione dei pagamenti risponde alla richiesta di Google nel punto 5, segnalando che l'OTP è stata inviata correttamente.
  7. L'utente inserisce questa OTP nell'interfaccia utente di Google (telefono o sito web).
  8. La UI di Google invia l'OTP al server di Google, dove viene poi inviata all'integratore dei pagamenti per la verifica. Questa operazione consente di verificare l'identità dell'utente e di autenticarlo.

Autenticazione e riautenticazione

L'autenticazione può avvenire in due momenti:

  1. Autenticazione iniziale: utilizzata per identificare e autenticare un utente. L'autenticazione iniziale viene utilizzata come input per il metodo associateAccount.
  2. Riautenticazione: utilizzata in tutti gli altri contesti, ad esempio in modo autonomo o come input in capture.

La riautenticazione è diversa dall'autenticazione iniziale. Non vuole mai reidentificare un utente, semplicemente autenticarsi di nuovo. La riautenticazione viene utilizzata da Google per richiedere all'utente di dimostrare di essere il proprietario di un determinato account e questo avviene a discrezione di Google.

In questo processo, viene fornito un riferimento, chiamato associationId, all'associazione originale (dal flusso di associazione). Questo viene fornito tramite la chiamata al metodo associateAccount durante il flusso di associazione. Il associationId identifica l'account da cui contestare. Per motivi di sicurezza, l'utente non deve essere in grado di modificare l'account oggetto della richiesta.

Per la riautenticazione OTP tramite SMS-MT, Google conserva come numero fisso il numero di telefono fornito durante la chiamata originale al numero sendOtp. Questa impostazione non può essere modificata, sempre per motivi di sicurezza.

Di seguito è riportato un flusso di esempio in cui Google decide di eseguire una verifica (nuova autenticazione) prima di effettuare un acquisto:

Flusso di riautenticazione

Flusso di riautenticazione

Di seguito è riportato l'elenco degli oggetti e di ciò che rappresentano:

  • Utente: si tratta della persona che vuole effettuare un acquisto.
  • UI di Google: in questo caso, un sito web o un'app per telefoni di Google in cui il cliente inizia a effettuare l'acquisto.
  • UI di integratore dei pagamenti: l'app o il sito web rivolto al cliente in cui l'utente può accedere ai dati del proprio account con l'integratore.
  • Server di Google: il server di backend di Google che effettua il controllo di riautenticazione, insieme ad altre attività.
  • Server integratore dei pagamenti: il server di backend dell'integratore in cui vengono archiviate le informazioni dell'utente.

Il flusso di riautenticazione inizia quando un cliente inizia a effettuare un acquisto. Questo inizializza un flusso per riautenticare l'utente.

  1. L'utente decide di acquistare un articolo o un servizio.
  2. La richiesta viene inviata dall'interfaccia utente di Google al server di Google.
  3. Il server di Google invia una richiesta di autenticazione (authenticationRequest) alla UI di Google.
  4. La UI di Google invia una richiesta alla UI dell'integratore dei pagamenti per autenticare (associationId, authenticationRequest) l'utente.
  5. La UI dell'integratore dei pagamenti cerca l'utente per verificare la sua identità (LookupIdentity(associationId)).
  6. La UI dell'integratore dei pagamenti richiede all'utente le credenziali nella UI (sito web o app dell'integratore).
  7. La risposta di autenticazione viene inviata al server di integrazione dei pagamenti.
  8. La risposta dell'autenticazione firmata (authenticationResponse) viene inviata all'UI di integratore dei pagamenti.
  9. La risposta di autenticazione (authenticationResponse) viene inviata dall'UI di integratore dei pagamenti alla UI di Google.
  10. L'interfaccia utente di Google invia la risposta con le informazioni sull'acquisto al server di Google.
  11. Il server di Google invia un messaggio capture (per trovare i fondi disponibili) al server di integrazione dei pagamenti (authenticationRequestId, GPT, importo).
  12. Il server di integrazione dei pagamenti invia un messaggio di esito positivo al server di Google.
  13. Il server di Google invia un messaggio di esito positivo all'interfaccia utente di Google.
  14. L'interfaccia utente di Google consegna gli articoli al cliente (o avvisa che saranno consegnati a breve).

Autenticazione SMS-MO

Short Message Service, il flusso di autenticazione generato da dispositivi mobili utilizza un SMS contenente un ID richiesta di autenticazione inviato dal telefono dell'utente all'integratore dei pagamenti per autenticare l'utente.

Flusso di autenticazione SMS-MO

Ecco un elenco degli oggetti nel diagramma e di ciò che rappresentano:

  • Utente: si tratta della persona che vuole aggiungere un metodo di pagamento al proprio Account Google.
  • Dispositivo/UI di Google: in questo caso, un'app per telefoni Google in cui il cliente inizia a configurare un metodo di pagamento.
  • Server di Google: il server di backend di Google che genera le istruzioni SMS con un ID richiesta di autenticazione (ARID) e riceve il risultato dell'autenticazione dall'integratore.
  • Server integratore dei pagamenti: il server di backend dell'integratore che riceve l'SMS di autenticazione e restituisce l'ID richiesta di autenticazione a Google.

Poiché si tratta di un flusso di autenticazione, supponiamo già che l'utente stia utilizzando un'app (UI di Google) e stia cercando di aggiungere un metodo di pagamento. È qui che inizia l'inizializzazione.

  1. L'utente seleziona uno strumento tokenizzato da aggiungere.
  2. La UI di Google chiama il server di Google per avviare la sfida SMS-MO.
  3. Il server di Google restituisce le istruzioni SMS, composte da una destinazione e un corpo contenente l'ID richiesta di autenticazione.
  4. L'interfaccia utente di Google invia l'SMS all'integratore dei pagamenti.
  5. Il server di integrazione dei pagamenti chiama l'endpoint di AuthenticationResultNotification sul server Google con l'ID della richiesta di autenticazione.
  6. L'ID richiesta di autenticazione viene convalidato dal server di Google, che risponde con SUCCESS.
  7. La UI di Google chiama il server di Google per ottenere il risultato del tentativo di autenticazione.
  8. La risposta di Google Server SUCCESS.

Autenticazione SMS-MO simulata

Per eseguire i test diagnostici del flusso di autenticazione SMS-MO, Google definisce un endpoint Simulate SMS (Simula SMS). Questo elimina la necessità di inviare e convalidare un SMS reale durante l'esecuzione di associazioni di test nell'ambiente sandbox.

Flusso di autenticazione SMS-MO simulato

Ecco un elenco degli oggetti nel diagramma e di ciò che rappresentano:

  • Tester: è la persona che avvia un test diagnostico dell'associazione SMS-MO.
  • UI di Google: una UI di Google in cui il tester inizia e monitora lo stato del test diagnostico SMS-MO.
  • Server di Google: il server di backend di Google che genera le istruzioni SMS con un ID richiesta di autenticazione (ARID), invia l'SMS simulato e riceve il risultato dell'autenticazione dall'integratore.
  • Server integratore dei pagamenti: il server di backend dell'integratore che riceve l'SMS di autenticazione simulato e restituisce l'ID richiesta di autenticazione a Google.

I passaggi di questa procedura sono:

  1. Il tester inizia il test diagnostico SMS-MO fornendo un ID abbonato (SID) di prova da utilizzare per il test. Questo SID verrà incluso nella chiamata di simulateSms all'integratore dei pagamenti.
  2. La UI di Google chiama il server di Google per avviare la sfida SMS-MO.
  3. Il server di Google restituisce le istruzioni SMS, composte da una destinazione e un corpo contenente l'ID richiesta di autenticazione. Ai fini di questo test, la destinazione verrà sostituita dalla connessione HTTPS della sandbox dell'integratore dei pagamenti.
  4. L'interfaccia utente di Google chiama il server di Google per inviare l'SMS simulato.
  5. La chiamata simulateSms viene effettuata dal server Google al server di integrazione dei pagamenti. Sia l'ID richiesta di autenticazione sia l'ID abbonato (come indicato nel passaggio 1) sono inclusi nella chiamata API.
  6. Il server di integrazione dei pagamenti risponde con ACKNOWLEDGED.
  7. Il server di Google risponde con SUCCESSO alla UI di Google.
  8. Il server di integrazione dei pagamenti chiama l'endpoint di AuthenticationResultNotification sul server Google con l'ID della richiesta di autenticazione.
  9. Il server di Google risponde con SUCCESSO.
  10. La UI di Google chiama il server di Google per ottenere il risultato del tentativo di autenticazione.
  11. Il server di Google risponde COMPLETATO.
  12. La UI di Google chiama il server di Google perché esegua un tentativo di associazione.
  13. La chiamata associateAccount viene effettuata dal server Google al server di integrazione dei pagamenti.
  14. Il server di integrazione dei pagamenti risponde con SUCCESSO.
  15. Il server di Google risponde con SUCCESSO.
  16. La UI di Google viene aggiornata per indicare al tester che il test diagnostico SMS-MO è stato completato correttamente.

Best practice e altre considerazioni

Scelta di piattaforme

Fornire un flusso di autenticazione web per app mobile e desktop consentirà all'integratore di raggiungere la maggior parte degli utenti. Google consiglia vivamente agli integratori di supportare l'applicazione Android, in quanto fornisce la migliore esperienza utente e, di conseguenza, il tasso di conversione più elevato. I parametri trasmessi nelle API di autenticazione per il web e per le app per Android sono gli stessi.