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.
![](https://developers-dot-devsite-v2-prod.appspot.com/static/assistant/df-asdk/identity/images/gsi-oauth-flow.png?authuser=6&hl=pl)
Aby przeprowadzić łączenie kont za pomocą protokołu OAuth i Logowania przez Google, wykonaj te ogólne czynności:
- Najpierw poproś użytkownika o zgodę na dostęp do jego profilu Google.
- Użyć informacji z profilu do zidentyfikowania użytkownika.
- 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.
![Jeśli zezwalasz na głosowe tworzenie kont i nie możesz znaleźć dopasowania do profilu Google w swoim systemie uwierzytelniania, musisz zweryfikować 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 użytkowników za pomocą głosu, użytkownik zostanie przeniesiony do przeglądarki, w której może wczytać stronę autoryzacji i dokończyć ten proces.](https://developers-dot-devsite-v2-prod.appspot.com/static/assistant/df-asdk/identity/images/gsi-oauth-flow-creation.png?authuser=6&hl=pl)
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.
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.
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:
- 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.
- 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.
Konfigurowanie projektu
Aby skonfigurować projekt do korzystania z protokołu OAuth i łączenia kont z logowaniem przez Google, wykonaj te czynności:
- Otwórz Konsolę Actions i wybierz projekt, którego chcesz użyć.
- Kliknij kartę Programowanie i wybierz Łączenie kont.
- Kliknij przełącznik obok opcji Łączenie kont.
- W sekcji Tworzenie konta wybierz Tak.
W sekcji Typ połączenia wybierz Logowanie przez OAuth i Google oraz Pośredni.
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.
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:
- 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ł.
- 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.
- 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:
Sprawdź wartości
client_id
iredirect_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.
- Sprawdź, czy
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.
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ąć.
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ówbearer
.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
Potwierdzenie JWT możesz zweryfikować i zdekodować za pomocą biblioteki dekodowania JWT dla swojego języka. Użyj kluczy publicznych Google (dostępnych w językach JWK lub PEM), aby zweryfikować token podpis.
Po zdekodowaniu potwierdzenie JWT wygląda jak w tym przykładzie:
{ "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": "jan@gmail.com", // 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 lista odbiorców (pole aud
)
to identyfikator klienta przypisany do Twojej 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
Potwierdzenie JWT możesz zweryfikować i zdekodować za pomocą biblioteki dekodowania JWT dla swojego języka. Użyj kluczy publicznych Google (dostępnych w językach JWK lub PEM), aby zweryfikować token podpis.
Po zdekodowaniu potwierdzenie JWT wygląda jak w tym przykładzie:
{ "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": "jan@gmail.com", // 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 lista odbiorców (pole aud
)
to identyfikator klienta przypisany do Twojej 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":"foo@bar.com" }
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
Aby rozpocząć proces uwierzytelniania, użyj intencji pomocniczej logowania na konto.
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')) })
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(); }
const app = actionssdk({ clientId: CLIENT_ID, }) app.intent('Start Signin', conv => { conv.ask(new SignIn('To get your account details')) })
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.