Как реализовать сервер OAuth 2.0

Каждая интеграция Cloud-to-cloud должна включать механизм аутентификации пользователей.

Аутентификация позволяет связать аккаунты Google ваших пользователей с аккаунтами пользователей в вашей системе аутентификации. Это позволяет идентифицировать пользователей, когда выполнение получает намерение умного дома. Умный дом Google поддерживает только OAuth с потоком кода авторизации.

На этой странице описано, как настроить сервер OAuth 2.0 для работы с интеграцией Cloud-to-cloud.

Связывание аккаунта Google с помощью OAuth

При использовании кода авторизации вам понадобятся две конечные точки:

  • Конечная точка авторизации, которая показывает интерфейс входа пользователям, не выполнившим вход. Конечная точка авторизации также создает краткосрочный код авторизации, чтобы зафиксировать согласие пользователей на запрошенный доступ.

  • Конечная точка обмена токенами, которая отвечает за два типа обмена:

    1. Обменивает код авторизации на долгосрочный токен обновления и краткосрочный токен доступа. Этот обмен происходит, когда пользователь проходит процесс связывания аккаунтов.
    2. Обменивает долгосрочный токен обновления на токен доступа с коротким сроком действия. Это происходит, когда Google требуется новый токен доступа, поскольку срок действия предыдущего истек.

Рекомендации по проектированию

В этом разделе описаны требования к дизайну и рекомендации для экрана пользователя, который вы размещаете для потоков связывания OAuth. После вызова из приложения Google ваша платформа показывает пользователю страницу входа в Google и окно запроса доступа для связывания аккаунтов. После того как пользователь даст согласие на связывание аккаунтов, он будет перенаправлен обратно в приложение Google.

На этом рисунке показаны шаги, которые пользователь должен выполнить, чтобы связать свой аккаунт Google с вашей системой аутентификации. На первом скриншоте показано, как пользователь инициирует связывание аккаунтов на вашей платформе. На втором изображении показан вход пользователя в аккаунт Google, а на третьем – согласие пользователя и подтверждение связывания аккаунта Google с вашим приложением. На последнем скриншоте показан успешно связанный аккаунт пользователя в приложении Google.
Рисунок 1. Экраны входа в аккаунт Google и согласия на связывание аккаунтов.

Требования

  1. Вы должны сообщить пользователю, что его аккаунт будет связан с Google, а не с определенным продуктом Google, например Google Home или Google Ассистентом.
  2. Вам необходимо добавить заявление о разрешении для Google, например: "Выполняя вход, вы разрешаете Google управлять вашими устройствами". Ознакомьтесь с разделом Разрешение на управление устройствами Google в Правилах для разработчиков Google Home.
  3. Вы должны открыть страницу связывания Web OAuth и убедиться, что у пользователей есть понятный способ входа в аккаунт Google, например поля для имени пользователя и пароля. Не используйте метод входа с аккаунтом Google (GSI), который позволяет пользователям связывать аккаунты без перехода на страницу связывания через веб-OAuth. Это нарушает правила Google.
  4. На странице связывания OAuth должен быть хотя бы один из следующих элементов, указывающих на интеграцию, с которой связывается пользователь:
    • Логотип компании
    • Название компании
    • Название интеграции
    • Значок приложения

Рекомендации

Мы рекомендуем сделать следующее:

  1. Политика конфиденциальности Google Добавьте ссылку на Политику конфиденциальности Google в окно запроса доступа.

  2. Данные, которыми вы готовы поделиться. Простым и понятным языком объясните пользователю, какие его данные требуются Google и зачем, а также какие данные об использовании или взаимодействии Google может передавать вам.

  3. Четкий призыв к действию. Добавьте на экран согласия четкий призыв к действию, например "Принять и связать". Это необходимо, чтобы пользователи понимали, какими данными они делятся с Google, когда связывают аккаунты.

  4. Возможность отмены. Предоставьте пользователям возможность вернуться назад или отменить действие, если они не хотят связывать аккаунты.

  5. Понятный процесс входа. Убедитесь, что у пользователей есть понятный способ входа в аккаунт Google, например поля для ввода имени пользователя и пароля или кнопка Войти с аккаунтом Google.

  6. Возможность отменить связь. Предоставьте пользователям возможность отменить связь, например URL страницы с настройками аккаунта на вашей платформе. Вы также можете добавить ссылку на аккаунт Google, где пользователи могут управлять связанными аккаунтами. Если пользователь отменит связь с вашей интеграцией, используйте agentUsers.delete, чтобы уведомить Google об этом изменении.

  7. Возможность сменить аккаунт пользователя. Предложите пользователям способ переключения аккаунтов. Это особенно полезно, если у пользователей несколько аккаунтов.

    • Если пользователю нужно закрыть окно запроса доступа, чтобы сменить аккаунт, отправьте в Google устранимую ошибку, чтобы пользователь мог войти в нужный аккаунт с помощью связывания через OAuth.
  8. Добавьте логотип. Показывать логотип компании в окне запроса доступа. Разместите логотип в соответствии с вашим руководством по стилю. Если вы хотите также показывать логотип Google, ознакомьтесь с разделом Логотипы и товарные знаки.

