В этом документе объясняется, как приложения, установленные на таких устройствах, как телефоны, планшеты и компьютеры, используют конечные точки OAuth 2.0 Google для авторизации доступа к API YouTube Analytics или API отчетов YouTube.
OAuth 2.0 позволяет пользователям обмениваться определенными данными с приложением, сохраняя при этом свои имена пользователей, пароли и другую информацию конфиденциальной. Например, приложение может использовать OAuth 2.0 для получения разрешения на получение данных YouTube Analytics канала.
Установленные приложения распространяются на отдельные устройства, и предполагается, что эти приложения не могут хранить секреты. Они могут получить доступ к 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 Analytics и API отчетов YouTube. Многие приложения, получающие данные YouTube Analytics, также взаимодействуют с 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.
Примечание. Поле «Идентификатор команды» является обязательным, если вы включаете проверку приложений для своего клиента. - (Необязательный)
Включите проверку приложений для вашего приложения iOS. Когда вы включаете проверку приложений, служба Apple App Attest используется для проверки того, что запросы OAuth 2.0, исходящие от вашего клиента OAuth, являются подлинными и поступают из вашего приложения. Это помогает снизить риск подделки приложения. Узнайте больше о включении проверки приложений для вашего приложения iOS .
- Нажмите Создать .
UWP
- Выберите тип приложения универсальной платформы Windows .
- Введите имя клиента OAuth. Это имя отображается в вашем проекте Credentials page для идентификации клиента.
- Введите 12-значный идентификатор вашего приложения в Microsoft Store. Это значение можно найти в Центре партнеров Microsoft на странице удостоверения приложения в разделе «Управление приложениями».
- Нажмите Создать .
Для приложений UWP длина пользовательской схемы URI не может превышать 39 символов.
Определить области доступа
Области позволяют вашему приложению запрашивать доступ только к тем ресурсам, которые ему необходимы, а также позволяют пользователям контролировать объем доступа, который они предоставляют вашему приложению. Таким образом, может существовать обратная зависимость между количеством запрошенных областей и вероятностью получения согласия пользователя.
Прежде чем приступить к реализации авторизации OAuth 2.0, мы рекомендуем вам определить области, для доступа к которым вашему приложению потребуется разрешение.
API YouTube Analytics использует следующие области действия:
| Области применения | |
|---|---|
| https://www.googleapis.com/auth/youtube | Управляйте своим аккаунтом YouTube |
| https://www.googleapis.com/auth/youtube.readonly | Просмотрите свой аккаунт YouTube |
| https://www.googleapis.com/auth/youtubepartner | Просматривайте свои объекты и связанный с ними контент на YouTube и управляйте ими. |
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | Просматривайте денежные и неденежные отчеты YouTube Analytics для вашего контента YouTube. |
| https://www.googleapis.com/auth/yt-analytics.readonly | Просмотр отчетов YouTube Analytics для вашего контента YouTube |
| Области применения | |
|---|---|
| https://www.googleapis.com/auth/youtube | Управляйте своим аккаунтом YouTube |
| https://www.googleapis.com/auth/youtube.readonly | Просмотрите свой аккаунт YouTube |
| https://www.googleapis.com/auth/youtubepartner | Просматривайте свои объекты и связанный с ними контент на YouTube и управляйте ими. |
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | Просматривайте денежные и неденежные отчеты YouTube Analytics для вашего контента YouTube. |
| https://www.googleapis.com/auth/yt-analytics.readonly | Просмотр отчетов YouTube Analytics для вашего контента YouTube |
| Области применения | |
|---|---|
| https://www.googleapis.com/auth/youtube | Управляйте своим аккаунтом YouTube |
| https://www.googleapis.com/auth/youtube.readonly | Просмотрите свой аккаунт YouTube |
| https://www.googleapis.com/auth/youtubepartner | Просматривайте свои объекты и связанный с ними контент на YouTube и управляйте ими. |
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | Просматривайте денежные и неденежные отчеты YouTube Analytics для вашего контента YouTube. |
| https://www.googleapis.com/auth/yt-analytics.readonly | Просмотр отчетов YouTube Analytics для вашего контента YouTube |
| Области применения | |
|---|---|
| https://www.googleapis.com/auth/youtube | Управляйте своим аккаунтом YouTube |
| https://www.googleapis.com/auth/youtube.readonly | Просмотрите свой аккаунт YouTube |
| https://www.googleapis.com/auth/youtubepartner | Просматривайте свои объекты и связанный с ними контент на YouTube и управляйте ими. |
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | Просматривайте денежные и неденежные отчеты YouTube Analytics для вашего контента YouTube. |
| https://www.googleapis.com/auth/yt-analytics.readonly | Просмотр отчетов YouTube Analytics для вашего контента YouTube |
API отчетов YouTube использует следующие области действия:
| Области применения | |
|---|---|
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | Просматривайте денежные и неденежные отчеты YouTube Analytics для вашего контента YouTube. |
| https://www.googleapis.com/auth/yt-analytics.readonly | Просмотр отчетов YouTube Analytics для вашего контента YouTube |
| Области применения | |
|---|---|
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | Просматривайте денежные и неденежные отчеты YouTube Analytics для вашего контента YouTube. |
| https://www.googleapis.com/auth/yt-analytics.readonly | Просмотр отчетов YouTube Analytics для вашего контента YouTube |
| Области применения | |
|---|---|
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | Просмотр денежных и неденежных отчетов YouTube Analytics для вашего контента YouTube. |
| https://www.googleapis.com/auth/yt-analytics.readonly | Просмотр отчетов YouTube Analytics для вашего контента YouTube |
| Области применения | |
|---|---|
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | Просматривайте денежные и неденежные отчеты YouTube Analytics для вашего контента YouTube. |
| https://www.googleapis.com/auth/yt-analytics.readonly | Просмотр отчетов YouTube Analytics для вашего контента 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 Analytics использует следующие области действия:
API отчетов YouTube использует следующие области действия:
В документе «Области API OAuth 2.0» представлен полный список областей, которые вы можете использовать для доступа к API Google. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
code_challenge | Рекомендуется Указывает закодированный | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
code_challenge_method | Рекомендуется Указывает, какой метод использовался для кодирования | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
state | Рекомендуется Указывает любое строковое значение, которое ваше приложение использует для поддержания состояния между вашим запросом авторизации и ответом сервера авторизации. Сервер возвращает точное значение, которое вы отправляете в виде пары Этот параметр можно использовать для нескольких целей, например для направления пользователя к правильному ресурсу в вашем приложении, отправки одноразовых номеров и предотвращения подделки межсайтовых запросов. Поскольку ваш | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
login_hint | Необязательный Если ваше приложение знает, какой пользователь пытается пройти аутентификацию, оно может использовать этот параметр, чтобы предоставить подсказку серверу аутентификации Google. Сервер использует подсказку, чтобы упростить процесс входа в систему, либо предварительно заполнив поле электронной почты в форме входа, либо выбрав соответствующий сеанс с несколькими входами. Установите в качестве значения параметра адрес электронной почты или | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Примеры URL-адресов авторизации
На вкладках ниже показаны примеры URL-адресов авторизации для различных вариантов URI перенаправления.
Каждый URL-адрес запрашивает доступ к области, которая разрешает доступ для получения отчетов YouTube Analytics пользователя. 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%2Fyt-analytics.readonly& 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%2Fyt-analytics.readonly& 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/yt-analytics.readonly",
"refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}Вызов API Google
После того как ваше приложение получит токен доступа, вы можете использовать его для выполнения вызовов API Google от имени определенной учетной записи пользователя, если предоставлены области доступа, требуемые API. Для этого включите токен доступа в запрос к API, включив либо параметр запроса access_token , либо значение Bearer HTTP-заголовка Authorization . Если это возможно, предпочтительнее использовать HTTP-заголовок, поскольку строки запроса обычно видны в журналах сервера. В большинстве случаев вы можете использовать клиентскую библиотеку для настройки вызовов API Google (например, при вызове API YouTube Analytics ).
Обратите внимание, что API YouTube Analytics не поддерживает поток сервисного аккаунта. API отчетов YouTube поддерживает учетные записи служб только для владельцев контента YouTube, которые владеют и управляют несколькими каналами YouTube, например звукозаписывающих компаний и киностудий.
Вы можете опробовать все API Google и просмотреть их возможности на игровой площадке OAuth 2.0 .
Примеры HTTP GET
Вызов конечной точки reports.query (API YouTube Analytics) с использованием HTTP-заголовка Authorization: Bearer может выглядеть следующим образом. Обратите внимание, что вам необходимо указать свой собственный токен доступа:
GET /youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Вот вызов того же API для аутентифицированного пользователя с использованием параметра строки запроса access_token :
GET https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
примеры curl
Вы можете протестировать эти команды с помощью приложения командной строки curl . Вот пример, в котором используется опция HTTP-заголовка (предпочтительно):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
Или, альтернативно, опция параметра строки запроса:
curl https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
Обновление токена доступа
Срок действия маркеров доступа периодически истекает, и они становятся недействительными учетными данными для связанного запроса 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 возвращается вместе с кодом ошибки.
Методы перенаправления приложений
Пользовательская схема URI (Android, iOS, UWP)
Пользовательские схемы URI — это форма диплинкинга, в которой для открытия вашего приложения используется настраиваемая схема.
Альтернатива использованию пользовательских схем URI на Android
Используйте Google Sign-In для Android SDK , который доставляет ответ OAuth 2.0 непосредственно в ваше приложение, устраняя необходимость в URI перенаправления.
Как перейти на Google Sign-In для Android SDK
Если вы используете специальную схему для интеграции OAuth на Android, вам потребуется выполнить следующие действия, чтобы полностью перейти на использование рекомендуемого пакета SDK Google Sign-In для Android:
- Обновите свой код, чтобы использовать 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.
Альтернатива использованию пользовательских схем URI в приложениях Chrome.
Используйте Chrome Identity API , который доставляет ответ OAuth 2.0 непосредственно в ваше приложение, устраняя необходимость в URI перенаправления.
IP-адрес обратной связи (macOS, Linux, рабочий стол Windows)
Чтобы получить код авторизации с использованием этого URL-адреса, ваше приложение должно прослушивать локальный веб-сервер. Это возможно на многих, но не на всех платформах. Однако, если ваша платформа поддерживает это, это рекомендуемый механизм получения кода авторизации.
Когда ваше приложение получает ответ на авторизацию, для максимального удобства использования оно должно отреагировать, отобразив HTML-страницу, которая инструктирует пользователя закрыть браузер и вернуться в ваше приложение.
| Рекомендуемое использование | Настольные приложения для macOS, Linux и Windows (но не для универсальной платформы Windows) |
| Формировать значения | Установите тип приложения « Приложение для ПК» . |
Копирование/вставка вручную (устарело)
Защитите свои приложения
Подтвердите право собственности на приложение (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. Узнайте больше о синхронизации списка участников издателя.
Проверка приложений (только iOS)
Функция проверки приложений помогает защитить ваши приложения iOS от несанкционированного использования, используя службу Apple App Attest , чтобы убедиться, что запросы, сделанные к конечным точкам Google OAuth 2.0, исходят от ваших подлинных приложений. Это помогает снизить риск подделки приложения.
Включите проверку приложений для вашего iOS-клиента
Для успешного включения проверки приложений для вашего клиента iOS должны быть выполнены следующие требования:- Вы должны указать идентификатор команды для вашего iOS-клиента.
- Вы не должны использовать подстановочный знак в идентификаторе пакета, поскольку он может относиться к более чем одному приложению. Это означает, что идентификатор пакета не должен содержать символ звездочки (*).
После включения проверки приложений вы начнете видеть метрики, связанные с запросами OAuth от вашего клиента, в режиме редактирования клиента OAuth. Запросы из непроверенных источников не будут блокироваться, пока вы не включите проверку приложений . Информация на странице мониторинга показателей может помочь вам определить, когда начинать принудительное применение.
Вы можете увидеть ошибки, связанные с функцией проверки приложений, при включении проверки приложений для вашего приложения iOS. Чтобы исправить эти ошибки, попробуйте следующее:
- Убедитесь, что указанные вами идентификатор пакета и идентификатор группы действительны.
- Убедитесь, что вы не используете подстановочный знак для идентификатора пакета.
Принудительная проверка приложений для вашего iOS-клиента
Включение проверки приложений для вашего приложения не блокирует автоматически нераспознанные запросы. Чтобы обеспечить эту защиту, перейдите в режим редактирования вашего клиента iOS. Там вы увидите показатели проверки приложений справа на странице в разделе Google Identity для iOS . Метрики включают в себя следующую информацию:- Количество проверенных запросов — запросов, имеющих действительный токен проверки приложений. После включения принудительной проверки приложений успешны будут только запросы этой категории.
- Количество непроверенных запросов: вероятно, устаревшие клиентские запросы — запросы, в которых отсутствует токен проверки приложений; этот запрос может исходить от более старой версии вашего приложения, которая не включает реализацию проверки приложений.
- Количество непроверенных запросов: запросы неизвестного происхождения — запросы, в которых отсутствует токен проверки приложений, и которые не выглядят так, как будто они исходят из вашего приложения.
- Количество непроверенных запросов: недействительные запросы — запросы с недействительным токеном проверки приложений, которые могут исходить от недостоверного клиента, пытающегося выдать себя за ваше приложение, или из эмулируемых сред.
Чтобы принудительно выполнить проверку приложений, нажмите кнопку «ПРИМЕНИТЬ» и подтвердите свой выбор. Как только принудительное исполнение будет активировано, все непроверенные запросы от вашего клиента будут отклонены.
Примечание . После включения принудительного применения изменения вступят в силу в течение 15 минут.
Отмените обязательную проверку приложений для вашего iOS-клиента
Отмена проверки приложений для вашего приложения приведет к прекращению принудительного применения и разрешению всех запросов от вашего клиента к конечным точкам Google OAuth 2.0, включая непроверенные запросы.
Чтобы отменить проверку приложений для вашего клиента iOS, перейдите в режим редактирования клиента iOS, нажмите кнопку ОТМЕНИТЬ ПРИМЕНЕНИЕ и подтвердите свой выбор.
Примечание . После отмены проверки приложений изменения вступят в силу в течение 15 минут.
Отключите проверку приложений для вашего iOS-клиента
Отключение проверки приложений для вашего приложения приведет к прекращению любого мониторинга и применения проверки приложений. Вместо этого рассмотрите возможность отмены принудительной проверки приложений, чтобы вы могли продолжать отслеживать показатели для своего клиента.
Чтобы отключить проверку приложений для вашего клиента iOS, перейдите в режим редактирования клиента iOS и отключите кнопку-переключатель Защитите свой клиент OAuth от злоупотреблений с помощью проверки приложений Firebase .
Примечание . После отключения проверки приложений может пройти до 15 минут, прежде чем изменения вступят в силу.
Дальнейшее чтение
В документе 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
См. страницу «Защита учетных записей пользователей с помощью защиты нескольких учетных записей», чтобы получить дополнительную информацию о том, как реализовать защиту нескольких учетных записей, а также полный список доступных событий.