Wdrażanie serwera OAuth 2.0

Każda integracja z Cloud-to-cloud musi zawierać mechanizm uwierzytelniania użytkowników.

Uwierzytelnianie umożliwia Ci łączenie kont Google użytkowników z kontami użytkowników w Twoim systemie uwierzytelniania. Dzięki temu możesz zidentyfikować użytkowników, gdy usługa otrzyma intencję związaną z inteligentnym domem. Usługa Google Smart Home obsługuje OAuth tylko z procesem kodu autoryzacji.

Na tej stronie opisaliśmy, jak skonfigurować serwer OAuth 2.0, aby współpracował z integracją Cloud-to-cloud.

Łączenie konta Google przez OAuth

W procesie kodu autoryzacji potrzebujesz 2 punktów końcowych:

• Punkt końcowy autoryzacji, który wyświetla interfejs logowania użytkownikom, którzy nie są jeszcze zalogowani. Punkt końcowy autoryzacji tworzy też krótkotrwały kod autoryzacji do rejestrowania zgody użytkownika na żądany dostęp.

• Punkt końcowy wymiany tokenów, który odpowiada za 2 typy giełd:

  1. Wymienia kod autoryzacji na długoterminowy token odświeżania i token dostępu o ograniczonym czasie ważności. Wymiana ma miejsce wtedy, gdy użytkownik przechodzi przez proces łączenia kont.
  2. Wymienia długoterminowy token odświeżania na token dostępu o ograniczonym czasie ważności. Ta wymiana ma miejsce, gdy Google potrzebuje nowego tokena dostępu, ponieważ ten, który stracił ważność.

Wskazówki dotyczące wyglądu

W tej sekcji opisano wymagania i zalecenia dotyczące projektu ekranu użytkownika hostowanego na potrzeby procesów łączenia z protokołem OAuth. Po wywołaniu go przez aplikację Google platforma wyświetla użytkownikowi ekran z prośbą o zgodę na logowanie się na stronie Google i łączeniem kont. Po wyrażeniu zgody na połączenie kont użytkownik jest kierowany z powrotem do aplikacji Google.

Wymagania

1. Musisz poinformować, że konto użytkownika zostanie połączone z Google, a nie z konkretną usługą Google, taką jak Google Home czy Asystent Google.
2. Musisz mieć oświadczenie autoryzacji Google, np. „Logując się, upoważniasz Google do kontrolowania Twoich urządzeń”. Przeczytaj sekcję dotyczącą autoryzacji sterowania urządzeniami w Google w zasadach dla deweloperów Google Home.
3. Musisz umożliwić użytkownikom powrót do gry lub anulowanie połączenia, jeśli nie zdecydują się na połączenie.
4. Musisz otworzyć stronę połączenia z internetem OAuth i upewnić się, że użytkownicy mają łatwy dostęp do metody logowania się na konto Google, takie jak pola nazwy użytkownika i hasła. Nie używaj metody logowania przez Google (GSI), która umożliwia użytkownikom tworzenie połączeń bez przechodzenia na stronę łączenia OAuth. Narusza to zasady Google.

Rekomendacje

Zalecamy wykonanie tych czynności:

1. Wyświetl Politykę prywatności Google. Umieść na ekranie zgody link do Polityki prywatności Google.

2. Dane do udostępnienia. W jasny i zwięzły sposób wyjaśnij użytkownikom, jakich danych Google wymaga od Google i dlaczego.

3. Jednoznaczne wezwanie do działania. Umieść na ekranie zgody jasne wezwanie do działania, np. „Zgadzam się i połącz”. Dzieje się tak, ponieważ użytkownicy muszą wiedzieć, jakie dane muszą udostępnić Google, aby połączyć swoje konta.

4. Możliwość odłączenia. Udostępnij użytkownikom mechanizm odłączania konta, np. adres URL do ich ustawień konta na Twojej platformie. Możesz też podać link do konta Google, na którym użytkownicy mogą zarządzać swoim połączonym kontem.

5. Możliwość zmiany konta użytkownika. Zasugeruj użytkownikom metodę przełączenia kont. Jest to szczególnie przydatne, gdy użytkownicy mają wiele kont.

   • Jeśli użytkownik musi zamknąć ekran zgody, aby przełączyć konta, wyślij do Google błąd umożliwiający przywrócenie danych, aby użytkownik mógł zalogować się na wybrane konto za pomocą łączenia przez OAuth.

6. Dodaj logo. Wyświetlaj logo swojej firmy na ekranie zgody. Umieść logo zgodnie ze wskazówkami dotyczącymi stylu. Jeśli chcesz też wyświetlać logo Google, zobacz Logo i znaki towarowe.

