В этом документе объясняется, как приложения, установленные на таких устройствах, как телефоны, планшеты и компьютеры, используют конечные точки Google OAuth 2.0 для авторизации доступа к API данных YouTube.
OAuth 2.0 позволяет пользователям обмениваться определенными данными с приложением, сохраняя при этом свои имена пользователей, пароли и другую информацию конфиденциальной. Например, приложение может использовать OAuth 2.0 для получения разрешения на получение данных канала YouTube.
Установленные приложения распространяются на отдельные устройства, и предполагается, что эти приложения не могут хранить секреты. Они могут получить доступ к API Google, пока пользователь присутствует в приложении или когда приложение работает в фоновом режиме.
Этот поток авторизации аналогичен тому, который используется для приложений веб-сервера . Основное отличие состоит в том, что установленные приложения должны открыть системный браузер и предоставить локальный URI перенаправления для обработки ответов от сервера авторизации Google.
Альтернативы
Для мобильных приложений вы можете предпочесть использовать вход в Google для Android или iOS . Клиентские библиотеки входа в Google обрабатывают аутентификацию и авторизацию пользователей, и их может быть проще реализовать, чем описанный здесь протокол более низкого уровня.
Для приложений, работающих на устройствах, которые не поддерживают системный браузер или имеют ограниченные возможности ввода, таких как телевизоры, игровые консоли, камеры или принтеры, см. OAuth 2.0 для телевизоров и устройств или Вход на телевизорах и устройствах с ограниченным вводом .
Библиотеки и образцы
Мы рекомендуем следующие библиотеки и примеры, которые помогут вам реализовать поток OAuth 2.0, описанный в этом документе:
Предварительные условия
Включите API для вашего проекта
Любое приложение, которое вызывает API Google, должно включить эти API в API Console.
Чтобы включить API для вашего проекта:
- Open the API Library в Google API Console.
- If prompted, select a project, or create a new one.
- Используйте страницу библиотеки, чтобы найти и включить API данных YouTube. Найдите любые другие API, которые будет использовать ваше приложение, и включите их.
Создать учетные данные для авторизации
Любое приложение, использующее OAuth 2.0 для доступа к API Google, должно иметь учетные данные авторизации, которые идентифицируют приложение на сервере Google OAuth 2.0. Следующие шаги объясняют, как создать учетные данные для вашего проекта. Затем ваши приложения смогут использовать учетные данные для доступа к API, которые вы включили для этого проекта.
- Go to the Credentials page.
- Нажмите Создать учетные данные > Идентификатор клиента OAuth .
- В разделах ниже описаны типы клиентов и методы перенаправления, которые поддерживает сервер авторизации Google. Выберите тип клиента, рекомендуемый для вашего приложения, назовите свой клиент OAuth и задайте соответствующие поля в форме.
Андроид
- Выберите тип приложения Android .
- Введите имя клиента OAuth. Это имя отображается в вашем проекте Credentials page для идентификации клиента.
- Введите имя пакета вашего приложения для Android. Это значение определяется в атрибуте
package
элемента<manifest>
в файле манифеста вашего приложения. - Введите отпечаток сертификата подписи SHA-1 для распространения приложения.
- Если ваше приложение использует подпись приложения Google Play , скопируйте отпечаток SHA-1 со страницы подписи приложения в Play Console.
- Если вы управляете собственным хранилищем ключей и ключами подписи, используйте утилиту keytool , входящую в состав Java, для печати информации о сертификате в удобочитаемом формате. Скопируйте значение
SHA1
в разделCertificate fingerprints
выходных данных keytool . Дополнительную информацию см. в разделе «Аутентификация вашего клиента» в документации Google API для Android.
- (Необязательно) Подтвердите право собственности на ваше приложение для Android.
- Нажмите Создать .
iOS
- Выберите тип приложения iOS .
- Введите имя клиента OAuth. Это имя отображается в вашем проекте Credentials page для идентификации клиента.
- Введите идентификатор пакета для вашего приложения. Идентификатор пакета — это значение ключа CFBundleIdentifier в файле ресурсов списка информационных свойств вашего приложения ( info.plist ). Значение чаще всего отображается на панели «Общие» или на панели «Подписание и возможности» редактора проекта Xcode. Идентификатор пакета также отображается в разделе «Общая информация» на странице «Информация о приложении» на сайте Apple App Store Connect .
- (Необязательный)
Введите идентификатор вашего приложения в App Store, если приложение опубликовано в Apple App Store. Идентификатор магазина — это числовая строка, включенная в каждый URL-адрес Apple App Store.
- Откройте приложение Apple App Store на своем устройстве iOS или iPadOS.
- Найдите свое приложение.
- Нажмите кнопку «Поделиться» (символ квадрата и стрелки вверх).
- Выберите «Копировать ссылку» .
- Вставьте ссылку в текстовый редактор. Идентификатор App Store — это последняя часть URL-адреса.
Пример:
https://apps.apple.com/app/google/id 284815942
- (Необязательный)
Введите идентификатор своей команды. Дополнительную информацию см. в разделе «Найдите свой идентификатор команды» в документации по учетной записи разработчика Apple.
- Нажмите Создать .
UWP
- Выберите тип приложения универсальной платформы Windows .
- Введите имя клиента OAuth. Это имя отображается в вашем проекте Credentials page для идентификации клиента.
- Введите 12-значный идентификатор вашего приложения в Microsoft Store. Это значение можно найти в Центре партнеров Microsoft на странице удостоверения приложения в разделе «Управление приложениями».
- Нажмите Создать .
Для приложений UWP длина пользовательской схемы URI не может превышать 39 символов.
Пользовательская схема URI (Android, iOS, UWP)
Пользовательские схемы URI — это форма диплинкинга, в которой для открытия вашего приложения используется настраиваемая схема.
Альтернатива использованию пользовательских схем URI на AndroidИспользуйте Google Sign-In для Android SDK , который доставляет ответ OAuth 2.0 непосредственно в ваше приложение, устраняя необходимость в URI перенаправления.
Как перейти на Google Sign-In для Android SDK
Если в настоящее время вы используете собственную схему для интеграции OAuth на Android, вам необходимо выполнить следующие действия, чтобы полностью перейти на использование рекомендованного Google Sign-In для Android SDK:
- Обновите свой код, чтобы использовать SDK для входа в Google.
- Отключите поддержку пользовательской схемы в консоли Google API.
Выполните следующие действия, чтобы перейти на Android SDK для входа в Google:
- Обновите свой код, чтобы использовать Android SDK для входа в Google:
- Проверьте свой код, чтобы определить, куда вы отправляете запрос на сервер Google OAuth 2.0 ; Если вы используете собственную схему, ваш запрос будет выглядеть следующим образом:
https://accounts.google.com/o/oauth2/v2/auth? scope=<SCOPES>& response_type=code& &state=<STATE>& redirect_uri=com.example.app:/oauth2redirect& client_id=<CLIENT_ID>
com.example.app:/oauth2redirect
— это URI перенаправления пользовательской схемы в приведенном выше примере. Дополнительные сведения о формате значения пользовательской схемы URI см. в определении параметраredirect_uri
. - Запишите параметры
scope
иclient_id
, которые вам понадобятся для настройки SDK для входа в Google. - Следуйте инструкциям по началу интеграции входа в Google в ваше приложение Android, чтобы настроить SDK. Вы можете пропустить шаг «Получить идентификатор клиента OAuth 2.0 вашего внутреннего сервера», так как вам придется повторно использовать
client_id
, полученный на предыдущем шаге. - Следуйте инструкциям по включению доступа к серверному API . Это включает в себя следующие шаги:
- Используйте метод
getServerAuthCode
, чтобы получить код аутентификации для областей, для которых вы запрашиваете разрешение. - Отправьте код авторизации на серверную часть вашего приложения, чтобы обменять его на токен доступа и обновления.
- Используйте полученный токен доступа для выполнения вызовов API Google от имени пользователя.
- Используйте метод
- Проверьте свой код, чтобы определить, куда вы отправляете запрос на сервер Google OAuth 2.0 ; Если вы используете собственную схему, ваш запрос будет выглядеть следующим образом:
- Отключите поддержку пользовательской схемы в консоли Google API:
- Перейдите в список учетных данных OAuth 2.0 и выберите свой клиент Android.
- Перейдите в раздел «Дополнительные настройки» , снимите флажок «Включить настраиваемую схему URI» и нажмите « Сохранить» , чтобы отключить поддержку настраиваемой схемы URI.
Включение пользовательской схемы URI
Если рекомендуемый вариант вам не подходит, вы можете включить собственные схемы URI для вашего клиента Android, следуя инструкциям ниже:- Перейдите в список учетных данных OAuth 2.0 и выберите свой клиент Android.
- Перейдите в раздел «Дополнительные настройки» , установите флажок «Включить настраиваемую схему URI» и нажмите « Сохранить» , чтобы включить поддержку настраиваемой схемы URI.
Используйте Chrome Identity API , который доставляет ответ OAuth 2.0 непосредственно в ваше приложение, устраняя необходимость в URI перенаправления.
Подтвердите право собственности на приложение (Android, Chrome)
Вы можете подтвердить право собственности на свое приложение, чтобы снизить риск выдачи себя за другое лицо.
Андроид
Чтобы завершить процесс проверки, вы можете использовать свою учетную запись разработчика Google Play, если она у вас есть и ваше приложение зарегистрировано в консоли Google Play . Для успешной проверки должны быть выполнены следующие требования:
- У вас должно быть зарегистрированное приложение в консоли Google Play с тем же именем пакета и отпечатком сертификата подписи SHA-1, что и у клиента Android OAuth, для которого вы выполняете проверку.
- У вас должны быть права администратора для приложения в консоли Google Play. Узнайте больше об управлении доступом в консоли Google Play.
В разделе «Подтвердить право собственности на приложение» клиента Android нажмите кнопку «Подтвердить право собственности» , чтобы завершить процесс проверки.
Если проверка прошла успешно, отобразится уведомление, подтверждающее успех процесса проверки. В противном случае будет показано сообщение об ошибке.
Чтобы исправить неудачную проверку, попробуйте следующее:
- Убедитесь, что приложение, которое вы проверяете, зарегистрировано в консоли Google Play.
- Убедитесь, что у вас есть права администратора для приложения в консоли Google Play.
Хром
Для завершения процесса проверки вам потребуется использовать свою учетную запись разработчика Интернет-магазина Chrome. Для успешной проверки должны быть выполнены следующие требования:
- У вас должен быть зарегистрированный элемент на панели инструментов разработчика Интернет-магазина Chrome с тем же идентификатором элемента, что и у клиента OAuth расширения Chrome, для которого вы завершаете проверку.
- Вы должны быть издателем элемента Интернет-магазина Chrome. Узнайте больше об управлении доступом на панели разработчика Интернет-магазина Chrome.
В разделе «Подтвердить право собственности на приложение» клиента расширений Chrome нажмите кнопку «Подтвердить право собственности» , чтобы завершить процесс проверки.
Примечание. Подождите несколько минут, прежде чем завершить процесс проверки после предоставления доступа к вашей учетной записи.
Если проверка прошла успешно, отобразится уведомление, подтверждающее успех процесса проверки. В противном случае будет показано сообщение об ошибке.
Чтобы исправить неудачную проверку, попробуйте следующее:
- Убедитесь, что на панели разработчика Интернет-магазина Chrome есть зарегистрированный элемент с тем же идентификатором, что и у клиента OAuth расширения Chrome, для которого вы завершаете проверку.
- Убедитесь, что вы являетесь издателем приложения, т. е. вы должны быть либо индивидуальным издателем приложения, либо членом группы издателей приложения. Узнайте больше об управлении доступом на панели разработчика Интернет-магазина Chrome.
- Если вы только что обновили список издателей группы, убедитесь, что список участников группы синхронизирован с панелью разработчика Интернет-магазина Chrome. Узнайте больше о синхронизации списка участников издателя.
IP-адрес обратной связи (macOS, Linux, рабочий стол Windows)
Чтобы получить код авторизации с использованием этого URL-адреса, ваше приложение должно прослушивать локальный веб-сервер. Это возможно на многих, но не на всех платформах. Однако, если ваша платформа поддерживает это, это рекомендуемый механизм получения кода авторизации.
Когда ваше приложение получает ответ на авторизацию, для лучшего удобства использования оно должно отреагировать, отобразив HTML-страницу, которая инструктирует пользователя закрыть браузер и вернуться в ваше приложение.
Рекомендуемое использование | Приложения для настольных компьютеров macOS, Linux и Windows (но не для универсальной платформы Windows) |
Формировать значения | Установите тип приложения « Приложение для ПК» . |
Ручное копирование/вставка
Определить области доступа
Области позволяют вашему приложению запрашивать доступ только к тем ресурсам, которые ему необходимы, а также позволяют пользователям контролировать объем доступа, который они предоставляют вашему приложению. Таким образом, может существовать обратная зависимость между количеством запрошенных областей и вероятностью получения согласия пользователя.
Прежде чем приступить к реализации авторизации OAuth 2.0, мы рекомендуем вам определить области, для доступа к которым вашему приложению потребуется разрешение.
API данных YouTube версии 3 использует следующие области действия:
Сферы | |
---|---|
https://www.googleapis.com/auth/youtube | Управляйте своим аккаунтом YouTube |
https://www.googleapis.com/auth/youtube.channel-memberships.creator | Просматривайте список ваших текущих активных участников канала, их текущий уровень и время, когда они стали участником. |
https://www.googleapis.com/auth/youtube.force-ssl | Просматривайте, редактируйте и безвозвратно удаляйте свои видео, рейтинги, комментарии и подписи на YouTube. |
https://www.googleapis.com/auth/youtube.readonly | Просмотрите свой аккаунт YouTube |
https://www.googleapis.com/auth/youtube.upload | Управляйте своими видео на YouTube |
https://www.googleapis.com/auth/youtubepartner | Просмотр и управление своими объектами и связанным контентом на YouTube |
https://www.googleapis.com/auth/youtubepartner-channel-audit | Просмотр личной информации о вашем канале YouTube, актуальной в процессе аудита с партнером YouTube. |
Документ «Области API OAuth 2.0» содержит полный список областей, которые вы можете использовать для доступа к API Google.
Получение токенов доступа OAuth 2.0
Следующие шаги показывают, как ваше приложение взаимодействует с сервером OAuth 2.0 Google, чтобы получить согласие пользователя на выполнение запроса API от имени пользователя. Ваше приложение должно получить это согласие, прежде чем оно сможет выполнить запрос Google API, требующий авторизации пользователя.
Шаг 1. Создайте средство проверки кода и проверите его.
Google поддерживает протокол Proof Key for Code Exchange (PKCE), чтобы сделать работу установленного приложения более безопасной. Для каждого запроса авторизации создается уникальный верификатор кода, и его преобразованное значение, называемое «code_challenge», отправляется на сервер авторизации для получения кода авторизации.
Создайте верификатор кода
code_verifier
— это криптографическая случайная строка с высокой энтропией, использующая незарезервированные символы [AZ] / [az] / [0-9] / «-» / «». / «_» / «~», минимальной длиной 43 символа и максимальной длиной 128 символов.
Верификатор кода должен иметь достаточную энтропию, чтобы угадать значение было непрактично.
Создать задачу по коду
Поддерживаются два метода создания задачи кода.
Методы генерации задач кода | |
---|---|
S256 (рекомендуется) | Задача кода — это хэш SHA256, закодированный в Base64URL (без заполнения), верификатора кода.
|
простой | Запрос кода имеет то же значение, что и верификатор кода, созданный выше.
|
Шаг 2. Отправьте запрос на сервер Google OAuth 2.0.
Чтобы получить авторизацию пользователя, отправьте запрос на сервер авторизации Google по адресу https://accounts.google.com/o/oauth2/v2/auth
. Эта конечная точка обрабатывает поиск активного сеанса, аутентифицирует пользователя и получает согласие пользователя. Конечная точка доступна только через SSL и отказывается от подключений HTTP (не SSL).
Сервер авторизации поддерживает следующие параметры строки запроса для установленных приложений:
Параметры | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id | Необходимый Идентификатор клиента для вашего приложения. Вы можете найти это значение в API ConsoleCredentials page. | ||||||||||||||||
redirect_uri | Необходимый Определяет, как сервер авторизации Google отправляет ответ вашему приложению. Для установленных приложений доступно несколько вариантов перенаправления, и вы должны настроить свои учетные данные для авторизации с учетом конкретного метода перенаправления. Значение должно точно совпадать с одним из авторизованных URI перенаправления для клиента OAuth 2.0, который вы настроили в настройках вашего клиента. API ConsoleCredentials page. Если это значение не соответствует авторизованному URI, вы получите ошибку В таблице ниже показано соответствующее значение параметра
| ||||||||||||||||
response_type | Необходимый Определяет, возвращает ли конечная точка Google OAuth 2.0 код авторизации. Установите значение параметра для | ||||||||||||||||
scope | Необходимый Список областей, разделенных пробелами, которые определяют ресурсы, к которым ваше приложение может получить доступ от имени пользователя. Эти значения указывают на экран согласия, который Google отображает пользователю. Области позволяют вашему приложению запрашивать доступ только к тем ресурсам, которые ему необходимы, а также позволяют пользователям контролировать объем доступа, который они предоставляют вашему приложению. Таким образом, существует обратная зависимость между количеством запрашиваемых областей и вероятностью получения согласия пользователя. API данных YouTube версии 3 использует следующие области действия:
В документе «Области API OAuth 2.0» представлен полный список областей, которые вы можете использовать для доступа к API Google. | ||||||||||||||||
code_challenge | Рекомендуется Указывает закодированный | ||||||||||||||||
code_challenge_method | Рекомендуется Указывает, какой метод использовался для кодирования | ||||||||||||||||
state | Рекомендуется Указывает любое строковое значение, которое ваше приложение использует для поддержания состояния между вашим запросом авторизации и ответом сервера авторизации. Сервер возвращает точное значение, которое вы отправляете в виде пары Вы можете использовать этот параметр для нескольких целей, например для направления пользователя на правильный ресурс в вашем приложении, отправки одноразовых номеров и предотвращения подделки межсайтовых запросов. Поскольку ваш | ||||||||||||||||
login_hint | Необязательный Если ваше приложение знает, какой пользователь пытается пройти аутентификацию, оно может использовать этот параметр, чтобы предоставить подсказку серверу аутентификации Google. Сервер использует подсказку, чтобы упростить процесс входа в систему, либо предварительно заполнив поле электронной почты в форме входа, либо выбрав соответствующий сеанс с несколькими входами. Установите в качестве значения параметра адрес электронной почты или |
Примеры URL-адресов авторизации
На вкладках ниже показаны примеры URL-адресов авторизации для различных вариантов URI перенаправления.
Каждый URL-адрес запрашивает доступ к области, которая разрешает доступ для получения данных пользователя YouTube. URL-адреса идентичны, за исключением значения параметра redirect_uri
. URL-адреса также содержат обязательные параметры response_type
и client_id
, а также необязательный параметр state
. Каждый URL-адрес содержит разрывы строк и пробелы для удобства чтения.
Пользовательская схема URI
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=com.example.app%3A/oauth2redirect& client_id=client_id
IP-адрес обратной связи
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=http%3A//127.0.0.1%3A9004& client_id=client_id
Шаг 3. Google запрашивает у пользователя согласие
На этом этапе пользователь решает, предоставить ли вашему приложению запрошенный доступ. На этом этапе Google отображает окно согласия, в котором отображается имя вашего приложения и сервисов Google API, к которым он запрашивает разрешение, с учетными данными авторизации пользователя и сводной информацией об объемах доступа, которые необходимо предоставить. Затем пользователь может согласиться предоставить доступ к одной или нескольким областям, запрошенным вашим приложением, или отклонить запрос.
На этом этапе вашему приложению не нужно ничего делать, поскольку оно ожидает ответа от сервера Google OAuth 2.0, указывающего, был ли предоставлен какой-либо доступ. Этот ответ объясняется на следующем шаге.
Ошибки
Запросы к конечной точке авторизации OAuth 2.0 Google могут отображать сообщения об ошибках вместо ожидаемых потоков аутентификации и авторизации. Ниже перечислены распространенные коды ошибок и предлагаемые решения.
admin_policy_enforced
Аккаунт Google не может авторизовать одну или несколько запрошенных областей в соответствии с правилами администратора Google Workspace. Дополнительную информацию о том, как администратор может ограничить доступ ко всем областям или конфиденциальным и ограниченным областям до тех пор, пока доступ не будет явно предоставлен вашему идентификатору клиента OAuth, можно найти в справочной статье администратора Google Workspace «Управление тем, какие сторонние и внутренние приложения получают доступ к данным Google Workspace».
disallowed_useragent
Конечная точка авторизации отображается внутри встроенного пользовательского агента, запрещенного политиками Google OAuth 2.0 .
Андроид
Разработчики Android могут столкнуться с этим сообщением об ошибке при открытии запросов авторизации вandroid.webkit.WebView
. Вместо этого разработчикам следует использовать библиотеки Android, такие как Google Sign-In для Android или AppAuth OpenID Foundation для Android .
Веб-разработчики могут столкнуться с этой ошибкой, когда приложение Android открывает общую веб-ссылку во встроенном пользовательском агенте, и пользователь переходит к конечной точке авторизации Google OAuth 2.0 с вашего сайта. Разработчики должны разрешить открытие общих ссылок в обработчике ссылок по умолчанию операционной системы, который включает в себя как обработчики ссылок приложений Android , так и браузерное приложение по умолчанию. Библиотека пользовательских вкладок Android также поддерживается.
iOS
Разработчики iOS и macOS могут столкнуться с этой ошибкой при открытии запросов авторизации вWKWebView
. Вместо этого разработчикам следует использовать библиотеки iOS, такие как Google Sign-In для iOS или AppAuth OpenID Foundation для iOS .
Веб-разработчики могут столкнуться с этой ошибкой, когда приложение iOS или macOS открывает общую веб-ссылку во встроенном пользовательском агенте, и пользователь переходит к конечной точке авторизации Google OAuth 2.0 с вашего сайта. Разработчики должны разрешить открытие общих ссылок в обработчике ссылок по умолчанию операционной системы, который включает в себя как обработчики универсальных ссылок , так и браузерное приложение по умолчанию. БиблиотекаSFSafariViewController
также поддерживается.
org_internal
Идентификатор клиента OAuth в запросе является частью проекта, ограничивающего доступ к аккаунтам Google в конкретной организации Google Cloud . Дополнительные сведения об этом параметре конфигурации см. в разделе «Тип пользователя» в справочной статье «Настройка экрана согласия OAuth».
invalid_grant
Если вы используете средство проверки кода и вызов , параметр code_callenge
недействителен или отсутствует. Убедитесь, что параметр code_challenge
установлен правильно.
При обновлении токена доступа возможно, срок действия токена истек или он стал недействительным. Аутентифицируйте пользователя еще раз и запросите согласие пользователя на получение новых токенов. Если вы продолжаете видеть эту ошибку, убедитесь, что ваше приложение настроено правильно и что вы используете правильные токены и параметры в своем запросе. В противном случае учетная запись пользователя могла быть удалена или отключена.
redirect_uri_mismatch
redirect_uri
, переданный в запросе авторизации, не соответствует авторизованному URI перенаправления для идентификатора клиента OAuth. Просмотрите разрешенные URI перенаправления в Google API Console Credentials page.
Переданный redirect_uri
может быть недопустимым для типа клиента.
Параметр redirect_uri
может относиться к внеполосному потоку OAuth (OOB), который устарел и больше не поддерживается. Обратитесь к руководству по миграции , чтобы обновить интеграцию.
invalid_request
Что-то не так с вашим запросом. Это может быть связано с рядом причин:
- Запрос был неправильно отформатирован
- В запросе отсутствовали необходимые параметры
- В запросе используется метод авторизации, который Google не поддерживает. Убедитесь, что в вашей интеграции OAuth используется рекомендуемый метод интеграции.
- Для URI перенаправления используется пользовательская схема: если вы видите сообщение об ошибке. Пользовательская схема URI не поддерживается в приложениях Chrome или пользовательская схема URI не включена для вашего клиента Android , это означает, что вы используете собственную схему URI, которая не поддерживается. поддерживается в приложениях Chrome и по умолчанию отключен на Android. Узнайте больше об альтернативах пользовательских схем URI.
Шаг 4. Обработка ответа сервера OAuth 2.0
Способ получения приложением ответа на авторизацию зависит от используемой им схемы URI перенаправления . Независимо от схемы, ответ будет содержать либо код авторизации ( code
), либо ошибку ( error
). Например, error=access_denied
указывает, что пользователь отклонил запрос.
Если пользователь предоставляет доступ к вашему приложению, вы можете обменять код авторизации на токен доступа и токен обновления, как описано в следующем шаге.
Шаг 5. Обмен кода авторизации для токенов обновления и доступа.
Чтобы обменять код авторизации на токен доступа, вызовите конечную точку https://oauth2.googleapis.com/token
и установите следующие параметры:
Поля | |
---|---|
client_id | Идентификатор клиента, полученный из API ConsoleCredentials page. |
client_secret | Секрет клиента, полученный от API ConsoleCredentials page. |
code | Код авторизации, возвращенный из первоначального запроса. |
code_verifier | Средство проверки кода, созданное на шаге 1 . |
grant_type | Как определено в спецификации OAuth 2.0 , значение этого поля должно быть установлено в authorization_code . |
redirect_uri | Один из URI перенаправления, перечисленных для вашего проекта в API ConsoleCredentials page для данного client_id . |
В следующем фрагменте показан пример запроса:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your_client_id& client_secret=your_client_secret& redirect_uri=http://127.0.0.1:9004& grant_type=authorization_code
Google отвечает на этот запрос, возвращая объект JSON, содержащий кратковременный токен доступа и токен обновления.
Ответ содержит следующие поля:
Поля | |
---|---|
access_token | Токен, который ваше приложение отправляет для авторизации запроса Google API. |
expires_in | Оставшийся срок действия токена доступа в секундах. |
id_token | Примечание. Это свойство возвращается только в том случае, если ваш запрос включал область идентификации, например openid , profile или email . Значением является веб-токен JSON (JWT), который содержит идентификационную информацию пользователя с цифровой подписью. |
refresh_token | Токен, который можно использовать для получения нового токена доступа. Токены обновления действительны до тех пор, пока пользователь не отзовет доступ. Обратите внимание, что токены обновления всегда возвращаются для установленных приложений. |
scope | Области доступа, предоставляемые access_token , выражаются в виде списка строк, разделенных пробелами и чувствительных к регистру. |
token_type | Тип возвращенного токена. В настоящее время значение этого поля всегда установлено на Bearer . |
В следующем фрагменте показан пример ответа:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/youtube.force-ssl", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Вызов API Google
После того как ваше приложение получит токен доступа, вы можете использовать его для выполнения вызовов API Google от имени определенной учетной записи пользователя, если предоставлены области доступа, требуемые API. Для этого включите токен доступа в запрос к API, включив либо параметр запроса access_token
, либо значение Bearer
HTTP-заголовка Authorization
. Когда это возможно, предпочтительнее использовать HTTP-заголовок, поскольку строки запроса обычно видны в журналах сервера. В большинстве случаев вы можете использовать клиентскую библиотеку для настройки вызовов API Google (например, при вызове API потоковой передачи YouTube Live ).
Обратите внимание, что API YouTube Live Streaming не поддерживает поток учетной записи службы. Поскольку невозможно связать учетную запись службы с учетной записью YouTube, попытки авторизовать запросы с помощью этого процесса приведут к ошибке NoLinkedYouTubeAccount
.
Вы можете опробовать все API Google и просмотреть их возможности на игровой площадке OAuth 2.0 .
Примеры HTTP GET
Вызов конечной точки liveBroadcasts.list
(API YouTube Live Streaming) с использованием HTTP-заголовка Authorization: Bearer
может выглядеть следующим образом. Обратите внимание, что вам необходимо указать свой собственный токен доступа:
GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Вот вызов того же API для аутентифицированного пользователя с использованием параметра строки запроса access_token
:
GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
примеры curl
Вы можете протестировать эти команды с помощью приложения командной строки curl
. Вот пример, в котором используется опция HTTP-заголовка (предпочтительно):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true
Или, альтернативно, опция параметра строки запроса:
curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
Обновление токена доступа
Срок действия маркеров доступа периодически истекает, и они становятся недействительными учетными данными для связанного запроса API. Вы можете обновить токен доступа, не запрашивая у пользователя разрешения (в том числе, когда пользователь отсутствует), если вы запросили автономный доступ к областям, связанным с токеном.
Чтобы обновить токен доступа, ваше приложение отправляет запрос HTTPS POST
на сервер авторизации Google ( https://oauth2.googleapis.com/token
), который включает следующие параметры:
Поля | |
---|---|
client_id | Идентификатор клиента, полученный из API Console. |
client_secret | Секрет клиента, полученный от API Console. (Свойство client_secret неприменимо к запросам от клиентов, зарегистрированных как приложения Android, iOS или Chrome.) |
grant_type | Как определено в спецификации OAuth 2.0 , для этого поля должно быть установлено refresh_token . |
refresh_token | Токен обновления, возвращенный в результате обмена кодами авторизации. |
В следующем фрагменте показан пример запроса:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=your_client_id& client_secret=your_client_secret& refresh_token=refresh_token& grant_type=refresh_token
Пока пользователь не отозвал доступ, предоставленный приложению, сервер токенов возвращает объект JSON, содержащий новый токен доступа. В следующем фрагменте показан пример ответа:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "scope": "https://www.googleapis.com/auth/drive.metadata.readonly", "token_type": "Bearer" }
Обратите внимание, что существуют ограничения на количество выпускаемых токенов обновления; одно ограничение на комбинацию клиент/пользователь и другое на пользователя для всех клиентов. Вам следует сохранять токены обновления в долгосрочном хранилище и продолжать использовать их, пока они остаются действительными. Если ваше приложение запрашивает слишком много токенов обновления, оно может столкнуться с этими ограничениями, и в этом случае старые токены обновления перестанут работать.
Отзыв токена
В некоторых случаях пользователь может захотеть отозвать доступ, предоставленный приложению. Пользователь может отозвать доступ, посетив настройки учетной записи . Дополнительную информацию см . в разделе «Удалить доступ к сайту или приложению» в документе поддержки «Сторонние сайты и приложения с доступом к вашей учетной записи» .
Приложение также может программно отозвать предоставленный ему доступ. Программный отзыв важен в тех случаях, когда пользователь отписывается от подписки, удаляет приложение или ресурсы API, необходимые приложению, значительно изменились. Другими словами, часть процесса удаления может включать запрос API, чтобы гарантировать удаление ранее предоставленных приложению разрешений.
Чтобы программно отозвать токен, ваше приложение отправляет запрос https://oauth2.googleapis.com/revoke
и включает токен в качестве параметра:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \ https://oauth2.googleapis.com/revoke?token={token}
Маркер может быть маркером доступа или маркером обновления. Если токен является токеном доступа и имеет соответствующий токен обновления, токен обновления также будет отозван.
Если отзыв успешно обработан, код состояния HTTP ответа — 200
. В случае возникновения ошибки код состояния HTTP 400
возвращается вместе с кодом ошибки.
Дальнейшее чтение
В документе IETF Best Current Practice OAuth 2.0 для собственных приложений отражены многие из лучших практик, описанных здесь.
Реализация защиты между аккаунтами
Дополнительным шагом, который вам следует предпринять для защиты учетных записей ваших пользователей, является внедрение защиты между учетными записями с помощью службы защиты между учетными записями Google. Эта служба позволяет вам подписаться на уведомления о событиях безопасности, которые предоставляют вашему приложению информацию о серьезных изменениях в учетной записи пользователя. Затем вы можете использовать эту информацию, чтобы принять меры в зависимости от того, как вы решите реагировать на события.
Вот некоторые примеры типов событий, отправляемых в ваше приложение службой защиты нескольких аккаунтов Google:
-
https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
-
https://schemas.openid.net/secevent/oauth/event-type/token-revoked
-
https://schemas.openid.net/secevent/risc/event-type/account-disabled
См. страницу «Защита учетных записей пользователей с помощью защиты нескольких учетных записей» для получения дополнительной информации о том, как реализовать защиту между учетными записями, а также для получения полного списка доступных событий.
В этом документе объясняется, как приложения, установленные на таких устройствах, как телефоны, планшеты и компьютеры, используют конечные точки Google OAuth 2.0 для авторизации доступа к API данных YouTube.
OAuth 2.0 позволяет пользователям обмениваться определенными данными с приложением, сохраняя при этом свои имена пользователей, пароли и другую информацию конфиденциальной. Например, приложение может использовать OAuth 2.0 для получения разрешения на получение данных канала YouTube.
Установленные приложения распространяются на отдельные устройства, и предполагается, что эти приложения не могут хранить секреты. Они могут получить доступ к API Google, пока пользователь присутствует в приложении или когда приложение работает в фоновом режиме.
Этот поток авторизации аналогичен тому, который используется для приложений веб-сервера . Основное отличие состоит в том, что установленные приложения должны открыть системный браузер и предоставить локальный URI перенаправления для обработки ответов от сервера авторизации Google.
Альтернативы
Для мобильных приложений вы можете предпочесть использовать вход в Google для Android или iOS . Клиентские библиотеки входа в Google обрабатывают аутентификацию и авторизацию пользователей, и их может быть проще реализовать, чем описанный здесь протокол более низкого уровня.
Для приложений, работающих на устройствах, которые не поддерживают системный браузер или имеют ограниченные возможности ввода, таких как телевизоры, игровые консоли, камеры или принтеры, см. OAuth 2.0 для телевизоров и устройств или Вход на телевизорах и устройствах с ограниченным вводом .
Библиотеки и образцы
Мы рекомендуем следующие библиотеки и примеры, которые помогут вам реализовать поток OAuth 2.0, описанный в этом документе:
Предварительные условия
Включите API для вашего проекта
Любое приложение, которое вызывает API Google, должно включить эти API в API Console.
Чтобы включить API для вашего проекта:
- Open the API Library в Google API Console.
- If prompted, select a project, or create a new one.
- Используйте страницу библиотеки, чтобы найти и включить API данных YouTube. Найдите любые другие API, которые будет использовать ваше приложение, и включите их.
Создать учетные данные для авторизации
Любое приложение, использующее OAuth 2.0 для доступа к API Google, должно иметь учетные данные авторизации, которые идентифицируют приложение на сервере Google OAuth 2.0. Следующие шаги объясняют, как создать учетные данные для вашего проекта. Затем ваши приложения смогут использовать учетные данные для доступа к API, которые вы включили для этого проекта.
- Go to the Credentials page.
- Нажмите Создать учетные данные > Идентификатор клиента OAuth .
- В разделах ниже описаны типы клиентов и методы перенаправления, которые поддерживает сервер авторизации Google. Выберите тип клиента, рекомендуемый для вашего приложения, назовите свой клиент OAuth и задайте соответствующие поля в форме.
Андроид
- Выберите тип приложения Android .
- Введите имя клиента OAuth. Это имя отображается в вашем проекте Credentials page для идентификации клиента.
- Введите имя пакета вашего приложения для Android. Это значение определяется в атрибуте
package
элемента<manifest>
в файле манифеста вашего приложения. - Введите отпечаток сертификата подписи SHA-1 для распространения приложения.
- Если ваше приложение использует подпись приложения Google Play , скопируйте отпечаток SHA-1 со страницы подписи приложения в Play Console.
- Если вы управляете собственным хранилищем ключей и ключами подписи, используйте утилиту keytool , входящую в состав Java, для печати информации о сертификате в удобочитаемом формате. Скопируйте значение
SHA1
в разделCertificate fingerprints
выходных данных keytool . Дополнительную информацию см. в разделе «Аутентификация вашего клиента» в документации Google API для Android.
- (Необязательно) Подтвердите право собственности на ваше приложение для Android.
- Нажмите Создать .
iOS
- Выберите тип приложения iOS .
- Введите имя клиента OAuth. Это имя отображается в вашем проекте Credentials page для идентификации клиента.
- Введите идентификатор пакета для вашего приложения. Идентификатор пакета — это значение ключа CFBundleIdentifier в файле ресурсов списка информационных свойств вашего приложения ( info.plist ). Значение чаще всего отображается на панели «Общие» или на панели «Подписание и возможности» редактора проекта Xcode. Идентификатор пакета также отображается в разделе «Общая информация» на странице «Информация о приложении» на сайте Apple App Store Connect .
- (Необязательный)
Введите идентификатор вашего приложения в App Store, если приложение опубликовано в Apple App Store. Идентификатор магазина — это числовая строка, включенная в каждый URL-адрес Apple App Store.
- Откройте приложение Apple App Store на своем устройстве iOS или iPadOS.
- Найдите свое приложение.
- Нажмите кнопку «Поделиться» (символ квадрата и стрелки вверх).
- Выберите «Копировать ссылку» .
- Вставьте ссылку в текстовый редактор. Идентификатор App Store — это последняя часть URL-адреса.
Пример:
https://apps.apple.com/app/google/id 284815942
- (Необязательный)
Введите идентификатор своей команды. Дополнительную информацию см. в разделе «Найдите свой идентификатор команды» в документации по учетной записи разработчика Apple.
- Нажмите Создать .
UWP
- Выберите тип приложения универсальной платформы Windows .
- Введите имя клиента OAuth. Это имя отображается в вашем проекте Credentials page для идентификации клиента.
- Введите 12-значный идентификатор вашего приложения в Microsoft Store. Это значение можно найти в Центре партнеров Microsoft на странице удостоверения приложения в разделе «Управление приложениями».
- Нажмите Создать .
Для приложений UWP длина пользовательской схемы URI не может превышать 39 символов.
Пользовательская схема URI (Android, iOS, UWP)
Пользовательские схемы URI — это форма диплинкинга, в которой для открытия вашего приложения используется настраиваемая схема.
Альтернатива использованию пользовательских схем URI на AndroidИспользуйте Google Sign-In для Android SDK , который доставляет ответ OAuth 2.0 непосредственно в ваше приложение, устраняя необходимость в URI перенаправления.
Как перейти на Google Sign-In для Android SDK
Если в настоящее время вы используете собственную схему для интеграции OAuth на Android, вам необходимо выполнить следующие действия, чтобы полностью перейти на использование рекомендованного Google Sign-In для Android SDK:
- Обновите свой код, чтобы использовать SDK для входа в Google.
- Отключите поддержку пользовательской схемы в консоли Google API.
Выполните следующие действия, чтобы перейти на Android SDK для входа в Google:
- Обновите свой код, чтобы использовать Android SDK для входа в Google:
- Проверьте свой код, чтобы определить, куда вы отправляете запрос на сервер Google OAuth 2.0 ; Если вы используете собственную схему, ваш запрос будет выглядеть следующим образом:
https://accounts.google.com/o/oauth2/v2/auth? scope=<SCOPES>& response_type=code& &state=<STATE>& redirect_uri=com.example.app:/oauth2redirect& client_id=<CLIENT_ID>
com.example.app:/oauth2redirect
— это URI перенаправления пользовательской схемы в приведенном выше примере. Дополнительные сведения о формате значения пользовательской схемы URI см. в определении параметраredirect_uri
. - Запишите параметры
scope
иclient_id
, которые вам понадобятся для настройки SDK для входа в Google. - Следуйте инструкциям по началу интеграции входа в Google в ваше приложение Android, чтобы настроить SDK. Вы можете пропустить шаг «Получить идентификатор клиента OAuth 2.0 вашего внутреннего сервера», так как вам придется повторно использовать
client_id
, полученный на предыдущем шаге. - Следуйте инструкциям по включению доступа к серверному API . Это включает в себя следующие шаги:
- Используйте метод
getServerAuthCode
, чтобы получить код аутентификации для областей, для которых вы запрашиваете разрешение. - Отправьте код авторизации на серверную часть вашего приложения, чтобы обменять его на токен доступа и обновления.
- Используйте полученный токен доступа для выполнения вызовов API Google от имени пользователя.
- Используйте метод
- Проверьте свой код, чтобы определить, куда вы отправляете запрос на сервер Google OAuth 2.0 ; Если вы используете собственную схему, ваш запрос будет выглядеть следующим образом:
- Отключите поддержку пользовательской схемы в консоли Google API:
- Перейдите в список учетных данных OAuth 2.0 и выберите свой клиент Android.
- Перейдите в раздел «Дополнительные настройки» , снимите флажок «Включить настраиваемую схему URI» и нажмите « Сохранить» , чтобы отключить поддержку настраиваемой схемы URI.
Включение пользовательской схемы URI
Если рекомендуемый вариант вам не подходит, вы можете включить собственные схемы URI для вашего клиента Android, следуя инструкциям ниже:- Перейдите в список учетных данных OAuth 2.0 и выберите свой клиент Android.
- Перейдите в раздел «Дополнительные настройки» , установите флажок «Включить настраиваемую схему URI» и нажмите « Сохранить» , чтобы включить поддержку настраиваемой схемы URI.
Используйте Chrome Identity API , который доставляет ответ OAuth 2.0 непосредственно в ваше приложение, устраняя необходимость в URI перенаправления.
Подтвердите право собственности на приложение (Android, Chrome)
Вы можете подтвердить право собственности на свое приложение, чтобы снизить риск выдачи себя за другое лицо.
Андроид
Чтобы завершить процесс проверки, вы можете использовать свою учетную запись разработчика Google Play, если она у вас есть и ваше приложение зарегистрировано в консоли Google Play . Для успешной проверки должны быть выполнены следующие требования:
- У вас должно быть зарегистрированное приложение в консоли Google Play с тем же именем пакета и отпечатком сертификата подписи SHA-1, что и у клиента Android OAuth, для которого вы выполняете проверку.
- У вас должны быть права администратора для приложения в консоли Google Play. Узнайте больше об управлении доступом в консоли Google Play.
В разделе «Подтвердить право собственности на приложение» клиента Android нажмите кнопку «Подтвердить право собственности» , чтобы завершить процесс проверки.
Если проверка прошла успешно, отобразится уведомление, подтверждающее успех процесса проверки. В противном случае будет показано сообщение об ошибке.
Чтобы исправить неудачную проверку, попробуйте следующее:
- Убедитесь, что приложение, которое вы проверяете, зарегистрировано в консоли Google Play.
- Убедитесь, что у вас есть права администратора для приложения в консоли Google Play.
Хром
Для завершения процесса проверки вам потребуется использовать свою учетную запись разработчика Интернет-магазина Chrome. Для успешной проверки должны быть выполнены следующие требования:
- У вас должен быть зарегистрированный элемент на панели инструментов разработчика Интернет-магазина Chrome с тем же идентификатором элемента, что и у клиента OAuth расширения Chrome, для которого вы завершаете проверку.
- Вы должны быть издателем элемента Интернет-магазина Chrome. Узнайте больше об управлении доступом на панели разработчика Интернет-магазина Chrome.
В разделе «Подтвердить право собственности на приложение» клиента расширений Chrome нажмите кнопку «Подтвердить право собственности» , чтобы завершить процесс проверки.
Примечание. Подождите несколько минут, прежде чем завершить процесс проверки после предоставления доступа к вашей учетной записи.
Если проверка прошла успешно, отобразится уведомление, подтверждающее успех процесса проверки. В противном случае будет показано сообщение об ошибке.
Чтобы исправить неудачную проверку, попробуйте следующее:
- Убедитесь, что на панели разработчика Интернет-магазина Chrome есть зарегистрированный элемент с тем же идентификатором, что и у клиента OAuth расширения Chrome, для которого вы завершаете проверку.
- Убедитесь, что вы являетесь издателем приложения, т. е. вы должны быть либо индивидуальным издателем приложения, либо членом группы издателей приложения. Узнайте больше об управлении доступом на панели разработчика Интернет-магазина Chrome.
- Если вы только что обновили список издателей группы, убедитесь, что список участников группы синхронизирован с панелью разработчика Интернет-магазина Chrome. Узнайте больше о синхронизации списка участников издателя.
IP-адрес обратной связи (macOS, Linux, рабочий стол Windows)
Чтобы получить код авторизации с использованием этого URL-адреса, ваше приложение должно прослушивать локальный веб-сервер. Это возможно на многих, но не на всех платформах. Однако, если ваша платформа поддерживает это, это рекомендуемый механизм получения кода авторизации.
Когда ваше приложение получает ответ на авторизацию, для лучшего удобства использования оно должно отреагировать, отобразив HTML-страницу, которая инструктирует пользователя закрыть браузер и вернуться в ваше приложение.
Рекомендуемое использование | Приложения для настольных компьютеров macOS, Linux и Windows (но не для универсальной платформы Windows) |
Формировать значения | Установите тип приложения « Приложение для ПК» . |
Ручное копирование/вставка
Определить области доступа
Области позволяют вашему приложению запрашивать доступ только к тем ресурсам, которые ему необходимы, а также позволяют пользователям контролировать объем доступа, который они предоставляют вашему приложению. Таким образом, может существовать обратная зависимость между количеством запрошенных областей и вероятностью получения согласия пользователя.
Прежде чем приступить к реализации авторизации OAuth 2.0, мы рекомендуем вам определить области, для доступа к которым вашему приложению потребуется разрешение.
API данных YouTube версии 3 использует следующие области действия:
Сферы | |
---|---|
https://www.googleapis.com/auth/youtube | Управляйте своим аккаунтом YouTube |
https://www.googleapis.com/auth/youtube.channel-memberships.creator | Просматривайте список ваших текущих активных участников канала, их текущий уровень и время, когда они стали участником. |
https://www.googleapis.com/auth/youtube.force-ssl | Просматривайте, редактируйте и безвозвратно удаляйте свои видео, рейтинги, комментарии и подписи на YouTube. |
https://www.googleapis.com/auth/youtube.readonly | Просмотрите свой аккаунт YouTube |
https://www.googleapis.com/auth/youtube.upload | Управляйте своими видео на YouTube |
https://www.googleapis.com/auth/youtubepartner | Просмотр и управление своими объектами и связанным контентом на YouTube |
https://www.googleapis.com/auth/youtubepartner-channel-audit | Просмотр личной информации о вашем канале YouTube, актуальной в процессе аудита с партнером YouTube. |
Документ «Области API OAuth 2.0» содержит полный список областей, которые вы можете использовать для доступа к API Google.
Получение токенов доступа OAuth 2.0
Следующие шаги показывают, как ваше приложение взаимодействует с сервером OAuth 2.0 Google, чтобы получить согласие пользователя на выполнение запроса API от имени пользователя. Ваше приложение должно получить это согласие, прежде чем оно сможет выполнить запрос Google API, требующий авторизации пользователя.
Шаг 1. Создайте средство проверки кода и проверите его.
Google поддерживает протокол Proof Key for Code Exchange (PKCE), чтобы сделать работу установленного приложения более безопасной. Для каждого запроса авторизации создается уникальный верификатор кода, и его преобразованное значение, называемое «code_challenge», отправляется на сервер авторизации для получения кода авторизации.
Создайте верификатор кода
code_verifier
— это криптографическая случайная строка с высокой энтропией, использующая незарезервированные символы [AZ] / [az] / [0-9] / «-» / «». / «_» / «~», минимальной длиной 43 символа и максимальной длиной 128 символов.
Верификатор кода должен иметь достаточную энтропию, чтобы угадать значение было непрактично.
Создать задачу по коду
Поддерживаются два метода создания задачи кода.
Методы генерации задач кода | |
---|---|
S256 (рекомендуется) | Задача кода — это хэш SHA256, закодированный в Base64URL (без заполнения), верификатора кода.
|
простой | Запрос кода имеет то же значение, что и верификатор кода, созданный выше.
|
Шаг 2. Отправьте запрос на сервер Google OAuth 2.0.
Чтобы получить авторизацию пользователя, отправьте запрос на сервер авторизации Google по адресу https://accounts.google.com/o/oauth2/v2/auth
. Эта конечная точка обрабатывает поиск активного сеанса, аутентифицирует пользователя и получает согласие пользователя. Конечная точка доступна только через SSL и отказывается от подключений HTTP (не SSL).
Сервер авторизации поддерживает следующие параметры строки запроса для установленных приложений:
Параметры | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id | Необходимый Идентификатор клиента для вашего приложения. Вы можете найти это значение в API ConsoleCredentials page. | ||||||||||||||||
redirect_uri | Необходимый Определяет, как сервер авторизации Google отправляет ответ вашему приложению. Для установленных приложений доступно несколько вариантов перенаправления, и вы должны настроить свои учетные данные для авторизации с учетом конкретного метода перенаправления. Значение должно точно совпадать с одним из авторизованных URI перенаправления для клиента OAuth 2.0, который вы настроили в настройках вашего клиента. API ConsoleCredentials page. Если это значение не соответствует авторизованному URI, вы получите ошибку В таблице ниже показано соответствующее значение параметра
| ||||||||||||||||
response_type | Необходимый Определяет, возвращает ли конечная точка Google OAuth 2.0 код авторизации. Установите значение параметра для | ||||||||||||||||
scope | Необходимый Список областей, разделенных пробелами, которые определяют ресурсы, к которым ваше приложение может получить доступ от имени пользователя. Эти значения указывают на экран согласия, который Google отображает пользователю. Области позволяют вашему приложению запрашивать доступ только к тем ресурсам, которые ему необходимы, а также позволяют пользователям контролировать объем доступа, который они предоставляют вашему приложению. Таким образом, существует обратная зависимость между количеством запрашиваемых областей и вероятностью получения согласия пользователя. API данных YouTube версии 3 использует следующие области действия:
В документе «Области API OAuth 2.0» представлен полный список областей, которые вы можете использовать для доступа к API Google. | ||||||||||||||||
code_challenge | Рекомендуется Указывает закодированный | ||||||||||||||||
code_challenge_method | Рекомендуется Указывает, какой метод использовался для кодирования | ||||||||||||||||
state | Рекомендуется Указывает любое строковое значение, которое ваше приложение использует для поддержания состояния между вашим запросом авторизации и ответом сервера авторизации. Сервер возвращает точное значение, которое вы отправляете в виде пары Вы можете использовать этот параметр для нескольких целей, например для направления пользователя на правильный ресурс в вашем приложении, отправки одноразовых номеров и предотвращения подделки межсайтовых запросов. Поскольку ваш | ||||||||||||||||
login_hint | Необязательный Если ваше приложение знает, какой пользователь пытается пройти аутентификацию, оно может использовать этот параметр, чтобы предоставить подсказку серверу аутентификации Google. Сервер использует подсказку, чтобы упростить процесс входа в систему, либо предварительно заполнив поле электронной почты в форме входа, либо выбрав соответствующий сеанс с несколькими входами. Установите в качестве значения параметра адрес электронной почты или |
Примеры URL-адресов авторизации
На вкладках ниже показаны примеры URL-адресов авторизации для различных вариантов URI перенаправления.
Каждый URL-адрес запрашивает доступ к области, которая разрешает доступ для получения данных пользователя YouTube. URL-адреса идентичны, за исключением значения параметра redirect_uri
. URL-адреса также содержат обязательные параметры response_type
и client_id
, а также необязательный параметр state
. Каждый URL-адрес содержит разрывы строк и пробелы для удобства чтения.
Пользовательская схема URI
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=com.example.app%3A/oauth2redirect& client_id=client_id
IP-адрес обратной связи
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=http%3A//127.0.0.1%3A9004& client_id=client_id
Шаг 3. Google запрашивает у пользователя согласие
На этом этапе пользователь решает, предоставить ли вашему приложению запрошенный доступ. На этом этапе Google отображает окно согласия, в котором отображается имя вашего приложения и сервисов Google API, к которым он запрашивает разрешение, с учетными данными авторизации пользователя и сводной информацией об объемах доступа, которые необходимо предоставить. Затем пользователь может согласиться предоставить доступ к одной или нескольким областям, запрошенным вашим приложением, или отклонить запрос.
На этом этапе вашему приложению не нужно ничего делать, поскольку оно ожидает ответа от сервера Google OAuth 2.0, указывающего, был ли предоставлен какой-либо доступ. Этот ответ объясняется на следующем шаге.
Ошибки
Запросы к конечной точке авторизации OAuth 2.0 Google могут отображать сообщения об ошибках вместо ожидаемых потоков аутентификации и авторизации. Ниже перечислены распространенные коды ошибок и предлагаемые решения.
admin_policy_enforced
Аккаунт Google не может авторизовать одну или несколько запрошенных областей в соответствии с правилами администратора Google Workspace. Дополнительную информацию о том, как администратор может ограничить доступ ко всем областям или конфиденциальным и ограниченным областям до тех пор, пока доступ не будет явно предоставлен вашему идентификатору клиента OAuth, можно найти в справочной статье администратора Google Workspace «Управление тем, какие сторонние и внутренние приложения получают доступ к данным Google Workspace».
disallowed_useragent
Конечная точка авторизации отображается внутри встроенного пользовательского агента, запрещенного политиками Google OAuth 2.0 .
Андроид
Разработчики Android могут столкнуться с этим сообщением об ошибке при открытии запросов авторизации вandroid.webkit.WebView
. Вместо этого разработчикам следует использовать библиотеки Android, такие как Google Sign-In для Android или AppAuth OpenID Foundation для Android .
Веб-разработчики могут столкнуться с этой ошибкой, когда приложение Android открывает общую веб-ссылку во встроенном пользовательском агенте, и пользователь переходит к конечной точке авторизации Google OAuth 2.0 с вашего сайта. Разработчики должны разрешить открытие общих ссылок в обработчике ссылок по умолчанию операционной системы, который включает в себя как обработчики ссылок приложений Android , так и браузерное приложение по умолчанию. Библиотека пользовательских вкладок Android также поддерживается.
iOS
Разработчики iOS и macOS могут столкнуться с этой ошибкой при открытии запросов авторизации вWKWebView
. Вместо этого разработчикам следует использовать библиотеки iOS, такие как Google Sign-In для iOS или AppAuth OpenID Foundation для iOS .
Веб-разработчики могут столкнуться с этой ошибкой, когда приложение iOS или macOS открывает общую веб-ссылку во встроенном пользовательском агенте, и пользователь переходит к конечной точке авторизации Google OAuth 2.0 с вашего сайта. Разработчики должны разрешить открытие общих ссылок в обработчике ссылок по умолчанию операционной системы, который включает в себя как обработчики универсальных ссылок , так и браузерное приложение по умолчанию. БиблиотекаSFSafariViewController
также поддерживается.
org_internal
Идентификатор клиента OAuth в запросе является частью проекта, ограничивающего доступ к аккаунтам Google в конкретной организации Google Cloud . Дополнительные сведения об этом параметре конфигурации см. в разделе «Тип пользователя» в справочной статье «Настройка экрана согласия OAuth».
invalid_grant
Если вы используете средство проверки кода и вызов , параметр code_callenge
недействителен или отсутствует. Убедитесь, что параметр code_challenge
установлен правильно.
При обновлении токена доступа возможно, срок действия токена истек или он стал недействительным. Аутентифицируйте пользователя еще раз и запросите согласие пользователя на получение новых токенов. Если вы продолжаете видеть эту ошибку, убедитесь, что ваше приложение настроено правильно и что вы используете правильные токены и параметры в своем запросе. В противном случае учетная запись пользователя могла быть удалена или отключена.
redirect_uri_mismatch
redirect_uri
, переданный в запросе авторизации, не соответствует авторизованному URI перенаправления для идентификатора клиента OAuth. Просмотрите разрешенные URI перенаправления в Google API Console Credentials page.
Переданный redirect_uri
может быть недопустимым для типа клиента.
Параметр redirect_uri
может относиться к внеполосному потоку OAuth (OOB), который устарел и больше не поддерживается. Обратитесь к руководству по миграции , чтобы обновить интеграцию.
invalid_request
Что-то не так с вашим запросом. Это может быть связано с рядом причин:
- Запрос был неправильно отформатирован
- В запросе отсутствовали необходимые параметры
- В запросе используется метод авторизации, который Google не поддерживает. Убедитесь, что в вашей интеграции OAuth используется рекомендуемый метод интеграции.
- Для URI перенаправления используется пользовательская схема: если вы видите сообщение об ошибке. Пользовательская схема URI не поддерживается в приложениях Chrome или пользовательская схема URI не включена для вашего клиента Android , это означает, что вы используете собственную схему URI, которая не поддерживается. поддерживается в приложениях Chrome и по умолчанию отключен на Android. Узнайте больше об альтернативах пользовательских схем URI.
Шаг 4. Обработка ответа сервера OAuth 2.0
Способ получения приложением ответа на авторизацию зависит от используемой им схемы URI перенаправления . Независимо от схемы, ответ будет содержать либо код авторизации ( code
), либо ошибку ( error
). Например, error=access_denied
указывает, что пользователь отклонил запрос.
Если пользователь предоставляет доступ к вашему приложению, вы можете обменять код авторизации на токен доступа и токен обновления, как описано в следующем шаге.
Шаг 5. Обмен кода авторизации для токенов обновления и доступа.
Чтобы обменять код авторизации на токен доступа, вызовите конечную точку https://oauth2.googleapis.com/token
и установите следующие параметры:
Поля | |
---|---|
client_id | Идентификатор клиента, полученный из API ConsoleCredentials page. |
client_secret | Секрет клиента, полученный от API ConsoleCredentials page. |
code | Код авторизации, возвращенный из первоначального запроса. |
code_verifier | Средство проверки кода, созданное на шаге 1 . |
grant_type | Как определено в спецификации OAuth 2.0 , значение этого поля должно быть установлено в authorization_code . |
redirect_uri | Один из URI перенаправления, перечисленных для вашего проекта в API ConsoleCredentials page для данного client_id . |
В следующем фрагменте показан пример запроса:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your_client_id& client_secret=your_client_secret& redirect_uri=http://127.0.0.1:9004& grant_type=authorization_code
Google отвечает на этот запрос, возвращая объект JSON, содержащий кратковременный токен доступа и токен обновления.
Ответ содержит следующие поля:
Поля | |
---|---|
access_token | Токен, который ваше приложение отправляет для авторизации запроса Google API. |
expires_in | Оставшийся срок действия токена доступа в секундах. |
id_token | Примечание. Это свойство возвращается только в том случае, если ваш запрос включал область идентификации, например openid , profile или email . Значением является веб-токен JSON (JWT), который содержит идентификационную информацию пользователя с цифровой подписью. |
refresh_token | Токен, который можно использовать для получения нового токена доступа. Токены обновления действительны до тех пор, пока пользователь не отзовет доступ. Обратите внимание, что токены обновления всегда возвращаются для установленных приложений. |
scope | Области доступа, предоставляемые access_token , выражаются в виде списка строк, разделенных пробелами и чувствительных к регистру. |
token_type | Тип возвращенного токена. В настоящее время значение этого поля всегда установлено на Bearer . |
В следующем фрагменте показан пример ответа:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/youtube.force-ssl", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Вызов API Google
После того как ваше приложение получит токен доступа, вы можете использовать его для выполнения вызовов API Google от имени определенной учетной записи пользователя, если предоставлены области доступа, требуемые API. Для этого включите токен доступа в запрос к API, включив либо параметр запроса access_token
, либо значение Bearer
HTTP-заголовка Authorization
. Когда это возможно, предпочтительнее использовать HTTP-заголовок, поскольку строки запроса обычно видны в журналах сервера. В большинстве случаев вы можете использовать клиентскую библиотеку для настройки вызовов API Google (например, при вызове API потоковой передачи YouTube Live ).
Обратите внимание, что API YouTube Live Streaming не поддерживает поток учетной записи службы. Поскольку невозможно связать учетную запись службы с учетной записью YouTube, попытки авторизовать запросы с помощью этого процесса приведут к ошибке NoLinkedYouTubeAccount
.
Вы можете опробовать все API Google и просмотреть их возможности на игровой площадке OAuth 2.0 .
Примеры HTTP GET
Вызов конечной точки liveBroadcasts.list
(API YouTube Live Streaming) с использованием HTTP-заголовка Authorization: Bearer
может выглядеть следующим образом. Обратите внимание, что вам необходимо указать свой собственный токен доступа:
GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Вот вызов того же API для аутентифицированного пользователя с использованием параметра строки запроса access_token
:
GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
примеры curl
Вы можете протестировать эти команды с помощью приложения командной строки curl
. Вот пример, в котором используется опция HTTP-заголовка (предпочтительно):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true
Или, альтернативно, опция параметра строки запроса:
curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
Обновление токена доступа
Срок действия маркеров доступа периодически истекает, и они становятся недействительными учетными данными для связанного запроса API. Вы можете обновить токен доступа, не запрашивая у пользователя разрешения (в том числе, когда пользователь отсутствует), если вы запросили автономный доступ к областям, связанным с токеном.
Чтобы обновить токен доступа, ваше приложение отправляет запрос HTTPS POST
на сервер авторизации Google ( https://oauth2.googleapis.com/token
), который включает следующие параметры:
Поля | |
---|---|
client_id | Идентификатор клиента, полученный из API Console. |
client_secret | Секрет клиента, полученный от API Console. (Свойство client_secret неприменимо к запросам от клиентов, зарегистрированных как приложения Android, iOS или Chrome.) |
grant_type | Как определено в спецификации OAuth 2.0 , для этого поля должно быть установлено refresh_token . |
refresh_token | Токен обновления, возвращенный в результате обмена кодами авторизации. |
В следующем фрагменте показан пример запроса:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=your_client_id& client_secret=your_client_secret& refresh_token=refresh_token& grant_type=refresh_token
Пока пользователь не отозвал доступ, предоставленный приложению, сервер токенов возвращает объект JSON, содержащий новый токен доступа. В следующем фрагменте показан пример ответа:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "scope": "https://www.googleapis.com/auth/drive.metadata.readonly", "token_type": "Bearer" }
Обратите внимание, что существуют ограничения на количество выпускаемых токенов обновления; одно ограничение на комбинацию клиент/пользователь и другое на пользователя для всех клиентов. Вам следует сохранять токены обновления в долгосрочном хранилище и продолжать использовать их, пока они остаются действительными. Если ваше приложение запрашивает слишком много токенов обновления, оно может столкнуться с этими ограничениями, и в этом случае старые токены обновления перестанут работать.
Отзыв токена
В некоторых случаях пользователь может захотеть отозвать доступ, предоставленный приложению. Пользователь может отозвать доступ, посетив настройки учетной записи . Дополнительную информацию см . в разделе «Удалить доступ к сайту или приложению» в документе поддержки «Сторонние сайты и приложения с доступом к вашей учетной записи» .
Приложение также может программно отозвать предоставленный ему доступ. Программный отзыв важен в тех случаях, когда пользователь отписывается от подписки, удаляет приложение или ресурсы API, необходимые приложению, значительно изменились. Другими словами, часть процесса удаления может включать запрос API, чтобы гарантировать удаление ранее предоставленных приложению разрешений.
Чтобы программно отозвать токен, ваше приложение отправляет запрос на https://oauth2.googleapis.com/revoke
и включает токен в качестве параметра:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \ https://oauth2.googleapis.com/revoke?token={token}
Маркер может быть маркером доступа или маркером обновления. Если токен является токеном доступа и имеет соответствующий токен обновления, токен обновления также будет отозван.
Если отзыв успешно обработан, код состояния HTTP ответа — 200
. В случае возникновения ошибки код состояния HTTP 400
возвращается вместе с кодом ошибки.
Дальнейшее чтение
В документе IETF Best Current Practice OAuth 2.0 для собственных приложений отражены многие из лучших практик, описанных здесь.
Реализация защиты между аккаунтами
Дополнительным шагом, который вам следует предпринять для защиты учетных записей ваших пользователей, является внедрение защиты между учетными записями с помощью службы защиты между учетными записями Google. Эта служба позволяет вам подписаться на уведомления о событиях безопасности, которые предоставляют вашему приложению информацию о серьезных изменениях в учетной записи пользователя. Затем вы можете использовать эту информацию, чтобы принять меры в зависимости от того, как вы решите реагировать на события.
Вот некоторые примеры типов событий, отправляемых в ваше приложение службой защиты нескольких аккаунтов Google:
-
https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
-
https://schemas.openid.net/secevent/oauth/event-type/token-revoked
-
https://schemas.openid.net/secevent/risc/event-type/account-disabled
См. страницу «Защита учетных записей пользователей с помощью защиты нескольких учетных записей», чтобы получить дополнительную информацию о том, как реализовать защиту нескольких учетных записей, а также полный список доступных событий.