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, описанный в этом документе:

• Библиотека AppAuth для Android
• AppAuth для библиотеки iOS
• OAuth для приложений: примеры Windows

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

Включите 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, должно иметь учетные данные авторизации, которые идентифицируют приложение на сервере Google OAuth 2.0. Следующие шаги объясняют, как создать учетные данные для вашего проекта. Затем ваши приложения смогут использовать учетные данные для доступа к API, которые вы включили для этого проекта.

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

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

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

Прежде чем приступить к реализации авторизации 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 символов.

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

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

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

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

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

Шаг 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&
client_secret=your_client_secret&
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",
  "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 ), который включает следующие параметры:

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

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

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

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

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

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

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

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

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

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

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

• Appauth для библиотеки Android
• Appauth для библиотеки iOS
• Оаут для приложений: образцы Windows

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

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

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

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

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

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

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

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

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

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

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

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

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

Шаг 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&
client_secret=your_client_secret&
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",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Вызов Google API

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

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

Http Получите примеры

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

Чтобы обновить токен доступа, ваше приложение отправляет запрос POST HTTPS на сервер авторизации 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&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

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

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

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

Отмена токена

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

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

To programmatically revoke a token, your application makes a request to https://oauth2.googleapis.com/revoke and includes the token as a parameter:

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

The token can be an access token or a refresh token. If the token is an access token and it has a corresponding refresh token, the refresh token will also be revoked.

If the revocation is successfully processed, then the HTTP status code of the response is 200 . For error conditions, an HTTP status code 400 is returned along with an error code.

App redirect methods

Protect your apps

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

The IETF Best Current Practice OAuth 2.0 for Native Apps establishes many of the best practices documented here.

This document explains how applications installed on devices like phones, tablets, and computers use Google's OAuth 2.0 endpoints to authorize access to Google APIs.

OAuth 2.0 allows users to share specific data with an application while keeping their usernames, passwords, and other information private. For example, an application can use OAuth 2.0 to obtain permission from users to store files in their Google Drives.

Installed apps are distributed to individual devices, and it is assumed that these apps cannot keep secrets. They can access Google APIs while the user is present at the app or when the app is running in the background.

This authorization flow is similar to the one used for web server applications . The main difference is that installed apps must open the system browser and supply a local redirect URI to handle responses from Google's authorization server.

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

For mobile apps, you may prefer to use Google Sign-in for Android or iOS . The Google Sign-in client libraries handle authentication and user authorization, and they may be simpler to implement than the lower-level protocol described here.

For apps running on devices that do not support a system browser or that have limited input capabilities, such as TVs, game consoles, cameras, or printers, see OAuth 2.0 for TVs & Devices or Sign-In on TVs and Limited Input Devices .

Libraries and samples

We recommend the following libraries and samples to help you implement the OAuth 2.0 flow described in this document:

• AppAuth for Android library
• AppAuth for iOS library
• OAuth for Apps: Windows Samples

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

Enable APIs for your project

Any application that calls Google APIs needs to enable those APIs in the API Console.

To enable an API for your project:

1. Open the API Library в Google API Console.
2. If prompted, select a project, or create a new one.
3. API Library lists all available APIs, grouped by product family and popularity. If the API you want to enable isn't visible in the list, use search to find it, or click View All in the product family it belongs to.
4. Select the API you want to enable, then click the Enable button.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

Create authorization credentials

Any application that uses OAuth 2.0 to access Google APIs must have authorization credentials that identify the application to Google's OAuth 2.0 server. The following steps explain how to create credentials for your project. Your applications can then use the credentials to access APIs that you have enabled for that project.

1. Go to the Credentials page.
2. Click Create credentials > OAuth client ID .
3. The following sections describe the client types that Google's authorization server supports. Choose the client type that is recommended for your application, name your OAuth client, and set the other fields in the form as appropriate.

Identify access scopes

Scopes enable your application to only request access to the resources that it needs while also enabling users to control the amount of access that they grant to your application. Thus, there may be an inverse relationship between the number of scopes requested and the likelihood of obtaining user consent.

Before you start implementing OAuth 2.0 authorization, we recommend that you identify the scopes that your app will need permission to access.

The OAuth 2.0 API Scopes document contains a full list of scopes that you might use to access Google APIs.

Obtaining OAuth 2.0 access tokens

The following steps show how your application interacts with Google's OAuth 2.0 server to obtain a user's consent to perform an API request on the user's behalf. Your application must have that consent before it can execute a Google API request that requires user authorization.

Step 1: Generate a code verifier and challenge

Google supports the Proof Key for Code Exchange (PKCE) protocol to make the installed app flow more secure. A unique code verifier is created for every authorization request, and its transformed value, called "code_challenge", is sent to the authorization server to obtain the authorization code.