Przepływ kodu autoryzacji

Implementacja na serwerze OAuth 2.0 przepływu kodu autoryzacji składa się z 2 punktów końcowych, które usługa udostępnia przez HTTPS. Pierwszym punktem końcowym jest punkt końcowy autoryzacji, który odpowiada za znalezienie lub uzyskanie zgody użytkowników 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 żądany dostęp. Drugim punktem końcowym jest punkt końcowy wymiany tokenów, który służy do uzyskiwania zaszyfrowanych ciągów znaków, zwanych tokenami, które autoryzują użytkownika do uzyskiwania dostępu do usługi.

Gdy aplikacja Google musi wywołać interfejs API jednej z Twoich usług, Google używa tych punktów końcowych, aby uzyskać od użytkowników zgodę na wywoływanie tych interfejsów API w ich imieniu.

Sesja OAuth 2.0 z kodem autoryzacji inicjowana przez Google ma następujący przepływ:

1. Google otwiera w przeglądarce użytkownika Twój punkt końcowy autoryzacji. Jeśli proces został rozpoczęty na urządzeniu obsługującym tylko polecenia głosowe, Google przeniesie jego wykonanie na telefon.
2. Użytkownik loguje się (jeśli nie jest już zalogowany) i daje Google uprawnienia do dostępu do swoich danych za pomocą Twojego interfejsu API (jeśli jeszcze ich nie ma).
3. Usługa tworzy kod autoryzacji i zwraca go do Google. Aby to zrobić, przekieruj przeglądarkę użytkownika z powrotem do Google z dołączonym do żądania kodem autoryzacji.
4. Google wysyła kod autoryzacji do punktu końcowego wymiany tokenów, który weryfikuje autentyczność kodu i zwraca token dostępu oraz token odświeżania. Token dostępu to krótkoterminowy token, który Twoja usługa akceptuje jako dane logowania do interfejsów API. Token odświeżania to długotrwały token, który Google może przechowywać i wykorzystywać do uzyskiwania nowych tokenów dostępu po ich wygaśnięciu.
5. Po zakończeniu przez użytkownika procesu łączenia kont każde kolejne żądanie wysłane z Google będzie zawierać token dostępu.

Obsługa próśb o autoryzację

Gdy musisz połączyć konto za pomocą 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 przypisany do Google.
redirect_uri	Adres URL, na który wysyłasz odpowiedź na to żądanie.
state	Wartość księgowa, która jest przekazywana z powrotem do Google w identyfikatorze URI przekierowania bez zmian.
scope	Opcjonalnie: zestaw oddzielonych spacjami ciągów znaków określających zakres danych, do których Google prosi o autoryzację.
response_type	Typ wartości do zwrócenia w odpowiedzi. W przypadku OAuth 2.0 przepływu kodu autoryzacji typ odpowiedzi jest zawsze code.
user_locale	Ustawienie języka konta Google w formacie RFC5646 służące do zlokalizowania treści w preferowanym języku użytkownika.

Jeśli na przykład Twój punkt końcowy autoryzacji jest dostępny pod adresem https://myservice.example.com/auth, prośba 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&user_locale=LOCALE

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

1. Sprawdź, czy client_id odpowiada identyfikatorowi klienta przypisanemu Google, a redirect_uri odpowiada adresowi URL przekierowania podanemu przez Google dla Twojej usługi. Te kontrole są ważne, aby zapobiec przyznaniu dostępu do aplikacji klienta niepożądanych lub źle skonfigurowanych. Jeśli obsługujesz wiele przepływów OAuth 2.0, sprawdź też, czy response_type to code.
2. Sprawdź, czy użytkownik jest zalogowany w usłudze. Jeśli użytkownik nie jest zalogowany, przeprowadź proces logowania lub rejestracji w usłudze.
3. wygenerować kod autoryzacji, który Google będzie używać do uzyskiwania dostępu do Twojego interfejsu API. Kod autoryzacji może być dowolną wartością ciągu znaków, ale musi jednoznacznie reprezentować użytkownika, klienta, dla którego przeznaczony jest token, oraz czas jego ważności. Nie może być też łatwy do odgadnięcia. Zazwyczaj wydajesz kody autoryzacyjne, które wygasają po około 10 minutach.
4. Sprawdź, czy adres URL określony przez parametr redirect_uri ma następujący format:

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

