Wdrażanie serwera OAuth 2.0

Każde działanie smart home musi zawierać mechanizm obsługujący funkcję uwierzytelnianie użytkowników.

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

Na tej stronie dowiesz się, jak skonfigurować serwer OAuth 2.0 tak, by działał Twoja akcja smart home.

Łączenie konta Google z użyciem 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.

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 procesu kodu autoryzacji na serwerze OAuth 2.0 składa się z tych elementów: dwa punkty końcowe, które Twoja usługa udostępnia przez HTTPS. Pierwszy punkt końcowy to punkt końcowy autoryzacji, który odpowiada za znalezienie lub uzyskanie zgody użytkowników na dostęp do danych. Punkt końcowy autoryzacji przedstawia niezalogowanym użytkownikom i rejestrujący zgodę na o dostęp, którego dotyczy prośba. Drugi punkt końcowy to punkt końcowy wymiany tokenów, jest używany do uzyskiwania zaszyfrowanych ciągów znaków (nazywanych tokenami), które upoważniają użytkownika do dostęp do usługi.

Gdy aplikacja Google musi wywołać jeden z interfejsów API Twojej usługi, te punkty końcowe razem, 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 ma następujący przepływ:

1. Google otworzy punkt końcowy autoryzacji w przeglądarce użytkownika. Jeśli przepływ na urządzeniu z włączonym głosem dla akcji, Google przesyła na telefon.
2. Użytkownik loguje się (jeśli jeszcze nie jest zalogowany) i zezwala Google na uzyskać dostęp do swoich danych za pomocą Twojego interfejsu API, jeśli nie przyznał on jeszcze odpowiednich uprawnień.
3. Usługa tworzy kod autoryzacji i zwraca go do Google. Do zrobienia więc przekieruj przeglądarkę użytkownika z powrotem do Google, podając kod autoryzacji do żądania.
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 token o ograniczonym czasie ważności, który jest blokowany to dane logowania umożliwiające dostęp do interfejsów API. Token odświeżania jest trwały który Google może przechowywać i wykorzystywać do pozyskiwania nowych tokenów dostępu, gdy tracą ważność.
5. Gdy użytkownik zakończy proces łączenia kont, każdy kolejny żądanie wysłane z Google zawiera token dostępu.

Obsługa żądań autoryzacji

Gdy chcesz połączyć konta, korzystając z kodu autoryzacji OAuth 2.0 Google wysyła użytkownika do punktu końcowego autoryzacji z żądaniem, które zawiera następujące parametry:

Parametry punktu końcowego autoryzacji
client_id	Identyfikator klienta przypisany przez Ciebie do Google.
redirect_uri	Adres URL, na który została wysłana odpowiedź na to żądanie.
state	wartości księgowej, która jest przesyłana do Google bez zmian w identyfikator URI przekierowania.
scope	Opcjonalnie: rozdzielany spacjami zestaw ciągów tekstowych zakresu, które określają danych, w przypadku których Google żąda autoryzacji.
response_type	Typ wartości do zwrócenia w odpowiedzi. Protokół OAuth 2.0 przepływu kodu autoryzacji, typ odpowiedzi to zawsze code.
user_locale	Ustawienia języka konta Google w RFC5646 używany do lokalizowania treści na język preferowany przez użytkownika.

Jeśli na przykład punkt końcowy autoryzacji jest dostępny pod adresem 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 mógł obsługiwać żądania logowania, wykonaj te czynności kroki:

1. Sprawdź, czy identyfikator client_id jest zgodny z identyfikatorem klienta przypisanym do Google i czy redirect_uri odpowiada adresowi URL przekierowania dostarczonemu przez Google dla Twojej usługi. Te kontrole są ważne, ponieważ uniemożliwiają przyznawanie dostępu do niezamierzonych lub błędnie skonfigurowanych aplikacji klienckich. Jeśli obsługujesz kilka dla przepływów OAuth 2.0, sprawdź też, czy response_type to code.
2. Sprawdź, czy użytkownik jest zalogowany w Twojej usłudze. Jeśli użytkownik nie jest zalogowany, zalogować się w usłudze lub zarejestrować się w niej.
3. Wygeneruj kod autoryzacji, którego Google będzie używać do uzyskiwania dostępu do Twojego interfejsu API. Kod autoryzacji może być dowolnym ciągiem znaków, ale musi być unikalny reprezentuje użytkownika, klienta, dla którego jest przeznaczony token, i datę ważności kodu. i nie może być odgadywany. Zwykle zajmujesz się autoryzacją które wygasają po około 10 minutach.
4. Sprawdź, czy adres URL określony przez parametr redirect_uri zawiera parametr ten formularz:

     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 do adresu URL określonego w atrybucie redirect_uri. Dołącz kod autoryzacji właśnie wygenerowano oraz pierwotną, niezmodyfikowaną wartość stanu w przypadku przekierowania. , dołączając parametry code i state. Oto przykład otrzymanego adresu URL:

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

