Przewodnik po koncepcji połączenia OAuth

Typ połączenia OAuth obsługuje 2 standardowe w branży przepływy OAuth 2.0: przepływy niejawny i kod autoryzacji. W przepływie kodu niejawnego Google otwiera punkt końcowy autoryzacji w przeglądarce użytkownika. Po zalogowaniu się zwracasz do Google długoterminowy token dostępu. Ten token dostępu jest dołączany do każdego żądania wysłanego z Asystenta do akcji.

Łączenie przez OAuth jest zalecanym rozwiązaniem do łączenia kont, jeśli:

• Masz już implementację serwera OAuth 2.0 i nie możesz rozszerzyć punktu końcowego tokena wymiany tokenów, aby dodać obsługę protokołów Google do automatycznego łączenia i tworzenia kont na podstawie tokena identyfikatora (np. dodaj parametry intent=get i intent=create w żądaniach do tego punktu końcowego).

Aby sprawdzić, czy połączenie przez OAuth jest dla Ciebie odpowiednim rozwiązaniem, przeczytaj artykuł Wybór typu połączenia konta.

Kluczowe terminy

Zanim przeczytasz, jak działa łączenie OAuth, zapoznaj się z tymi terminami:

• user.verificationStatus: usługa ustawiona przez system, która wskazuje, czy w bieżącej sesji ma zweryfikowanego użytkownika.

• user.accountLinkingStatus: właściwość ustawiona przez system, która wskazuje, czy użytkownik w bieżącej sesji ma połączoną tożsamość.

• Scena systemu łączenia kont: wstępnie zdefiniowana scena, która implementuje proces potwierdzania podczas łączenia kont i można ją dostosować do konkretnych przypadków użycia.

• Przepływ kodu autoryzacji: w ramach tego procesu OAuth 2.0 Google otwiera punkt końcowy autoryzacji w przeglądarce użytkownika. Jeśli logowanie się uda, usługa utworzy kod autoryzacji i zwróci go do Google. Google wysyła ten kod autoryzacji do punktu końcowego tokena wymiany tokenów, który weryfikuje autentyczność kodu i zwraca token dostępu oraz token odświeżania.

  Ten proces wymaga 2 punktów końcowych:

  • Punkt końcowy autoryzacji: punkt końcowy, który odpowiada za wyszukiwanie lub uzyskiwanie zgody użytkowników na dostęp do danych. Ten punkt końcowy wykonuje te działania:
    1. Wyświetla interfejs logowania użytkownikom, którzy nie są jeszcze zalogowani.
    2. Rejestruje zgodę na żądany dostęp w postaci krótkoterminowego kodu autoryzacji.
  • Punkt końcowy wymiany tokenów: ten punkt końcowy służy do uzyskiwania zaszyfrowanych ciągów znaków zwanych tokenami, które upoważniają użytkownika akcji do dostępu do Twojej usługi. Ten punkt końcowy odpowiada za 2 rodzaje wymian:
    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: podczas tego procesu OAuth 2.0 Google otwiera punkt końcowy autoryzacji w przeglądarce użytkownika. Jeśli logowanie się powiedzie, zwrócisz Google długoterminowy token dostępu. Ten token dostępu jest dołączany do każdego żądania wysyłanego z Asystenta do akcji. Ten proces wymaga tylko punktu końcowego autoryzacji.

• Token dostępu: token, który upoważnia usługę do uzyskiwania dostępu do części danych użytkownika. Tokeny dostępu są powiązane z poszczególnymi użytkownikami i powinny być niemożliwe do odgadnięcia.

• Token odświeżania: token jest wymieniany na nowy token dostępu po krótkotrwałym wygaśnięciu tokena dostępu.

Jak to działa

W tej sekcji opisano ogólny przepływ kodu autoryzacji OAuth i przepływów niejawnych. W sekcji Procesy łączenia przez OAuth opisujemy różne procesy, które mogą występować w przypadku protokołu OAuth.

Przepływ kodu autoryzacji można opisać w ten sposób:

1. Akcja pyta użytkownika, czy chce połączyć swoje konto z Twoją usługą.
2. Gdy użytkownik wyrazi zgodę na połączenie kont, Google otworzy punkt końcowy autoryzacji w przeglądarce użytkownika. Jeśli akcja rozpoczęła się na urządzeniu tylko głosowym, Google przekazuje wykonanie na telefon.
3. 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ł).
4. Usługa tworzy kod autoryzacji i zwraca go do Google, przekierowując przeglądarkę użytkownika z powrotem do Google z kodem autoryzacji dołączonym do żądania.
5. Google wysyła kod autoryzacji do punktu końcowego tokena wymiany tokenów, który weryfikuje autentyczność kodu oraz zwraca token dostępu i token odświeżania. Token dostępu jest krótkotrwałym tokenem, który Twoja usługa akceptuje jako dane uwierzytelniające, aby umożliwiać dostęp do interfejsów API. Token odświeżania jest długoterminowym tokenem, który Google może przechowywać i wykorzystywać do uzyskiwania nowych tokenów dostępu po ich wygaśnięciu.
6. Gdy użytkownik zakończy proces łączenia kont, każde kolejne żądanie wysłane z Asystenta do webhooka realizacji zawiera token dostępu.

