Łą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.

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

Wdrażanie łączenia kont OAuth

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 Kod autoryzacji.

  6. W sekcji Informacje o kliencie:

    • Przypisz wartość do Identyfikatora klienta wydanego przez Actions to Google, aby identyfikować żądania pochodzące od Google.
    • Zwróć uwagę na wartość Identyfikator klienta wydany przez Google dla Twoich akcji.
    • Wstaw adresy URL punktów końcowych autoryzacji i Token Exchange.
  1. Kliknij Zapisz.

Wdrażanie serwera OAuth

Implementacja przepływu kodu autoryzacji przez serwer OAuth 2.0 składa się z 2 punktów końcowych, które Twoja usługa udostępnia za pomocą protokołu HTTPS. Pierwszym punktem końcowym jest punkt końcowy autoryzacji, który odpowiada za znajdowanie użytkowników i uzyskiwanie ich zgody na dostęp do danych. Punkt końcowy autoryzacji wyświetla interfejs logowania użytkownikom, którzy nie są jeszcze zalogowani, i rejestruje zgodę na dostęp. Drugi punkt końcowy to punkt końcowy wymiany tokenów, który służy do uzyskiwania zaszyfrowanych ciągów znaków zwanych tokenami, które upoważniają użytkownika akcji do dostępu do usługi.

Gdy akcja musi wywoływać jeden z interfejsów API Twojej usługi, Google używa tych punktów końcowych razem, aby uzyskać od użytkowników pozwolenie na wywoływanie tych interfejsów API w ich imieniu.

Sesja przepływu kodu autoryzacji OAuth 2.0 zainicjowana przez Google ma następujący przepływ:

  1. Google otworzy punkt końcowy autoryzacji w przeglądarce użytkownika. Jeśli akcja rozpoczęła się na urządzeniu tylko głosowym, Google przeniesie wykonanie na telefon.
  2. 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ł.

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

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

  5. Gdy użytkownik zakończy proces łączenia kont, każde kolejne żądanie wysłane z Asystenta do webhooka realizacji zamówienia będzie zawierać token dostępu.

Obsługa żądań autoryzacji

Gdy akcja musi przeprowadzić łączenie kont za pomocą przepływu kodu autoryzacji 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 Google zarejestrowany w 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.
scope Opcjonalnie: rozdzielany spacjami zestaw ciągów zakresu określających dane, których dotyczy autoryzacja Google.
response_type Ciąg code.

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&scope=REQUESTED_SCOPES&response_type=code

Aby punkt końcowy autoryzacji obsługiwał żądania logowania, wykonaj te czynności:

  1. Sprawdź, czy client_id jest zgodny z identyfikatorem klienta Google zarejestrowanym w Google i czy redirect_uri jest zgodny z przekierowaniem podanym przez Google dla Twojej usługi. Te kontrole są ważne, ponieważ zapobiegają przyznawaniu dostępu do niezamierzonych lub nieprawidłowo skonfigurowanych aplikacji klienckich.

    Jeśli obsługujesz wiele przepływów OAuth 2.0, sprawdź też, czy response_type ma wartość code.

  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 kod autoryzacji, którego Google będzie używać do uzyskiwania dostępu do Twojego interfejsu API. Kod autoryzacji może być dowolną wartością ciągu, ale musi jednoznacznie reprezentować użytkownika, klienta, dla którego jest przeznaczony token, oraz termin ważności kodu. Kod nie może dać się odgadnąć. Zwykle wydajesz kody autoryzacji, które wygasają po około 10 minutach.

  4. 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 ze strony Ustawienia projektu w Konsoli Actions.

  5. Przekieruj przeglądarkę użytkownika na adres URL określony przez parametr redirect_uri. Podczas przekierowywania dodaj wygenerowany kod autoryzacji i pierwotną, niezmodyfikowaną wartość stanu, dołączając parametry code i state. Oto przykład uzyskanego adresu URL:

    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

Obsługuj żądania wymiany tokenów

Punkt końcowy wymiany tokenów Twojej usługi jest odpowiedzialny za 2 rodzaje wymiany tokenów:

  • Wymiana kodów autoryzacji tokenów dostępu i tokenów odświeżania
  • Wymiana tokenów odświeżania tokenów dostępu

Żądania wymiany tokenów zawierają te parametry:

