В этом документе объясняется, как приложения, установленные на таких устройствах, как телефоны, планшеты и компьютеры, используют конечные точки Google OAuth 2.0 для авторизации доступа к API YouTube Analytics или API YouTube Reporting.
OAuth 2.0 позволяет пользователям делиться определёнными данными с приложением, сохраняя при этом свои имена пользователей, пароли и другую информацию в тайне. Например, приложение может использовать OAuth 2.0 для получения разрешения на доступ к данным YouTube Analytics канала.
Установленные приложения распространяются на отдельные устройства, и предполагается, что эти приложения не могут хранить секреты. Они могут обращаться к API Google, пока пользователь находится в приложении или когда приложение работает в фоновом режиме.
Этот процесс авторизации аналогичен процессу, используемому для приложений веб-сервера . Основное отличие заключается в том, что установленные приложения должны открывать системный браузер и предоставлять локальный URI перенаправления для обработки ответов сервера авторизации Google.
Библиотеки и образцы
Для мобильных приложений мы рекомендуем использовать последнюю версию нативной библиотеки Google Identity Services для Android и нативную библиотеку Google Sign-In для iOS . Эти библиотеки обрабатывают авторизацию пользователей и проще в реализации, чем описанный здесь протокол более низкого уровня.
Для приложений, работающих на устройствах, которые не поддерживают системный браузер или имеют ограниченные возможности ввода, таких как телевизоры, игровые консоли, камеры или принтеры, см. раздел 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 Reporting на странице «Библиотека». Многие приложения, извлекающие данные YouTube Analytics, также взаимодействуют с API данных YouTube. Найдите другие API, которые будет использовать ваше приложение, и включите их.
Создать учетные данные авторизации
Любое приложение, использующее OAuth 2.0 для доступа к API Google, должно иметь учётные данные авторизации, которые идентифицируют приложение на сервере OAuth 2.0 Google. Ниже описано, как создать учётные данные для вашего проекта. Затем ваши приложения смогут использовать эти учётные данные для доступа к API, которые вы включили для этого проекта.
- Go to the Credentials page.
- Нажмите «Создать клиента» .
- В следующих разделах описаны типы клиентов, поддерживаемые сервером авторизации Google. Выберите тип клиента, рекомендуемый для вашего приложения, назовите своего OAuth-клиента и заполните остальные поля формы соответствующим образом.
Андроид
- Выберите тип приложения Android .
- Введите имя для клиента OAuth. Это имя будет отображаться в вашем проекте. для идентификации клиента.
- Введите имя пакета вашего приложения для Android. Это значение указано в атрибуте
packageэлемента<manifest>в файле манифеста вашего приложения. - Введите отпечаток сертификата подписи SHA-1 для дистрибутива приложения.
- Если ваше приложение использует функцию подписи приложений Google Play , скопируйте отпечаток SHA-1 со страницы подписи приложений в Play Console.
- Если вы управляете собственным хранилищем ключей и ключами подписи, используйте утилиту keytool , входящую в состав Java, для вывода информации о сертификате в удобном для восприятия формате. Скопируйте значение
SHA1из разделаCertificate fingerprintsв результатах работы keytool . Подробнее см. в разделе «Аутентификация клиента» в документации по API Google для Android.
- (Необязательно) Подтвердите право собственности на ваше приложение для Android.
- Нажмите «Создать» .
iOS
- Выберите тип приложения iOS .
- Введите имя для клиента OAuth. Это имя будет отображаться в вашем проекте. для идентификации клиента.
- Введите идентификатор пакета для вашего приложения. Идентификатор пакета — это значение ключа CFBundleIdentifier в файле ресурсов списка свойств информации вашего приложения ( info.plist ). Это значение чаще всего отображается на панели «Общие» или на панели «Подписание и возможности» редактора проектов Xcode. Идентификатор пакета также отображается в разделе «Общая информация» на странице «Информация о приложении» на сайте App Store Connect от Apple .
Убедитесь, что вы используете правильный идентификатор пакета для своего приложения, так как вы не сможете изменить его, если используете функцию проверки приложений.
- (Необязательный)
Введите идентификатор App Store вашего приложения, если оно опубликовано в App Store от Apple. Идентификатор Store — это числовая строка, включённая в каждый URL-адрес Apple App Store.
- Откройте приложение Apple App Store на устройстве iOS или iPadOS.
- Найдите свое приложение.
- Нажмите кнопку «Поделиться» (квадрат и стрелка вверх).
- Выберите Копировать ссылку .
- Вставьте ссылку в текстовый редактор. Идентификатор App Store — это последняя часть URL.
Пример:
https://apps.apple.com/app/google/id 284815942
- (Необязательный)
Введите идентификатор вашей команды. Подробнее см. в разделе «Как найти идентификатор вашей команды» в документации по учётной записи разработчика Apple.
Примечание: Поле «Идентификатор команды» является обязательным, если вы включаете проверку приложений для своего клиента. - (Необязательный)
Включите проверку приложений (App Check) для вашего приложения iOS. При включении проверки приложений (App Check) служба App Attest от Apple используется для проверки подлинности запросов OAuth 2.0, исходящих от вашего клиента OAuth, и их исходимости от вашего приложения. Это помогает снизить риск маскировки приложения под другое лицо. Узнайте больше о включении проверки приложений (App Check) для вашего приложения iOS .
- Нажмите «Создать» .
UWP
- Выберите тип приложения «Универсальная платформа Windows» .
- Введите имя для клиента OAuth. Это имя будет отображаться в вашем проекте. для идентификации клиента.
- Введите 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 |
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 |
Документ «Области действия API OAuth 2.0» содержит полный список областей действия, которые можно использовать для доступа к API Google.
Получение токенов доступа OAuth 2.0
Следующие шаги показывают, как ваше приложение взаимодействует с сервером OAuth 2.0 Google для получения согласия пользователя на выполнение API-запроса от его имени. Ваше приложение должно получить это согласие, прежде чем сможет выполнить запрос к API Google, требующий авторизации пользователя.
Шаг 1: Создайте верификатор кода и задайте вопрос
Google поддерживает протокол Proof Key for Code Exchange (PKCE) для повышения безопасности процесса установки приложения. Для каждого запроса авторизации создаётся уникальный код-верификатор, и его преобразованное значение, называемое «code_challenge», отправляется на сервер авторизации для получения кода авторизации.
Создайте верификатор кода
code_verifier — это высокоэнтропийная криптографическая случайная строка, использующая незарезервированные символы [AZ] / [az] / [0-9] / "-" / "." / "_" / "~", минимальной длиной 43 символа и максимальной длиной 128 символов.
Верификатор кода должен обладать достаточной энтропией, чтобы сделать угадывание значения нецелесообразным.
Создайте кодовое задание
Поддерживаются два метода создания задания по коду.
| Методы генерации кода вызова | |
|---|---|
| S256 (рекомендуется) | Проверка кода представляет собой хэш SHA256 верификатора кода, закодированный в формате Base64URL (без заполнения).
|
| простой | Код проверки имеет то же значение, что и верификатор кода, сгенерированный выше.
|
Шаг 2: Отправьте запрос на сервер OAuth 2.0 Google.
Чтобы получить авторизацию пользователя, отправьте запрос на сервер авторизации Google по адресу https://accounts.google.com/o/oauth2/v2/auth . Эта конечная точка обрабатывает поиск активных сеансов, аутентифицирует пользователя и получает его согласие. Доступ к конечной точке возможен только по протоколу SSL, и она отклоняет HTTP-подключения (не SSL).
Сервер авторизации поддерживает следующие параметры строки запроса для установленных приложений:
| Параметры | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id | Необходимый Идентификатор клиента для вашего приложения. Вы можете найти это значение в . | ||||||||||||||||||
redirect_uri | Необходимый Определяет, как сервер авторизации Google отправляет ответ вашему приложению. Для установленных приложений доступно несколько вариантов перенаправления, и вам необходимо настроить учётные данные авторизации с учётом конкретного метода перенаправления. Значение должно точно соответствовать одному из разрешенных URI перенаправления для клиента OAuth 2.0, который вы настроили в клиенте. . Если это значение не соответствует авторизованному 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 о предоставлении доступа. Этот ответ поясняется на следующем шаге.
Ошибки
Запросы к конечной точке авторизации Google OAuth 2.0 могут отображать сообщения об ошибках вместо ожидаемых процессов аутентификации и авторизации. Ниже перечислены распространённые коды ошибок и рекомендуемые способы их устранения.
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 для Android от OpenID Foundation.
Веб-разработчики могут столкнуться с этой ошибкой, когда приложение Android открывает общую веб-ссылку во встроенном пользовательском агенте, а пользователь переходит с вашего сайта на конечную точку авторизации Google OAuth 2.0. Разработчикам следует разрешить открытие общих ссылок в обработчике ссылок по умолчанию операционной системы, который включает как обработчики ссылок приложений Android, так и приложение браузера по умолчанию. Библиотека Android Custom Tabs также поддерживается.
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».
deleted_client
Клиент OAuth, использованный для выполнения запроса, был удалён. Удаление может быть выполнено вручную или автоматически в случае неиспользуемых клиентов . Удалённые клиенты могут быть восстановлены в течение 30 дней с момента удаления. Подробнее .
invalid_grant
Если вы используете верификатор кода и вызов , параметр code_callenge недействителен или отсутствует. Убедитесь, что параметр code_challenge задан правильно.
При обновлении токена доступа он мог быть просрочен или недействителен. Повторно аутентифицируйте пользователя и запросите его согласие на получение новых токенов. Если эта ошибка продолжает появляться, убедитесь, что ваше приложение настроено правильно и вы используете правильные токены и параметры в запросе. В противном случае учётная запись пользователя могла быть удалена или отключена.
redirect_uri_mismatch
redirect_uri переданный в запросе авторизации, не соответствует авторизованному URI перенаправления для идентификатора клиента OAuth. Проверьте авторизованные URI перенаправления в .
Переданный redirect_uri может быть недопустимым для данного типа клиента.
Параметр redirect_uri может ссылаться на внеполосный (OOB) поток OAuth, который устарел и больше не поддерживается. Чтобы обновить интеграцию, обратитесь к руководству по миграции .
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 | Идентификатор клиента, полученный из . |
client_secret | Секрет клиента, полученный от . |
code | Код авторизации, возвращенный из первоначального запроса. |
code_verifier | Верификатор кода, созданный вами на Шаге 1 . |
grant_type | Как определено в спецификации OAuth 2.0 , значение этого поля должно быть установлено на authorization_code . |
redirect_uri | Один из URI перенаправления, перечисленных для вашего проекта в для заданного 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 | Токен, который ваше приложение отправляет для авторизации запроса API Google. |
expires_in | Оставшееся время жизни токена доступа в секундах. |
id_token | Примечание: Это свойство возвращается только в том случае, если ваш запрос включает область действия идентификатора, например, openid , profile или email . Значение представляет собой веб-токен JSON (JWT), содержащий цифровую подпись идентификационной информации пользователя. |
refresh_token | Токен, который можно использовать для получения нового токена доступа. Токены обновления действительны до тех пор, пока пользователь не отзовёт доступ или пока не истечёт срок действия токена обновления. Обратите внимание, что токены обновления всегда возвращаются для установленных приложений. |
refresh_token_expires_in | Оставшееся время жизни токена обновления в секундах. Это значение устанавливается только в том случае, если пользователь предоставляет доступ с ограничением по времени . |
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 https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Шаг 6: Проверьте, какие области действия предоставлены пользователями
При запросе нескольких разрешений (областей действия) пользователи могут не предоставить вашему приложению доступ ко всем из них. Ваше приложение должно проверять, какие области действия были фактически предоставлены, и корректно обрабатывать ситуации, когда некоторые разрешения отклонены, обычно путём отключения функций, зависящих от этих отклоненных областей действия.
Однако есть исключения. Приложения Google Workspace Enterprise с делегированием полномочий на уровне домена или приложения, помеченные как «Доверенные» , обходят экран согласия на детализированные разрешения. В таких приложениях пользователи не увидят экран согласия на детализированные разрешения. Вместо этого ваше приложение либо получит все запрошенные области действия, либо не получит ни одной.
Более подробную информацию см. в разделе Как обрабатывать детализированные разрешения .
Чтобы проверить, предоставил ли пользователь вашему приложению доступ к определённой области действия, проверьте поле scope в ответе токена доступа. Области действия, предоставляемые токеном доступа, представлены в виде списка строк, разделённых пробелами и чувствительных к регистру.
Например, следующий пример ответа токена доступа указывает, что пользователь предоставил вашему приложению доступ только для чтения к действиям Диска и событиям Календаря:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/yt-analytics.readonly https://www.googleapis.com/auth/calendar.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 Reporting поддерживает сервисные аккаунты только для владельцев контента 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 https://www.googleapis.com/auth/calendar.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
Используйте рекомендуемую альтернативу , которая доставляет ответ OAuth 2.0 непосредственно в ваше приложение, устраняя необходимость в URI перенаправления.
Как перейти на библиотеку Android служб идентификации Google
Если вы используете пользовательскую схему для интеграции OAuth на Android, вам потребуется выполнить следующие действия, чтобы полностью перейти на использование рекомендуемой библиотеки Android для служб идентификации Google:
- Обновите свой код, чтобы использовать библиотеку Android для служб идентификации Google.
- Отключить поддержку пользовательской схемы в Google Cloud Console.
Ниже подробно описан процесс перехода на библиотеку Google Identity Services для Android.
- Обновите свой код, чтобы использовать библиотеку Android для служб идентификации Google:
- Проверьте свой код, чтобы определить, отправляете ли вы запрос на сервер OAuth 2.0 Google ; если вы используете пользовательскую схему, ваш запрос будет выглядеть следующим образом:
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, которые вам понадобятся для настройки Google Sign-In SDK. - Следуйте инструкциям по авторизации доступа к данным пользователей Google , чтобы настроить SDK. Шаг «Настройка проекта Google Cloud Console» можно пропустить, так как вы повторно используете
client_id, полученный на предыдущем шаге. - Следуйте инструкциям по запросу разрешений, необходимых для действий пользователя . Это включает в себя следующие шаги:
- Запросить разрешения у пользователя.
- Используйте метод
getServerAuthCodeдля получения кода авторизации для областей, для которых вы запрашиваете разрешение. - Отправьте код авторизации на серверную часть вашего приложения, чтобы обменять его на токен доступа и обновления.
- Используйте полученный токен доступа для совершения вызовов API Google от имени пользователя.
- Проверьте свой код, чтобы определить, отправляете ли вы запрос на сервер OAuth 2.0 Google ; если вы используете пользовательскую схему, ваш запрос будет выглядеть следующим образом:
- Отключить поддержку пользовательской схемы в консоли API Google:
- Перейдите в список учетных данных OAuth 2.0 и выберите свой клиент Android.
- Перейдите в раздел «Дополнительные параметры» , снимите флажок «Включить пользовательскую схему URI» и нажмите « Сохранить» , чтобы отключить поддержку пользовательской схемы URI.
Включить пользовательскую схему URI
Если рекомендуемая альтернатива вам не подходит, вы можете включить пользовательские схемы URI для своего клиента Android, выполнив следующие инструкции:- Перейдите в список учетных данных OAuth 2.0 и выберите свой клиент Android.
- Перейдите в раздел «Дополнительные параметры» , установите флажок «Включить пользовательскую схему URI» и нажмите « Сохранить» , чтобы включить поддержку пользовательской схемы URI.
Альтернатива использованию пользовательских схем URI в приложениях Chrome
Используйте API Chrome Identity , который доставляет ответ OAuth 2.0 непосредственно в ваше приложение, устраняя необходимость в URI перенаправления.
IP-адрес обратной связи (macOS, Linux, Windows Desktop)
Чтобы получить код авторизации с помощью этого URL -адреса, ваше приложение должно слушать на локальном веб -сервере. Это возможно на многих, но не на всех платформах. Однако, если ваша платформа поддерживает ее, это рекомендуемый механизм для получения кода авторизации.
Когда ваше приложение получает ответ авторизации, для лучшего удобства использования оно должно ответить, отображая HTML -страницу, которая дает инструктаж пользователю закрыть браузер и вернуться в ваше приложение.
| Рекомендуемое использование | Приложения MacOS, Linux и Windows Desktop (но не универсальная платформа Windows) |
| Значения формы | Установите тип приложения на настольное приложение . |
Ручная копия/вставка (устарела)
Защитите свои приложения
Проверьте владение приложениями (Android, Chrome)
Вы можете проверить право собственности на свою заявку на снижение риска подражания приложения.
Android
Чтобы завершить процесс проверки, вы можете использовать свою учетную запись разработчика Google Play, если у вас есть ее, и ваше приложение зарегистрировано в консоли Google Play . Следующие требования должны быть выполнены для успешной проверки:
- У вас должно быть зарегистрированное приложение в консоли Google Play с тем же именем пакета и отпечатка Fingfint Sha-1, что и клиент Android OAuth, которого вы выполняете проверку.
- У вас должно быть разрешение администратора для приложения в консоли Google Play. Узнайте больше о управлении доступом в консоли Google Play.
В разделе «Проверка владения приложениями» клиента Android нажмите кнопку «Проверьте право собственности» , чтобы завершить процесс проверки.
Если проверка будет успешной, будет отображаться уведомление для подтверждения успеха процесса проверки. В противном случае будет показана подсказка ошибки.
Чтобы исправить неудачную проверку, попробуйте следующее:
- Убедитесь, что приложение, которое вы проверяете, является зарегистрированным приложением в консоли Google Play.
- Убедитесь, что у вас есть разрешение администратора для приложения в консоли Google Play.
Хром
Чтобы завершить процесс проверки, вы используете свою учетную запись разработчика Chrome Web Store. Следующие требования должны быть выполнены для успешной проверки:
- У вас должен быть зарегистрированный элемент в панели разработчиков Chrome Web Store Dashinger с тем же идентификатором элемента, что и клиент hrome Extension OAuth, которого вы выполняете проверку.
- Вы должны быть издателем элемента Chrome Web Store. Узнайте больше о управлении доступом в Dashboard Developer Chrome Web Store.
В разделе «Проверка владения приложениями клиента chrome Extension» нажмите кнопку «Проверить владение» , чтобы завершить процесс проверки.
Примечание. Подождите несколько минут, прежде чем завершить процесс проверки после предоставления доступа к вашей учетной записи.
Если проверка будет успешной, будет отображаться уведомление для подтверждения успеха процесса проверки. В противном случае будет показана подсказка ошибки.
Чтобы исправить неудачную проверку, попробуйте следующее:
- Убедитесь, что в приборной панели разработчика веб -магазина Chrome Web Store с тем же идентификатором элемента, что и клиент oauth oauth Chrome, вы завершаете проверку.
- Убедитесь, что вы являетесь издателем приложения, то есть вы должны быть индивидуальным издателем приложения или участником издателя группы приложения. Узнайте больше о управлении доступом в Dashboard Developer Chrome Web Store.
- Если вы только что обновили список издателей группы, убедитесь, что список членов группы Publisher синхронизируется на приборной панели разработчика Chrome Web Store. Узнайте больше о синхронизации вашего списка членства издателя.
Проверка приложения (только для iOS)
Функция проверки приложений помогает защитить ваши приложения для iOS от несанкционированного использования, используя приложение Apple Attest для проверки того, что запросы, сделанные в Google OAuth 2.0 конечных точках, происходящие из ваших подлинных приложений. Это помогает снизить риск подражания приложения.
Включите проверку приложения для вашего клиента iOS
Следующие требования должны быть выполнены для успешного включения проверки приложений для вашего клиента iOS:- Вы должны указать идентификатор команды для вашего клиента iOS.
- Вы не должны использовать подстановочный знак в своем идентификаторе пакета, поскольку он может разрешить более чем одно приложение. Это означает, что идентификатор пакета не должен включать символ звездочки (*).
После включения проверки приложений вы начнете видеть метрики, связанные с запросами OAuth, от вашего клиента, при редактировании клиента OAuth. Запросы из неверных источников не будут заблокированы до тех пор, пока вы не обеспечите проверку приложений . Информация на странице мониторинга метрик может помочь вам определить, когда начинать правоприменение.
Вы можете увидеть ошибки, связанные с функцией проверки приложений при включении проверки приложений для вашего приложения для iOS. Чтобы исправить эти ошибки, попробуйте следующее:
- Убедитесь, что указанный вами идентификатор пакета и идентификатор команды действительны.
- Убедитесь, что вы не используете подстановку для идентификатора пакета.
Приложение для приложения для вашего клиента iOS
Включение проверки приложений для вашего приложения не автоматически блокирует непризнанные запросы. Чтобы обеспечить соблюдение этой защиты, перейдите к редактированию вашего клиента iOS. Там вы увидите метрики проверки приложений справа от страницы в разделе Google Identity for iOS . Метрики включают следующую информацию:- Количество проверенных запросов - запросы, которые имеют действительный токен проверки приложений. После того, как вы включите приложение проверить правоприменение, только запросы в этой категории будут успешными.
- Количество незавершенных запросов: вероятные устаревшие запросы клиентов - запросы пропустили токен проверки приложения; Этот запрос может быть из более старой версии вашего приложения, которая не включает реализацию проверки приложений.
- Количество незавершенных запросов: Неизвестные запросы на происхождение - Запросы отсутствуют токен проверки приложений, который не выглядит так, как будто они приходят из вашего приложения.
- Количество незавершенных запросов: неверные запросы - запросы с неверным токеном проверки приложений, который может быть от недостоверного клиента, пытающегося выдать себя за ваше приложение или из эмулированных сред.
Чтобы обеспечить проверку приложений, нажмите кнопку «Объяснение» и подтвердите свой выбор. Как только принудительное исполнение будет активно, все незавершенные запросы от вашего клиента будут отклонены.
Примечание . После того, как вы включите правоприменение, для вступления в силу изменений может занять до 15 минут.
Приложения Uncforce Проверка приложения для вашего клиента для iOS
Uncencring App Проверка приложения для вашего приложения прекратит правоприменение и позволит всем запросам от вашего клиента в Google OAuth 2.0 конечные точки, включая незавершенные запросы.
Чтобы Uncerforce App проверьте для вашего клиента iOS, перейдите к просмотру редактирования клиента iOS и нажмите кнопку Unenforce и подтвердите свой выбор.
ПРИМЕЧАНИЕ . После нельзя применить проверку приложений, для вступления в силу изменений может занять до 15 минут.
Отключить проверку приложения для вашего клиента iOS
Отключение проверки приложений для вашего приложения остановит мониторинг и правоприменение всех приложений. Вместо этого рассмотрим проверку приложения без прирождения , чтобы вы могли продолжить мониторинг метрик для своего клиента.
Чтобы отключить проверку приложений для вашего клиента iOS, перейдите к редактированию вида клиента iOS и отключите клиент Protect Your OAuth от злоупотребления с помощью кнопки «Проверка приложения Firebase» .
ПРИМЕЧАНИЕ . После отключения проверки приложений, для вступления в силу может потребоваться до 15 минут.
Основанный на времени доступ
Доступ на основе времени позволяет пользователю предоставить вашему приложению доступ к своим данным для ограниченной продолжительности для завершения действия. Доступ на основе времени доступен в избранных продуктах Google во время потока согласия, предоставляя пользователям возможность предоставить доступ в течение ограниченного периода времени. Примером является API портативности данных , который обеспечивает одноразовую передачу данных.
Когда пользователь предоставляет доступ к вашему приложению, токен обновления истекает после указанной продолжительности. Обратите внимание, что токены обновления могут быть недействительными ранее при конкретных обстоятельствах; Смотрите эти случаи для деталей. Поле refresh_token_expires_in , возвращаемое в ответе обмена кода авторизации, представляет время, оставшееся до тех пор, пока в таких случаях не истечет срок действия токена обновления.
Дальнейшее чтение
Лучшая текущая практика IETF OAuth 2.0 для местных приложений устанавливает многие из лучших практик, задокументированных здесь.
Реализация защиты от поперечного доступа
Дополнительным шагом, который вы должны предпринять для защиты учетных записей ваших пользователей, является реализация защиты от аккунт, используя службу защиты Google Cross-account. Эта услуга позволяет подписаться на уведомления о событиях безопасности, которые предоставляют информацию в вашем приложении о серьезных изменениях в учетной записи пользователя. Затем вы можете использовать информацию для принятия мер в зависимости от того, как вы решите ответить на события.
Некоторые примеры типов событий, отправленных в ваше приложение, с помощью службы защиты 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
См. Защита пользовательских учетных записей на странице защиты Cross-Account для получения дополнительной информации о том, как реализовать защиту учетных записей и полный список доступных событий.