Wdrażanie serwera OAuth 2.0

Każda akcja 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 realizacja zostanie przypisana do intencji inteligentnego domu. Google Smart Home obsługuje tylko protokół OAuth z przepływem kodu autoryzacji.

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

Łączenie konta Google za pomocą protokołu 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.

Ten rysunek pokazuje kroki, jakie musi wykonać użytkownik, aby połączyć swoje konto Google z Twoim systemem uwierzytelniania. Pierwszy zrzut ekranu pokazuje inicjowane przez użytkownika połączenie z Twojej platformy. Drugi obraz przedstawia
 zgodę użytkownika i potwierdzenie na potrzeby połączenia konta Google z Twoją aplikacją. Ostatni zrzut ekranu przedstawia konto użytkownika, które jest połączone w aplikacji Google.
Rysunek 1. Łączenie kont: logowanie użytkownika w Google i ekrany zgody.

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

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.