Oto ogólny przepływ kodu:

1. Akcja pyta użytkownika, czy chce połączyć swoje konto z Twoją usługą.
2. Gdy użytkownik wyrazi zgodę na połączenie kont, Google otworzy punkt końcowy autoryzacji w przeglądarce użytkownika.
3. 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ł).
4. 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.
5. Gdy użytkownik zakończy proces łączenia kont, Google wywołuje interfejsy API Twojej usługi i dołącza do każdego żądania token dostępu. Usługa sprawdza, czy token dostępu przyznaje Google autoryzację dostępu do interfejsu API, a następnie wykonuje wywołanie interfejsu API.

Podstawowy przepływ kodu autoryzacji jest następujący:

1. Akcja pyta użytkownika, czy chce połączyć swoje konto z Twoją usługą.
2. Gdy użytkownik wyrazi zgodę na połączenie kont, Google otworzy punkt końcowy autoryzacji w przeglądarce użytkownika. Jeśli akcja rozpoczęła się na urządzeniu tylko głosowym, Google przekazuje wykonanie na telefon.
3. 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ł).
4. Usługa tworzy kod autoryzacji i zwraca go do Google, przekierowując przeglądarkę użytkownika z powrotem do Google z dołączonym do żądania kodem autoryzacji o krótkim czasie ważności.
5. Google wysyła kod autoryzacji do punktu końcowego tokena wymiany tokenów, który weryfikuje autentyczność kodu oraz zwraca token dostępu i token odświeżania. Token dostępu jest krótkotrwałym tokenem, który Twoja usługa akceptuje jako dane uwierzytelniające, aby umożliwiać dostęp do interfejsów API. Token odświeżania jest długoterminowym tokenem, który Google może przechowywać i wykorzystywać do uzyskiwania nowych tokenów dostępu po ich wygaśnięciu.
6. Gdy użytkownik zakończy proces łączenia kont, każde kolejne żądanie wysłane z Asystenta do webhooka realizacji zawiera token dostępu.

Procesy łączenia OAuth

W tej sekcji omawiamy różne procesy, które mogą wystąpić w przypadku łączenia kont OAuth.

Uwaga: w poniższych procesach przyjęto, że użytkownik zgadza się połączyć swoje konto z Twoją usługą i przyznawać Google uprawnienia dostępu do jego danych za pomocą Twojego interfejsu API. Jeśli użytkownik nie wyrazi zgody, zapewnij mu możliwość kontynuowania akcji z alternatywnym, ograniczonym procesem. Więcej informacji znajdziesz w artykule Sprawdzone metody.

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

Uwaga: wiersz od Webhooka do Użytkownika reprezentuje prostą odpowiedź, którą tworzysz i dostosowujesz. Linie rysowane od Asystenta do Użytkownika to prompty należące do Asystenta i mają ograniczone opcje dostosowywania (prośby, które wymagają uprawnień, zawsze należą do Asystenta). Z perspektywy użytkownika Asystent odpowiada na oba rodzaje odpowiedzi.

W ramach tej procedury przejdziesz do sceny systemu łączenia kont i podasz spersonalizowane uzasadnienie. Asystent pyta użytkownika, czy chce połączyć swoje konto z usługą, i wyświetla ekran z wymaganymi uprawnieniami. Gdy użytkownik wyrazi zgodę, Google przekierowuje go do punktu końcowego autoryzacji usługi w przeglądarce. Użytkownik loguje się (lub, w zależności od konfiguracji, tworzy nowe konto) i przyznaje Akcjom uprawnienia dostępu do swoich danych.

Przepływy po tym punkcie różnią się w zależności od tego, czy wdrożysz przepływ niejawny lub kod autoryzacji. W dalszej części znajdziesz opis tych procesów.

Proces 1. Użytkownik loguje się w sposób niejawny

Uwaga: ten diagram powstał na podstawie diagramu Typowe kroki opisanego powyżej.

Gdy użytkownik się zaloguje i zweryfikuje dane logowania, usługa tworzy długoterminowy token dostępu i zwraca go do Google. Na tym etapie tożsamość użytkownika w akcji jest połączona z kontem, na które się zalogował, a token dostępu jest dołączany do każdego wywołania interfejsu API używanego przez Google do interfejsów API Twojej usługi.

Proces 2. Użytkownik loguje się, korzystając z przepływu kodu autoryzacji

Uwaga: ten diagram powstał na podstawie diagramu Typowe kroki opisanego powyżej.

Gdy użytkownik się zaloguje i zweryfikuje dane logowania, usługa tworzy kod autoryzacji i zwraca go do Google.

Ten kod autoryzacji jest wysyłany do punktu końcowego tokena wymiany tokenów, który zwraca zarówno token dostępu, jak i token odświeżania. Tożsamość użytkownika w akcji jest na tym etapie powiązana z kontem, na które się zalogował. Każde kolejne żądanie wysłane z Asystenta do Twojej realizacji zawiera token dostępu.