5. Przekierowywanie przeglądarki użytkownika na adres URL podany w parametrze redirect_uri. Podczas przekierowania dołącz wygenerowany kod autoryzacji i pierwotną, niezmienioną wartość stanu, dodając parametry code i state. Poniżej przedstawiamy przykładowy adres URL:

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

Obsługa próśb o wymianę tokenów

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

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

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

Parametry punktu końcowego wymiany tokenów
client_id	Ciąg znaków wskazujący, że źródłem żądania jest Google. Ten ciąg znaków musi być zarejestrowany w Twoim systemie jako unikalny identyfikator Google.
client_secret	Tajny ciąg znaków zarejestrowany w Google w przypadku Twojej usługi.
grant_type	Typ tokena, który jest wymieniany. Może to być authorization_code lub refresh_token.
code	Gdy grant_type=authorization_code, ten parametr to kod otrzymany przez Google z Twojego punktu końcowego logowania lub wymiany tokenów.
redirect_uri	Gdy grant_type=authorization_code, ten parametr to adres URL użyty w pierwotnym żądaniu autoryzacji.
refresh_token	Gdy grant_type=refresh_token, ten parametr to token odświeżania otrzymany przez Google od punktu końcowego wymiany tokenów.

Konfigurowanie sposobu wysyłania przez Google danych logowania na Twój serwer

W zależności od implementacji serwer autoryzacji oczekuje, że otrzyma dane uwierzytelniające klienta w treści żądania lub w nagłówku żądania.

Domyślnie Google wysyła te dane w treści żądania. Jeśli Twój serwer autoryzacji wymaga, aby dane logowania klienta znajdowały się w nagłówku żądania, musisz odpowiednio skonfigurować integrację Cloud-to-cloud:

Otwórz konsolę programistów

1. Na liście projektów kliknij Otwórz obok projektu, nad którym chcesz pracować.

2. W sekcji Z chmury do chmury wybierz Opracuj.

3. Kliknij Otwórz obok integracji.

4. Przewiń w dół do sekcji Uprawnienia (opcjonalnie) i zaznacz pole wyboru Zezwalaj Google na przesyłanie identyfikatora klienta i klucza tajnego w nagłówku HTTP Basic Auth.

5. Kliknij Zapisz, aby zapisać zmiany.

Wymiana kodów autoryzacji na tokeny dostępu i tokeny odświeżania

Gdy użytkownik zaloguje się i punkt końcowy autoryzacji zwróci do Google krótkotrwały kod autoryzacji, Google wyśle do punktu końcowego wymiany tokenów żądanie wymiany kodu autoryzacji na token dostępu i token odświeżania.

W przypadku tych żądań wartość grant_type to authorization_code, a wartość code to kod autoryzujący, który został wcześniej przekazany Google. Oto przykład żądania wymiany kodu autoryzacji na token dostępu i token 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 wymienić kody autoryzacji na token dostępu i token odświeżania, punkt końcowy wymiany tokenów odpowiada na żądania POST, wykonując te czynności:

1. Sprawdź, czy client_id wskazuje, że źródło żądania jest autoryzowane, oraz czy client_secret odpowiada oczekiwanej wartości.
2. Sprawdź, czy kod autoryzacji jest prawidłowy i czy nie wygasł, a identyfikator klienta podany w żądaniu jest zgodny z identyfikatorem klienta powiązanym z kodem autoryzacji.
3. Sprawdź, czy adres URL podany w parametrze redirect_uri jest identyczny z wartością użytą w pierwotnym żądaniu autoryzacji.
4. Jeśli nie możesz zweryfikować wszystkich powyższych kryteriów, zwracaj błąd HTTP 400 „Zła prośba” z wartością {"error": "invalid_grant"} w sekcji treści.
5. W przeciwnym razie użyj identyfikatora użytkownika z kodu autoryzacji, aby wygenerować token odświeżania i token dostępu. Tokeny mogą być dowolnymi ciągami znaków, ale muszą jednoznacznie identyfikować użytkownika i klienta, dla którego są przeznaczone, oraz nie mogą być łatwe do odgadnięcia. W przypadku tokenów dostępu zapisz też czas ich wygaśnięcia, który zwykle wynosi 1 godzinę od momentu wydania tokenu. Tokeny odświeżania nie wygasają.
6. W treści odpowiedzi HTTPS zwracaj ten obiekt JSON:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "refresh_token": "REFRESH_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }
   

Google przechowuje token dostępu i token odświeżania dla użytkownika oraz rejestruje datę wygaśnięcia tokenu dostępu. Gdy token dostępu wygaśnie, Google użyje tokena odświeżania, aby uzyskać nowy token dostępu z punktu końcowego wymiany tokenów.

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

