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

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

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

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

Этот поток авторизации аналогичен тому, который используется для приложений веб-сервера . Основное отличие состоит в том, что установленные приложения должны открыть системный браузер и предоставить локальный URI перенаправления для обработки ответов от сервера авторизации Google.

Альтернативы

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

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

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

Мы рекомендуем следующие библиотеки и примеры, которые помогут вам реализовать поток OAuth 2.0, описанный в этом документе:

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

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

Любое приложение, которое вызывает API Google, должно включить эти API в .

Чтобы включить API для вашего проекта:

  1. в .
  3. перечисляет все доступные API, сгруппированные по семействам продуктов и популярности. Если API, который вы хотите включить, не отображается в списке, воспользуйтесь поиском, чтобы найти его, или нажмите «Просмотреть все» в семействе продуктов, к которому он принадлежит.
  4. Выберите API, который вы хотите включить, затем нажмите кнопку «Включить» .

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

Любое приложение, использующее OAuth 2.0 для доступа к API Google, должно иметь учетные данные авторизации, которые идентифицируют приложение на сервере Google OAuth 2.0. Следующие шаги объясняют, как создать учетные данные для вашего проекта. Затем ваши приложения смогут использовать учетные данные для доступа к API, которые вы включили для этого проекта.

  2. Нажмите Создать учетные данные > Идентификатор клиента OAuth .
  3. В следующих разделах описаны типы клиентов, которые поддерживает сервер авторизации Google. Выберите тип клиента, рекомендуемый для вашего приложения, назовите свой клиент OAuth и задайте соответствующие поля в форме.
Андроид
  1. Выберите тип приложения Android .
  2. Введите имя клиента OAuth. Это имя отображается в вашем проекте для идентификации клиента.
  3. Введите имя пакета вашего приложения для Android. Это значение определяется в атрибуте package элемента <manifest> в файле манифеста вашего приложения.
  4. Введите отпечаток сертификата подписи SHA-1 для распространения приложения.
    • Если ваше приложение использует подпись приложения Google Play , скопируйте отпечаток SHA-1 со страницы подписи приложения в Play Console.
    • Если вы управляете собственным хранилищем ключей и ключами подписи, используйте утилиту keytool, входящую в состав Java, для печати информации о сертификате в удобочитаемом формате. Скопируйте значение SHA1 в раздел Certificate fingerprints выходных данных keytool . Дополнительную информацию см. в разделе «Аутентификация вашего клиента» в документации Google API для Android.
  5. (Необязательно) Подтвердите право собственности на ваше приложение для Android.
  6. Нажмите Создать .
iOS
  1. Выберите тип приложения iOS .
  2. Введите имя клиента OAuth. Это имя отображается в вашем проекте для идентификации клиента.
  3. Введите идентификатор пакета для вашего приложения. Идентификатор пакета — это значение ключа CFBundleIdentifier в файле ресурсов списка информационных свойств вашего приложения ( info.plist ). Значение чаще всего отображается на панели «Общие» или на панели «Подписание и возможности» редактора проекта Xcode. Идентификатор пакета также отображается в разделе «Общая информация» на странице «Информация о приложении» на сайте Apple App Store Connect .

    Убедитесь, что вы используете правильный идентификатор пакета для своего приложения, поскольку вы не сможете изменить его, если используете функцию проверки приложений.

  4. (Необязательный)

    Введите идентификатор вашего приложения в 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

  5. (Необязательный)

    Введите идентификатор своей команды. Дополнительную информацию см. в разделе «Найдите свой идентификатор команды» в документации по учетной записи разработчика Apple.

    Примечание. Поле «Идентификатор команды» является обязательным, если вы включаете проверку приложений для своего клиента.
  6. (Необязательный)

    Включите проверку приложений для вашего приложения iOS. Когда вы включаете проверку приложений, служба Apple App Attest используется для проверки того, что запросы OAuth 2.0, исходящие от вашего клиента OAuth, являются подлинными и поступают из вашего приложения. Это помогает снизить риск подделки приложения. Узнайте больше о включении проверки приложений для вашего приложения iOS .

  7. Нажмите Создать .
