Эта страница переведена с помощью Cloud Translation API.

OAuth 2.0 для мобильных и настольных приложений

В этом документе объясняется, как приложения, установленные на таких устройствах, как телефоны, планшеты и компьютеры, используют конечные точки 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.
1. Откройте приложение Apple App Store на своем устройстве iOS или iPadOS.
2. Найдите свое приложение.
3. Нажмите кнопку «Поделиться» (квадрат и стрелка вверх).
4. Выберите «Копировать ссылку» .
5. Вставьте ссылку в текстовый редактор. Идентификатор 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 версии 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 (без заполнения), верификатора кода. `code_challenge` = BASE64URL-ENCODE(SHA256(ASCII(`code_verifier`)))
простой	Запрос кода имеет то же значение, что и верификатор кода, созданный выше. `code_challenge` = `code_verifier`

Шаг 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, вы получите ошибку redirect_uri_mismatch .

В таблице ниже показано соответствующее значение параметра redirect_uri для каждого метода:

значения redirect_uri

Пользовательская схема URI

com.example.app : redirect_uri_path

или

com.googleusercontent.apps.123 : redirect_uri_path

com.example.app — это обратная запись DNS домена, находящегося под вашим контролем. Чтобы пользовательская схема была действительной, она должна содержать период.
com.googleusercontent.apps.123 — это обратная DNS-нотация идентификатора клиента.
redirect_uri_path — это необязательный компонент пути, например /oauth2redirect . Обратите внимание, что путь должен начинаться с одной косой черты, которая отличается от обычных URL-адресов HTTP.

IP-адрес обратной связи

http://127.0.0.1: port или http://[::1]: port

Запросите у вашей платформы соответствующий IP-адрес обратной связи и запустите HTTP-прослушиватель на случайном доступном порту. Замените port фактическим номером порта, который прослушивает ваше приложение.

Обратите внимание, что поддержка опции перенаправления IP-адреса обратной связи в мобильных приложениях УСТАРЕЛА .

response_type

Необходимый

Определяет, возвращает ли конечная точка Google OAuth 2.0 код авторизации.

Установите значение параметра для code установленных приложений.

scope

Необходимый

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

Области позволяют вашему приложению запрашивать доступ только к тем ресурсам, которые ему необходимы, а также позволяют пользователям контролировать объем доступа, который они предоставляют вашему приложению. Таким образом, существует обратная зависимость между количеством запрашиваемых областей и вероятностью получения согласия пользователя.

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.

code_challenge

Рекомендуется

Указывает закодированный code_verifier , который будет использоваться в качестве запроса на стороне сервера во время обмена кодами авторизации. Дополнительную информацию см. в разделе «Создание кода» выше.

code_challenge_method

Рекомендуется

Указывает, какой метод использовался для кодирования code_verifier , который будет использоваться при обмене кодами авторизации. Этот параметр необходимо использовать с параметром code_challenge описанным выше. Значение code_challenge_method по умолчанию равно plain , если оно не присутствует в запросе, включающем code_challenge . Единственные поддерживаемые значения для этого параметра — S256 или plain .

state

Рекомендуется