Обработка кода авторизации

Реализация сервера OAuth 2.0 для обработки кода авторизации состоит из двух конечных точек, которые ваш сервис делает доступными по протоколу HTTPS. Первая конечная точка – это конечная точка авторизации, которая отвечает за поиск или получение согласия пользователей на доступ к данным. Конечная точка авторизации показывает интерфейс входа пользователям, которые ещё не вошли в систему, и записывает согласие на запрошенный доступ. Вторая конечная точка используется для обмена токенами. С ее помощью можно получать зашифрованные строки (токены), которые разрешают пользователю доступ к вашему сервису.

Когда приложению Google нужно вызвать один из API вашего сервиса, Google использует эти конечные точки, чтобы получить от пользователей разрешение на вызов API от их имени.

Сеанс обработки кода авторизации OAuth 2.0, инициированный Google, состоит из следующих этапов:

  1. Google открывает конечную точку авторизации в браузере пользователя. Если пользователь начал взаимодействие с Действием на устройстве, которое поддерживает только голосовые команды, Google перенесет выполнение на телефон.
  2. Пользователь входит в аккаунт (если он ещё не вошел) и разрешает Google доступ к своим данным через ваш API (если он ещё не предоставил такое разрешение).
  3. Ваш сервис создает код авторизации и возвращает его Google. Для этого перенаправьте браузер пользователя обратно в Google, прикрепив к запросу код авторизации.
  4. Google отправляет код авторизации на вашу конечную точку обмена токенами, которая проверяет подлинность кода и возвращает токен доступа и токен обновления. Токен доступа – это токен с коротким сроком действия, который ваш сервис принимает в качестве учетных данных для доступа к API. Токен обновления – это долгосрочный токен, который Google может хранить и использовать для получения новых токенов доступа по истечении срока их действия.
  5. После того как пользователь завершит связывание аккаунтов, каждый последующий запрос, отправленный из 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

Чтобы конечная точка авторизации могла обрабатывать запросы на вход, выполните следующие действия:

  1. Убедитесь, что client_id соответствует идентификатору клиента, который вы назначили Google, а redirect_uri – URL переадресации, предоставленному Google для вашего сервиса. Это важно, чтобы не предоставить доступ нежелательным или неправильно настроенным клиентским приложениям. Если вы поддерживаете несколько процессов OAuth 2.0, также убедитесь, что response_type – это code.
  2. Проверьте, вошел ли пользователь в ваш сервис. Если пользователь не вошел в аккаунт, завершите процесс входа или регистрации в сервисе.
  3. Сгенерируйте код авторизации, который Google будет использовать для доступа к вашему API. Код авторизации может быть любым строковым значением, но он должен уникальным образом представлять пользователя, клиента, для которого предназначен токен, и срок действия кода, и его нельзя угадать. Обычно вы выдаете коды авторизации, срок действия которых истекает примерно через 10 минут.
  4. Убедитесь, что URL, указанный в параметре redirect_uri, имеет следующий формат:
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
      https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
      
  5. Перенаправьте браузер пользователя на 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:

Перейти в Developer Console

  1. В списке проектов нажмите Open (Открыть) рядом с нужным проектом.

  2. В разделе Cloud-to-Cloud выберите Develop (Разработка).

  3. Нажмите Open (Открыть) рядом с нужной интеграцией.

  4. Перейдите в раздел Permissions (optional) (Разрешения (необязательно)) и установите флажок Have Google transmit Client ID and secret via HTTP basic auth header (Разрешить Google передавать идентификатор клиента и секретный код через заголовок базовой аутентификации HTTP).

  5. Нажмите Сохранить.

