Przewodnik po koncepcji protokołu OAuth i logowania przez Google (Dialogflow)

Typ połączenia OAuth i Logowanie przez Google oprócz łączenia kont przez OAuth dodaje Logowanie przez Google. Jeśli używasz tego typu połączenia w akcji, proces rozpoczyna się od Logowania przez Google, który umożliwia sprawdzenie, czy informacje o profilu Google użytkownika istnieją w Twoim systemie. Jeśli tak się nie stanie, rozpocznie się standardowy przepływ OAuth. Dzięki połączeniu tych 2 rodzajów połączeń użytkownicy mogą powiązać swoją tożsamość w akcji z kontem Google lub innym niż Google. Mogą też utworzyć nowe konto z informacjami w profilu Google.

Protokół OAuth i Logowanie przez Google to zalecane rozwiązanie do łączenia kont w tych przypadkach:

• Masz akcję, która obejmuje wiele platform (np. jeśli działa z aplikacją na Androida).
• Masz system uwierzytelniania i chcesz zezwolić użytkownikom na łączenie ich tożsamości z kontami spoza Google. Stanie się tak na przykład wtedy, gdy oferujesz program lojalnościowy i chcesz mieć pewność, że użytkownik nie utraci punktów zgromadzonych na jego istniejącym koncie.

Aby sprawdzić, czy OAuth i Logowanie przez Google to dla Ciebie odpowiednie rozwiązanie, wejdź na stronę Wybór typu połączenia konta.

Kluczowe terminy

Zanim przeczytasz, jak działają OAuth i Logowanie przez Google, zapoznaj się z tymi terminami:

• Token tożsamości Google: podpisane potwierdzenie tożsamości użytkownika, które zawiera podstawowe informacje z jego profilu Google (imię i nazwisko, adres e-mail i zdjęcie profilowe). Token identyfikatora Google to token sieciowy JSON (JWT). Oto przykład zdekodowanego tokena:

{
  "sub": 1234567890,        // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The token's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Client ID assigned to your Actions project
  "iat": 233366400,         // Unix timestamp of the token's creation time
  "exp": 233370000,         // Unix timestamp of the token's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "[e-mail]", // If present, the user's email address
  "locale": "en_US"
}

• Intencja pomocnicza dotycząca logowania na konto: intencja pomocnicza, którą wywołujesz, aby poprosić Asystenta o połączenie kont. Więcej informacji znajdziesz w artykule Logowanie się na konto.
  • Ciąg kontekstowy: niestandardowy ciąg znaków dodawany do intencji pomocniczej logowania na konto, który informuje użytkownika, dlaczego chcesz połączyć swoje konto.
• Przepływ kodu autoryzacji: proces OAuth 2.0, który możesz wdrożyć za pomocą protokołu OAuth + Logowanie przez Google. Ten proces wymaga 2 punktów końcowych:
  • Punkt końcowy autoryzacji: punkt końcowy, który wyświetla interfejs logowania użytkownikom, którzy nie są jeszcze zalogowani. Rejestruje zgodę na przyznanie dostępu w formie krótkoterminowego kodu autoryzacji.
  • Punkt końcowy wymiany tokenów: ten punkt końcowy odpowiada za 2 typy giełd:
    1. Wymienia kod autoryzacji długoterminowym tokenem odświeżania i krótkotrwałym tokenem dostępu. Wymiana ta ma miejsce, gdy użytkownik przechodzi proces łączenia kont.
    2. Wymienia długotrwały token odświeżania na token dostępu krótkotrwały. Dzieje się tak, gdy Google potrzebuje nowego tokena dostępu z powodu tego, który wygasł.
• Przepływ kodu niejawnego: proces OAuth 2.0, który możesz wdrożyć za pomocą logowania OAuth i logowania Google. Ten proces wymaga tylko punktu końcowego autoryzacji. Podczas tego procesu Google otwiera punkt końcowy autoryzacji w przeglądarce użytkownika. Jeśli logowanie się uda, zwrócisz Google długoterminowy token dostępu. Ten token dostępu jest teraz uwzględniany w każdym żądaniu wysłanym przez Asystenta do akcji.
• Token dostępu: token, który upoważnia usługę do uzyskiwania dostępu do części danych użytkownika. Tokeny dostępu są przypisywane poszczególnym użytkownikom.
• Token odświeżania: token jest wymieniany na nowy token dostępu po krótkotrwałym wygaśnięciu tokena dostępu.

Wymagania wstępne

Aby używać typu połączenia OAuth i Logowanie przez Google, musisz mieć:

• serwer OAuth 2;

• Punkt końcowy wymiany tokenów

  Punkt końcowy wymiany tokenów musi być rozszerzony, aby mógł obsługiwać protokoły Google do automatycznego łączenia i tworzenia kont na podstawie tokena identyfikatora (np. dodawać parametry intent=get i intent=create w żądaniach do tego punktu końcowego).

Jak to działa