UWP
  1. Выберите тип приложения универсальной платформы Windows .
  2. Введите имя клиента OAuth. Это имя отображается в вашем проекте для идентификации клиента.
  3. Введите 12-значный идентификатор вашего приложения в Microsoft Store. Это значение можно найти в Центре партнеров Microsoft на странице удостоверения приложения в разделе «Управление приложениями».
  4. Нажмите Создать .

Для приложений UWP длина пользовательской схемы URI не может превышать 39 символов.

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

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

Прежде чем приступить к реализации авторизации OAuth 2.0, мы рекомендуем вам определить области, для доступа к которым вашему приложению потребуется разрешение.

Документ «Области 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 Необходимый

Идентификатор клиента для вашего приложения. Вы можете найти это значение в .

redirect_uri Необходимый

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

Значение должно точно совпадать с одним из авторизованных URI перенаправления для клиента OAuth 2.0, который вы настроили в настройках вашего клиента. . Если это значение не соответствует авторизованному 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 отображает пользователю.

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

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 .

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

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

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

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

На вкладках ниже показаны примеры URL-адресов авторизации для различных вариантов URI перенаправления.

URL-адреса идентичны, за исключением значения параметра redirect_uri . URL-адреса также содержат обязательные параметры response_type и client_id , а также необязательный параметр state . Каждый URL-адрес содержит разрывы строк и пробелы для удобства чтения.

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

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 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=email%20profile&
 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 перенаправления в .

Переданный 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 Идентификатор клиента, полученный из .
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 Токен, который ваше приложение отправляет для авторизации запроса Google API.
expires_in Оставшийся срок действия токена доступа в секундах.
id_token Примечание. Это свойство возвращается только в том случае, если ваш запрос включал область идентификации, например openid , profile или email . Значением является веб-токен JSON (JWT), который содержит идентификационную информацию пользователя с цифровой подписью.
refresh_token Токен, который можно использовать для получения нового токена доступа. Токены обновления действительны до тех пор, пока пользователь не отзовет доступ. Обратите внимание, что токены обновления всегда возвращаются для установленных приложений.
scope Области доступа, предоставляемые access_token выражаются в виде списка строк, разделенных пробелами и чувствительных к регистру.
token_type Тип возвращенного токена. В настоящее время значение этого поля всегда установлено на Bearer .

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

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

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

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

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

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

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.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-заголовок, поскольку строки запроса обычно видны в журналах сервера. В большинстве случаев вы можете использовать клиентскую библиотеку для настройки вызовов Google API (например, при вызове Drive Files API ).

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

Примеры HTTP GET

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

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

примеры curl

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

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

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

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

Срок действия токенов доступа периодически истекает, и они становятся недействительными учетными данными для связанного запроса API. Вы можете обновить токен доступа, не запрашивая у пользователя разрешения (в том числе, когда пользователь отсутствует), если вы запросили автономный доступ к областям, связанным с токеном.

