В этом документе рассказывается, как приложения, установленные на таких устройствах, как телефоны, планшеты и компьютеры, используют конечные точки OAuth 2.0 от Google для авторизации доступа к API Google.
OAuth 2.0 позволяет пользователям делиться определенными данными с приложением, сохраняя при этом свои имена пользователей, пароли и другую конфиденциальную информацию. Например, приложение может использовать OAuth 2.0, чтобы получить разрешение от пользователей на хранение файлов на их Google Диске.
Установленные приложения распространяются на отдельные устройства, и предполагается, что эти приложения не могут хранить секреты. Они могут получать доступ к API Google, когда пользователь находится в приложении или когда оно работает в фоновом режиме.
Этот процесс авторизации похож на тот, который используется для приложений веб-сервера. Основное отличие заключается в том, что установленные приложения должны открывать системный браузер и предоставлять локальный URI перенаправления для обработки ответов от сервера авторизации Google.
Библиотеки и примеры кода
Для приложений iOS мы рекомендуем использовать последнюю версию Sign In With Google iOS SDK. SDK обрабатывает авторизацию пользователей и проще в реализации, чем описанный в этом руководстве низкоуровневый протокол.
Если ваше приложение работает на устройствах, которые не поддерживают системный браузер или имеют ограниченные возможности ввода, например на телевизорах, игровых консолях, камерах или принтерах, ознакомьтесь с информацией о OAuth 2.0 для телевизоров и устройств или входе в аккаунт на телевизорах и устройствах с ограниченными возможностями ввода.
Требования
Как включить API для проекта
Любое приложение, вызывающее API Google, должно включить эти API в API Console.
Чтобы включить API для вашего проекта:
- Откройте библиотеку API в Google API Console.
- Выберите существующий проект или создайте новый.
- В библиотеке API перечислены все доступные API, сгруппированные по семейству продуктов и популярности. Если нужного API нет в списке, найдите его с помощью поиска или нажмите Показать все в семействе продуктов, к которому он относится.
- Выберите нужный API и нажмите кнопку Включить.
- Если появится запрос, включите оплату.
- При необходимости прочтите и примите Условия использования API.
Создайте учетные данные для авторизации
Любое приложение, которое использует OAuth 2.0 для доступа к API Google, должно иметь учетные данные для авторизации, которые идентифицируют приложение на сервере OAuth 2.0 Google. Ниже описано, как создать учетные данные для проекта. Затем ваши приложения смогут использовать эти учетные данные для доступа к API, которые вы включили для этого проекта.
- Перейдите на страницу клиентов.
- Нажмите Создать клиент.
- В следующих разделах описаны типы клиентов, которые поддерживает сервер авторизации Google. Выберите тип клиента, рекомендованный для вашего приложения, укажите название клиента OAuth и заполните остальные поля формы.
iOS
- Выберите тип приложения iOS.
- Введите название клиента OAuth. Это название будет показываться на странице клиентов вашего проекта.
- Введите идентификатор пакета приложения. Это значение ключа CFBundleIdentifier в файле списка свойств приложения (info.plist). Обычно это значение отображается на панели General (Общие) или Signing & Capabilities (Подпись и возможности) в редакторе проектов Xcode. Идентификатор пакета также указан в разделе "Общая информация" на странице приложения на сайте Apple App Store Connect.
Убедитесь, что вы используете правильный идентификатор пакета для своего приложения, так как вы не сможете изменить его, если используете функцию проверки приложений.
- (Необязательно)
Если приложение опубликовано в Apple App Store, введите его идентификатор в этом магазине. Идентификатор магазина – это числовая строка, которая есть в каждом URL в Apple App Store.
- Откройте приложение Apple App Store на устройстве iOS или iPadOS.
- Выполните поиск по названию своего приложения.
- Нажмите кнопку "Поделиться" (квадрат со стрелкой вверх).
- Выберите Копировать ссылку.
- Вставьте ссылку в текстовый редактор. Идентификатор магазина приложений – это последняя часть URL.
Пример:
https://apps.apple.com/app/google/id284815942
- (Необязательно)
Введите идентификатор команды. Подробную информацию можно найти в статье Как найти идентификатор команды в документации по аккаунту разработчика Apple.
Примечание. Поле "Идентификатор команды" обязательно, если вы включаете App Check для клиента. - (Необязательно)
Включите проверку приложений для iOS. В этом случае сервис App Attest от Apple будет проверять, что запросы OAuth 2.0, поступающие от вашего клиента OAuth, подлинные и исходят из вашего приложения. Это помогает снизить риск имитации приложения. Подробнее о том, как включить App Check для приложения iOS…
- Нажмите Создать.
UWP
- Выберите тип приложения Universal Windows Platform.
- Введите название клиента OAuth. Это название будет показываться в проекте для идентификации клиента.
- Введите 12-значный идентификатор приложения в Microsoft Store. Это значение можно найти в Центре партнеров Microsoft на странице Идентификация приложения в разделе "Управление приложениями".
- Нажмите Создать.
Для приложений UWP URI перенаправления формируется с помощью уникального идентификатора безопасности пакета (SID) приложения. Package SID приложения можно найти в файле Package.appxmanifest в проекте Visual Studio.
При создании идентификатора клиента в консоли Google Cloud необходимо указать URI перенаправления в следующем формате, используя значение SID пакета в нижнем регистре:
ms-app://YOUR_APP_PACKAGE_SID
Для приложений UWP длина специальной схемы URI не может превышать 39 символов, как указано в документации Microsoft.
Как определить области доступа
Области действия позволяют приложению запрашивать доступ только к необходимым ресурсам, а пользователям – контролировать объем доступа, предоставляемого приложению. Таким образом, между количеством запрошенных областей и вероятностью получения согласия пользователя может существовать обратная зависимость.
Прежде чем приступать к реализации авторизации OAuth 2.0, рекомендуем определить области действия, к которым вашему приложению потребуется доступ.
Полный список областей действия, которые можно использовать для доступа к API Google, приведен в документе Области действия API OAuth 2.0.
Получение токенов доступа OAuth 2.0
Ниже описано, как ваше приложение взаимодействует с сервером OAuth 2.0 Google, чтобы получить согласие пользователя на выполнение запроса к API от его имени. Приложение должно получить такое согласие, прежде чем выполнять запрос к API Google, требующий авторизации пользователя.
Шаг 1. Сгенерируйте код подтверждения и запрос
Google поддерживает протокол Proof Key for Code Exchange (PKCE), который повышает безопасность установленных приложений. Для каждого запроса авторизации создается уникальный верификатор кода, а его преобразованное значение, называемое code_challenge, отправляется на сервер авторизации для получения кода авторизации.
Создайте верификатор кода
code_verifier – это криптографическая случайная строка с высокой энтропией, в которой используются незарезервированные символы [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~". Минимальная длина строки – 43 символа, максимальная – 128 символов.
У верификатора кода должно быть достаточно энтропии, чтобы угадать значение было невозможно.
Создайте код для подтверждения
Поддерживается два метода создания кода.
| Методы генерации кода вызова | |
|---|---|
| S256 (рекомендуется) | Code challenge – это хеш SHA256 code verifier, закодированный по алгоритму Base64URL без заполнителей.
|
| plain | Код запроса совпадает со значением кода подтверждения, сгенерированного выше.
|
Шаг 2. Отправьте запрос на сервер OAuth 2.0 Google
Чтобы получить разрешение пользователя, отправьте запрос на сервер авторизации Google по адресу https://accounts.google.com/o/oauth2/v2/auth. Этот конечный адрес используется для поиска активного сеанса, аутентификации пользователя и получения его согласия. Конечная точка доступна только по протоколу SSL и отклоняет подключения по протоколу HTTP (без SSL).
Сервер авторизации поддерживает следующие параметры строки запроса для установленных приложений:
| Параметры | |||||||
|---|---|---|---|---|---|---|---|
client_id |
Обязательно
Идентификатор клиента для вашего приложения. Это значение можно найти на странице клиентов в Cloud Console. |
||||||
redirect_uri |
Обязательно
Определяет, как сервер авторизации Google отправляет ответ вашему приложению. Для установленных приложений доступно несколько вариантов перенаправления. Вы можете настроить учетные данные авторизации с учетом определенного метода перенаправления. Значение должно точно совпадать с одним из авторизованных URI перенаправления для клиента OAuth 2.0, который вы настроили на странице клиентов в Cloud Console. Если это значение не совпадает с авторизованным URI, вы получите ошибку В таблице ниже приведены значения параметра
|
||||||
response_type |
Обязательно
Определяет, возвращает ли конечная точка Google OAuth 2.0 код авторизации. Для установленных приложений задайте значение параметра |
||||||
scope |
Обязательно
Список областей действия, разделенных пробелами, которые определяют ресурсы, к которым ваше приложение может получить доступ от имени пользователя. Эти значения используются в окне запроса доступа, которое Google показывает пользователю. Области действия позволяют приложению запрашивать доступ только к тем ресурсам, которые ему нужны, а пользователям – контролировать объем доступа, предоставляемого приложению. Таким образом, существует обратная зависимость между количеством запрашиваемых областей и вероятностью получения согласия пользователя. |
||||||
code_challenge |
Рекомендуется
Указывает закодированный |
||||||
code_challenge_method |
Рекомендуется
Указывает, какой метод использовался для кодирования |
||||||
state |
Рекомендуется
Любое строковое значение, которое ваше приложение использует для сохранения состояния между запросом авторизации и ответом сервера авторизации.
Сервер возвращает точное значение, которое вы отправили в виде пары Этот параметр можно использовать для разных целей, например чтобы направлять пользователя к нужному ресурсу в приложении, отправлять одноразовые коды и предотвращать подделку межсайтовых запросов. Поскольку ваш |
||||||
login_hint |
Необязательно
Если приложение знает, какой пользователь пытается выполнить аутентификацию, оно может использовать этот параметр, чтобы предоставить подсказку серверу аутентификации Google. Сервер использует подсказку, чтобы упростить процесс входа, заполнив поле адреса электронной почты в форме входа или выбрав соответствующий сеанс с несколькими входами. В качестве значения параметра укажите адрес электронной почты или идентификатор |
||||||
Примеры 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 показывает окно запроса согласия, в котором указано название вашего приложения и сервисы API Google, к которым оно запрашивает доступ с использованием учетных данных пользователя, а также сводка областей действия, которые будут предоставлены. Пользователь может предоставить доступ к одной или нескольким областям действия, запрошенным вашим приложением, или отклонить запрос.
На этом этапе вашему приложению не нужно ничего делать, пока оно ожидает ответа от сервера OAuth 2.0 Google, указывающего, был ли предоставлен доступ. Этот ответ описан на следующем шаге.
Ошибки
При запросах к конечной точке авторизации OAuth 2.0 от Google могут показываться пользовательские сообщения об ошибках вместо ожидаемых процессов аутентификации и авторизации. Распространенные коды ошибок и способы их устранения:
admin_policy_enforced
Аккаунт Google не может авторизовать одну или несколько запрошенных областей действия из-за правил, установленных администратором Google Workspace. В справочной статье Справочного центра Google Workspace для администраторов Как управлять доступом сторонних и внутренних приложений к данным Google Workspace приведена информация о том, как администратор может ограничить доступ ко всем областям действия или к областям действия с конфиденциальными и ограниченными данными, пока не будет явно предоставлен доступ к идентификатору клиента OAuth.
disallowed_useragent
Конечная точка авторизации отображается во встроенном агенте пользователя, запрещенном правилами OAuth 2.0 Google.
Разработчики iOS и macOS могут столкнуться с этой ошибкой при открытии запросов на авторизацию в WKWebView.
Вместо этого разработчикам следует использовать библиотеки iOS, например вход с аккаунтом Google для iOS или AppAuth для iOS от OpenID Foundation.
Веб-разработчики могут столкнуться с этой ошибкой, когда приложение для iOS или macOS открывает общую веб-ссылку во встроенном агенте пользователя, а пользователь переходит на конечную точку авторизации OAuth 2.0 Google с вашего сайта. Разработчикам следует разрешить открывать обычные ссылки в обработчике ссылок по умолчанию, который используется в операционной системе. К нему относятся обработчики универсальных ссылок и браузер по умолчанию. Также поддерживается библиотека SFSafariViewController.
org_internal
Идентификатор клиента OAuth в запросе относится к проекту, который ограничивает доступ к аккаунтам Google в определенной организации Google Cloud. Подробнее об этом параметре конфигурации см. в разделе Тип пользователя справочной статьи Настройка окна запроса доступа OAuth.
deleted_client
Клиент OAuth, используемый для выполнения запроса, был удален. Удаление может быть выполнено вручную или автоматически в случае неиспользуемых клиентов . Удаленных клиентов можно восстановить в течение 30 дней. Подробнее…
invalid_grant
Если вы используете подтверждение кода и запрос, параметр code_callenge недействителен или отсутствует. Убедитесь, что параметр code_challenge задан правильно.
При обновлении токена доступа срок его действия может истечь или он может быть аннулирован. Повторно аутентифицируйте пользователя и запросите у него согласие на получение новых токенов. Если вы продолжаете видеть эту ошибку, убедитесь, что ваше приложение настроено правильно и что вы используете правильные токены и параметры в своем запросе. В противном случае аккаунт пользователя может быть удален или отключен.
redirect_uri_mismatch
Значение redirect_uri, переданное в запросе на авторизацию, не соответствует авторизованному URI переадресации для идентификатора клиента OAuth. Проверьте авторизованные URI перенаправления на странице клиентов в консоли Google Cloud.
Переданное значение redirect_uri может быть недопустимым для типа клиента.
Параметр redirect_uri может относиться к внеполосному потоку OAuth, который устарел и больше не поддерживается. Чтобы обновить интеграцию, следуйте инструкциям в руководстве по переносу.
invalid_request
В вашем запросе что-то было не так. Это может быть связано со следующими причинами:
- Запрос был неправильно отформатирован.
- В запросе отсутствовали обязательные параметры
- В запросе используется способ авторизации, который не поддерживается Google. Проверьте, что при интеграции OAuth используется рекомендуемый метод
- Для URI переадресации использована неподдерживаемая специальная схема. Если вы видите сообщение об ошибке Пользовательская схема URI не поддерживается в приложениях для Android и Chrome, ознакомьтесь с альтернативными вариантами.
Шаг 4. Обработайте ответ сервера OAuth 2.0
Способ получения ответа на запрос авторизации зависит от схемы URI перенаправления, используемой в приложении. Независимо от схемы ответ будет содержать код авторизации (code) или ошибку (error). Например, error=access_denied означает, что пользователь отклонил запрос.
Если пользователь предоставит приложению доступ, вы сможете обменять код авторизации на токен доступа и токен обновления, как описано в следующем шаге.
Шаг 5. Обменяйте код авторизации на токены обновления и доступа
Чтобы обменять код авторизации на токен доступа, вызовите конечную точку https://oauth2.googleapis.com/token и задайте следующие параметры:
| Поля | |
|---|---|
client_id |
Идентификатор клиента, полученный на странице клиентов в Cloud Console. |
client_secret |
Необязательно
Секретный код клиента, полученный на странице клиентов в Cloud Console. |
code |
Код авторизации, возвращенный в ответ на первоначальный запрос. |
code_verifier |
Проверочный код, созданный на шаге 1. |
grant_type |
Согласно спецификации OAuth 2.0, значение этого поля должно быть равно authorization_code. |
redirect_uri |
Один из URI перенаправления, указанных для вашего проекта на странице клиентов в Cloud Console для заданного client_id. |
Использовать DPoP необязательно, но рекомендуется для повышения безопасности. Безопасность DPoP зависит от того, ограничен ли закрытый ключ одним устройством. Мы рекомендуем хранить его так, чтобы его нельзя было скопировать с устройства, например с помощью TPM, Secure Enclave или других аппаратных хранилищ ключей. Чтобы использовать DPoP, ваше приложение должно генерировать новый уникальный токен JWT для подтверждения DPoP для каждого запроса к конечной точке токена и добавлять его в качестве заголовка HTTP-запроса.
| Заголовок | Обязательно | Описание |
|---|---|---|
DPoP |
Необязательно | Доказательство DPoP – это токен JWT, который подтверждает владение закрытым ключом. Это заголовок, а не параметр. Если он указан, возвращаемые токены привязываются к этому ключу. Для каждого запроса необходимо создать новое уникальное доказательство, которое должно включать утверждения htm (метод HTTP) и htu (URI HTTP), соответствующие запросу. |
Ниже приведен пример запроса.
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik\ VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR\ nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE\ QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj\ oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia\ WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg\ 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your_client_id& redirect_uri=http://127.0.0.1:9004& grant_type=authorization_code
Как создать доказательство DPoP
Ниже описано, как создать доказательство DPoP с помощью OpenSSL из командной строки.
- Создайте пару ключей EC P-256:
openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem openssl ec -in dpop_private.pem -pubout -out dpop_public.pem
- Как создать заголовок DPoP
Заголовок должен содержать утверждения
typ,algиjwk(открытый ключ). Значенияxиy– это координаты вашего открытого ключа EC, закодированные в формате Base64Url. Закодируйте этот JSON с помощью Base64Url:{ "typ":"dpop+jwt", "alg":"ES256", "jwk": { "kty":"EC", "x":"YOUR_PUBLIC_KEY_X", "y":"YOUR_PUBLIC_KEY_Y", "crv":"P-256" } } - Создайте полезную нагрузку DPoP.
Полезная нагрузка должна включать
jti(уникальный идентификатор запроса),htm(метод HTTP, напримерPOST),htu(URI HTTP, напримерhttps://oauth2.googleapis.com/token) иiat(время выпуска). Если вы получили одноразовый код от сервера в заголовкеDPoP-Nonceв ответе на предыдущий запрос, вы должны включить это значение одноразового кода в утверждениеnonce. Заявление nonce является необязательным для обмена кода авторизации и используется только в том случае, если ранее был получен заголовок DPoP-Nonce. Закодируйте этот JSON-код с помощью Base64Url:{ "jti":"JTI_VALUE", "htm":"POST", "htu":"https://oauth2.googleapis.com/token", "iat":YOUR_JWT_ISSUED_TIME, "nonce":"SERVER_PROVIDED_NONCE" }Значение
jtiзависит от типа биржи:- Для обмена кодами авторизации значение
jtiдолжно быть хешем SHA256 кода авторизации, закодированным по стандарту Base64 для URL:"jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))". - Для обмена токенов обновления параметр
jtiдолжен быть уникальным идентификатором для каждого запроса:"jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
- Для обмена кодами авторизации значение
- Подпишите подтверждение:
Объедините закодированный заголовок и полезную нагрузку, разделив их точкой (
.), а затем подпишите результат закрытым ключом, используя ES256. Обратите внимание, что JWS требует, чтобы подпись была в необработанном объединенном форматеR | S(64 байта для P-256). Если вы используете OpenSSL напрямую, вам необходимо преобразовать подпись, закодированную по умолчанию в формате ASN.1 DER, в необработанный формат.
Успешный обмен подтверждается ответом 200 OK, содержащим токены. Если при обмене используется действительное доказательство DPoP, возвращаемый Google токен обновления будет связан с вашим ключом, но токены доступа не будут связаны с DPoP. Токены доступа сохранят token_type Bearer вместо DPoP.
Кроме того, Google возвращает в ответе HTTP-заголовок DPoP-Nonce.
Клиент должен кешировать этот nonce и включать его в утверждение nonce подтверждения DPoP в последующих запросах (например, при обмене токена обновления на новый токен доступа или при вызове API, защищенных DPoP). Используя этот одноразовый код, вы можете избежать дополнительной ошибки (use_dpop_nonce) при следующем запросе.
Подтверждения DPoP должны быть включены в запросы на обмен токенов, сделанные с помощью токенов обновления, связанных с DPoP.
Неудачный обмен происходит, если заголовок DPoP отсутствует, когда он должен быть, или недействителен, а также если доказательство использует ключ, отличный от того, который связан с токеном. В таких случаях сервер возвращает ошибку 400 Bad Request.
Если в доказательстве DPoP не совпадают утверждения htm или htu, истек срок действия iat, повторно используется jti или подпись недействительна, Google возвращает код ошибки invalid_dpop_proof.
Если требуется одноразовый код DPoP, например при обмене токена обновления, а в подтверждении DPoP отсутствует утверждение nonce или значение одноразового кода неприемлемо для сервера (например, оно устарело, уже использовалось или неправильное), Google возвращает код ошибки use_dpop_nonce вместе с HTTP-заголовком DPoP-Nonce, содержащим новый одноразовый код, который можно использовать в следующем запросе.
В других случаях может возвращаться значение invalid_grant.
В ответ на этот запрос Google возвращает объект JSON, содержащий токен доступа с коротким сроком действия и токен обновления.
Ответ содержит следующие поля:
| Поля | |
|---|---|
access_token |
Токен, который приложение отправляет для авторизации запроса к API Google. |
expires_in |
Оставшееся время действия токена доступа в секундах. |
id_token |
Примечание. Это свойство возвращается, только если запрос включает область идентификации, например openid, profile или email. Значение представляет собой веб-токен JSON (JWT), который содержит информацию о пользователе с цифровой подписью. |
refresh_token |
Токен, который можно использовать для получения нового токена доступа. Токены обновления действительны, пока пользователь не отзовет доступ или не истечет срок действия токена обновления. Если использовался DPoP, токен обновления привязывается к закрытому ключу, который использовался для подписи подтверждения DPoP. Обратите внимание, что для установленных приложений всегда возвращаются токены обновления. |
refresh_token_expires_in |
Оставшийся срок действия токена обновления в секундах. Это значение задается, только если пользователь предоставляет доступ на определенное время. |
scope |
Области действия, предоставленные access_token, в виде списка строк, разделенных пробелами и с учетом регистра. |
token_type |
Тип возвращенного токена. Это значение всегда равно Bearer, даже если используется DPoP. |
Ниже приведен пример заголовков и тела успешного ответа при использовании DPoP:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI
{
"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. Проверьте, какие области действия предоставили пользователи
Если вы запрашиваете несколько разрешений (областей действия), пользователи могут не предоставить вашему приложению доступ ко всем из них. Приложение должно проверять, какие области доступа были предоставлены, и корректно обрабатывать ситуации, когда в некоторых разрешениях отказано. Обычно в таких случаях отключаются функции, которые зависят от этих разрешений.
Однако из этого правила бывают исключения. Приложения Google Workspace Enterprise с делегированием доступа к данным в домене или приложения, помеченные как надежные, обходят окно запроса доступа с детализированными разрешениями. Для таких приложений пользователи не увидят окно запроса доступа с детализированными разрешениями. Вместо этого приложение получит либо все запрошенные области действия, либо ни одной.
Подробную информацию можно найти в статье Как работать с детализированными разрешениями.
Чтобы проверить, предоставил ли пользователь вашему приложению доступ к определенной области действия, изучите поле scope в ответе токена доступа. Области действия доступа, предоставленные токеном доступа, выраженные в виде списка строк с учетом регистра, разделенных пробелами.
Например, в следующем примере ответа на запрос токена доступа указано, что пользователь предоставил вашему приложению доступ к разрешениям на чтение активности на Диске и мероприятий в Календаре:
{ "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
После того как ваше приложение получит токен доступа, вы можете использовать его для вызовов Google API от имени определенного аккаунта пользователя, если предоставлены необходимые для API области доступа. Для этого включите токен доступа в запрос к API, добавив параметр запроса access_token или значение заголовка HTTP Authorization Bearer. По возможности лучше использовать заголовок HTTP, поскольку строки запроса обычно видны в журналах сервера. В большинстве случаев для настройки вызовов API Google можно использовать клиентскую библиотеку (например, при вызове Drive Files API).
Вы можете попробовать все API Google и посмотреть их области действия в OAuth 2.0 Playground.
Примеры запросов HTTP GET
Вызов конечной точки
drive.files (Drive Files API) с использованием 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 |
Идентификатор клиента, полученный из API Console. |
client_secret |
Необязательно
Секретный код клиента, полученный из API Console.
(Параметр |
grant_type |
В соответствии со спецификацией OAuth 2.0 в этом поле должно быть указано значение refresh_token. |
refresh_token |
Токен обновления, возвращенный в результате обмена кодами авторизации. |
Использование DPoP не обязательно, но рекомендуется для повышения уровня безопасности. Чтобы использовать DPoP с токеном обновления, ваше приложение должно генерировать новый уникальный JWT-токен подтверждения DPoP для каждого запроса к конечной точке токена. Это подтверждение должно быть подписано тем же закрытым ключом, который использовался при первоначальном обмене кодами авторизации. Приложение добавляет доказательство в виде заголовка HTTP-запроса.
| Заголовок | Обязательно | Описание |
|---|---|---|
DPoP |
Необязательно | Подтверждение DPoP – это JWT, который подтверждает владение закрытым ключом. Это заголовок, а не параметр. Если он указан, возвращаемые токены будут привязаны к этому ключу. Для каждого запроса необходимо создать новое уникальное доказательство, которое должно включать утверждения htm (метод HTTP) и htu (URI HTTP), соответствующие запросу. |
Ниже приведен пример запроса.
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded DPoP: DPOP_PROOF_JWT client_id=your_client_id& refresh_token=refresh_token& grant_type=refresh_token
Чтобы использовать DPoP с токеном обновления, необходимо сгенерировать новый уникальный JWT-доказательство DPoP для запроса. Пошаговые инструкции по созданию пары ключей и JWT приведены в разделе Как создать доказательство DPoP.
Успешный обмен обозначается ответом 200 OK, содержащим новый токен доступа. Если используется DPoP, то token_type – это Bearer. Успешный ответ подтверждает, что доказательство DPoP для токена обновления было принято. Google также может вернуть в ответе новый HTTP-заголовок DPoP-Nonce. Если это произойдет, ваш клиент должен сохранить этот nonce в кеше и включить его в утверждение nonce доказательства DPoP в последующих запросах.
Неудачный обмен происходит, если заголовок DPoP отсутствует, недействителен или использует неправильный ключ. Подробнее о кодах ошибок DPoP и обработке однократно используемых номеров…
Ниже приведен пример заголовков и тела успешного ответа при использовании DPoP:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI
{
"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
Специальные схемы URI – это ссылки на контент, которые используют специальную схему для открытия приложения.
Альтернатива пользовательским схемам URI в приложениях Chrome
Используйте Chrome Identity API, который передает ответ OAuth 2.0 непосредственно в приложение, устраняя необходимость в URI перенаправления.
Петлевой IP-адрес (macOS, Linux, Windows)
Чтобы получить код авторизации с помощью этого URL, ваше приложение должно прослушивать локальный веб-сервер. Это возможно на многих, но не на всех платформах. Однако если ваша платформа поддерживает этот механизм, мы рекомендуем использовать его для получения кода авторизации.
Когда ваше приложение получит ответ с авторизацией, для удобства использования оно должно показать HTML-страницу с инструкцией закрыть браузер и вернуться в приложение.
| Рекомендуемое использование | Приложения для macOS, Linux и Windows (кроме приложений для универсальной платформы Windows). |
| Значения формы | В качестве типа приложения выберите Компьютерное приложение. |
Копирование и вставка вручную (поддержка прекращена)
Как защитить приложения
Как подтвердить право собственности на приложение для Chrome
Вы можете подтвердить право собственности на приложение, чтобы снизить риск его имитации.
Чтобы завершить проверку, используйте аккаунт разработчика в интернет-магазине Chrome. Чтобы успешно пройти проверку, необходимо выполнить следующие требования:
- В Личном кабинете разработчика продуктов для интернет-магазина Chrome должен быть зарегистрирован продукт с тем же идентификатором товара, что и у клиента OAuth расширения Chrome, для которого вы проходите проверку.
- Вы должны быть издателем продукта в интернет-магазине Chrome. Подробнее об управлении доступом в Личном кабинете разработчика продуктов для интернет-магазина Chrome…
В разделе Подтверждение права собственности на приложение клиента расширения Chrome нажмите кнопку Подтвердить право собственности, чтобы завершить процесс проверки.
Примечание. После предоставления доступа к аккаунту подождите несколько минут, прежде чем завершить процедуру подтверждения.
Если проверка пройдет успешно, вы увидите уведомление. В противном случае появится сообщение об ошибке.
Чтобы устранить проблему, попробуйте сделать следующее:
- Убедитесь, что в Личном кабинете разработчика продуктов для интернет-магазина Chrome зарегистрирован продукт с тем же идентификатором, что и у OAuth-клиента расширения Chrome, для которого вы проходите проверку.
- Убедитесь, что вы являетесь издателем приложения, то есть его индивидуальным издателем или участником издательской группы. Подробнее об управлении доступом в Личном кабинете разработчика продуктов для интернет-магазина Chrome…
- Если вы только что обновили список издателей группы, убедитесь, что он синхронизирован с Личным кабинетом разработчика продуктов для интернет-магазина Chrome. Подробнее о синхронизации списка участников издателя…
Проверка приложений (только iOS)
Функция App Check помогает защитить приложения для iOS от несанкционированного использования. Она проверяет, исходят ли запросы к конечным точкам Google OAuth 2.0 из ваших приложений, с помощью сервиса App Attest от Apple. Это помогает снизить риск подделки приложений.
Как включить проверку приложений для клиента iOS
Чтобы успешно включить App Check для клиента iOS, необходимо выполнить следующие требования:- Укажите идентификатор команды для клиента iOS.
- В идентификаторе пакета нельзя использовать подстановочные знаки, поскольку он может относиться к нескольким приложениям. Это означает, что идентификатор пакета не должен содержать символ звездочки (*).
После включения Проверки приложений в режиме редактирования клиента OAuth начнут показываться показатели, связанные с запросами OAuth от вашего клиента. Запросы из непроверенных источников не будут блокироваться, пока вы не включите принудительное использование Проверки приложений. Информация на странице мониторинга показателей поможет вам определить, когда следует начать принудительное применение.
При включении Проверки приложений для приложения iOS могут возникать ошибки. Чтобы их устранить, попробуйте сделать следующее:
- Убедитесь, что идентификаторы пакета и команды указаны правильно.
- Убедитесь, что вы не используете подстановочный знак для идентификатора пакета.
Как включить проверку приложений для клиента iOS
Включение Проверки приложений не приводит к автоматической блокировке нераспознанных запросов. Чтобы применить эту защиту, перейдите в режим редактирования клиента iOS. Показатели проверки приложений будут в правой части страницы в разделе Google Identity для iOS. В частности, вы можете узнать:- Количество проверенных запросов – запросы с действительным токеном App Check. После того как вы включите принудительное применение App Check, будут выполняться только запросы из этой категории.
- Количество непроверенных запросов: вероятно, устаревшие запросы клиентов – запросы, в которых отсутствует токен Проверки приложений. Они могут поступать из более старой версии приложения, в которой не реализована Проверка приложений.
- Количество неподтвержденных запросов: запросы из неизвестных источников – запросы без токена проверки приложений, которые, по всей видимости, поступают не из вашего приложения.
- Количество неподтвержденных запросов: недействительные запросы – запросы с недействительным токеном App Check, которые могут быть отправлены с поддельного клиента, пытающегося выдать себя за ваше приложение, или из эмулируемой среды.
Чтобы включить Проверку приложений, нажмите кнопку ENFORCE и подтвердите выбор. После этого все неподтвержденные запросы от вашего клиента будут отклоняться.
Примечание. После включения принудительного применения может пройти до 15 минут, прежде чем изменения вступят в силу.
Как отключить проверку приложений для клиента iOS
Если вы отключите проверку приложений для своего приложения, принудительное применение будет остановлено и все запросы от вашего клиента к конечным точкам Google OAuth 2.0, в том числе непроверенные, будут разрешены.
Чтобы отключить проверку приложений для клиента iOS, перейдите в режим редактирования клиента iOS, нажмите кнопку Отключить и подтвердите выбор.
Примечание. После отключения App Check изменения вступят в силу в течение 15 минут.
Как отключить проверку приложений для клиента iOS
Если вы отключите App Check для своего приложения, мониторинг и принудительное применение App Check будут остановлены. Вместо этого вы можете отключить принудительное применение Проверки приложений, чтобы продолжить отслеживать показатели клиента.
Чтобы отключить проверку приложений для клиента iOS, перейдите в режим редактирования клиента iOS и отключите переключатель Защитите свой клиент OAuth от злоупотреблений с помощью Firebase App Check.
Примечание. После отключения проверки приложений изменения вступят в силу в течение 15 минут.
Доступ на основе времени
Временный доступ позволяет пользователю предоставить приложению доступ к своим данным на ограниченный период времени, чтобы выполнить определенное действие. В некоторых продуктах Google во время запроса согласия пользователям предлагается предоставить доступ на ограниченный период времени. Пример – Data Portability API, который позволяет выполнить однократный перенос данных.
Если пользователь предоставляет вашему приложению доступ на определенный период времени, токен обновления станет недействительным по истечении этого периода. Обратите внимание, что токены обновления могут быть аннулированы раньше при определенных обстоятельствах. Подробнее о таких случаях… В таких случаях поле refresh_token_expires_in, возвращаемое в ответе обмена кода авторизации, представляет собой время, оставшееся до истечения срока действия токена обновления.
Дополнительные ресурсы
Многие из приведенных здесь рекомендаций основаны на документе OAuth 2.0 for Native Apps (OAuth 2.0 для нативных приложений), который опубликован на сайте IETF.
Как реализовать защиту связанных аккаунтов
Чтобы дополнительно защитить аккаунты пользователей, реализуйте защиту связанных аккаунтов с помощью сервиса защиты связанных аккаунтов 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
Подробнее о том, как реализовать защиту связанных аккаунтов и какие события доступны, рассказывается на странице Защита аккаунтов пользователей с помощью функции "Защита связанных аккаунтов" .