W tej sekcji opisujemy ogólny proces korzystania z protokołu OAuth i logowania przez Google. W następnej sekcji, poświęconej przepływom protokołu OAuth i GSI, opisaliśmy różne procesy, które mogą wystąpić w zależności od tego, czy włączysz czy wyłączysz tworzenie kont za pomocą poleceń głosowych, oraz b) korzystasz z przepływu kodu niejawnego czy kodu autoryzacji.

Proces ten wygląda tak:

1. Akcja prosi użytkownika o zgodę na dostęp do jego profilu Google.
2. Gdy użytkownik wyrazi zgodę, akcja otrzyma token identyfikatora Google, który zawiera informacje z profilu Google użytkownika.
3. Aby odczytywać zawartość profilu, musisz zweryfikować i zdekodować token.
4. Akcja używa tego tokena do sprawdzania, czy informacje o profilu Google użytkownika istnieją w Twoim systemie.
   1. Jeśli tak, użytkownik zalogował się już w Twoim systemie za pomocą swojego konta Google, a Asystent połączył jego tożsamość z kontem Google. Użytkownik może kontynuować rozmowę z Asystentem po połączeniu konta.
   2. Jeśli nie, przejdź do kroku 5.
5. Użytkownik może a) utworzyć nowe konto, używając swoich informacji z profilu Google, lub b) zalogować się w Twoim systemie za pomocą innego konta. Dostępne opcje zmieniają się w zależności od tego, czy włączysz, czy wyłączysz tworzenie kont za pomocą poleceń głosowych. Jeśli użytkownik postanowi zalogować się do systemu za pomocą innego konta, rozpocznie się standardowy proces OAuth.
6. Gdy użytkownik utworzy nowe konto lub zaloguje się u innego dostawcy, usługa zwróci token dostępu do Google. (Jeśli korzystasz z przepływu kodu autoryzacji, usługa zwraca też token odświeżania.
7. Użytkownik może teraz kontynuować rozmowę z Asystentem po połączeniu konta.

Przepływy OAuth i GSI

W tej sekcji omawiamy różne przepływy, które mogą występować w przypadku OAuth i GSI. Te diagramy dotyczą przepływów realizowanych za pomocą przepływu kodu autoryzacji, a nie tajnego przepływu kodu. Zakładamy, że używasz Dialogflow jako rozwiązania do rozumienia języka naturalnego na potrzeby akcji.

Uwaga: w poniższych procesach zakładamy, że użytkownik wyraził zgodę na dostęp do informacji z profilu Google przez akcję. Jeśli użytkownik nie wyrazi zgody, zapewnij mu możliwość kontynuowania akcji w ramach alternatywnego, ograniczonego procesu. Więcej informacji znajdziesz w artykule Sprawdzone metody.

Każdy proces zawiera te typowe kroki po wywołaniu akcji przez użytkownika:

W ramach tego procesu wywołujesz intencję pomocniczą actions.intent.SIGN_IN za pomocą dostosowanego ciągu znaków kontekstu. W ten sposób użytkownik prosi o zgodę na dostęp do informacji z jego profilu Google. Gdy użytkownik wyrazi zgodę, Asystent wyśle żądanie zawierające informacje z profilu użytkownika [e-mail].

Procedura po tym punkcie różni się w zależności od tego, czy skonfigurujesz łączenie kont za pomocą głosu i czy informacje o użytkowniku znajdują się już w Twoim systemie. Wszystkie te procesy opisaliśmy w kolejnych sekcjach.

Procesy z włączonym tworzeniem konta głosowego

W tej sekcji znajdziesz szczegółowe informacje o procesach łączenia kont, które mogą wystąpić, jeśli włączysz opcję tworzenia kont za pomocą poleceń głosowych.

Uwaga: poniższe diagramy bazują na schemacie Typowe kroki powyżej.

Proces 1. W systemie istnieją informacje o użytkowniku

Uwaga: wiersz od webhooka do Użytkownika reprezentuje prostą odpowiedź, którą możesz utworzyć i dostosować. Linie rysowane od Asystenta do Użytkownika to prompty, które są własnością Asystenta i mają ograniczone opcje dostosowywania (prośby, które wymagają uprawnień, należą zawsze do Asystenta). Z perspektywy użytkownika Asystent odpowiada na oba rodzaje odpowiedzi.

W tym przypadku użytkownik reprezentowany przez [e-mail] istnieje w backendzie, więc punkt końcowy tokena wymiany tokenów zwraca token użytkownika. Tożsamość użytkownika w akcji jest teraz połączona z jego kontem Google. Pierwotne żądanie użytkownika („Zamów moje zwykłe”) pasuje do intencji niestandardowej. order_drink. webhook obsługuje realizację dopasowanych intencji i wysyła zapytania do bazy danych w zwykły sposób, jak w przypadku elementu [e-mail]. Użytkownik może kontynuować rozmowę z Asystentem.

Proces 2. Dane użytkownika nie istnieją, a użytkownik tworzy konto

Ponieważ masz włączone głosowe tworzenie kont, a klasa [e-mail] nie istnieje w Twoim backendzie, Asystent pyta użytkownika, czy chce wykonać jedną z tych czynności:

a) Utworzenie nowego konta w systemie przy użyciu informacji z profilu Google użytkownika, które zostanie wykonane za pomocą głosu.

