Łączenie kont za pomocą protokołu OAuth

Typ połączenia OAuth obsługuje 2 standardowe przepływy kodu OAuth 2.0: przepływy niejawne i przepływy kodu autoryzacyjne.

In the implicit code flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from the Assistant to your Action.

In the authorization code flow, you need two endpoints:

• The authorization endpoint, which is responsible for presenting the sign-in UI to your users that aren't already signed in and recording consent to the requested access in the form of a short-lived authorization code.
• The token exchange endpoint, which is responsible for two types of exchanges:
  1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
  2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Although the implicit code flow is simpler to implement, Google recommends that access tokens issued using the implicit flow never expire, because using token expiration with the implicit flow forces the user to link their account again. If you need token expiration for security reasons, you should strongly consider using the auth code flow instead.

Note: Please choose which OAuth 2.0 flow you want to implement. If needed, the content of this guide reloads to adapt to your choice.

Auth code Implicit flow

Wdrażanie łączenia kont OAuth

Uwaga: jeśli wdrażasz łączenie kont w celu obsługi informacji finansowych, pamiętaj, że do akcji mogą obowiązywać dodatkowe zasady. Weryfikacja działania powiązanego z kontem pod kątem informacji finansowych może potrwać do 6 tygodni, więc należy uwzględnić ten czas podczas planowania harmonogramu publikacji. Aby ułatwić proces weryfikacji, zanim prześlesz akcję do sprawdzenia, upewnij się, że przestrzegasz zasad dotyczących usług finansowych.

Konfigurowanie projektu

Aby skonfigurować projekt do korzystania z połączenia OAuth, wykonaj te czynności:

1. Otwórz Konsolę Actions i wybierz projekt, którego chcesz użyć.
2. Kliknij kartę Programowanie i wybierz Łączenie kont.
3. Włącz przełącznik obok opcji Łączenie kont.
4. W sekcji Tworzenie konta wybierz Nie, chcę zezwolić na tworzenie konta tylko na mojej stronie internetowej.

5. W sekcji Typ połączenia wybierz Protokół OAuth i Pośredni.

   

6. W sekcji Informacje o kliencie:

   • 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.

Uwaga: jeśli chcesz, aby Twój identyfikator klienta był wysyłany jako ciąg zakodowany w base64, kliknij strzałkę obok opcji Skonfiguruj klienta (opcjonalnie) i zaznacz pole Google ma przesyłać identyfikator klienta i obiekt tajny za pomocą nagłówka uwierzytelniania podstawowego HTTP.

6. Kliknij Zapisz.

Wdrażanie serwera OAuth

Aby obsługiwać niejawny przepływ OAuth 2.0, Twoja usługa wymaga autoryzacji punktu końcowego dostępnego przez HTTPS. Ten punkt końcowy odpowiada za uwierzytelnianie i uzyskiwania 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, wyrazić zgodę na żądany dostęp.

Gdy akcja musi wywołać jeden z autoryzowanych interfejsów API usługi, Google używa ten punkt końcowy, aby uzyskać od użytkowników uprawnienia do wywoływania tych interfejsów API w imieniu Google.

Typowa sesja niejawnego przepływu zainicjowana przez Google w języku OAuth 2.0 ma następujący przepływ:

1. Google otworzy punkt końcowy autoryzacji w przeglądarce użytkownika. loguje się, jeśli jeszcze nie jest zalogowany, i zezwala Google na dostęp swoich danych za pomocą interfejsu API, jeśli nie udzielili jeszcze zgody.
2. Usługa tworzy token dostępu i zwraca go do Google przez przekierowanie przeglądarki użytkownika z powrotem do Google wraz z tokenem dostępu. do żądania.
3. Google wywołuje interfejsy API Twojej usługi i łączy token dostępu z każdego żądania. Usługa sprawdza, czy token dostępu przyznaje Google aby uzyskać dostęp do interfejsu API, a następnie wykonać jego wywołanie.

Obsługa żądań autoryzacji

Jeśli akcja musi połączyć konta przez niejawny przepływ OAuth 2.0, Google wysyła użytkownika do punktu końcowego autoryzacji z żądaniem zawierającym ciąg następujące parametry:

Parametry punktu końcowego autoryzacji
client_id	Identyfikator klienta przypisany przez Ciebie do Google.
redirect_uri	Adres URL, na który została wysłana odpowiedź na to żądanie.
state	wartości księgowej, która jest przesyłana do Google bez zmian w identyfikator URI przekierowania.
response_type	Typ wartości do zwrócenia w odpowiedzi. W przypadku protokołu OAuth 2.0 implicit przepływu, 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 mógł obsługiwać żądania logowania, wykonaj te czynności:

1. Sprawdź wartości client_id i redirect_uri w zapobiegaj przyznawaniu dostępu do niezamierzonych lub błędnie skonfigurowanych aplikacji klienckich:

   • Sprawdź, czy identyfikator client_id jest zgodny z Twoim identyfikatorem klienta przypisane do Google.
   • Sprawdź, czy URL podany w pliku redirect_uri ma taką postać:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

     YOUR_PROJECT_ID to identyfikator, który znajdziesz na stronie Ustawienia projektu w Konsoli Actions.

2. 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.

3. Wygeneruj token dostępu, którego Google będzie używać, aby uzyskiwać dostęp do Twojego interfejsu API. token dostępu może być dowolną wartością ciągu, ale musi jednoznacznie reprezentować i klienta, dla którego jest przeznaczony token, i nie może być odgadywany.

4. Wyślij odpowiedź HTTP przekierowującą przeglądarkę użytkownika na ten adres URL wskazywaną przez parametr redirect_uri. Uwzględnij wszystkie następujące parametry we fragmencie adresu URL:

   • access_token: wygenerowany właśnie przez Ciebie token dostępu.
   • token_type: ciąg znaków bearer
   • state: niezmodyfikowana wartość stanu pierwotnego, prośba Oto przykład powstałego 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 od Google otrzyma token dostępu i potwierdzi że wartość state się nie zmieniła. Po uzyskaniu przez Google dla Twojej usługi, Google będzie dołączać ten token do kolejnych wywołań do akcji w ramach żądania AppRequest.

Zaprojektuj interfejs głosowy pod kątem przepływu uwierzytelniania

Ostrzeżenie: na początku rozmowy z akcją nie wyświetlaj użytkownikom prośby o połączenie kont. Zamiast tego zorganizuj nieuwierzytelnionym użytkownikom tryb gościa, aby pokazać, jak działa akcja, i poproś o połączenie kont tylko wtedy, gdy jest to konieczne. Jeśli użytkownicy regularnie opuszczają akcję z powodu problemów z połączeniem kont, Google nie będzie aktywnie promować tego działania, co może zmniejszyć ruch użytkowników generowany przez akcję.

Uwaga: aby utworzyć akcję, która implementuje łączenie kont, musisz użyć narzędzia Actions Builder.

Sprawdź, czy użytkownik został zweryfikowany, i rozpocznij proces łączenia kont

1. Otwórz projekt Actions Builder w Konsoli Actions.
2. Utwórz nową scenę, aby rozpocząć łączenie kont w Akcji:
   1. Kliknij Sceny.
   2. Aby dodać nową scenę, kliknij ikonę dodaj (+).
3. W nowo utworzonej scenie kliknij ikonę dodawania w sekcji Warunki.
4. 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.
   1. W polu Enter new expression w sekcji Warunek wpisz tę funkcję: user.verificationStatus != "VERIFIED"
   2. 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.

1. Kliknij ikonę dodawania obok pozycji Warunki.
2. Dodaj warunek aktywujący proces łączenia kont, jeśli użytkownik nie ma powiązanej tożsamości.
   1. W polu Enter new expression w sekcji Warunek wpisz tę funkcję: user.verificationStatus == "VERIFIED"
   2. W sekcji Przenoszenie wybierz scenę systemową Łączenie kont.
   3. Kliknij Zapisz.

Po zapisaniu do projektu zostanie dodana nowa scena systemu łączenia kont o nazwie <SceneName>_AccountLinking.

Dostosowywanie sceny łączenia kont

1. W sekcji Sceny wybierz scenę systemową łączenia kont.
2. 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”).
3. Kliknij Zapisz.

1. W sekcji Warunki kliknij Jeśli użytkownik ukończy łączenie kont.
2. 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.
3. Kliknij Zapisz.

1. W sekcji Warunki kliknij Jeśli użytkownik anuluje lub odrzuci łączenie kont.
2. 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.
3. Kliknij Zapisz.

1. W sekcji Warunki kliknij W przypadku wystąpienia błędu systemu lub sieci.
2. 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.
3. 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 następnie pobierz powiązane konto użytkownika z bazy danych.