Wdrażanie serwera OAuth 2.0

Każde działanie smart home musi zawierać mechanizm uwierzytelniania użytkowników.

Uwierzytelnianie pozwala połączyć konta Google użytkowników z kontami użytkowników w systemie uwierzytelniania. Dzięki temu możesz zidentyfikować użytkowników, gdy Twoja realizacja otrzyma intencję inteligentnego domu. Inteligentny dom Google obsługuje protokół OAuth tylko z kodem autoryzacji.

Na tej stronie dowiesz się, jak skonfigurować serwer OAuth 2.0, aby działał z działaniem smart home.

Łączenie konta Google z OAuth

W ramach procesu 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 również krótkotrwały kod autoryzacji do rejestrowania zgody użytkowników na żądany dostęp.

• 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 proces łączenia kont.
  2. Wymienia długotrwały 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ż wygasł.

Wskazówki dotyczące wyglądu

W tej sekcji opisano wymagania dotyczące projektowania i zalecenia związane z ekranem użytkownika hostowanym na potrzeby procesów łączenia protokołu OAuth. Po jej wywołaniu przez aplikację Google Twoja platforma wyświetla użytkownikowi stronę logowania i ekran zgody na połączenie konta. Gdy użytkownik wyrazi zgodę na połączenie kont, zostanie przekierowany z powrotem do aplikacji Google.

Wymagania

1. Musisz poinformować, że konto użytkownika będzie połączone z Google, a nie z konkretnej usługi Google, takiej jak Google Home czy Asystent Google.
2. Musisz mieć oświadczenie Google dotyczące autoryzacji, np. „Logując aplikację, upoważniasz Google do sterowania Twoimi urządzeniami”. Zapoznaj się z sekcją dotyczącą autoryzacji urządzeń w Google w zasadach Google Home dla deweloperów.

Rekomendacje

Zalecamy wykonanie tych czynności:

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

2. Dane do udostępnienia. Jasny i zwięzły język informuje użytkowników, jakich danych Google potrzebuje i dlaczego.

3. Umieść jasne wezwanie do działania. Na ekranie zgody podaj jasne wezwanie do działania, np. „Zgadzam się i łączę”. Wynika to z faktu, że użytkownicy muszą wiedzieć, jakie dane muszą udostępnić Google, aby połączyć swoje konta.

4. Możliwość anulowania. Udostępnij użytkownikom możliwość cofnięcia lub anulowania linku, jeśli nie zechcą go połączyć.

5. Wyczyść proces logowania Upewnij się, że użytkownicy mają jasną metodę logowania się na swoje konto Google, np. za pomocą pól nazwy użytkownika i hasła lub Zaloguj się przez Google.

6. Możliwość odłączenia Udostępnij użytkownikom możliwość odłączenia konta, np. URL do ustawień konta na Twojej platformie. Możesz też podać link do konta Google, za pomocą którego użytkownicy będą mogli zarządzać połączonym kontem.

7. Możliwość zmiany konta użytkownika. Zasugeruj użytkownikom metodę zmiany konta. Jest to szczególnie przydatne, jeśli użytkownicy mają wiele kont.

   • Jeśli użytkownik musi zamknąć ekran zgody, aby przełączyć konto, wyślij powtarzalny błąd do Google, aby umożliwić użytkownikowi zalogowanie się na żądane konto za pomocą połączenia OAuth.

8. Włącz logo. Wyświetlaj logo swojej firmy na ekranie zgody. Umieść logo, korzystając ze wskazówek dotyczących stylu. Jeśli chcesz wyświetlać logo, zapoznaj się z artykułem Logo i znaki towarowe.

Przepływ kodu autoryzacji

Implementacja serwera OAuth 2.0 w procesie autoryzacji składa się z 2 punktów końcowych udostępnianych przez HTTPS. Pierwszy punkt końcowy to punkt końcowy autoryzacji, który odpowiada za znajdowanie lub uzyskiwanie 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 upoważniają użytkownika do uzyskania dostępu do usługi.

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

Sesja przepływu kodu autoryzacji OAuth 2.0 zainicjowana przez Google wygląda tak:

1. Google otwiera punkt końcowy autoryzacji w przeglądarce użytkownika. Jeśli proces rozpoczyna się na urządzeniu w trybie głosowym dla działania, Google przenosi wykonanie na telefon.
2. Użytkownik się zaloguje (w razie potrzeby), przyznając mu dostęp do jego danych za pomocą interfejsu API, chyba że użytkownik jeszcze tego nie zrobił.
3. Usługa utworzy kod autoryzacji i zwróci go do Google. Aby to zrobić, przekieruj przeglądarkę użytkownika z powrotem do Google, podając kod autoryzacji załączony do żądania.
4. Google wysyła kod autoryzacji do punktu końcowego wymiany tokena, który weryfikuje autentyczność kodu i zwraca token dostępu oraz token odświeżania. Token dostępu to krótkotrwały token akceptowany przez usługę 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 pozyskiwania nowych tokenów dostępu, gdy wygasną.
5. Po zakończeniu procesu łączenia kont każde kolejne żądanie wysłane z Google zawiera token dostępu.

Obsługuj żądania autoryzacji

Gdy musisz przeprowadzić łączenie kont za pomocą kodu autoryzacji OAuth 2.0, Google wyśle 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 wyślesz odpowiedź na to żądanie.
state	Wartość księgowa przekazywana z powrotem do Google w identyfikatorze URI przekierowania.
scope	Opcjonalnie: rozdzielany spacjami ciąg znaków w zakresie określających dane, do których Google prosi o autoryzację.
response_type	Typ wartości, która ma być zwrócona w odpowiedzi. W przypadku procesu autoryzacji kodu OAuth 2.0 typ odpowiedzi to zawsze code.
user_locale	Ustawienie języka konta Google w formacie RFC5646 używane do lokalizowania treści w języku preferowanym przez użytkownika.

Jeśli na przykład Twój punkt końcowy autoryzacji jest dostępny w lokalizacji 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&user_locale=LOCALE

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

1. Sprawdź, czy client_id zgadza się z identyfikatorem klienta przypisanym do Google, a redirect_uri odpowiada adresowi URL przekierowania podanemu przez Google w przypadku Twojej usługi. Te kontrole są ważne, aby zapobiec przyznawaniu dostępu do niezamierzonych lub błędnie skonfigurowanych aplikacji klienckich. 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 do Twojej usługi. Jeśli użytkownik nie jest zalogowany, dokończ proces logowania lub rejestracji w usłudze.
3. Wygeneruj kod autoryzacji do użycia w interfejsie API Google. Może to być dowolna wartość ciągu, ale musi ona reprezentować użytkownika, klienta, dla którego token jest przeznaczony, oraz kod wygaśnięcia kodu i nie może on być odgadnięty. Zazwyczaj kody autoryzacji są wystawiane po około 10 minutach.
4. Upewnij się, że adres URL określony w parametrze redirect_uri ma taką postać:

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

5. Przekieruj przeglądarkę użytkownika na adres URL określony w parametrze redirect_uri. Dodając kod autoryzacji i pierwotną, niezmienioną wartość stanu, podczas przekierowywania dodaj parametry code i state. Przykładowy wynikowy adres URL:

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

Obsługa żądań wymiany tokenów

Twój punkt końcowy wymiany tokenów odpowiada za 2 rodzaje giełd tokenów:

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

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

Parametry punktu końcowego wymiany tokenów
client_id	Ciąg znaków identyfikujący żądanie jako Google. Ten ciąg znaków musi być zarejestrowany w Twoim systemie jako unikalny identyfikator Google.
client_secret	Tajny ciąg znaków zarejestrowany przez Ciebie w Google na potrzeby tej usługi.
grant_type	Typ wymiany tokena. authorization_code lub refresh_token.
code	Gdy ten parametr to grant_type=authorization_code, ten kod to kod otrzymany przez Google z punktu końcowego logowania lub wymiany tokena.
redirect_uri	Gdy ten parametr to grant_type=authorization_code, ten adres URL jest używany w początkowym żądaniu autoryzacji.
refresh_token	Gdy grant_type=refresh_token to ten parametr to token odświeżania otrzymany od Google z punktu końcowego wymiany tokenów.

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

Gdy użytkownik się zaloguje, a Twój punkt końcowy autoryzacji zwraca do Google krótki czas kodu autoryzacji, Google wysyła do punktu końcowego wymiany tokena żądanie wymiany kodu 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 przyznanego wcześniej Google. Oto 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 wymienić kody autoryzacji dla tokena dostępu i tokena odświeżania, Twój punkt końcowy Exchange odpowiada na żądania POST, wykonując te czynności:

1. Sprawdź, czy element client_id identyfikuje źródło żądania jako autoryzowane źródło i czy client_secret odpowiada oczekiwanej wartości.
2. Sprawdź, czy kod autoryzacji jest prawidłowy i nie stracił ważności, a identyfikator klienta podany w żądaniu jest zgodny z identyfikatorem klienta powiązanym z kodem autoryzacji.
3. Sprawdź, czy adres URL określony w parametrze redirect_uri jest taki sam jak wartość użyta we wstępnym żądaniu autoryzacji.
4. Jeśli nie możesz zweryfikować wszystkich powyższych kryteriów, zwróć błąd HTTP o złym żądaniu HTTP z informacją {"error": "invalid_grant"} w treści.
5. W innym przypadku użyj identyfikatora użytkownika z kodu autoryzacji, aby wygenerować token odświeżania i token dostępu. Może to być dowolna wartość ciągu, ale musi jednoznacznie reprezentować użytkownika i klienta, którym jest token, i nie może być ich odgadnięcie. W przypadku tokenów dostępu zanotuj też czas ich wygaśnięcia, co zazwyczaj zajmuje godzinę po wydaniu tokena. Tokeny odświeżania nie wygasają.
6. Zwraca ten obiekt JSON w treści odpowiedzi HTTPS:

   {
   "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 użytkownika oraz rejestruje datę jego wygaśnięcia. Po wygaśnięciu tokena dostępu Google używa tokena odświeżania w celu uzyskania nowego tokena dostępu z punktu końcowego wymiany tokena.

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

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

W przypadku tych żądań wartość grant_type to refresh_token, a wartość refresh_token to wartość tokena odświeżania przyznanego wcześniej 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 dla tokena dostępu, punkt końcowy Exchange Exchange odpowiada na żądania POST, wykonując te czynności:

1. Sprawdź, czy element client_id identyfikuje źródło żądania jako Google i czy client_secret odpowiada oczekiwanej wartości.
2. Sprawdź, czy token odświeżania jest prawidłowy i czy identyfikator klienta podany w żądaniu odpowiada identyfikatorowi klienta powiązanego z tokenem odświeżania.
3. Jeśli nie możesz zweryfikować wszystkich powyższych kryteriów, zwróć błąd HTTP 400 (nieprawidłowe żądanie) z wartością {"error": "invalid_grant"} w treści.
4. W innym przypadku użyj identyfikatora użytkownika z tokena odświeżania, aby wygenerować token dostępu. Może to być dowolna wartość ciągu, ale musi być reprezentowana przez użytkownika i klienta, których dotyczy, i nie może być odgadany. W przypadku tokenów dostępu zanotuj też czas ich wygaśnięcia, zwykle godzinę po wydaniu tokena.
5. Zwraca ten obiekt JSON w treści odpowiedzi HTTPS:

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

Obsługiwanie żądań informacji o użytkownikach

Punkt końcowy użytkownika to chroniony zasób OAuth 2.0 zasób, który zwraca roszczenia dotyczące połączonego użytkownika. Implementacja i hostowanie punktu końcowego informacji o użytkowniku są opcjonalne. Wyjątkiem są te przypadki użycia:

• Łączenie kont z Google One.
• Bezproblemowa subskrypcja na Androidzie TV.

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 o profilu z połączonego użytkownika.

nagłówki żądań punktów końcowych użytkownika
Authorization header	Token dostępu typu Bearer.

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 umożliwić punktowi końcowemu obsługi użytkowników obsługę żądań, wykonaj te czynności:

1. Wyodrębnij token dostępu z nagłówka autoryzacji i informacje o użytkowniku powiązanym z tokenem dostępu.
2. Jeśli token dostępu jest nieprawidłowy, zwróć błąd „Brak autoryzacji HTTP” 4 przy użyciu nagłówka odpowiedzi WWW-Authenticate. Poniżej znajduje się przykładowa odpowiedź dotycząca błędu użytkownika:

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

   Jeśli podczas łączenia wystąpi błąd 401 (Brak autoryzacji) lub inna nieudana odpowiedź, błąd nie będzie można odzyskać, natomiast pobrany token zostanie odrzucony, a użytkownik będzie musiał ponownie rozpocząć proces łączenia.

3. Jeśli token dostępu jest prawidłowy, w odpowiedzi na żądanie HTTP zwracany jest kod HTTP 200 z poniższym obiektem JSON:

   {
   "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 deklaracja są rejestrowane na koncie Google użytkownika.

   odpowiedź punktu końcowego (infoinfo)
   sub	Niepowtarzalny identyfikator użytkownika identyfikujący użytkownika w systemie.
   email	Adres e-mail użytkownika.
   given_name	Opcjonalnie: imię użytkownika.
   family_name	Opcjonalnie: nazwisko użytkownika.
   name	Opcjonalnie: imię i nazwisko użytkownika.
   picture	Opcjonalnie: zdjęcie profilowe użytkownika.