Create the code verifier

A code_verifier is a high-entropy cryptographic random string using the unreserved characters [AZ] / [az] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters.

The code verifier should have enough entropy to make it impractical to guess the value.

Create the code challenge

Two methods of creating the code challenge are supported.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

Step 2: Send a request to Google's OAuth 2.0 server

To obtain user authorization, send a request to Google's authorization server at https://accounts.google.com/o/oauth2/v2/auth . This endpoint handles active session lookup, authenticates the user, and obtains user consent. The endpoint is only accessible over SSL, and it refuses HTTP (non-SSL) connections.

The authorization server supports the following query string parameters for installed applications:

Sample authorization URLs

The tabs below show sample authorization URLs for the different redirect URI options.

The URLs are identical except for the value of the redirect_uri parameter. The URLs also contain the required response_type and client_id parameters as well as the optional state parameter. Each URL contains line breaks and spaces for readability.

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

Step 3: Google prompts user for consent

In this step, the user decides whether to grant your application the requested access. At this stage, Google displays a consent window that shows the name of your application and the Google API services that it is requesting permission to access with the user's authorization credentials and a summary of the scopes of access to be granted. The user can then consent to grant access to one or more scopes requested by your application or refuse the request.

Your application doesn't need to do anything at this stage as it waits for the response from Google's OAuth 2.0 server indicating whether any access was granted. That response is explained in the following step.

Step 4: Handle the OAuth 2.0 server response

The manner in which your application receives the authorization response depends on the redirect URI scheme that it uses. Regardless of the scheme, the response will either contain an authorization code ( code ) or an error ( error ). For example, error=access_denied indicates that the user declined the request.

If the user grants access to your application, you can exchange the authorization code for an access token and a refresh token as described in the next step.

Step 5: Exchange authorization code for refresh and access tokens

To exchange an authorization code for an access token, call the https://oauth2.googleapis.com/token endpoint and set the following parameters:

The following snippet shows a sample request:

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 responds to this request by returning a JSON object that contains a short-lived access token and a refresh token.

The response contains the following fields:

The following snippet shows a sample response:

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

Calling Google APIs

After your application obtains an access token, you can use the token to make calls to a Google API on behalf of a given user account if the scope(s) of access required by the API have been granted. To do this, include the access token in a request to the API by including either an access_token query parameter or an Authorization HTTP header Bearer value. When possible, the HTTP header is preferable, because query strings tend to be visible in server logs. In most cases you can use a client library to set up your calls to Google APIs (for example, when calling the Drive Files API ).

You can try out all the Google APIs and view their scopes at the OAuth 2.0 Playground .

HTTP GET examples

A call to the drive.files endpoint (the Drive Files API) using the Authorization: Bearer HTTP header might look like the following. Note that you need to specify your own access token:

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

Here is a call to the same API for the authenticated user using the access_token query string parameter:

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

curl examples

You can test these commands with the curl command-line application. Here's an example that uses the HTTP header option (preferred):

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

Or, alternatively, the query string parameter option:

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

Refreshing an access token

Access tokens periodically expire and become invalid credentials for a related API request. You can refresh an access token without prompting the user for permission (including when the user is not present) if you requested offline access to the scopes associated with the token.

To refresh an access token, your application sends an HTTPS POST request to Google's authorization server ( https://oauth2.googleapis.com/token ) that includes the following parameters:

The following snippet shows a sample request:

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

As long as the user has not revoked the access granted to the application, the token server returns a JSON object that contains a new access token. The following snippet shows a sample response:

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

Note that there are limits on the number of refresh tokens that will be issued; one limit per client/user combination, and another per user across all clients. You should save refresh tokens in long-term storage and continue to use them as long as they remain valid. If your application requests too many refresh tokens, it may run into these limits, in which case older refresh tokens will stop working.

Revoking a token

In some cases a user may wish to revoke access given to an application. A user can revoke access by visiting Account Settings . See the Remove site or app access section of the Third-party sites & apps with access to your account support document for more information.

It is also possible for an application to programmatically revoke the access given to it. Programmatic revocation is important in instances where a user unsubscribes, removes an application, or the API resources required by an app have significantly changed. In other words, part of the removal process can include an API request to ensure the permissions previously granted to the application are removed.

To programmatically revoke a token, your application makes a request to https://oauth2.googleapis.com/revoke and includes the token as a parameter:

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

The token can be an access token or a refresh token. If the token is an access token and it has a corresponding refresh token, the refresh token will also be revoked.

If the revocation is successfully processed, then the HTTP status code of the response is 200 . For error conditions, an HTTP status code 400 is returned along with an error code.

App redirect methods

Protect your apps

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

The IETF Best Current Practice OAuth 2.0 for Native Apps establishes many of the best practices documented here.