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

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

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

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

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

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

Для iOS-приложений мы рекомендуем использовать последнюю версию SDK Sign In With Google iOS . Этот SDK обрабатывает авторизацию пользователей и проще в реализации, чем низкоуровневый протокол, описанный в этом руководстве.

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

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

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

Любое приложение, использующее API Google, должно включить эти API в своих настройках. API Console.

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

1. Open the API Library в Google API Console.
2. If prompted, select a project, or create a new one.
3. Он API Library В списке отображаются все доступные API, сгруппированные по семействам продуктов и популярности. Если нужный вам API отсутствует в списке, воспользуйтесь поиском, чтобы найти его, или нажмите «Показать все» в семействе продуктов, к которому он относится.
4. Выберите API, который хотите включить, затем нажмите кнопку «Включить» .
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

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

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

1. Go to the Clients page.
2. Нажмите «Создать клиента» .
3. В следующих разделах описаны типы клиентов, поддерживаемые сервером авторизации Google. Выберите рекомендуемый для вашего приложения тип клиента, назовите свой OAuth-клиент и заполните остальные поля формы соответствующим образом.

ms-app://YOUR_APP_PACKAGE_SID

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

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

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

В документе «Области действия API OAuth 2.0» содержится полный список областей действия, которые вы можете использовать для доступа к API Google.

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

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

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

Google поддерживает протокол Proof Key for Code Exchange (PKCE), чтобы сделать процесс установки приложения более безопасным. Для каждого запроса на авторизацию создается уникальный верификатор кода, и его преобразованное значение, называемое "code_challenge", отправляется на сервер авторизации для получения кода авторизации.

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

code_verifier — это высокоэнтропийная криптографическая случайная строка, использующая незарезервированные символы [AZ] / [az] / [0-9] / "-" / "." / "_" / "~", с минимальной длиной 43 символа и максимальной длиной 128 символов.

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

Задание «Создай код»

Поддерживаются два метода создания задания по программированию.

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

Сервер авторизации поддерживает следующие параметры строки запроса для установленных приложений:

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

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

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

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

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

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

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

Способ получения вашим приложением ответа об авторизации зависит от используемой схемы URI перенаправления . Независимо от схемы, ответ будет содержать либо код авторизации ( code ), либо ошибку ( error ). Например, error=access_denied означает, что пользователь отклонил запрос.

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

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

Для обмена кода авторизации на токен доступа вызовите конечную точку https://oauth2.googleapis.com/token и установите следующие параметры:

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

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&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

В ответ на этот запрос Google возвращает JSON-объект, содержащий кратковременный токен доступа и токен обновления.

Ответ содержит следующие поля:

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

{
  "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. Области действия, предоставленные access_token, представлены в виде списка строк, разделенных пробелами и чувствительных к регистру.

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

  {
    "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 , либо значение заголовка HTTP Authorization Bearer . По возможности предпочтительнее использовать заголовок HTTP, поскольку строки запроса обычно видны в логах сервера. В большинстве случаев вы можете использовать клиентскую библиотеку для настройки вызовов к API Google (например, при вызове API файлов Google Drive ).

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

Примеры HTTP GET-запросов

Вызов конечной точки drive.files (API файлового сервиса Drive) с использованием 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 ), который включает следующие параметры:

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

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
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 вместе с кодом ошибки.

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

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

Доступ по времени

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

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

Дополнительная литература

В документе IETF Best Current Practice OAuth 2.0 for Native Apps изложены многие из лучших практик, описанных здесь.