Чтобы обновить токен доступа, ваше приложение отправляет запрос HTTPS POST на сервер авторизации Google ( https://oauth2.googleapis.com/token ), который включает следующие параметры:

Поля
client_id Идентификатор клиента, полученный из .
client_secret Секрет клиента, полученный от . (Свойство 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

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

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

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

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

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

  1. Обновите свой код, чтобы использовать 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 от имени пользователя.
  2. Отключите поддержку пользовательской схемы в консоли Google API:
    1. Перейдите в список учетных данных OAuth 2.0 и выберите свой клиент Android.
    2. Перейдите в раздел «Дополнительные настройки» , снимите флажок « Включить настраиваемую схему URI» и нажмите «Сохранить» , чтобы отключить поддержку настраиваемой схемы URI.

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

Если рекомендуемый вариант вам не подходит, вы можете включить собственные схемы URI для вашего клиента Android, следуя инструкциям ниже:
  1. Перейдите в список учетных данных OAuth 2.0 и выберите свой клиент Android.
  2. Перейдите в раздел «Дополнительные настройки» , установите флажок « Включить настраиваемую схему URI» и нажмите «Сохранить» , чтобы включить поддержку настраиваемой схемы URI.

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

Используйте Chrome Identity API , который доставляет ответ OAuth 2.0 непосредственно в ваше приложение, устраняя необходимость в URI перенаправления.

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

Чтобы получить код авторизации с использованием этого URL-адреса, ваше приложение должно прослушивать локальный веб-сервер. Это возможно на многих, но не на всех платформах. Однако, если ваша платформа поддерживает это, это рекомендуемый механизм получения кода авторизации.

Когда ваше приложение получает ответ на авторизацию, для лучшего удобства использования оно должно отреагировать, отобразив HTML-страницу, которая инструктирует пользователя закрыть браузер и вернуться в ваше приложение.

Рекомендуемое использование Приложения для настольных компьютеров macOS, Linux и Windows (но не для универсальной платформы Windows)
Формировать значения Установите тип приложения «Приложение для ПК» .

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

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

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

Вы можете подтвердить право собственности на свое приложение, чтобы снизить риск выдачи себя за другое лицо.

Андроид

Чтобы завершить процесс проверки, вы можете использовать свою учетную запись разработчика Google Play, если она у вас есть и ваше приложение зарегистрировано в консоли Google Play . Для успешной проверки должны быть выполнены следующие требования:

  • У вас должно быть зарегистрированное приложение в консоли Google Play с тем же именем пакета и отпечатком сертификата подписи SHA-1, что и у клиента Android OAuth, для которого вы выполняете проверку.
  • У вас должны быть права администратора для приложения в консоли Google Play. Узнайте больше об управлении доступом в консоли Google Play.

В разделе «Подтвердить право собственности на приложение» клиента Android нажмите кнопку «Подтвердить право собственности», чтобы завершить процесс проверки.

Если проверка прошла успешно, отобразится уведомление, подтверждающее успех процесса проверки. В противном случае будет показано сообщение об ошибке.

Чтобы исправить неудачную проверку, попробуйте следующее:

  • Убедитесь, что приложение, которое вы проверяете, зарегистрировано в консоли Google Play.
  • Убедитесь, что у вас есть права администратора для приложения в консоли Google Play.
Хром

Для завершения процесса проверки вам потребуется использовать свою учетную запись разработчика Интернет-магазина Chrome. Для успешной проверки должны быть выполнены следующие требования:

В разделе «Проверка владения приложением» клиента расширений Chrome нажмите кнопку «Подтвердить право собственности», чтобы завершить процесс проверки.

Примечание. Подождите несколько минут, прежде чем завершить процесс проверки после предоставления доступа к вашей учетной записи.

Если проверка прошла успешно, отобразится уведомление, подтверждающее успех процесса проверки. В противном случае будет показано сообщение об ошибке.

Чтобы исправить неудачную проверку, попробуйте следующее:

  • Убедитесь, что на панели разработчика Интернет-магазина Chrome есть зарегистрированный элемент с тем же идентификатором, что и у клиента OAuth расширения Chrome, для которого вы завершаете проверку.
  • Убедитесь, что вы являетесь издателем приложения, то есть вы должны быть либо индивидуальным издателем приложения, либо членом группы издателей приложения. Узнайте больше об управлении доступом на панели разработчика Интернет-магазина Chrome.
  • Если вы только что обновили список издателей группы, убедитесь, что список участников группы синхронизирован с панелью разработчика Интернет-магазина Chrome. Узнайте больше о синхронизации списка участников издателя.

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

Функция проверки приложений помогает защитить ваши приложения iOS от несанкционированного использования, используя службу Apple App Attest, чтобы убедиться, что запросы, сделанные к конечным точкам Google OAuth 2.0, исходят от ваших подлинных приложений. Это помогает снизить риск подделки приложения.

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

Для успешного включения проверки приложений для вашего клиента iOS должны быть выполнены следующие требования:
  • Вы должны указать идентификатор команды для вашего iOS-клиента.
  • Вы не должны использовать подстановочный знак в идентификаторе пакета, поскольку он может относиться к более чем одному приложению. Это означает, что идентификатор пакета не должен содержать символ звездочки (*).
Чтобы включить проверку приложений, включите переключатель «Защитить свой 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

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