Obsługa żądań wymiany tokenów

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

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

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

Parametry punktu końcowego wymiany tokenów
client_id	Ciąg tekstowy identyfikujący źródło żądania jako Google. Ten ciąg musi: być zarejestrowany w Twoim systemie jako unikalny identyfikator Google.
client_secret	Ciąg znaków tajny zarejestrowany w Google na potrzeby usługi.
grant_type	Typ wymienianego tokena. Jest albo authorization_code lub refresh_token.
code	Jeśli parametr ma wartość grant_type=authorization_code, tym parametrem jest kod otrzymany przez Google z Twojego loginu lub wymiany tokenów punktu końcowego.
redirect_uri	Jeśli parametr ma wartość grant_type=authorization_code, tym parametrem jest Adres URL użyty w wstępnym żądaniu autoryzacji.
refresh_token	Jeśli parametr ma wartość grant_type=refresh_token, tym parametrem jest odśwież token odebrany przez 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 punkt końcowy autoryzacji zwróci krótkotrwały błąd kod autoryzacji do Google, wyślemy żądanie do systemu wymiany tokenów punktu końcowego do wymiany kodu autoryzacji na token dostępu i odświeżenia token.

Dla tych żądań wartość grant_type wynosi authorization_code, a parametr wartość code to wartość wcześniej przypisanego kodu autoryzacji o korzystaniu. Oto przykład żądania wymiany 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 na token dostępu i token odświeżania, Punkt końcowy wymiany tokenów odpowiada na żądania POST, wykonując to kroki:

1. Sprawdź, czy client_id identyfikuje źródło żądania jako autoryzowane origin oraz że client_secret jest zgodny z oczekiwaną wartością.
2. Sprawdź, czy kod autoryzacji jest prawidłowy i nie stracił ważności Client-ID określony w żądaniu jest zgodny z identyfikatorem klienta powiązanym z kodu autoryzacji.
3. Sprawdź, czy adres URL określony przez parametr redirect_uri jest identyczny do wartości użytej we wstępnym żądaniu autoryzacji.
4. Jeśli nie możesz sprawdzić wszystkich powyższych kryteriów, zwróć żądanie HTTP Błąd 400 Nieprawidłowe żądanie z treścią {"error": "invalid_grant"}.
5. W innym przypadku użyj identyfikatora użytkownika z kodu autoryzacji, aby wygenerować odświeżenie token i token dostępu. Tokenami mogą być dowolne wartości ciągu znaków, ale musi jednoznacznie reprezentować użytkownika i klienta, dla którego jest przeznaczony token. muszą być trudne do odgadnięcia. W przypadku tokenów dostępu zanotuj również zazwyczaj w ciągu godziny od jego wydania. Tokeny odświeżania nie tracą ważności.
6. Zwróć następujący 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 oraz token odświeżania użytkownika i rekordów wygaśnięcie tokenu dostępu. Po wygaśnięciu tokena dostępu Google używa token odświeżania, aby uzyskać nowy token dostępu z punktu końcowego wymiany tokenów.

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

Gdy token dostępu wygaśnie, Google wysyła żądanie do systemu wymiany tokenów w punkcie końcowym, aby wymienić token odświeżania na nowy token dostępu.

W przypadku tych żądań wartość grant_type wynosi refresh_token, a wartość z refresh_token to wartość tokena odświeżania, który został przez Ciebie wcześniej przydzielony Google. Poniżej znajdziesz przykład żądania wymiany tokena odświeżania dla tokena 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 można było 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 identyfikuje źródło żądania jako Google oraz że client_secret jest zgodna z oczekiwaną wartością.
2. Sprawdź, czy token odświeżania jest prawidłowy i czy identyfikator klienta określony w żądanie pasuje do identyfikatora klienta powiązanego z tokenem odświeżania.
3. Jeśli nie możesz sprawdzić wszystkich powyższych kryteriów, zwróć kod HTTP 400 Błąd nieprawidłowego żądania z treścią {"error": "invalid_grant"}.
4. W przeciwnym razie użyj identyfikatora użytkownika z tokena odświeżania, aby wygenerować dostęp token. Tokeny te mogą mieć dowolną wartość w postaci ciągu, ale muszą być unikatowe reprezentują użytkownika i klienta, dla którego jest przeznaczony token. Nie mogą zgadywać. W przypadku tokenów dostępu zanotuj też czas ich ważności. zwykle godzinę po wydaniu tokena.
5. Zwróć następujący obiekt JSON w treści protokołu HTTPS odpowiedź:

   {
   "token_type": "Nośnik",
   "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.