Gdy token dostępu wygaśnie, Google wysyła żądanie do punktu końcowego wymiany tokenów w celu wymiany tokena odświeżania na nowy token dostępu.

W przypadku tych żądań wartość grant_type to refresh_token, a wartość refresh_token to wartość tokena odświeżania, który został wcześniej przyznany Google. Oto 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 wymiany tokenów odpowiada na żądania POST, wykonując te czynności:

1. Sprawdź, czy client_id wskazuje, że źródłem żądania jest Google, oraz czy client_secret odpowiada oczekiwanej wartości.
2. Sprawdź, czy token odświeżania jest prawidłowy, a identyfikator klienta podany w żądaniu odpowiada identyfikatorowi klienta powiązanemu z tokenem odświeżania.
3. Jeśli nie możesz zweryfikować wszystkich powyższych kryteriów, zwracaj błąd HTTP 400 Bad Request z wartością {"error": "invalid_grant"} w sekcji treści.
4. W przeciwnym razie użyj identyfikatora użytkownika z tokena odświeżania, aby wygenerować token dostępu. Tokeny mogą być dowolną wartością ciągu znaków, ale muszą jednoznacznie reprezentować użytkownika i klienta, dla którego są przeznaczone, oraz nie mogą być łatwe do odgadnięcia. W przypadku tokenów dostępu odnotuj też czas ich wygaśnięcia, który zwykle wynosi godzinę od momentu wydania tokenu.
5. W treści odpowiedzi HTTPS zwracaj ten obiekt JSON:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }

Obsługa żądań informacji o użytkowniku

Punkt końcowy informacji o użytkowniku jest chronionym przez OAuth 2.0 zasobem, który zwraca deklaracje dotyczące połączonego użytkownika. Wdrożenie i hosting punktu końcowego informacji o użytkowniku jest opcjonalne. Wyjątkiem są te przypadki użycia:

• Logowanie się na połączone konto za pomocą Google One Tap
• Bezproblemowa subskrypcja na AndroidTV.

Po pobraniu tokena dostępu z punktu końcowego tokena Google wysyła żądanie do punktu końcowego informacji o użytkowniku, aby pobrać podstawowe informacje profilowe połączonego użytkownika.

nagłówki żądań punktu końcowego informacji o użytkowniku
Authorization header	Token dostępu typu okaziciela.

Jeśli na przykład punkt końcowy informacji o użytkowniku jest dostępny pod adresem https://myservice.example.com/userinfo, żądanie może wyglądać tak:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

Aby punkt końcowy informacji o użytkowniku mógł obsługiwać żądania, wykonaj te czynności:

1. Wyodrębnij token dostępu z nagłówka autoryzacji i zwróć informacje o użytkowniku powiązanym z tym tokenem.
2. Jeśli token dostępu jest nieprawidłowy, zwróć błąd HTTP 401 (Brak autoryzacji) i użyj nagłówka odpowiedzi WWW-Authenticate. Poniżej znajduje się przykładowa odpowiedź na pytanie o błąd w informacjach o użytkowniku:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: error="invalid_token",
   error_description="The Access Token expired"
   

   Jeśli podczas procesu łączenia pojawi się błąd 401 (Brak autoryzacji) lub inna nieudana próba połączenia, błędu nie będzie można odzyskać, pobrany token zostanie odrzucony, a użytkownik będzie musiał ponownie zainicjować proces łączenia.

3. Jeśli token dostępu jest prawidłowy, zwróć odpowiedź HTTP 200 z podanym niżej obiektem JSON w treści HTTPS odpowiedź:

   {
   "sub": "USER_UUID",
   "email": "EMAIL_ADDRESS",
   "given_name": "FIRST_NAME",
   "family_name": "LAST_NAME",
   "name": "FULL_NAME",
   "picture": "PROFILE_PICTURE",
   }
   

   Jeśli punkt końcowy informacji o użytkowniku zwraca odpowiedź HTTP 200, pobrany token i żądania są rejestrowane dla konta Google użytkownika.

   odpowiedź dotycząca punktu końcowego informacji o użytkowniku
   sub	Unikalny identyfikator, który identyfikuje użytkownika w Twoim systemie.
   email	Adres e-mail użytkownika.
   given_name	Opcjonalnie: imię użytkownika.
   family_name	Opcjonalnie: nazwisko użytkownika.
   name	Opcjonalnie: pełna nazwa użytkownika.
   picture	Opcjonalnie: zdjęcie profilowe użytkownika.