Обмен кодов авторизации на токены доступа и токены обновления

После того как пользователь выполнит вход и ваша конечная точка авторизации вернет 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, выполняя следующие действия:

  1. Убедитесь, что client_id идентифицирует источник запроса как авторизованный источник и что client_secret соответствует ожидаемому значению.
  2. Убедитесь, что код авторизации действителен и не просрочен, а идентификатор клиента, указанный в запросе, совпадает с идентификатором клиента, связанным с кодом авторизации.
  3. Убедитесь, что URL, указанный в параметре redirect_uri, совпадает со значением, которое использовалось в исходном запросе на авторизацию.
  4. Если вы не можете проверить все перечисленные выше критерии, верните ошибку HTTP 400 Bad Request с телом {"error": "invalid_grant"}.
  5. В противном случае используйте идентификатор пользователя из кода авторизации, чтобы сгенерировать токен обновления и токен доступа. Токены могут быть любыми строковыми значениями, но они должны уникальным образом представлять пользователя и клиента, для которых предназначены, и их должно быть невозможно угадать. Для токенов доступа также запишите время окончания срока действия токена, которое обычно наступает через час после его выпуска. Срок действия токенов обновления не ограничен.
  6. Верните следующий объект 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, выполняя следующие действия:

  1. Убедитесь, что в поле client_id указано, что запрос поступил от Google, а в поле client_secret – ожидаемое значение.
  2. Убедитесь, что токен обновления действителен и что идентификатор клиента, указанный в запросе, совпадает с идентификатором клиента, связанным с токеном обновления.
  3. Если вы не можете проверить все перечисленные выше критерии, верните ошибку HTTP 400 Bad Request с телом {"error": "invalid_grant"}.
  4. В противном случае используйте идентификатор пользователя из токена обновления, чтобы сгенерировать токен доступа. Эти токены могут быть любым строковым значением, но они должны уникальным образом представлять пользователя и клиента, для которого предназначен токен, и их нельзя угадать. Для токенов доступа также запишите время окончания срока действия токена, обычно через час после его выдачи.
  5. Верните следующий объект JSON в теле HTTPS-ответа:
    {
    "token_type": "Bearer",
    "access_token": "ACCESS_TOKEN",
    "expires_in": SECONDS_TO_EXPIRATION
    }

Обработка запросов userinfo

Конечная точка userinfo – это защищенный ресурс OAuth 2.0, который возвращает утверждения о связанном пользователе. Реализация и размещение конечной точки userinfo не обязательны, за исключением следующих случаев:

После того как токен доступа будет получен из конечной точки токена, 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 могла обрабатывать запросы, выполните следующие действия:

  1. Извлеките токен доступа из заголовка авторизации и верните информацию о пользователе, связанном с токеном доступа.
  2. Если токен доступа недействителен, верните ошибку HTTP 401 Unauthorized, используя заголовок ответа WWW-Authenticate. Ниже приведен пример ответа с ошибкой userinfo:
    HTTP/1.1 401 Unauthorized
    WWW-Authenticate: error="invalid_token",
    error_description="The Access Token expired"
    
    Если во время связывания аккаунтов возвращается ошибка 401 Unauthorized или любая другая ошибка, она будет считаться неисправимой, полученный токен будет удален, а пользователю придется заново инициировать процесс связывания.
  3. Если токен доступа действителен, верните ответ HTTP 200 со следующим объектом JSON в теле ответа HTTPS:

    {
    "sub": "USER_UUID",
    "email": "EMAIL_ADDRESS",
    "given_name": "FIRST_NAME",
    "family_name": "LAST_NAME",
    "name": "FULL_NAME",
    "picture": "PROFILE_PICTURE",
    }
    Если конечная точка userinfo возвращает ответ об успешном выполнении HTTP 200, полученный токен и утверждения регистрируются в аккаунте Google пользователя.

    Ответ конечной точки userinfo
    sub Уникальный идентификатор пользователя в вашей системе.
    email Адрес электронной почты пользователя.
    given_name Необязательно. Имя пользователя.
    family_name Optional: Last name of the user.
    name Optional (Необязательно) – полное имя пользователя.
    picture Необязательно. Фото профиля пользователя.