Łączenie kont za pomocą protokołu OAuth i logowania przez Google (Dialogflow)

Typ połączenia Protokół OAuth i Logowanie przez Google dodaje Logowanie przez Google zamiast łączenia kont przez OAuth. W ten sposób 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.

Rysunek 1. Gdy akcja uzyska dostęp do profilu Google użytkownika, możesz go użyć, aby znaleźć użytkownika w swoim systemie uwierzytelniania.

Aby przeprowadzić łączenie kont za pomocą protokołu OAuth i Logowania przez Google, wykonaj te ogólne czynności:

1. Najpierw poproś użytkownika o zgodę na dostęp do jego profilu Google.
2. Użyć informacji z profilu do zidentyfikowania użytkownika.
3. 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.

Rysunek 2. Wizualna reprezentacja procesu OAuth i logowania przez Google, gdy w systemie nie znaleziono danych użytkownika.

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.

Uwaga: aby dowiedzieć się więcej o implementowaniu wybranego procesu, wybierz jedną z opcji poniżej. W razie potrzeby zawartość przewodnika zostanie wczytana ponownie, aby dostosować ją do Twojego wyboru.

Zezwalaj na tworzenie kont za pomocą głosu Nie zezwalaj na tworzenie kont za pomocą głosu

Wdrażanie protokołu OAuth i łączenia kont do logowania się przez Google

Konta są połączone ze standardowymi procesami OAuth 2.0. Actions on Google obsługuje przepływy kodu niejawnego i autoryzacyjnego.

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.

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.

Uwaga: wybierz przepływ OAuth2, który chcesz zaimplementować. W razie potrzeby treść przewodnika zostanie ponownie załadowana, aby dostosować się do wybranych przez Ciebie ustawień.

Kod autoryzacji Przewidujący przepływ

Konfigurowanie projektu

Aby skonfigurować projekt do korzystania z protokołu OAuth i łączenia kont z logowaniem przez Google, 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. Kliknij przełącznik obok opcji Łączenie kont.
4. W sekcji Tworzenie konta wybierz Tak.

5. W sekcji Typ połączenia wybierz Logowanie przez OAuth i Google oraz Pośredni.

   

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

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

1. 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ł.
2. 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.
3. 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 w ramach niejawnego przepływu o protokołu OAuth2, 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:

1. Sprawdź wartości client_id i redirect_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.

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

4. 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ów bearer.
   • 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).

Uwaga: klucze nie powinny być zakodowane na stałe. Zamiast tego użyj protokołu wykrywania OpenID Connect i sprawdź nagłówek cache-control, aby zdecydować, jak długo klucz powinien być przechowywany w pamięci podręcznej.

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": "[e-mail]", // 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).

Uwaga: klucze nie powinny być zakodowane na stałe. Zamiast tego użyj protokołu wykrywania OpenID Connect i sprawdź nagłówek cache-control, aby zdecydować, jak długo klucz powinien być przechowywany w pamięci podręcznej.

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": "[e-mail]", // 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":"[e-mail]"
}

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
}

Rozpocznij proces 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ę.

Pamiętaj, że tylko zweryfikowani użytkownicy mogą łączyć konta. Jeśli użytkownik jest gościem, nie uda się połączyć kont. Dowiedz się, jak identyfikować gościów i postępować z nimi.

Aby rozpocząć proces uwierzytelniania, użyj intencji pomocniczej logowania na konto.

Dialogflow (Node.js)

const app = dialogflow({
  // REPLACE THE PLACEHOLDER WITH THE CLIENT_ID OF YOUR ACTIONS PROJECT
  clientId: CLIENT_ID,
})

// Intent that starts the account linking flow.
app.intent('Start Signin', conv => {
  conv.ask(new SignIn('To get your account details'))
})

Dialogflow (Java)

private String clientId = "<your_client_id>";

@ForIntent("Start Signin")
public ActionResponse text(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  return rb.add(new SignIn().setContext("To get your account details")).build();
}

Actions SDK (Node.js)

const app = actionssdk({
  clientId: CLIENT_ID,
})

app.intent('Start Signin', conv => {
  conv.ask(new SignIn('To get your account details'))
})

Pakiet SDK Actions (Java)

private String clientId = "<your_client_id>";

@ForIntent("actions.intent.TEXT")
public ActionResponse text(ActionRequest request) {
  ResponseBuilder rb = getResponseBuilder(request);
  return rb.add(new SignIn().setContext("To get your account details")).build();
}

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.