Witamy w Google Home Developer Center – nowym miejscu, gdzie możesz dowiedzieć się, jak tworzyć inteligentne działania domowe. Uwaga: nadal będziesz tworzyć działania w konsoli Actions.

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.

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.
Wstecz
Lista kontrolna dla programistów
Dalej
Tworzenie projektu w Actions