Google стремится продвигать расовое равенство для чернокожих сообществ. Смотри как.

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

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

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

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

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

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

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

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

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

Мы рекомендуем следующие библиотеки и образцы, которые помогут вам реализовать поток 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 Credentials page.
  2. Щелкните Создать учетные данные> Идентификатор клиента OAuth .
  3. В разделах ниже описаны типы клиентов и методы перенаправления, поддерживаемые сервером авторизации Google. Выберите тип клиента, рекомендуемый для вашего приложения, назовите своего клиента OAuth и задайте соответствующие поля в форме.

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

Для приложений Android, приложений iOS и приложений универсальной платформы Windows (UWP) рекомендуется использовать настраиваемую схему URI.

Android
  1. Выберите тип приложения Android .
  2. Введите имя клиента OAuth. Это имя отображается на Credentials page вашего проекта для идентификации клиента.
  3. Введите название пакета вашего Android-приложения. Это значение определяется в атрибуте package элемента <manifest> в файле манифеста приложения.
  4. Введите отпечаток сертификата подписи SHA-1 для распространения приложения.
    • Если ваше приложение использует подписывание приложений в Google Play , скопируйте отпечаток SHA-1 со страницы подписи приложения в Play Console.
    • Если вы управляете своим собственным хранилищем ключей и ключами подписи, используйте утилиту keytool, включенную в Java, для печати информации о сертификате в удобочитаемом формате. Скопируйте значение SHA1 в раздел « Отпечатки Certificate fingerprints вывода keytool . Дополнительную информацию см. В разделе « Аутентификация клиента» в документации по API Google для Android.
  5. Щелкните " Создать" .
iOS
  1. Выберите тип приложения iOS .
  2. Введите имя клиента OAuth. Это имя отображается на Credentials page вашего проекта для идентификации клиента.
  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. Щелкните " Создать" .
UWP
  1. Выберите тип приложения универсальной платформы Windows .
  2. Введите имя клиента OAuth. Это имя отображается на Credentials page вашего проекта для идентификации клиента.
  3. Введите 12-значный идентификатор вашего приложения в Microsoft Store. Это значение можно найти в Центре партнеров Майкрософт на странице « Удостоверение приложения» в разделе «Управление приложениями».
  4. Щелкните " Создать" .

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

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

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

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

Рекомендуемое использование настольные приложения для macOS, Linux и Windows (но не для универсальной платформы Windows)
Значения формы Задайте тип приложения Настольное приложение .

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

Программное извлечение

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

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

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

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

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

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

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

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

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

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

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

Создайте вызов кода

Поддерживаются два метода создания проблемы кода.

Методы создания запроса кода
S256 (рекомендуется) Проблема с кодом - это хэш SHA256, закодированный с помощью Base64URL (без заполнения), для верификатора кода.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
простой Запрос кода - это то же значение, что и созданный выше верификатор кода.
code_challenge = code_verifier

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

Чтобы получить авторизацию пользователя, отправьте запрос на сервер авторизации Google по адресу https://accounts.google.com/o/oauth2/v2/auth . Эта конечная точка обрабатывает активный поиск сеанса, аутентифицирует пользователя и получает согласие пользователя. Конечная точка доступна только через SSL и отклоняет соединения HTTP (не SSL).

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

Параметры
client_id Обязательный

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

redirect_uri Обязательный

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

Значение должно точно соответствовать одному из авторизованных URI перенаправления для клиента OAuth 2.0, который вы настроили в своем клиенте API Console Credentials page. Если это значение не соответствует авторизованному URI, вы получите ошибку redirect_uri_mismatch .

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

значения redirect_uri
Пользовательская схема URI com.example.app : redirect_uri_path

или же

com.googleusercontent.apps.123 : redirect_uri_path
  • com.example.app - это обратная DNS-запись домена, находящегося под вашим контролем. Пользовательская схема должна содержать период, чтобы быть действительной.
  • com.googleusercontent.apps.123 - это обратная DNS-запись идентификатора клиента.
  • redirect_uri_path - это необязательный компонент пути, например /oauth2redirect . Обратите внимание, что путь должен начинаться с одинарной косой черты, что отличается от обычных URL-адресов HTTP.
Loopback IP-адрес http://127.0.0.1: port или http://[::1]: port

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

Копирование / вставка вручную urn:ietf:wg:oauth:2.0:oob
Программное извлечение urn:ietf:wg:oauth:2.0:oob:auto
response_type Обязательный

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

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

scope Обязательный

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

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

code_challenge рекомендуемые

Задает закодированный code_verifier который будет использоваться в качестве code_verifier на стороне сервера во время обмена кодами авторизации. Этот параметр необходимо использовать с параметром code_challenge описанным выше. См. Раздел создания кода выше для получения дополнительной информации.

code_challenge_method рекомендуемые

Указывает, какой метод был использован для кодирования code_verifier который будет использоваться во время обмена кодами авторизации. Этот параметр необходимо использовать с параметром code_challenge . Значение code_challenge_method умолчанию 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

Loopback 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

Копировать вставить

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=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&
 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=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob%3Aauto&
 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 и установите следующие параметры:

Поля
client_id Идентификатор клиента, полученный из API Console Credentials page.
client_secret Секрет клиента, полученный от API Console Credentials page.
code Код авторизации, возвращенный из первоначального запроса.
code_verifier Средство проверки кода, созданное на шаге 1 .
grant_type Как определено в спецификации OAuth 2.0 , значение этого поля должно быть установлено на authorization_code .
redirect_uri Один из URI перенаправления, перечисленных для вашего проекта в API Console Credentials page для данного client_id .

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

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

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob%3Aauto&
grant_type=authorization_code

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

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

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

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

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

Вызов API Google

После того, как ваше приложение получит токен доступа, вы можете использовать этот токен для вызовов API Google от имени данной учетной записи пользователя, если предоставлены области доступа, требуемые API. Для этого, включите маркер доступа в запросе к API путем включения либо access_token параметр запроса или Authorization HTTP заголовка Bearer значение. По возможности предпочтительнее использовать заголовок HTTP, поскольку строки запроса обычно видны в журналах сервера. В большинстве случаев вы можете использовать клиентскую библиотеку для настройки вызовов API Google (например, при вызове API файлов Диска ).

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

Примеры HTTP GET

Вызов drive.files точки 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 запроса 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. ( client_secret не применяется к запросам от клиентов, зарегистрированных как приложения Android, iOS или Chrome.)
grant_type Как определено в спецификации OAuth 2.0 , значение этого поля должно быть установлено на refresh_token .
refresh_token Маркер обновления, возвращенный при обмене кодами авторизации.

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

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

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Пока пользователь не отозвал доступ, предоставленный приложению, сервер токенов возвращает объект JSON, содержащий новый токен доступа. В следующем фрагменте показан пример ответа:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

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

Отзыв токена

В некоторых случаях пользователь может захотеть отозвать доступ, предоставленный приложению. Пользователь может отозвать доступ, посетив настройки учетной записи . Дополнительные сведения см. В разделе « Удаление доступа к сайту или приложению» в документе «Сторонние сайты и приложения с доступом к вашей учетной записи» .

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

Чтобы программно отозвать токен, ваше приложение отправляет запрос на https://oauth2.googleapis.com/revoke и включает токен в качестве параметра:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

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

Если отзыв успешно обработан, код состояния HTTP ответа - 200 . В случае возникновения ошибок код состояния HTTP 400 возвращается вместе с кодом ошибки.

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

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