b) Zaloguj się do systemu za pomocą innego konta

Uwaga: możesz też zezwolić użytkownikowi na utworzenie nowego konta u innego dostawcy. Są to dostawcy wskazani na stronie autoryzacji.

W tym przypadku użytkownik tworzy nowe konto, używając poleceń głosowych. Google wywołuje punkt końcowy wymiany tokenów Twojej usługi, przesyłając żądanie utworzenia konta. To żądanie zawiera token identyfikatora Google, który zawiera komponenty potrzebne do utworzenia nowego konta. Następnie możesz użyć informacji z tego tokena (nazwy i adresu e-mail użytkownika), aby utworzyć dla niego konto.

Po utworzeniu konta usługa zwraca dla nowo utworzonego konta token dostępu i token odświeżania. Tożsamość użytkownika w akcji jest teraz połączona z jego kontem Google. Pierwotne żądanie użytkownika („Zamów moje zwykłe”) jest zgodne z niestandardową intencją order_drink.. Webhook obsługuje wówczas realizację dopasowanej intencji i wysyła zapytanie do bazy danych w odpowiedzi na standardowe zamówienie ([e-mail]), które jeszcze nie istnieje, ponieważ użytkownik jest nowy. Akcja może wtedy zapytać użytkownika, co chce zamówić.

Uwaga: 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.

Proces 3. Informacje o użytkowniku nie istnieją, a użytkownik loguje się na inne konto

Masz włączone głosowe tworzenie kont, więc Asystent pyta użytkownika, czy chce wykonać jedną z tych czynności:

a) Utworzenie nowego konta w systemie przy użyciu informacji z profilu Google użytkownika, które zostanie wykonane za pomocą głosu.

b) Zaloguj się do systemu za pomocą innego konta

Uwaga: możesz też zezwolić użytkownikowi na utworzenie nowego konta u innego dostawcy. Są to ci dostawcy, których udostępniasz na stronie autoryzacji.

W tym przypadku użytkownik loguje się za pomocą innego konta, co uruchamia standardowy przepływ OAuth. Jeśli proces rozpoczął się na urządzeniu tylko głosowym, Google przenosi wykonanie na telefon. Google otworzy Twój punkt końcowy autoryzacji w przeglądarce użytkownika i w zależności od konfiguracji użytkownik może: a) zalogować się w Twojej usłudze przy użyciu istniejącego konta, które nie korzysta z Logowania przez Google, lub b) utworzyć nowe konto, korzystając z innego dostawcy. Więcej informacji o procesie OAuth znajdziesz w poradniku dotyczącym protokołu OAuth.

Po zweryfikowaniu danych logowania użytkownika usługa zwraca do Google token dostępu i token odświeżania. Tożsamość użytkownika w akcji jest teraz połączona z kontem innym niż Google. Pierwotne żądanie użytkownika („Zamów moje zwykłe”) pasuje do intencji niestandardowej order_drink.. Webhook obsługuje wówczas realizację dopasowanej intencji i wysyła zapytania do bazy danych w standardowej kolejności, w której odpowiada kolejności [e-mail], która jeszcze nie istnieje, ponieważ użytkownik jest nowy. Akcja może zapytać użytkownika, co chce zamówić, lub poprosić go o ustawienie zwykłego zamówienia.

Proces z wyłączonym tworzeniem konta głosowego

W tej sekcji znajdziesz szczegółowe informacje o procesie łączenia kont, który może wystąpić, gdy wyłączysz tworzenie konta za pomocą głosu.

Uwaga: poniższe diagramy bazują na schemacie Typowe kroki powyżej.

Proces 4. Informacje o użytkowniku nie istnieją

Nie włączono głosowego tworzenia kont, a użytkownika nie ma w backendzie, więc rozpocznie się standardowy proces OAuth. Asystent otworzy punkt końcowy autoryzacji w przeglądarce użytkownika (jeśli proces rozpoczął się na urządzeniu tylko głosowym, Google przenosi wykonanie na urządzenie z wyświetlonym ekranem). Użytkownik może a) zalogować się u innego dostawcy, jeśli zarejestrował się w usłudze za pomocą innego konta, lub b) utworzyć nowe konto u innego dostawcy. Więcej informacji na temat procesu OAuth znajdziesz w poradniku dotyczącym protokołu OAuth.

Po zweryfikowaniu danych logowania użytkownika usługa zwraca do Google token dostępu i token odświeżania. Tożsamość użytkownika w akcji jest teraz połączona z kontem innym niż Google. Pierwotne żądanie użytkownika („Zamów moje zwykłe”) pasuje do intencji niestandardowej order_drink.. Webhook obsługuje wówczas realizację dopasowanej intencji i wysyła zapytania do bazy danych w standardowej kolejności, w której odpowiada kolejności [e-mail], która jeszcze nie istnieje, ponieważ użytkownik jest nowy. Akcja może poprosić użytkownika o ustalenie kolejności, w jakiej zwykle jest.