Wdrażanie serwera OAuth 2.0

Każda integracja z Cloud-to-cloud musi zawierać mechanizm uwierzytelniania użytkowników.

Uwierzytelnianie umożliwia Ci łączenie kont Google użytkowników z kontami użytkowników w Twoim systemie uwierzytelniania. Dzięki temu możesz zidentyfikować użytkowników, gdy usługa otrzyma intencję związaną z inteligentnym domem. Usługa Google Smart Home obsługuje OAuth tylko z procesem kodu autoryzacji.

Na tej stronie opisaliśmy, jak skonfigurować serwer OAuth 2.0, aby współpracował z integracją Cloud-to-cloud.

Łączenie konta Google przez 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 na serwerze OAuth 2.0 przepływu kodu autoryzacji składa się z 2 punktów końcowych, które usługa udostępnia przez HTTPS. Pierwszym punktem końcowym jest 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 autoryzują użytkownika do uzyskiwania dostępu do usługi.

Gdy aplikacja Google musi wywołać interfejs API jednej z Twoich usług, Google używa tych punktów końcowych, aby uzyskać od użytkowników zgodę na wywoływanie tych interfejsów API w ich imieniu.

Sesja OAuth 2.0 z kodem autoryzacji inicjowana przez Google ma następujący przepływ:

1. Google otwiera w przeglądarce użytkownika Twój punkt końcowy autoryzacji. Jeśli proces został rozpoczęty na urządzeniu obsługującym tylko polecenia głosowe, Google przeniesie jego wykonanie na telefon.
2. Użytkownik loguje się (jeśli nie jest już zalogowany) i daje Google uprawnienia do dostępu do swoich danych za pomocą Twojego interfejsu API (jeśli nie udzielił już tych uprawnień).
3. Usługa tworzy kod autoryzacji i zwraca go do Google. Aby to zrobić, przekieruj przeglądarkę użytkownika z powrotem do Google z dołączonym do żądania kodem autoryzacji.
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 krótkoterminowy token, który Twoja usługa akceptuje 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 uzyskiwania nowych tokenów dostępu po ich wygaśnięciu.
5. Po zakończeniu przez użytkownika procesu łączenia kont każde kolejne żądanie wysłane z Google będzie zawierać token dostępu.

Obsługa próśb o autoryzację

Gdy musisz połączyć konto za pomocą kodu autoryzacji OAuth 2.0, Google wysyła użytkownika do punktu końcowego autoryzacji z żądaniem zawierającym te parametry:

Jeśli na przykład Twój punkt końcowy autoryzacji jest dostępny pod adresem https://myservice.example.com/auth, prośba 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 odpowiada identyfikatorowi klienta przypisanemu Google, a redirect_uri odpowiada adresowi URL przekierowania podanemu przez Google dla Twojej usługi. Te kontrole są ważne, aby zapobiec przyznawaniu dostępu do aplikacji klienta niepożądanych lub źle skonfigurowanych. 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 w usłudze. Jeśli użytkownik nie jest zalogowany, przeprowadź proces logowania lub rejestracji w usłudze.
3. wygenerować kod autoryzacji, którego Google będzie używać do uzyskiwania dostępu do Twojego interfejsu API. Kod autoryzacji może być dowolną wartością ciągu znaków, ale musi jednoznacznie reprezentować użytkownika, klienta, dla którego przeznaczony jest token, oraz czas jego ważności. Nie może być też łatwy do odgadnięcia. Zazwyczaj wydajesz kody autoryzacyjne, które wygasają po około 10 minutach.
4. Sprawdź, czy adres URL podany w parametrze redirect_uri ma następujący format:

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

5. Przekierowywanie przeglądarki użytkownika na adres URL podany w parametrze redirect_uri. Podczas przekierowania dołącz wygenerowany kod autoryzacji i pierwotną, niezmienioną wartość stanu, dodając parametry code i state. Oto przykładowy adres URL:

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

Obsługa próśb o wymianę tokenów

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

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

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

Konfigurowanie sposobu wysyłania przez Google danych logowania na Twój serwer

W zależności od implementacji serwer autoryzacji oczekuje, że otrzyma dane uwierzytelniające klienta w treści żądania lub w nagłówku żądania.

Domyślnie Google wysyła te dane w treści żądania. Jeśli Twój serwer autoryzacji wymaga, aby dane logowania klienta znajdowały się w nagłówku żądania, musisz odpowiednio skonfigurować integrację Cloud-to-cloud:

Otwórz konsolę programistów

1. Na liście projektów kliknij Otwórz obok projektu, nad którym chcesz pracować.

2. W sekcji Z chmury do chmury wybierz Opracuj.

3. Kliknij Otwórz obok integracji.

4. Przewiń w dół do sekcji Uprawnienia (opcjonalnie) i zaznacz pole wyboru Pozwól Google przesyłać identyfikator klienta i klucz za pomocą nagłówka podstawowego uwierzytelniania HTTP.

5. Kliknij Zapisz, aby zapisać zmiany.

Wymiana kodów autoryzacji na tokeny dostępu i tokeny odświeżania

Gdy użytkownik zaloguje się i punkt końcowy autoryzacji zwróci do Google krótkoterminowy kod autoryzacji, Google wyśle do punktu końcowego wymiany tokenów żądanie wymiany kodu autoryzacji na token dostępu i token odświeżania.

