Учетные записи связаны с использованием неявных потоков кода авторизации и неявных потоков OAuth 2.0, являющихся отраслевым стандартом. Ваша служба должна поддерживать конечные точки авторизации и обмена токенами, совместимые с OAuth 2.0.
В неявном потоке Google открывает вашу конечную точку авторизации в браузере пользователя. После успешного входа вы возвращаете долговременный токен доступа в Google. Этот токен доступа теперь включается в каждый запрос, отправляемый из Google.
В потоке кода авторизации вам нужны две конечные точки:
Конечная точка авторизации , которая представляет пользовательский интерфейс для входа пользователям, которые еще не вошли в систему. Конечная точка авторизации также создает кратковременный код авторизации для записи согласия пользователей на запрошенный доступ.
Конечная точка обмена токенами, которая отвечает за два типа обмена:
- Обменивает код авторизации на долгоживущий токен обновления и недолговечный токен доступа. Этот обмен происходит, когда пользователь проходит процесс связывания учетной записи.
- Заменяет долгоживущий токен обновления на недолговечный токен доступа. Этот обмен происходит, когда Google нужен новый токен доступа, потому что срок его действия истек.
Выберите поток OAuth 2.0
Хотя неявный поток реализовать проще, Google рекомендует, чтобы токены доступа, выдаваемые неявным потоком, никогда не истекали. Это связано с тем, что пользователь вынужден снова связать свою учетную запись после истечения срока действия токена с неявным потоком. Если вам требуется истечение срока действия токена по соображениям безопасности, мы настоятельно рекомендуем вместо этого использовать поток кода авторизации .
Рекомендации по дизайну
В этом разделе описаны требования к дизайну и рекомендации для экрана пользователя, который вы размещаете для потоков связывания OAuth. После вызова приложением Google на вашей платформе отображается страница входа в Google и экран согласия учетной записи, связывающий пользователя с пользователем. Пользователь возвращается в приложение Google после того, как дает свое согласие на связывание учетных записей.
![На этом рисунке показаны шаги, необходимые пользователю для привязки своей учетной записи Google к вашей системе аутентификации. На первом снимке экрана показана ссылка, инициированная пользователем с вашей платформы. На втором изображении показан вход пользователя в Google, а на третьем показано согласие и подтверждение пользователя для привязки его учетной записи Google к вашему приложению. На последнем снимке экрана показана успешно связанная учетная запись пользователя в приложении Google.](https://developers-dot-devsite-v2-prod.appspot.com/static/identity/images/oauth-linking-flow.png?authuser=7&hl=ru)
Требования
- Вы должны сообщить, что учетная запись пользователя будет связана с Google, а не с конкретным продуктом Google, таким как Google Home или Google Assistant.
Рекомендации
Мы рекомендуем вам сделать следующее:
Показать Политику конфиденциальности Google. Включите ссылку на Политику конфиденциальности Google на экране согласия.
Данные для совместного использования. Используйте четкий и лаконичный язык, чтобы сообщить пользователю, какие данные требуются Google и почему.
Четкий призыв к действию. Сформулируйте четкий призыв к действию на экране согласия, например «Согласиться и дать ссылку». Это связано с тем, что пользователи должны понимать, какими данными они должны делиться с Google, чтобы связать свои учетные записи.
Возможность отмены. Предоставьте пользователям возможность вернуться или отменить, если они решат не связываться.
Очистить процесс входа. Убедитесь, что у пользователей есть четкий способ входа в свою учетную запись Google, например поля для имени пользователя и пароля или Войти с помощью Google .
Возможность отвязать. Предложите пользователям механизм отмены связи, например URL-адрес их настроек учетной записи на вашей платформе. Кроме того, вы можете включить ссылку на учетную запись Google , где пользователи могут управлять своей связанной учетной записью.
Возможность смены учетной записи пользователя. Предложите пользователям способ переключения их учетных записей. Это особенно полезно, если пользователи склонны иметь несколько учетных записей.
- Если пользователю необходимо закрыть экран согласия для переключения учетных записей, отправьте в Google устранимую ошибку, чтобы пользователь мог войти в нужную учетную запись с помощью привязки OAuth и неявного потока.
Включите свой логотип. Отобразите логотип вашей компании на экране согласия. Используйте свои рекомендации по стилю, чтобы разместить свой логотип. Если вы хотите также отобразить логотип Google, см. раздел Логотипы и товарные знаки .
![На этом рисунке показаны примеры экранов входа и согласия пользователя с вызовами отдельных требований и рекомендаций, которым следует следовать при разработке экрана входа и согласия пользователя.](https://developers-dot-devsite-v2-prod.appspot.com/static/identity/images/oauth-linking-consent.png?authuser=7&hl=ru)
Создать проект
Чтобы создать проект для использования привязки аккаунтов:
- Go to the Google API Console.
- Нажмите Создать проект .
- Введите имя или примите сгенерированное предложение.
- Подтвердите или отредактируйте оставшиеся поля.
- Нажмите Создать .
Для просмотра идентификатора вашего проекта:
- Go to the Google API Console.
- Найдите свой проект в таблице на целевой странице. Идентификатор проекта отображается в столбце идентификаторов .
Настройте экран согласия OAuth
Процесс привязки учетной записи Google включает в себя экран согласия, на котором пользователям сообщается, какое приложение запрашивает доступ к их данным, какие данные они запрашивают и какие условия применяются. Прежде чем создавать идентификатор клиента Google API, вам необходимо будет настроить экран согласия OAuth.
- Откройте страницу экрана согласия OAuth консоли API Google.
- При появлении запроса выберите только что созданный проект.
На странице «Экран согласия OAuth» заполните форму и нажмите кнопку «Сохранить».
Имя приложения: имя приложения, запрашивающего согласие. Имя должно точно отражать ваше приложение и соответствовать имени приложения, которое пользователи видят в других местах. Название приложения будет показано на экране согласия на привязку учетной записи.
Логотип приложения: изображение на экране согласия, которое поможет пользователям узнать ваше приложение. Логотип отображается на экране согласия на привязку учетной записи и в настройках учетной записи.
Электронная почта поддержки: чтобы пользователи могли связаться с вами и задать вопросы о своем согласии.
Области для API Google. Области позволяют вашему приложению получать доступ к личным данным Google вашего пользователя. Для варианта использования привязки учетной записи Google достаточно области по умолчанию (электронная почта, профиль, openid), вам не нужно добавлять какие-либо конфиденциальные области. Обычно рекомендуется запрашивать области постепенно, в тот момент, когда требуется доступ, а не заранее. Узнайте больше .
Авторизованные домены. Чтобы защитить вас и ваших пользователей, Google разрешает использовать авторизованные домены только приложениям, которые проходят аутентификацию с помощью OAuth. Ссылки ваших приложений должны размещаться на авторизованных доменах. Узнайте больше .
Ссылка на домашнюю страницу приложения: Домашняя страница вашего приложения. Должен быть размещен на авторизованном домене.
Ссылка на политику конфиденциальности приложения: отображается на экране согласия на привязку учетной записи Google. Должен быть размещен на авторизованном домене.
Ссылка на Условия использования приложения (необязательно): должна быть размещена в авторизованном домене.
Рисунок 1 . Экран согласия на привязку учетной записи Google к вымышленному приложению, Tunery
Проверьте «Статус проверки». Если ваше приложение требует проверки, нажмите кнопку «Отправить на проверку», чтобы отправить заявку на проверку. Подробную информацию см. в требованиях к проверке OAuth .
Внедрите свой сервер OAuth
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 . |
user_locale | Настройка языка аккаунта Google в RFC5646 формате, используемая для локализации содержания в выбранном языке пользователя. |
Например, если конечная точка авторизации доступна на 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&user_locale=LOCALE
Чтобы конечная точка авторизации могла обрабатывать запросы на вход, выполните следующие действия:
- Убедитесь в том, что
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
параметром. Включите код авторизации вы просто сгенерированные и оригинал, неизмененное значение состояния , когда вы поменяете путем добавления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, 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
параметр совпадает со значением , используемым в запросе начальной авторизации. - Если вы не можете проверить все из вышеперечисленных критериев, возвращает ошибку Bad Request HTTP 400 с
{"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
соответствует ожидаемому значению. - Убедитесь, что токен обновления действителен и что идентификатор клиента, указанный в запросе, совпадает с идентификатором клиента, связанным с токеном обновления.
- Если вы не можете проверить все из вышеперечисленных критериев, возвращает ошибку Bad Request HTTP 400 с
{"error": "invalid_grant"}
как тело. - В противном случае используйте идентификатор пользователя из токена обновления для создания токена доступа. Эти токены могут иметь любое строковое значение, но они должны однозначно представлять пользователя и клиента, для которого предназначен токен, и их нельзя угадывать. Для токенов доступа также записывайте время истечения срока действия токена, обычно через час после выдачи токена.
- Верните следующий объект JSON в теле ответа HTTPS:
{ "token_type": "Bearer", "access_token": " ACCESS_TOKEN ", "expires_in": SECONDS_TO_EXPIRATION }
Обработка запросов информации пользователя
UserInfo конечной точкой является OAuth 2,0 защищенный ресурс, возвратные претензии по поводу связанного пользователя. Внедрение и размещение конечной точки userinfo необязательно, за исключением следующих случаев использования:
- Linked входа в аккаунт с Google One Tap.
- Frictionless подписка на AndroidTV.
После того, как маркер доступа был успешно получен из вашей конечной точки маркера, 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 с помощью
WWW-Authenticate
заголовок ответа. Ниже приведен пример ответа ошибки UserInfo:HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"
Если 401 Несанкционированные, или любой другой неудачный ответ возвращается ошибка во время процесса , связывающего, ошибка будет неустранимой, извлеченный маркер будет отброшен , и пользователь будет иметь чтобы снова запустить процесс связывания. Если маркер доступа действителен, возврат и 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
Дополнительно: Фамилия пользователя. name
Дополнительно: Полное имя пользователя. picture
Дополнительно: Рисунок профиля пользователя.
Проверка вашей реализации
Вы можете проверить свою реализацию с помощью Playground OAuth 2.0 инструмента.
В инструменте проделайте следующие шаги:
- Нажмите Конфигурация , чтобы открыть окно настройки OAuth 2.0.
- В поле потока OAuth, выберите на стороне клиента.
- В поле OAuth Endpoints, выберите Custom.
- Укажите конечную точку OAuth 2.0 и идентификатор клиента, назначенный Google, в соответствующих полях.
- В разделе Шаг 1, не выбирайте области Google. Вместо этого оставьте это поле пустым или введите область действия, действительную для вашего сервера (или произвольную строку, если вы не используете области действия OAuth). Когда вы закончите, нажмите Авторизовать API.
- В секциях Шаг 2 и Шаг 3, пройти через поток OAuth 2.0 и убедитесь , что каждый шаг работает как задумано.
Вы можете проверить свою реализацию с помощью учетной записи Google Linking Демо инструмент.
В инструменте проделайте следующие шаги:
- Нажмите для входа в систему с помощью кнопки Google.
- Выберите учетную запись, которую вы хотите связать.
- Введите идентификатор службы.
- При желании введите одну или несколько областей, для которых вы запрашиваете доступ.
- Нажмите кнопку Пуск Demo.
- При появлении запроса подтвердите, что вы можете согласиться, и отклоните запрос на установление связи.
- Подтвердите, что вы перенаправлены на свою платформу.