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:
- 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.
- 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ł.
- 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.
- 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ą.
- 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:
- Sprawdź, czy
client_id
zgadza się z identyfikatorem klienta przypisanym do Google, aredirect_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ż, czyresponse_type
tocode
. - 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.
- 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.
- 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
- 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 parametrycode
istate
. 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:
- Sprawdź, czy element
client_id
identyfikuje źródło żądania jako autoryzowane źródło i czyclient_secret
odpowiada oczekiwanej wartości. - 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.
- Sprawdź, czy adres URL określony w parametrze
redirect_uri
jest taki sam jak wartość użyta we wstępnym żądaniu autoryzacji. - 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. - 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ą.
- 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:
- Sprawdź, czy element
client_id
identyfikuje źródło żądania jako Google i czyclient_secret
odpowiada oczekiwanej wartości. - 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.
- 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. - 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.
- 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:
- Wyodrębnij token dostępu z nagłówka autoryzacji i informacje o użytkowniku powiązanym z tokenem dostępu.
- 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. 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.