W przypadku tych żądań wartość grant_type to authorization_code, a wartość code to kod autoryzujący, który został wcześniej przekazany Google. Oto przykład żądania wymiany kodu autoryzacji na token dostępu i token 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 reaguje na żądania POST, wykonując te czynności:

1. Sprawdź, czy client_id wskazuje, że źródło żądania jest autoryzowane, oraz czy client_secret odpowiada oczekiwanej wartości.
2. Sprawdź, czy kod autoryzacji jest prawidłowy i czy nie wygasł, a identyfikator klienta podany w żądaniu jest zgodny z identyfikatorem klienta powiązanym z kodem autoryzacji.
3. Sprawdź, czy adres URL podany w parametrze redirect_uri jest identyczny z wartością użytą w pierwotnym żądaniu autoryzacji.
4. Jeśli nie możesz zweryfikować wszystkich powyższych kryteriów, zwracaj błąd HTTP 400 „Bad Request” z wartością {"error": "invalid_grant"} w sekcji treści.
5. W przeciwnym razie użyj identyfikatora użytkownika z kodu autoryzacji, aby wygenerować token odświeżania i token dostępu. Tokeny mogą być dowolnymi ciągami znaków, ale muszą jednoznacznie identyfikować użytkownika i klienta, dla którego są przeznaczone, oraz nie mogą być łatwe do odgadnięcia. W przypadku tokenów dostępu zapisz też czas ich wygaśnięcia, który zwykle wynosi 1 godzinę po wydaniu tokena. Tokeny odświeżania nie wygasają.
6. W treści odpowiedzi HTTPS zwracaj ten obiekt JSON:

   {
   "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 dla użytkownika oraz rejestruje datę wygaśnięcia tokenu dostępu. Gdy token dostępu wygaśnie, Google użyje tokena odświeżania, aby uzyskać nowy token dostępu z punktu końcowego wymiany tokenów.

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

Gdy token dostępu wygaśnie, Google wysyła żądanie do punktu końcowego wymiany tokenów w celu wymiany tokena odświeżania na nowy token dostępu.

W przypadku tych żądań wartość grant_type to refresh_token, a wartość refresh_token to wartość tokena odświeżania, który został wcześniej przyznany 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 na token dostępu, punkt końcowy wymiany tokenów odpowiada na żądania POST, wykonując te czynności:

1. Sprawdź, czy client_id wskazuje, że źródłem żądania jest Google, oraz czy client_secret odpowiada oczekiwanej wartości.
2. Sprawdź, czy token odświeżania jest prawidłowy, a identyfikator klienta podany w żądaniu odpowiada identyfikatorowi klienta powiązanemu z tokenem odświeżania.
3. Jeśli nie możesz zweryfikować wszystkich powyższych kryteriów, zwracaj błąd HTTP 400 Bad Request z wartością {"error": "invalid_grant"} w sekcji treści.
4. W przeciwnym razie użyj identyfikatora użytkownika z tokena odświeżania, aby wygenerować token dostępu. Tokeny mogą być dowolną wartością ciągu znaków, ale muszą jednoznacznie reprezentować użytkownika i klienta, dla którego są przeznaczone, oraz nie mogą być łatwe do odgadnięcia. W przypadku tokenów dostępu należy też zapisać czas ich wygaśnięcia, który zwykle wynosi godzinę od momentu wydania tokenu.
5. W treści odpowiedzi HTTPS zwracaj ten obiekt JSON:

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

Handle userinfo requests

The userinfo endpoint is an OAuth 2.0 protected resource that return claims about the linked user. Implementing and hosting the userinfo endpoint is optional, except for the following use cases:

• Linked Account Sign-In with Google One Tap.
• Frictionless subscription on AndroidTV.

After the access token has been successfully retrieved from your token endpoint, Google sends a request to your userinfo endpoint to retrieve basic profile information about the linked user.

For example, if your userinfo endpoint is available at https://myservice.example.com/userinfo, a request might look like the following:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

For your userinfo endpoint to handle requests, do the following steps:

1. Extract access token from the Authorization header and return information for the user associated with the access token.
2. If the access token is invalid, return an HTTP 401 Unauthorized error with using the WWW-Authenticate Response Header. Below is an example of a userinfo error response:

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

   If a 401 Unauthorized, or any other unsuccessful error response is returned during the linking process, the error will be non-recoverable, the retrieved token will be discarded and the user will have to initiate the linking process again.

3. If the access token is valid, return and HTTP 200 response with the following JSON object in the body of the HTTPS response:

   {
   "sub": "USER_UUID",
   "email": "EMAIL_ADDRESS",
   "given_name": "FIRST_NAME",
   "family_name": "LAST_NAME",
   "name": "FULL_NAME",
   "picture": "PROFILE_PICTURE",
   }

   If your userinfo endpoint returns an HTTP 200 success response, the retrieved token and claims are registered against the user's Google account.

   userinfo endpoint response
   sub	A unique ID that identifies the user in your system.
   email	Email address of the user.
   given_name	Optional: First name of the user.
   family_name	Optional: Last name of the user.
   name	Optional: Full name of the user.
   picture	Optional: Profile picture of the user.