Ujednolicone połączenie typu Logowanie przez Google oparte na protokole OAuth powoduje dodanie Logowania przez Google zamiast łączenia kont przez OAuth. Użytkownicy Google będą mogli bezproblemowo korzystać z połączeń głosowych, a jednocześnie umożliwić łączenie kont użytkownikom, którzy zarejestrowali się w Twojej usłudze przy użyciu tożsamości innej niż Google.
Ten typ połączenia zaczyna się od Logowania przez Google, który umożliwia sprawdzenie, czy informacje o profilu Google użytkownika istnieją w Twoim systemie. Jeśli dane użytkownika nie zostaną znalezione w systemie, rozpocznie się standardowy przepływ OAuth. Użytkownik może również utworzyć nowe konto z użyciem swoich informacji z profilu Google.
Aby przeprowadzić łączenie kont w ramach uproszczonych połączeń, wykonaj te ogólne czynności:
- Najpierw poproś użytkownika o zgodę na dostęp do jego profilu Google.
- Użyć informacji z profilu do zidentyfikowania użytkownika.
- Jeśli nie możesz znaleźć w swoim systemie uwierzytelniania pasującego do użytkownika Google, proces przebiega w zależności od tego, czy w Konsoli Actions skonfigurowano projekt Actions, aby umożliwiać tworzenie kont użytkowników za pomocą poleceń głosowych czy tylko w witrynie.
- Jeśli zezwalasz na tworzenie konta za pomocą głosu, zweryfikuj token identyfikatora otrzymany od Google. Następnie możesz utworzyć użytkownika na podstawie informacji o profilu zawartych w tokenie identyfikatora.
- Jeśli nie zezwolisz na tworzenie kont za pomocą głosu, użytkownik zostanie przeniesiony do przeglądarki, w której może wczytać stronę autoryzacji i dokończyć proces tworzenia konta.
Pomoc przy tworzeniu konta za pomocą głosu
Jeśli zezwolisz na tworzenie kont użytkowników za pomocą poleceń głosowych, Asystent zapyta użytkownika, czy chce:
- utworzyć nowe konto w systemie, korzystając z informacji o koncie Google użytkownika lub
- Jeśli użytkownik ma konto inne niż Google, zaloguj się do systemu uwierzytelniania, korzystając z innego konta.
Zezwolenie na tworzenie kont za pomocą poleceń głosowych jest zalecane, jeśli chcesz uprościć proces tworzenia konta. Użytkownik musi opuścić proces głosowy tylko wtedy, gdy chce zalogować się, korzystając z dotychczasowego konta innego niż konto Google.
Nie zezwalaj na tworzenie kont za pomocą głosu
Jeśli nie zezwolisz na tworzenie kont użytkowników za pomocą poleceń głosowych, Asystent otworzy adres URL witryny podanej przez Ciebie na potrzeby uwierzytelniania użytkownika. Jeśli interakcja odbywa się na urządzeniu bez ekranu, Asystent kieruje użytkownika do telefonu, na którym można kontynuować proces łączenia kont.
Niedozwolone jest tworzenie treści, jeśli:
nie chcesz zezwalać użytkownikom, którzy mają konta inne niż Google, na tworzenie nowych kont i łączenie ich z dotychczasowymi kontami w systemie uwierzytelniania. Jeśli na przykład oferujesz program lojalnościowy, warto upewnić się, że użytkownik nie straci punktów zgromadzonych na jego istniejącym koncie.
Musisz mieć pełną kontrolę nad procesem tworzenia konta. Możesz na przykład uniemożliwić tworzenie konta, jeśli musisz pokazać użytkownikowi warunki korzystania z usługi podczas tworzenia konta.
Implementowanie uproszczonego połączenia logowania przez Google opartego na protokole OAuth
Konta są połączone ze standardowymi procesami OAuth 2.0. Actions on Google obsługuje przepływy kodu niejawnego i autoryzacyjnego.
W pośrednim przepływie kodu Google otwiera punkt końcowy autoryzacji w przeglądarce użytkownika. Po udanym logowaniu zwracasz token dostępu o długim czasie do Google. Ten token dostępu jest teraz dołączany do każdego żądania wysyłanego przez Asystenta do działania.
W ramach procesu kodu autoryzacji potrzebujesz 2 punktów końcowych:
- Punkt końcowy autoryzacji, który odpowiada za wyświetlanie interfejsu logowania użytkownikom, którzy nie są jeszcze zalogowani, i rejestrowanie zgody w żądanym terminie w postaci kodu o ograniczonym czasie ważności.
- Punkt końcowy giełdy tokenów odpowiedzialny za 2 typy giełd:
- Wymienia kod autoryzacji tokena długoterminowego i tokena dostępu o ograniczonym czasie ważności. Ta wymiana ma miejsce, gdy użytkownik przechodzi przez proces łączenia kont.
- Wymienia długotrwały token odświeżania na token dostępu o ograniczonym czasie ważności. Ta giełda ma miejsce, gdy Google potrzebuje nowego tokena dostępu, ponieważ wygasł.
Implementacja niejawnego przepływu kodu jest prostsza, ale Google zaleca, aby tokeny dostępu wydane z wykorzystaniem niejawnego przepływu nigdy nie wygasały, ponieważ korzystanie z tożsamości w wyniku takiego działania wymusza na użytkowniku ponowne połączenie konta. Jeśli ze względów bezpieczeństwa zależy Ci na wygaśnięciu tokena, rozważ użycie kodu uwierzytelniania.
Konfigurowanie projektu
Aby skonfigurować w projekcie uproszczone łączenie, wykonaj te czynności:
- Otwórz Konsolę Actions i wybierz projekt, którego chcesz użyć.
- Kliknij kartę Programowanie i wybierz Łączenie kont.
- Kliknij przełącznik obok opcji Łączenie kont.
- W sekcji Tworzenie konta wybierz Tak.
W sekcji Typ połączenia wybierz Logowanie przez OAuth i Google oraz Pośredni.
W sekcji Informacje o kliencie wykonaj te czynności:
- Przypisz wartość do Identyfikatora klienta wydanego przez Actions to Google, aby identyfikować żądania pochodzące od Google.
- Wstaw adresy URL punktów końcowych autoryzacji i Token Exchange.
Kliknij Zapisz.
Wdrażanie serwera OAuth
Aby obsługiwać przepływ niejawny OAuth 2.0, Twoja usługa udostępnia punkt końcowy autoryzacji za pomocą protokołu HTTPS. Ten punkt końcowy odpowiada za uwierzytelnianie i uzyskiwanie od użytkowników zgody na dostęp do danych. Punkt końcowy autoryzacji wyświetla interfejs logowania użytkownikom, którzy nie są jeszcze zalogowani, i zapisuje zgodę na przyznanie dostępu.
Gdy akcja musi wywołać jeden z autoryzowanych interfejsów API Twojej usługi, Google używa tego punktu końcowego, aby uzyskać od użytkowników uprawnienia do wywoływania tych interfejsów API w ich imieniu.
Typowa sesja przepływu niejawnego OAuth 2.0 zainicjowana przez Google ma taki przepływ:
- Google otworzy punkt końcowy autoryzacji w przeglądarce użytkownika. Użytkownik loguje się, jeśli jeszcze nie jest zalogowany, i przyznaje Google uprawnienia dostępu do swoich danych za pomocą Twojego interfejsu API, jeśli jeszcze tego nie zrobił.
- Usługa tworzy token dostępu i zwraca go do Google, przekierowując przeglądarkę użytkownika z powrotem do Google z tokenem dostępu dołączonym do żądania.
- Google wywołuje interfejsy API Twojej usługi i do każdego żądania dołącza token dostępu. Twoja usługa sprawdza, czy token dostępu przyznaje Google autoryzację dostępu do interfejsu API, a następnie wykonuje wywołanie interfejsu API.
Obsługa żądań autoryzacji
Gdy akcja musi przeprowadzić łączenie kont z wykorzystaniem przepływu niejawnego OAuth 2.0, Google wysyła użytkownika do punktu końcowego autoryzacji z żądaniem zawierającym te parametry:
Parametry punktu końcowego autoryzacji | |
---|---|
client_id |
Identyfikator klienta przypisany przez Ciebie do Google. |
redirect_uri |
Adres URL, na który wysyłasz odpowiedź na to żądanie. |
state |
Wartość księgowa, która jest zwracana do Google bez zmian w identyfikatorze URI przekierowania. |
response_type |
Typ wartości do zwrócenia w odpowiedzi. W przypadku przepływu niejawnego OAuth 2.0 typ odpowiedzi to zawsze token . |
Jeśli na przykład punkt końcowy autoryzacji jest dostępny pod adresem https://myservice.example.com/auth
, żądanie może wyglądać tak:
GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token
Aby punkt końcowy autoryzacji obsługiwał żądania logowania, wykonaj te czynności:
Sprawdź wartości
client_id
iredirect_uri
, aby zapobiec przyznaniu dostępu do niezamierzonych lub błędnie skonfigurowanych aplikacji klienckich:- Sprawdź, czy
client_id
jest zgodny z identyfikatorem klienta przypisanym przez Ciebie do Google. - Sprawdź, czy adres URL określony przez parametr
redirect_uri
ma taki format:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
YOUR_PROJECT_ID to identyfikator znajdujący się na stronie Ustawienia projektu w Konsoli Actions.
- Sprawdź, czy
Sprawdź, czy użytkownik jest zalogowany w Twojej usłudze. Jeśli użytkownik nie jest zalogowany, dokończ proces logowania lub rejestracji w usłudze.
Wygeneruj token dostępu, którego Google będzie używać do uzyskiwania dostępu do Twojego interfejsu API. Token dostępu może być dowolną wartością ciągu znaków, ale musi w unikalny sposób reprezentować użytkownika oraz klienta, dla którego jest przeznaczony. Token nie może dać się odgadnąć.
Wyślij odpowiedź HTTP, która przekierowuje przeglądarkę użytkownika pod adres URL określony w parametrze
redirect_uri
. We fragmencie adresu URL uwzględnij wszystkie te parametry:access_token
: wygenerowany przed chwilą token dostępu;token_type
: ciąg znakówbearer
.state
: niezmodyfikowana wartość stanu z pierwotnego żądania. Oto przykład wynikowego adresu URL:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING
Moduł obsługi przekierowań OAuth 2.0 Google otrzyma token dostępu i sprawdzi, czy wartość state
się nie zmieniła. Gdy Google uzyska token dostępu do Twojej usługi, będzie dołączać go do kolejnych wywołań akcji w ramach żądania AppRequest.
Obsługa automatycznego łączenia
Gdy użytkownik wyrazi zgodę na dostęp przez akcję do jego profilu Google, Google wyśle żądanie zawierające podpisane potwierdzenie tożsamości użytkownika Google. Potwierdzenie zawiera informacje, które obejmują identyfikator konta Google użytkownika, imię i nazwisko oraz adres e-mail. Punkt końcowy giełdy tokenów skonfigurowany dla projektu obsługuje to żądanie.
Jeśli w Twoim systemie uwierzytelniania znajduje się już odpowiednie konto Google, punkt końcowy tokena Exchange zwraca token użytkownika. Jeśli konto Google nie pasuje do istniejącego użytkownika, punkt końcowy tokena wymiany tokenów zwraca błąd user_not_found
.
Prośba ma taką formę:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=get&assertion=JWT&consent_code=CONSENT_CODE&scope=SCOPES
Punkt końcowy tokena wymiany musi obsługiwać te parametry:
Parametry punktu końcowego tokena | |
---|---|
grant_type |
Typ wymienianego tokena. W przypadku tych żądań parametr ma wartość urn:ietf:params:oauth:grant-type:jwt-bearer . |
intent |
W przypadku tych żądań wartość tego parametru to „get”. |
assertion |
Token internetowy JSON (JWT) zawierający podpisane potwierdzenie tożsamości użytkownika Google. Token JWT zawiera informacje obejmujące identyfikator konta Google, imię i nazwisko oraz adres e-mail użytkownika. |
consent_code |
Opcjonalnie: jeśli występuje, jednorazowy kod wskazujący, że użytkownik wyraził zgodę na dostęp do określonych zakresów przez akcję. |
scope |
Opcjonalnie: wszelkie zakresy skonfigurowane przez Google, aby żądać od użytkowników. |
Gdy punkt końcowy wymiany tokenów otrzyma żądanie połączenia, powinien wykonać te czynności:
Weryfikowanie i dekodowanie potwierdzenia JWT
Możesz zweryfikować i zdekodować potwierdzenie JWT za pomocą biblioteki dekodowania JWT w swoim języku. Sprawdź podpis tokena za pomocą kluczy publicznych Google (dostępnych w formacie JWK lub PEM).
Po zdekodowaniu potwierdzenie JWT wygląda tak:
{ "sub": 1234567890, // The unique ID of the user's Google Account "iss": "https://accounts.google.com", // The assertion's issuer "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID "iat": 233366400, // Unix timestamp of the assertion's creation time "exp": 233370000, // Unix timestamp of the assertion's expiration time "name": "Jan Jansen", "given_name": "Jan", "family_name": "Jansen", "email": "jan@gmail.com", // If present, the user's email address "locale": "en_US" }
Oprócz weryfikacji podpisu tokena sprawdź, czy wydawca potwierdzenia (pole iss
) to https://accounts.google.com
, a grupa odbiorców (pole aud
) to identyfikator klienta przypisany do akcji.
Sprawdź, czy konto Google nie występuje już w Twoim systemie uwierzytelniania
Sprawdź, czy spełniony jest któryś z tych warunków:
- Identyfikator konta Google, który znajduje się w polu
sub
potwierdzenia, znajduje się w Twojej bazie danych użytkowników. - Adres e-mail w potwierdzeniu jest zgodny z adresem w bazie danych użytkowników.
Jeśli dowolny z tych warunków jest spełniony, użytkownik już się zarejestrował, więc możesz wystawić token dostępu.
Jeśli identyfikator konta Google ani adres e-mail określony w potwierdzeniu nie pasują do użytkownika w Twojej bazie danych, oznacza to, że jeszcze się nie zarejestrował. W tym przypadku punkt końcowy tokena wymiany tokenów powinien wysłać odpowiedź z komunikatem o błędzie HTTP 401, który określa error=user_not_found
, jak w tym przykładzie:
HTTP/1.1 401 Unauthorized Content-Type: application/json;charset=UTF-8 { "error":"user_not_found", }Gdy Google otrzyma odpowiedź o błędzie 401 z błędem
user_not_found
, wywołuje punkt końcowy wymiany tokenów z wartością parametru intent
ustawionego na create i wysyła w żądaniu token identyfikatora, który zawiera informacje o profilu użytkownika.
Obsługa tworzenia konta za pomocą Logowania przez Google
Gdy użytkownik musi utworzyć konto w Twojej usłudze, Google wysyła żądanie do punktu końcowego tokena wymiany tokenów, który określa intent=create
, jak w tym przykładzie:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded response_type=token&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope=SCOPES&intent=create&consent_code=CONSENT_CODE&assertion=JWT[&NEW_ACCOUNT_INFO]
Parametr assertion
zawiera token sieciowy JSON (JWT), który stanowi podpisane potwierdzenie tożsamości użytkownika Google. Token JWT zawiera informacje obejmujące identyfikator konta Google, imię i nazwisko oraz adres e-mail użytkownika, których możesz użyć do utworzenia nowego konta w swojej usłudze.
Aby odpowiadać na żądania utworzenia konta, punkt końcowy tokena wymiany musi wykonywać te czynności:
Weryfikowanie i dekodowanie potwierdzenia JWT
Możesz zweryfikować i zdekodować potwierdzenie JWT za pomocą biblioteki dekodowania JWT w swoim języku. Sprawdź podpis tokena za pomocą kluczy publicznych Google (dostępnych w formacie JWK lub PEM).
Po zdekodowaniu potwierdzenie JWT wygląda tak:
{ "sub": 1234567890, // The unique ID of the user's Google Account "iss": "https://accounts.google.com", // The assertion's issuer "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID "iat": 233366400, // Unix timestamp of the assertion's creation time "exp": 233370000, // Unix timestamp of the assertion's expiration time "name": "Jan Jansen", "given_name": "Jan", "family_name": "Jansen", "email": "jan@gmail.com", // If present, the user's email address "locale": "en_US" }
Oprócz weryfikacji podpisu tokena sprawdź, czy wydawca potwierdzenia (pole iss
) to https://accounts.google.com
, a grupa odbiorców (pole aud
) to identyfikator klienta przypisany do akcji.
Sprawdź poprawność informacji o użytkowniku i utwórz nowe konto
Sprawdź, czy spełniony jest któryś z tych warunków:
- Identyfikator konta Google, który znajduje się w polu
sub
potwierdzenia, znajduje się w Twojej bazie danych użytkowników. - Adres e-mail w potwierdzeniu jest zgodny z adresem w bazie danych użytkowników.
Jeśli którykolwiek z warunków jest spełniony, poproś użytkownika o połączenie istniejącego konta z kontem Google, odpowiadając na żądanie z komunikatem błędu HTTP 401, podając adres error=linking_error
i adres e-mail użytkownika jako login_hint
, jak w tym przykładzie:
HTTP/1.1 401 Unauthorized Content-Type: application/json;charset=UTF-8 { "error":"linking_error", "login_hint":"foo@bar.com" }
Jeśli żaden z tych warunków nie jest spełniony, utwórz nowe konto użytkownika na podstawie informacji podanych w tokenie JWT. Nowe konta zwykle nie mają ustawionego hasła. Zalecamy dodanie Logowania przez Google na innych platformach, aby umożliwić użytkownikom logowanie się przez Google w różnych miejscach w aplikacji. Możesz też wysłać użytkownikowi e-maila z linkiem rozpoczynającym proces odzyskiwania hasła, który umożliwi mu ustawienie hasła umożliwiającego logowanie się na innych platformach.
Po zakończeniu tworzenia wygeneruj token dostępu i zwróć wartości w obiekcie JSON w treści odpowiedzi HTTPS, jak w tym przykładzie:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
Zaprojektuj interfejs głosowy pod kątem przepływu uwierzytelniania
Sprawdź, czy użytkownik został zweryfikowany, i rozpocznij proces łączenia kont
- Otwórz projekt Actions Builder w Konsoli Actions.
- Utwórz nową scenę, aby rozpocząć łączenie kont w Akcji:
- Kliknij Sceny.
- Aby dodać nową scenę, kliknij ikonę dodaj (+).
- W nowo utworzonej scenie kliknij ikonę dodawania add w sekcji Warunki.
- Dodaj warunek, który będzie sprawdzał, czy użytkownik powiązany z rozmową jest użytkownikiem zweryfikowanym. Jeśli sprawdzanie się nie powiedzie, akcja nie będzie mogła łączyć kont w trakcie rozmowy i powinna przyznać dostęp do funkcji, które nie wymagają łączenia kont.
- W polu
Enter new expression
w sekcji Warunek wpisz tę funkcję:user.verificationStatus != "VERIFIED"
- W sekcji Przejście wybierz scenę, która nie wymaga łączenia kont, ani scenę, która stanowi punkt wejścia do funkcji tylko dla gości.
- W polu
- Kliknij ikonę dodawania add obok pozycji Warunki.
- Dodaj warunek aktywujący proces łączenia kont, jeśli użytkownik nie ma powiązanej tożsamości.
- W polu
Enter new expression
w sekcji Warunek wpisz tę funkcję:user.verificationStatus == "VERIFIED"
- W sekcji Przenoszenie wybierz scenę systemową Łączenie kont.
- Kliknij Zapisz.
- W polu
Po zapisaniu do projektu zostanie dodana nowa scena systemu łączenia kont o nazwie <SceneName>_AccountLinking
.
Dostosowywanie sceny łączenia kont
- W sekcji Sceny wybierz scenę systemową łączenia kont.
- Kliknij Wyślij prośbę i dodaj krótkie zdanie opisujące użytkownikowi, dlaczego akcja musi uzyskać dostęp do jego tożsamości (np. „Aby zapisać Twoje ustawienia”).
- Kliknij Zapisz.
- W sekcji Warunki kliknij Jeśli użytkownik ukończy łączenie kont.
- Skonfiguruj sposób postępowania, jeśli użytkownik zgodzi się na połączenie swojego konta. Możesz na przykład wywołać webhooka, aby przetworzyć dowolną niezbędną niestandardową logikę biznesową i przejść z powrotem do sceny źródłowej.
- Kliknij Zapisz.
- W sekcji Warunki kliknij Jeśli użytkownik anuluje lub odrzuci łączenie kont.
- Skonfiguruj sposób postępowania, jeśli użytkownik nie zgadza się na połączenie swojego konta. Możesz na przykład wysłać wiadomość z potwierdzeniem i przekierować użytkownika do scen, które udostępniają funkcje, które nie wymagają łączenia kont.
- Kliknij Zapisz.
- W sekcji Warunki kliknij W przypadku wystąpienia błędu systemu lub sieci.
- Skonfiguruj proces, jeśli nie można go ukończyć z powodu błędów systemu lub sieci. Możesz na przykład wysłać wiadomość z potwierdzeniem i przekierować użytkownika do scen, które udostępniają funkcje, które nie wymagają łączenia kont.
- Kliknij Zapisz.
Obsługiwanie próśb o dostęp do danych
Jeśli żądanie Asystenta zawiera token dostępu, najpierw sprawdź, czy token dostępu jest prawidłowy i nie wygasł, a potem pobierz z bazy danych konta użytkownika konto użytkownika powiązane z tokenem.