Каждая интеграция Cloud-to-cloud должна включать механизм аутентификации пользователей.
Аутентификация позволяет связать аккаунты Google ваших пользователей с аккаунтами пользователей в вашей системе аутентификации. Это позволяет идентифицировать пользователей, когда выполнение получает намерение умного дома. Умный дом Google поддерживает только OAuth с потоком кода авторизации.
На этой странице описано, как настроить сервер OAuth 2.0 для работы с интеграцией Cloud-to-cloud.
Связывание аккаунта Google с помощью OAuth
При использовании кода авторизации вам понадобятся две конечные точки:
Конечная точка авторизации, которая показывает интерфейс входа пользователям, не выполнившим вход. Конечная точка авторизации также создает краткосрочный код авторизации, чтобы зафиксировать согласие пользователей на запрошенный доступ.
Конечная точка обмена токенами, которая отвечает за два типа обмена:
- Обменивает код авторизации на долгосрочный токен обновления и краткосрочный токен доступа. Этот обмен происходит, когда пользователь проходит процесс связывания аккаунтов.
- Обменивает долгосрочный токен обновления на токен доступа с коротким сроком действия. Это происходит, когда Google требуется новый токен доступа, поскольку срок действия предыдущего истек.
Рекомендации по проектированию
В этом разделе описаны требования к дизайну и рекомендации для экрана пользователя, который вы размещаете для потоков связывания OAuth. После вызова из приложения Google ваша платформа показывает пользователю страницу входа в Google и окно запроса доступа для связывания аккаунтов. После того как пользователь даст согласие на связывание аккаунтов, он будет перенаправлен обратно в приложение Google.
Требования
- Вы должны сообщить пользователю, что его аккаунт будет связан с Google, а не с определенным продуктом Google, например Google Home или Google Ассистентом.
- Вам необходимо добавить заявление о разрешении для Google, например: "Выполняя вход, вы разрешаете Google управлять вашими устройствами". Ознакомьтесь с разделом Разрешение на управление устройствами Google в Правилах для разработчиков Google Home.
- Вы должны открыть страницу связывания Web OAuth и убедиться, что у пользователей есть понятный способ входа в аккаунт Google, например поля для имени пользователя и пароля. Не используйте метод входа с аккаунтом Google (GSI), который позволяет пользователям связывать аккаунты без перехода на страницу связывания через веб-OAuth. Это нарушает правила Google.
- На странице связывания OAuth должен быть хотя бы один из следующих элементов, указывающих на интеграцию, с которой связывается пользователь:
- Логотип компании
- Название компании
- Название интеграции
- Значок приложения
Рекомендации
Мы рекомендуем сделать следующее:
Политика конфиденциальности Google Добавьте ссылку на Политику конфиденциальности Google в окно запроса доступа.
Данные, которыми вы готовы поделиться. Простым и понятным языком объясните пользователю, какие его данные требуются Google и зачем, а также какие данные об использовании или взаимодействии Google может передавать вам.
Четкий призыв к действию. Добавьте на экран согласия четкий призыв к действию, например "Принять и связать". Это необходимо, чтобы пользователи понимали, какими данными они делятся с Google, когда связывают аккаунты.
Возможность отмены. Предоставьте пользователям возможность вернуться назад или отменить действие, если они не хотят связывать аккаунты.
Понятный процесс входа. Убедитесь, что у пользователей есть понятный способ входа в аккаунт Google, например поля для ввода имени пользователя и пароля или кнопка Войти с аккаунтом Google.
Возможность отменить связь. Предоставьте пользователям возможность отменить связь, например URL страницы с настройками аккаунта на вашей платформе. Вы также можете добавить ссылку на аккаунт Google, где пользователи могут управлять связанными аккаунтами. Если пользователь отменит связь с вашей интеграцией, используйте
agentUsers.delete, чтобы уведомить Google об этом изменении.Возможность сменить аккаунт пользователя. Предложите пользователям способ переключения аккаунтов. Это особенно полезно, если у пользователей несколько аккаунтов.
- Если пользователю нужно закрыть окно запроса доступа, чтобы сменить аккаунт, отправьте в Google устранимую ошибку, чтобы пользователь мог войти в нужный аккаунт с помощью связывания через OAuth.
Добавьте логотип. Показывать логотип компании в окне запроса доступа. Разместите логотип в соответствии с вашим руководством по стилю. Если вы хотите также показывать логотип Google, ознакомьтесь с разделом Логотипы и товарные знаки.
Обработка кода авторизации
Реализация сервера OAuth 2.0 для обработки кода авторизации состоит из двух конечных точек, которые ваш сервис делает доступными по протоколу HTTPS. Первая конечная точка – это конечная точка авторизации, которая отвечает за поиск или получение согласия пользователей на доступ к данным. Конечная точка авторизации показывает интерфейс входа пользователям, которые ещё не вошли в систему, и записывает согласие на запрошенный доступ. Вторая конечная точка используется для обмена токенами. С ее помощью можно получать зашифрованные строки (токены), которые разрешают пользователю доступ к вашему сервису.
Когда приложению Google нужно вызвать один из API вашего сервиса, Google использует эти конечные точки, чтобы получить от пользователей разрешение на вызов API от их имени.
Сеанс обработки кода авторизации OAuth 2.0, инициированный Google, состоит из следующих этапов:
- Google открывает конечную точку авторизации в браузере пользователя. Если пользователь начал взаимодействие с Действием на устройстве, которое поддерживает только голосовые команды, Google перенесет выполнение на телефон.
- Пользователь входит в аккаунт (если он ещё не вошел) и разрешает Google доступ к своим данным через ваш API (если он ещё не предоставил такое разрешение).
- Ваш сервис создает код авторизации и возвращает его Google. Для этого перенаправьте браузер пользователя обратно в Google, прикрепив к запросу код авторизации.
- Google отправляет код авторизации на вашу конечную точку обмена токенами, которая проверяет подлинность кода и возвращает токен доступа и токен обновления. Токен доступа – это токен с коротким сроком действия, который ваш сервис принимает в качестве учетных данных для доступа к API. Токен обновления – это долгосрочный токен, который Google может хранить и использовать для получения новых токенов доступа по истечении срока их действия.
- После того как пользователь завершит связывание аккаунтов, каждый последующий запрос, отправленный из Google, будет содержать токен доступа.
Как обрабатывать запросы на авторизацию
Когда вам нужно связать аккаунты с помощью обработки кода авторизации OAuth 2.0, Google направляет пользователя к вашей конечной точке авторизации с запросом, который включает следующие параметры:
| Параметры конечной точки авторизации | |
|---|---|
client_id |
Идентификатор клиента, который вы назначили Google. |
redirect_uri |
URL, на который вы отправляете ответ на этот запрос. |
state |
Значение, которое возвращается в Google без изменений в URI переадресации. |
scope |
Необязательно. Набор строк области действия, разделенных пробелами, которые указывают данные, для которых Google запрашивает авторизацию. |
response_type |
Тип значения, которое нужно вернуть в ответе. Для обработки кода авторизации OAuth 2.0 типом ответа всегда является code.
|
Например, если конечная точка авторизации доступна по адресу https://myservice.example.com/auth, запрос может выглядеть следующим образом:
GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&scope=REQUESTED_SCOPES&response_type=code
Чтобы конечная точка авторизации могла обрабатывать запросы на вход, выполните следующие действия:
- Убедитесь, что
client_idсоответствует идентификатору клиента, который вы назначили Google, аredirect_uri– URL переадресации, предоставленному Google для вашего сервиса. Это важно, чтобы не предоставить доступ нежелательным или неправильно настроенным клиентским приложениям. Если вы поддерживаете несколько процессов OAuth 2.0, также убедитесь, чтоresponse_type– этоcode. - Проверьте, вошел ли пользователь в ваш сервис. Если пользователь не вошел в аккаунт, завершите процесс входа или регистрации в сервисе.
- Сгенерируйте код авторизации, который Google будет использовать для доступа к вашему API. Код авторизации может быть любым строковым значением, но он должен уникальным образом представлять пользователя, клиента, для которого предназначен токен, и срок действия кода, и его нельзя угадать. Обычно вы выдаете коды авторизации, срок действия которых истекает примерно через 10 минут.
- Убедитесь, что URL, указанный в параметре
redirect_uri, имеет следующий формат:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
- Перенаправьте браузер пользователя на URL, указанный в параметре
redirect_uri. При перенаправлении добавьте в URL код авторизации, который вы только что сгенерировали, и исходное неизмененное значение состояния, используя параметрыcodeиstate. Ниже приведен пример итогового URL:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING
Обработка запросов на обмен токенов
Конечная точка обмена токенами вашего сервиса отвечает за два вида обмена токенами:
- Обмен кодов авторизации на токены доступа и токены обновления
- Обмен токенов обновления на токены доступа
Запросы на обмен токенов включают следующие параметры:
| Параметры конечной точки обмена токенами | |
|---|---|
client_id |
Строка, которая указывает, что запрос поступил от Google. Эта строка должна быть зарегистрирована в вашей системе как уникальный идентификатор Google. |
client_secret |
Секретная строка, которую вы зарегистрировали в Google для своего сервиса. |
grant_type |
Тип токена, который обменивается. Возможные значения: authorization_code или refresh_token. |
code |
Если grant_type=authorization_code, этот параметр содержит код, полученный Google от конечной точки входа или обмена токенами. |
redirect_uri |
Если grant_type=authorization_code, этот параметр представляет собой URL, используемый в первоначальном запросе авторизации. |
refresh_token |
Если grant_type=refresh_token, этот параметр является токеном обновления, который Google получил от вашей конечной точки обмена токенами. |
Настройте отправку учетных данных на ваш сервер
В зависимости от реализации сервер авторизации ожидает получить учетные данные клиента либо в теле запроса, либо в заголовке запроса.
По умолчанию Google отправляет учетные данные в теле запроса. Если сервер авторизации требует, чтобы учетные данные клиента были в заголовке запроса, необходимо соответствующим образом настроить интеграцию Cloud-to-cloud:
В списке проектов нажмите Open (Открыть) рядом с нужным проектом.
В разделе Cloud-to-Cloud выберите Develop (Разработка).
Нажмите Open (Открыть) рядом с нужной интеграцией.
Перейдите в раздел Permissions (optional) (Разрешения (необязательно)) и установите флажок Have Google transmit Client ID and secret via HTTP basic auth header (Разрешить Google передавать идентификатор клиента и секретный код через заголовок базовой аутентификации HTTP).
Нажмите Сохранить.
Обмен кодов авторизации на токены доступа и токены обновления
После того как пользователь выполнит вход и ваша конечная точка авторизации вернет Google краткосрочный код авторизации, Google отправит запрос к вашей конечной точке обмена токенов, чтобы обменять код авторизации на токен доступа и токен обновления.
В таких запросах значение grant_type – authorization_code, а значение code – это код авторизации, который вы ранее предоставили Google. Ниже приведен пример запроса на обмен кода авторизации на токен доступа и токен обновления.
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
Чтобы обменять коды авторизации на токен доступа и токен обновления, конечная точка обмена токенами отвечает на запросы POST, выполняя следующие действия:
- Убедитесь, что
client_idидентифицирует источник запроса как авторизованный источник и чтоclient_secretсоответствует ожидаемому значению. - Убедитесь, что код авторизации действителен и не просрочен, а идентификатор клиента, указанный в запросе, совпадает с идентификатором клиента, связанным с кодом авторизации.
- Убедитесь, что URL, указанный в параметре
redirect_uri, совпадает со значением, которое использовалось в исходном запросе на авторизацию. - Если вы не можете проверить все перечисленные выше критерии, верните ошибку HTTP 400 Bad Request с телом
{"error": "invalid_grant"}. - В противном случае используйте идентификатор пользователя из кода авторизации, чтобы сгенерировать токен обновления и токен доступа. Токены могут быть любыми строковыми значениями, но они должны уникальным образом представлять пользователя и клиента, для которых предназначены, и их должно быть невозможно угадать. Для токенов доступа также запишите время окончания срока действия токена, которое обычно наступает через час после его выпуска. Срок действия токенов обновления не ограничен.
- Верните следующий объект JSON в теле HTTPS-ответа:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "refresh_token": "REFRESH_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
Google сохраняет токен доступа и токен обновления для пользователя и записывает срок действия токена доступа. Когда срок действия токена доступа истекает, Google использует токен обновления, чтобы получить новый токен доступа от конечной точки обмена токенами.
Обмен токенов обновления на токены доступа
Когда срок действия токена доступа истекает, Google отправляет запрос на конечную точку обмена токенами, чтобы обменять токен обновления на новый токен доступа.
В таких запросах значением grant_type является refresh_token, а значением refresh_token – значение токена обновления, который вы ранее предоставили Google. Ниже приведен пример запроса на обмен токена обновления на токен доступа.
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
Чтобы обменять токен обновления на токен доступа, конечная точка обмена токенами отвечает на запросы POST, выполняя следующие действия:
- Убедитесь, что в поле
client_idуказано, что запрос поступил от Google, а в полеclient_secret– ожидаемое значение. - Убедитесь, что токен обновления действителен и что идентификатор клиента, указанный в запросе, совпадает с идентификатором клиента, связанным с токеном обновления.
- Если вы не можете проверить все перечисленные выше критерии, верните ошибку HTTP 400 Bad Request с телом
{"error": "invalid_grant"}. - В противном случае используйте идентификатор пользователя из токена обновления, чтобы сгенерировать токен доступа. Эти токены могут быть любым строковым значением, но они должны уникальным образом представлять пользователя и клиента, для которого предназначен токен, и их нельзя угадать. Для токенов доступа также запишите время окончания срока действия токена, обычно через час после его выдачи.
- Верните следующий объект JSON в теле HTTPS-ответа:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
Обработка запросов userinfo
Конечная точка userinfo – это защищенный ресурс OAuth 2.0, который возвращает утверждения о связанном пользователе. Реализация и размещение конечной точки userinfo не обязательны, за исключением следующих случаев:
- Вход через связанный аккаунт с помощью Google One Tap.
- Подписки на сторонние сервисы на Android TV.
После того как токен доступа будет получен из конечной точки токена, Google отправит запрос в конечную точку userinfo, чтобы получить основные данные профиля связанного пользователя.
| Заголовки запроса конечной точки userinfo | |
|---|---|
Authorization header |
Токен доступа типа Bearer. |
Например, если конечная точка userinfo доступна по адресу https://myservice.example.com/userinfo, запрос может выглядеть следующим образом:
GET /userinfo HTTP/1.1 Host: myservice.example.com Authorization: Bearer ACCESS_TOKEN
Чтобы конечная точка userinfo могла обрабатывать запросы, выполните следующие действия:
- Извлеките токен доступа из заголовка авторизации и верните информацию о пользователе, связанном с токеном доступа.
- Если токен доступа недействителен, верните ошибку HTTP 401 Unauthorized, используя заголовок ответа
WWW-Authenticate. Ниже приведен пример ответа с ошибкой userinfo: Если во время связывания аккаунтов возвращается ошибка 401 Unauthorized или любая другая ошибка, она будет считаться неисправимой, полученный токен будет удален, а пользователю придется заново инициировать процесс связывания.HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"
Если токен доступа действителен, верните ответ HTTP 200 со следующим объектом JSON в теле ответа HTTPS:
Если конечная точка userinfo возвращает ответ об успешном выполнении HTTP 200, полученный токен и утверждения регистрируются в аккаунте Google пользователя.{ "sub": "USER_UUID", "email": "EMAIL_ADDRESS", "given_name": "FIRST_NAME", "family_name": "LAST_NAME", "name": "FULL_NAME", "picture": "PROFILE_PICTURE", }Ответ конечной точки userinfo subУникальный идентификатор пользователя в вашей системе. emailАдрес электронной почты пользователя. given_nameНеобязательно. Имя пользователя. family_nameOptional: Last name of the user. nameOptional (Необязательно) – полное имя пользователя. pictureНеобязательно. Фото профиля пользователя.