Parametry punktów końcowych wymiany tokenów
client_id Ciąg określający źródło żądania jako Google. Ten ciąg musi być zarejestrowany w Twoim systemie jako unikalny identyfikator Google.
client_secret Tajny ciąg znaków zarejestrowany w Google na potrzeby korzystania z usługi.
grant_type Typ wymienianego tokena. Może to być authorization_code lub refresh_token.
code Gdy grant_type=authorization_code, kod otrzymany przez Google z punktu końcowego logowania lub tokena wymiany tokenów.
redirect_uri Gdy jest ustawiona wartość grant_type=authorization_code, ten parametr to adres URL użyty w początkowym żądaniu autoryzacji.
refresh_token Gdy grant_type=refresh_token, token odświeżania otrzymany przez Google z punktu końcowego tokena wymiany tokenów.
Wymiana kodów autoryzacji tokenów dostępu i tokenów odświeżania

Gdy użytkownik się zaloguje, a punkt końcowy autoryzacji zwróci do Google kod autoryzacji o ograniczonym czasie ważności, Google wyśle do niego żądanie, aby wymienić kod autoryzacji na token dostępu i token odświeżania.

W przypadku tych żądań wartość grant_type wynosi authorization_code, a wartość code to wartość kodu autoryzacji przypisanego wcześniej do Google. Poniżej znajdziesz przykład żądania wymiany kodu autoryzacji dla tokena dostępu i tokena odświeżania:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

Aby wymieniać kody autoryzacji na token dostępu i token odświeżania, punkt końcowy tokenu Exchange odpowiada na żądania POST wykonując te czynności:

  1. Sprawdź, czy client_id identyfikuje źródło żądania jako autoryzowane źródło i czy client_secret jest zgodna z oczekiwaną wartością.
  2. Sprawdź, czy:
    • Kod autoryzacji jest prawidłowy i nie stracił ważności, a identyfikator klienta określony w żądaniu odpowiada identyfikatorowi klienta powiązanym z kodem autoryzacji.
    • Adres URL określony przez parametr redirect_uri jest taki sam jak wartość użyta w pierwotnym żądaniu autoryzacji.
  3. Jeśli nie możesz zweryfikować wszystkich powyższych kryteriów, zwróć błąd HTTP 400 Bad Request z treścią {"error": "invalid_grant"}.
  4. W przeciwnym razie użyj identyfikatora użytkownika z kodu autoryzacji, aby wygenerować token odświeżania i token dostępu. Tokeny te mogą być dowolną wartością ciągu, ale muszą jednoznacznie reprezentować użytkownika oraz klienta, dla którego jest przeznaczony token. Tokeny nie mogą być odgadnięte. W przypadku tokenów dostępu zanotuj też czas ważności tokena (zwykle godzinę po jego wystawieniu). Tokeny odświeżania nie tracą ważności.
  5. Zwraca w treści odpowiedzi HTTPS ten obiekt JSON:
    {
    "token_type": "Bearer",
    "access_token": "ACCESS_TOKEN",
    "refresh_token": "REFRESH_TOKEN",
    "expires_in": SECONDS_TO_EXPIRATION
    }
    

Google przechowuje token dostępu oraz token odświeżania dla użytkownika i rejestruje datę wygaśnięcia tokena dostępu. Po wygaśnięciu tokena dostępu Google używa tokena odświeżania, aby pobrać nowy token dostępu z punktu końcowego tokena wymiany tokenów.

Wymiana tokenów odświeżania tokenów dostępu

Po wygaśnięciu tokena dostępu Google wysyła żądanie do punktu końcowego tokena Exchange, aby wymienić token odświeżania na nowy.

W przypadku tych żądań wartość grant_type wynosi refresh_token, a wartość refresh_token to wartość tokena odświeżania, który został przez Ciebie wcześniej przyznany Google. Poniżej znajdziesz przykład żądania wymiany tokena odświeżania na token dostępu:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

Aby wymienić token odświeżania na token dostępu, punkt końcowy tokena giełdy odpowiada na żądania POST. Aby to zrobić, wykonaj te czynności:

  1. Sprawdź, czy client_id identyfikuje źródło żądania jako Google i czy client_secret pasuje do oczekiwanej wartości.
  2. Sprawdź, czy token odświeżania jest prawidłowy oraz czy identyfikator klienta określony w żądaniu odpowiada identyfikatorowi klienta powiązanym z tokenem odświeżania.
  3. Jeśli nie możesz zweryfikować wszystkich powyższych kryteriów, zwróć błąd HTTP 400 Bad Request z treścią {"error": "invalid_grant"}.
  4. W przeciwnym razie użyj identyfikatora użytkownika z tokena odświeżania, aby wygenerować token dostępu. Tokeny te mogą być dowolną wartością ciągu, ale muszą jednoznacznie reprezentować użytkownika oraz klienta, dla którego jest przeznaczony token. Tokeny nie mogą być da się odgadnąć. W przypadku tokenów dostępu zanotuj też czas ważności tokena (zwykle godzinę po jego wystawieniu).
  5. Zwraca ten obiekt JSON w treści odpowiedzi HTTPS:
    {
    "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

  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.