Указывает любое строковое значение, которое ваше приложение использует для поддержания состояния между вашим запросом авторизации и ответом сервера авторизации. Сервер возвращает точное значение, которое вы отправляете в виде пары name=value в идентификаторе фрагмента URL-адреса ( # ) redirect_uri после того, как пользователь соглашается или отклоняет запрос доступа вашего приложения.

Вы можете использовать этот параметр для нескольких целей, например для направления пользователя на правильный ресурс в вашем приложении, отправки одноразовых номеров и предотвращения подделки межсайтовых запросов. Поскольку ваш redirect_uri можно угадать, использование значения state может повысить вашу уверенность в том, что входящее соединение является результатом запроса аутентификации. Если вы генерируете случайную строку или кодируете хэш файла cookie или другое значение, фиксирующее состояние клиента, вы можете проверить ответ, чтобы дополнительно убедиться, что запрос и ответ исходят из одного и того же браузера, обеспечивая защиту от таких атак, как межсайтовые атаки. запросить подделку . См. документацию OpenID Connect , где приведен пример создания и подтверждения токена state .

Важно: клиент OAuth должен предотвращать CSRF, как указано в спецификации OAuth2 . Один из способов добиться этого — использовать параметр state для поддержания состояния между вашим запросом авторизации и ответом сервера авторизации.

login_hint

Необязательный

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

Установите в качестве значения параметра адрес электронной почты или sub идентификатор, который эквивалентен идентификатору Google ID пользователя.

Примечание. Инкрементная авторизация с установленными приложениями не поддерживается, поскольку клиент не может сохранить конфиденциальность client_secret .

Примеры 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.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%2Fyoutube.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` .

Важно: ваше приложение должно хранить оба токена в безопасном, долгоживущем месте, доступном между различными вызовами вашего приложения. Токен обновления позволяет вашему приложению получить новый токен доступа, если срок действия имеющегося у вас истек. Таким образом, если ваше приложение потеряет токен обновления, пользователю потребуется повторить поток согласия OAuth 2.0, чтобы ваше приложение могло получить новый токен обновления.

В следующем фрагменте показан пример ответа:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Шаг 6. Проверьте, какие области действия предоставлены пользователями

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

Чтобы проверить, предоставил ли пользователь вашему приложению доступ к определенной области, проверьте поле scope в ответе токена доступа. Области доступа, предоставляемые access_token, выражаются в виде списка строк, разделенных пробелами и чувствительных к регистру.

Например, следующий пример ответа токена доступа показывает, что пользователь предоставил вашему приложению разрешение на просмотр, редактирование и безвозвратное удаление видео, оценок, комментариев и подписей на YouTube:

  {
    "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 ).

Обратите внимание, что API данных YouTube поддерживает учетные записи служб только для владельцев контента YouTube, которые владеют и управляют несколькими каналами YouTube, например звукозаписывающих компаний и киностудий.

Вы можете опробовать все API Google и просмотреть их возможности на игровой площадке OAuth 2.0 .

Примеры HTTP GET

Вызов конечной точки youtube.channels (API данных YouTube) с использованием HTTP-заголовка Authorization: Bearer может выглядеть следующим образом. Обратите внимание, что вам необходимо указать свой собственный токен доступа:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Вот вызов того же API для аутентифицированного пользователя с использованием параметра строки запроса access_token :

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

примеры `curl`

Вы можете протестировать эти команды с помощью приложения командной строки curl . Вот пример, в котором используется опция HTTP-заголовка (предпочтительно):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

Или, альтернативно, опция параметра строки запроса:

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&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 возвращается вместе с кодом ошибки.

Методы перенаправления приложений

Пользовательская схема URI (Android, iOS, UWP)

Пользовательские схемы URI — это форма глубоких ссылок, в которой для открытия вашего приложения используется настраиваемая схема.

Альтернатива использованию пользовательских схем URI на Android

Используйте Google Sign-In для Android SDK , который доставляет ответ OAuth 2.0 непосредственно в ваше приложение, устраняя необходимость в URI перенаправления.

Если вы используете собственную схему для интеграции OAuth на Android, вам необходимо выполнить следующие действия, чтобы полностью перейти на использование рекомендованного Google Sign-In для Android SDK:

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

Выполните следующие действия, чтобы перейти на Android SDK для входа в Google:

Обновите свой код, чтобы использовать Android SDK для входа в Google:
1. Проверьте свой код, чтобы определить, куда вы отправляете запрос на сервер 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 .
2. Запишите параметры scope и client_id , которые вам понадобятся для настройки SDK для входа в Google.
  Примечание. Если вы используете стороннюю библиотеку, просмотрите файл конфигурации библиотеки, чтобы найти эту информацию.
3. Следуйте инструкциям по началу интеграции входа в Google в ваше приложение Android, чтобы настроить SDK. Вы можете пропустить шаг «Получить идентификатор клиента OAuth 2.0 вашего внутреннего сервера», так как вам придется повторно использовать client_id , полученный на предыдущем шаге.
4. Следуйте инструкциям по включению доступа к серверному API . Это включает в себя следующие шаги:
  1. Используйте метод getServerAuthCode , чтобы получить код аутентификации для областей, для которых вы запрашиваете разрешение.
  2. Отправьте код авторизации на серверную часть вашего приложения, чтобы обменять его на токен доступа и обновления.
  3. Используйте полученный токен доступа для выполнения вызовов API Google от имени пользователя.
  Примечание. Если вашему приложению не требуется автономный доступ, вместо этого следуйте этим инструкциям , чтобы запросить доступ к API на стороне клиента.
Отключите поддержку пользовательской схемы в консоли Google API:
1. Перейдите в список учетных данных OAuth 2.0 и выберите свой клиент Android.
2. Перейдите в раздел «Дополнительные настройки» , снимите флажок « Включить настраиваемую схему 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)
Формировать значения	Установите тип приложения «Приложение для ПК» .

Примечание. Дополнительные сведения об IP-адресе обратной связи см. в определении параметра redirect_uri Также можно использовать localhost вместо IP-адреса обратной связи, но эта конфигурация может вызвать проблемы с клиентскими брандмауэрами. Большинство, но не все, межсетевых экранов допускают обратную связь.

Копирование/вставка вручную (устарело)

Защитите свои приложения

Подтвердить право собственности на приложение (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 без создания нового клиента. Прежде чем создавать клиент iOS или включать проверку приложений, убедитесь, что вы используете правильный идентификатор пакета. Обновление идентификатора пакета для существующего проекта может привести к ухудшению работы пользователей ваших приложений, если вы используете идентификатор пакета в качестве URI перенаправления.

Чтобы включить проверку приложений, включите переключатель «Защитить свой OAuth-клиент от злоупотреблений с помощью проверки приложений Firebase» в представлении редактирования вашего 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

См . страницу Защита учетных записей пользователей с помощью защиты нескольких учетных записей, чтобы получить дополнительную информацию о том, как реализовать защиту нескольких учетных записей, а также полный список доступных событий.

OAuth 2.0 для мобильных и настольных приложений

Библиотеки и образцы

Предварительные условия

Включите API для вашего проекта

Создать учетные данные для авторизации

Андроид

iOS

UWP

Определить области доступа

Получение токенов доступа OAuth 2.0

Шаг 1. Создайте средство проверки кода и проверите его.

Создайте верификатор кода

Создать задачу по коду

Шаг 2. Отправьте запрос на сервер Google OAuth 2.0.

Примеры URL-адресов авторизации

Пользовательская схема URI

IP-адрес обратной связи

Шаг 3. Google запрашивает у пользователя согласие

Ошибки

admin_policy_enforced

disallowed_useragent

Андроид

iOS

org_internal

invalid_grant

redirect_uri_mismatch

invalid_request

Шаг 4. Обработка ответа сервера OAuth 2.0

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

Шаг 6. Проверьте, какие области действия предоставлены пользователями

Вызов API Google

Примеры HTTP GET

примеры curl

Обновление токена доступа

Отзыв токена

Методы перенаправления приложений

Пользовательская схема URI (Android, iOS, UWP)

Альтернатива использованию пользовательских схем URI на Android

Как перейти на Google Sign-In для Android SDK

Включить пользовательскую схему URI

Альтернатива использованию пользовательских схем URI в приложениях Chrome.

IP-адрес обратной связи (macOS, Linux, рабочий стол Windows)

Копирование/вставка вручную (устарело)

Защитите свои приложения

Подтвердить право собственности на приложение (Android, Chrome)

Андроид

Хром

Проверка приложений (только iOS)

Включите проверку приложений для вашего iOS-клиента

Принудительная проверка приложений для вашего iOS-клиента

Отмените обязательную проверку приложений для вашего iOS-клиента

Отключите проверку приложений для вашего iOS-клиента

Дальнейшее чтение

Реализация защиты между аккаунтами

`admin_policy_enforced`

`disallowed_useragent`

`org_internal`

`invalid_grant`

`redirect_uri_mismatch`

`invalid_request`

примеры `curl`