OAuth ВКонтакте: использования в корыстных целях. OAuth: описание протокола простым и понятным языком

|

OAuth 2 – это протокол авторизации, который предоставляет приложениям ограниченный HTTP-доступ к учетным записям пользователей. Он передаёт аутентификацию пользователей сервису, на котором размещены учетные записи, и авторизует сторонние приложения и передаёт им доступ к учетной записи пользователя. OAuth 2 обеспечивает авторизацию веб-приложений и мобильных устройств.

Данное руководство ознакомит вас с ролями OAuth 2, типами авторизации, с потоками и случаями использования OAuth 2.

Роли OAuth

В OAuth существует четыре роли:

1. Владелец ресурса
2. Клиент
3. Сервер ресурсов
4. Сервер авторизации

Рассмотрим каждую роль подробнее.

Владелец ресурса: пользователь

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

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

Сервер ресурсов и авторизации: API

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

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

Клиент: приложение

Клиент – это приложение, которое хочет получить доступ к аккаунту пользователя. Прежде чем оно сможет сделать это, пользователь должен авторизоваться в приложении, а API должен подтвердить авторизацию.

Потоки протокола

Роли OAuth взаимодействуют между собой следующим образом:

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

Регистрация приложения

Прежде чем вы сможете использовать OAuth в приложении, вам необходимо зарегистрировать приложение. Это делается через регистрационную форму в разделе Developer или API на веб-сайте сервиса, где нужно предоставить следующую информацию:

• Название приложения;
• Сайт приложения;
• URL обратного вызова или URI переадресации (сюда сервис будет перенаправлять пользователя после того, как он прошел (или не прошел) авторизацию; эта часть приложения будет обрабатывать коды авторизации или токены доступа).

ID и секретный ключ клиента

После регистрации приложения сервис предоставит вам учётные данные приложения, которые можно найти в поле client identifier и client secret. Client ID – это общедоступная строка, которая используется API сервиса для определения приложения; также с её помощью создаются URL-ы авторизации. Client Secret позволяет API сервиса подтвердить подлинность приложения, когда оно запрашивает доступ к аккаунту пользователя. Эти конфиденциальные данные хранятся между приложением и API.

Полномочия авторизации

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

1. Код подтверждения: используется в приложениях серверной стороны.
2. Неявный доступ: используется в веб-и мобильных приложениях (приложениях, которые работают на устройстве пользователя).
3. Предоставление клиенту пароля: применяется в заведомо безопасных приложениях (например, в принадлежащих сервису приложениях).
4. Клиентские полномочия: доступ к API приложения.

Код подтверждения

Код подтверждения – самый распространённый тип полномочий, оптимизированный для приложений серверной стороны, в которых исходный код закрыт, а Client Secret недоступен посторонним. Этот поток основан на редиректе, а это означает, что приложение должно иметь возможность взаимодействовать с агентом пользователя (т.е. веб-браузером пользователя) и получать коды авторизации API, которые направляются через агента пользователя.

Поток с кодом подтверждения выглядит так:

1. Пользователь получает ссылку на код подтверждения.
2. Пользователь авторизуется. Кликая по ссылке, пользователь подтверждает подлинность данных. Если предоставленные данные неправильные, пользователю будет отказано в авторизации.
3. Приложение получает код подтверждения. Сервис перенаправляет агента пользователя к URI, который был указан при регистрации клиента, вместе с кодом подтверждения.
4. Приложение запрашивает токен доступа у API, предоставляя код подтверждения и данные об авторизации, включая client secret.
5. Приложение получает токен доступа, если авторизация валидна.

Поток неявного доступа

Поток неявного доступа используется мобильными приложениями или веб-приложениями, где конфиденциальность client secret гарантировать нельзя. Этот поток также основан на редиректе, но токен доступа получает агент пользователя, после чего он передаётся приложению. Таким образом он может быть виден пользователю или другим приложениям на устройстве пользователя. Кроме того, этот поток не выполняет проверку подлинности приложения, для этого используется URI (который был зарегистрирован в сервисе).

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

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

1. Пользователь получает ссылку неявного доступа, которая запрашивает токен у API.
2. Пользователь проходит авторизацию, кликнув по ссылке. Если пользователь не может авторизоваться, ему будет отказано в доступе.
3. Агент пользователя получает токен доступа и Redirect URI.
4. Агент пользователя следует Redirect URI.
5. Приложение отправляет сценарий извлечения токена доступа. Приложение возвращает веб-страницу со сценарием, который может извлечь токен доступа из Redirect URI.
6. Приложение получает токен доступа. Авторизация завершена.

Предоставление клиенту пароля

Данный тип подразумевает, что пользователь передаёт учётные данные непосредственно приложению, которое с их помощью получает токен доступа. Этот тип должен поддерживаться только на сервере авторизации. Кроме того, его следует использовать только в случае, если приложению можно доверять (например, оно принадлежит сервису или операционной системе пользователя).

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

Клиентские полномочия

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

Приложение запрашивает токен доступа, отправляя свои учетные данные, client ID и client secret. . Если учётные данные правильные, сервер авторизации предоставит токен доступа. Авторизация завершена.

Использование токенов доступа

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

Если токен валидный, API обрабатывает запрос. Если токен недействителен, API выдаст ошибку invalid_request.

Поток с обновляемым токеном

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

Теперь вы знакомы с основами OAuth 2.

Tags: ,

1. Открытие встроенного браузера со страницей авторизации
2. У пользователя запрашивается подтверждение выдачи прав
3. В случае согласия пользователя, браузер редиректится на страницу-заглушку во фрагменте (после #) URL которой добавляется access token
4. Приложение перехватывает редирект и получает access token из адреса страницы

Этот вариант требует поднятия в приложении окна браузера, но не требует серверной части и дополнительного вызова сервер-сервер для обмена authorization code на access token .

Пример

Открываем браузер со страницей авторизации:
> GET /oauth/authorize?response_type=token&client_id=464119 HTTP/1.1 > Host: connect.mail.ru

После того, как пользователь выдаст права, происходит редирект на стандартную страницу-заглушку, для Mail.Ru это connect.mail.ru/oauth/success.html :
< HTTP/1.1 302 Found < Location: http://connect.mail.ru/oauth/success.html#access_token=FJQbwq9&token_type=bearer& expires_in=86400&refresh_token=yaeFa0gu

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

Авторизация по логину и паролю

Авторизация по логину и паролю представляет простой POST-запрос, в результате которого возвращается access token . Такая схема не представляет из себя ничего нового, но вставлена в стандарт для общности и рекомендуется к применению только, когда другие варианты авторизации не доступны.

Пример

> POST /oauth/token HTTP/1.1 > Host: connect.mail.ru > Content-Type: application/x-www-form-urlencoded > > grant_type=password&client_id=31337&client_secret=deadbeef&username=api@corp.mail.ru& password=qwerty < HTTP/1.1 200 OK < Content-Type: application/json < < { < "access_token":"SlAV32hkKG", < "token_type":"bearer", < "expires_in":86400, < "refresh_token":"8xLOxBtZp8", < }
Описание в спецификации

Восстановление предыдущей авторизации

Обычно, access token имеет ограниченный срок годности. Это может быть полезно, например, если он передается по открытым каналам. Чтобы не заставлять пользователя проходить авторизацию после истечения срока действия access token "а, во всех перечисленных выше вариантах, в дополнение к access token "у может возвращаться еще refresh token . По нему можно получить access token с помощью HTTP-запроса, аналогично авторизации по логину и паролю.

Пример

> POST /oauth/token HTTP/1.1 > Host: connect.mail.ru > Content-Type: application/x-www-form-urlencoded > > grant_type=refresh_token&client_id=31337&client_secret=deadbeef&refresh_token=8xLOxBtZp8 < HTTP/1.1 200 OK < Content-Type: application/json < < { < "access_token":"Uu8oor1i", < "token_type":"bearer", < "expires_in":86400, < "refresh_token":"ohWo1ohr", < }

В 2010 году началась работа над совершенно новой версией протокола OAuth 2.0 , которая не будет обратно совместимой с OAuth 1.0. В октябре 2012 года структура OAuth 2.0 было опубликована в RFC 6749 , и использование носителя токена в RFC 6750 , оба стандарта отслеживают запросы на комментарии. Дополнительные документы RFC еще разрабатываются.

Предпосылок для создания OAuth 2.0 было несколько. В первую очередь, OAuth достаточно нетривиально использовать на клиентской стороне. Одна из поставленных целей при разработке нового OAuth - упростить разработку клиентских приложений. Во-вторых, несмотря на заявленную в стандарте реализацию трех методов (называемых потоками - flows) получения токена (уникального идентификатора) для авторизации: для веб-приложений, настольных клиентов и мобильных клиентов, фактически все три способа слиты в один. И, в-третьих, протокол оказался плохо масштабируемым. В него планируется добавить :

• 6 новых потоков.

Поток пользователя – агента (User-Agent Flow) - для клиентов, работающих внутри агента пользователя (обычно веб-браузер). Поток веб – сервера (Web Server Flow) - для клиентов, которые являются частью веб-приложения сервера, доступные через запросы HTTP . Поток устройства (Device Flow) - подходит для клиентов, выполняющихся на ограниченных устройствах, но там, где конечный пользователь имеет отдельный доступ к браузеру на другом компьютере или устройстве. Поток имени пользователя и пароля(Username and Password Flow) - используется в тех случаях, когда пользователь доверяет клиенту обрабатывать свои полномочия, но он по-прежнему нежелательно разрешит клиенту сохранить имя и пароль пользователя. Этот поток подходит только когда есть высокая степень доверия между пользователем и клиентом. Поток клиентских полномочий (Client Credentials Flow) - клиент использует свои полномочия для получения токена. Поток утверждения (Assertion Flow) - клиент представляет утверждение, такие как утверждение SAML к серверу авторизации в обмен на токен. Приложения, работающие на настольном компьютере или мобильном устройстве может быть реализованы с использованием выше сказанных потоков.

• Токен на предъявителя.

Метод авторизации аналогичен существующему способу авторизации с помощью cookie . В этом случае токен непосредственно используется как секрет (сам факт наличия токена авторизует клиента) и передается через HTTPS . Это позволяет получать доступ к API посредством простых скриптов (например, с использованием cURL).

• Упрощенная подпись.

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

• Короткоживущие токены с долговременной авторизацией.

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

• Разделение ролей.

За авторизацию и за предоставление доступа к API могут отвечать разные сервера.

Стоит отметить, что, хотя стандарт OAuth 2.0 ещё не утвержден, он уже используется некоторыми сервисами. Например, Graph API социальной сети Facebook поддерживает только OAuth 2.0.

Отличие OAuth от OpenID

Существует ошибочное мнение, что OAuth является расширением протокола OpenID. На самом деле это не так. Хотя OpenID и OAuth имеют много общего, последний является самостоятельным протоколом, никак не связанным с OpenID.

Метка времени и Nonce

Чтобы предотвратить угрозу запросов повторного использования, OAuth используется nonce и метку времени . Термин «nonce» означает что, данное время используется один раз и является уникальным случайным набором букв и цифр, который предназначен для уникальной идентификации каждого подписанного запроса. Имея уникальный идентификатор для каждого запроса, поставщик услуг сможет помешать запросы повторного использования. Это означает, что клиент генерирует уникальную строку для каждого отправляемого на сервер запроса, а сервер отслеживает все использованные nonce для предотвращения их использования во второй раз.

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

Полномочия и токены

OAuth используется три вида полномочий: учетные данные клиента (consumer key and secret или client credentials), временные учетные данные (request token and secret или temporary credentials) и токены (access token and secret или token credentials).

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

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

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

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

Как работает OAuth

Схема работы протокола OAuth

Поясним работу протокола OAuth на примере . Допустим, что пользователь (владелец ресурсов) хочет распечатать свои фотографии (ресурсы), загруженные на сайт «photos.example.net» (сервер), при помощи сервиса печати «printer.example.net» (клиент).

1. Клиент посредством протокола HTTPS отправляет серверу запрос, который содержит идентификатор клиента, метку времени, адрес обратного вызова по которому нужно вернуть токен, используемый тип цифровой подписи и саму подпись.
2. Сервер подтверждает запрос и отвечает клиенту токеном доступа (Access Token) и частью разделённого секрета.
3. Клиент передает токен владельцу ресурсов (пользователю) и перенаправляет его на сервер для прохождения авторизации.
4. Сервер, получив от пользователя токен, запрашивает у него его логин и пароль, и в случае успешной аутентификации просит пользователя подтвердить доступ клиента к ресурсам (авторизация), после чего пользователь перенаправляется сервером к клиенту.
5. Клиент передает серверу токен посредством протокола TLS и запрашивает доступ к ресурсам.
6. Сервер подтверждает запрос и отвечает клиенту новым токеном доступа.
7. Используя новый токен, клиент обращается к серверу за ресурсами.
8. Сервер подтверждает запрос и предоставляет ресурсы.

Данный пример описывает поток с кодом подтверждения (Authorization Code Flow). Помимо этого в стандарте OAuth 2.0 описаны следующие потоки:

• Поток неявного доступа (Implicit Grant Flow)

Отличие от потока с кодом подтверждения заключается в том, что клиент не проходит аутентификацию на сервере и токен доступа выдается сервером после запроса авторизации.

• Поток с обновляемым токеном (Refreshing an Expired Access Token Flow)

Отличия данного потока от приведённого примера в следующем: на шаге 2 сервер помимо токена доступа, который имеет ограниченное время жизни, выдает токен обновления; на шаге 8 сервер проверяет, является ли токен доступа валидным (в смысле истечения времени жизни), и в зависимости от этого либо предоставляет доступ к ресурсам, либо требует обновления токена доступа (который предоставляется при предъявлении токена обновления).

• Поток с предоставлением клиенту пароля (Resource Owner Password Credentials Flow)

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

• Поток клиентских полномочий (Client Credentials Flow)

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

OAuth поддерживает два метода аутентификации сообщений от клиента: HMAC -SHA1 и RSA -SHA1 . Есть возможность передавать сообщения без подписи, тогда в поле типа подписи указывается «plain text ». Но в этом случае, согласно спецификации, соединение между клиентом и сервером должно устанавливаться через протокол SSL или TLS .

Порталы, использующие OAuth

Дискуссия

В июле 2012 года, Эран Хаммер (Eran Hammer), действующий редактор стандарта OAuth 2.0, объявил об уходе с поста после трех лет работы над новым стандартом, и попросил вычеркнуть своё имя из спецификаций. Он говорил о своих взглядах на своем сайте . Он позже выступил с докладом. .

Примечания

См. также

Ссылки

Wikimedia Foundation . 2010 .

Если вы пользуетесь Почтой Mail.Ru - можете не бояться за безопасность своих данных. Благодаря OAuth   — авторизации .

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

Что такое протокол OAuth ?

По статистике у каждого пользователя в среднем три почтовых ящика. Проверять их все, особенно, если они находятся на разных сайтах, не очень удобно. В Почте Mail.Ru вы можете настроить сбор писем из почтовых ящиков на других доменах ().

Почему использовать сборщик писем в Почте Mail.Ru безопасно?

Обычно при настройке сборщика нужно вводить имя, адрес ящика и пароль. Чтобы обеспечить защищенную передачу ваших данных, Почта Mail.Ru давно использует шифрование этих данных с помощью протоколов SSL . А чтобы избавить от необходимости передачи паролей, мы реализовали сбор писем с использованием OAuth . Этот протокол позволяет программе не запрашивать и не хранить логины и пароли .

Как это работает?

Допустим вы решили настроить сборщик писем с почты Яндекса в вашем почтовом ящике Mail.Ru. Благодаря протоколу OAuth Почта Mail.Ru не будет запрашивать ваш логин и пароль от почты Яндекс, а будет запрашивать только право на доступ .

Просто нажмите «Добавить ящик» и Почта получит доступ до тех пор, пока он не будет вами отозван.

Но мы о вашем пароле не узнаем.

Полезный совет!

И напоследок, если вы решили настроить сборщик писем с вашего ящика Mail.Ru на стороннем почтовом сервисе – убедитесь, что в нем используется протокол OAuth . Если нет, мы не рекомендуем вам рисковать безопасностью своих данных.

Надеемся, что эта статья была полезной для вас. Если у вас возникли вопросы - задавайте в комментариях.

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

Создание учетных данных OAuth2

Чтобы создать учетные данные OAuth2, выполните перечисленные ниже действия.

Определение типа приложения

Во-первых, нужно определить тип приложения , которое вы хотите создать. В AdWords API существует два типа приложений:

• устанавливаемое приложение (рекомендуется);
• веб-приложение.

С помощью приведенной ниже таблицы определите нужный тип приложения.

Что нужно выбрать	Ситуация
Устанавливаемое приложение (рекомендуется)	Вы управляете всеми аккаунтами AdWords с помощью одного управляющего аккаунта верхнего уровня. Вы только начинаете работу или хотите быстро приступить к работе. Ваше приложение будет работать с одним набором аккаунтов AdWords с несколькими пользователями.
Веб-приложение	Вы хотите осуществлять аутентификацию, чтобы предоставлять разным пользователям разные права доступа к данным аккаунта AdWords. Вам требуется создавать несколько наборов учетных данных, например для управления сторонними аккаунтами. Вашему приложению требуются URL обратного вызова, не поддерживаемые в устанавливаемых приложениях.

Внимание! Даже если вы разрабатываете веб-приложение, все равно можно выбрать устанавливаемое приложение. Основное различие состоит в том, нужно ли осуществлять обратный вызов после выдачи токена. Например, если вы используете один управляющий аккаунт верхнего уровня для управления всеми аккаунтами AdWords, устанавливаемое приложение необходимо зарегистрировать, даже если клиентское приложение доступно через Интернет. Примечание. рассматриваются ниже. Если вам не требуются функции сервисного аккаунта, мы настоятельно рекомендуем использовать процесс авторизации для устанавливаемого либо для веб-приложения.

Создание идентификатора и секретного кода клиента

Определив тип приложения, нажмите на соответствующую вкладку ниже и следуйте инструкциям по созданию идентификатора и секретного кода клиента.

Устанавливаемое приложение

1. Откройте
2. Создать проект Создать .
3. Создать учетные данные , а затем – Идентификатор клиента OAuth .
4. Сохранить
5. В разделе Тип приложения выберите Другие типы и укажите необходимую информацию.
6. Нажмите Создать .
7. идентификатор и секретный ключ

Веб-приложение

1. Откройте
2. В раскрывающемся меню проектов выберите Создать проект , затем укажите название проекта и при необходимости измените его идентификатор, после чего нажмите кнопку Создать .
3. На странице "Учетные данные" выберите Создать учетные данные , а затем – Идентификатор клиента OAuth .
4. Вам может быть предложено указать название продукта. В этом случае нажмите Настроить окно запроса доступа , укажите запрашиваемую информацию и нажмите Сохранить , чтобы вернуться к экрану "Учетные данные".
5. В разделе Тип приложения выберите Веб-приложение . Следуя инструкциям, укажите источники JavaScript и/или URI перенаправления.
6. Нажмите Создать .
7. На появившейся странице скопируйте идентификатор и секретный ключ клиента – они понадобятся вам при настройке клиентской библиотеки.

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

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

OAuth2 Playground

Альтернативный вариант создания учетных данных OAuth2 состоит в использовании OAuth2 Playground . В сочетании с Google API Console эта система позволяет самостоятельно создавать токены OAuth2.

Система OAuth2 Playground предназначена для тех пользователей, которым нужен доступ к аккаунтам только для одного управляющего аккаунта или пользователя AdWords. Если вам необходимо запрашивать учетные данные для нескольких пользователей, тогда лучше использовать клиентские библиотеки, как описано выше.

Настройка

Предупреждение. Чтобы использовать OAuth2 Playground , вам необходимо создать идентификатор клиента для . Это единственный тип приложений, работающий с OAuth2 Playground. Подробнее читайте в разделе выше.

Как получить идентификатор и секретный ключ клиента

1. Откройте
2. В раскрывающемся меню выберите существующий проект или создайте новый.
3. На странице "Учетные данные" выберите Создать учетные данные , а затем – Идентификатор клиента OAuth .
4. В разделе Тип приложения выберите Веб-приложение .
5. В разделе добавьте следующую строку: https://сайт/oauthplayground
6. Нажмите Создать .
7. Запишите идентификатор и секретный ключ клиента, указанные на появившейся странице. Они понадобятся вам на следующем шаге.

Как создать токены

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

Как убрать OAuth2 Playground из идентификатора клиента

Поскольку у вас уже есть токен обновления , вам больше не нужно использовать OAuth2 Playground в качестве разрешенного URI перенаправления. Чтобы удалить эту систему из списка, выполните следующие действия:

1. Перейдите на .
2. В раскрывающемся меню выберите свой проект.
3. На странице "Учетные данные" выберите название идентификатора клиента.
4. Удалите https://сайт/oauthplayground в поле Разрешенные URI перенаправления . Обратите внимание, что необходимо оставить хотя бы один URI перенаправления.
5. Нажмите Сохранить .

Итак, у вас есть учетные данные OAuth. Теперь можно осуществлять запросы AdWords API и использовать для требуемой клиентской библиотеки.

Сервисные аккаунты OAuth2

В этом разделе описывается порядок доступа к AdWords API с использованием сервисных аккаунтов.

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

AdWords API разрешает доступ сервисного аккаунта через домены G Suite .

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

Применение сервисных аккаунтов дает два существенных преимущества:

• Авторизация доступа приложения к API Google осуществляется на этапе настройки. Это позволяет избежать трудностей, связанных с необходимостью вмешательства пользователя или кеширования токенов в других потоках OAuth2.
• Олицетворение других пользователей в приложении при необходимости осуществляется в рамках процесса утверждения OAuth2.

Примечание. Если вы не используете специальные функции домена , например олицетворение, вместо сервисных аккаунтов настоятельно рекомендуется применять процесс для . В рамках процессов для устанавливаемых и веб-приложений OAuth2 участие пользователя требуется лишь однажды – в момент предоставления доступа к аккаунту.

Альтернатива сервисным аккаунтам

Сервисные аккаунты широко применяются для обеспечения программного доступа к API по протоколу OAuth2 без вмешательства пользователя.

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

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

Требования

• Принадлежащий вам домен G Suite , например mydomain.com или mybusiness.com.
• Токен разработчика AdWords API и желательно тестовый аккаунт.
• для используемого языка.

Настройка доступа для клиентского аккаунта

Во-первых, необходимо создать ключ служебного аккаунта в Google API Console.

1. Войдите в аккаунт G Suite, откройте .
2. В раскрывающемся меню проектов выберите Создать проект , затем укажите требуемую информацию и нажмите кнопку Создать . Новый проект появится в списке активных.
3. В меню в левом верхнем углу выберите IAM и администрирование , а затем – Сервисные аккаунты в меню слева.
4. Нажмите Создать сервисный аккаунт вверху страницы.
5. Укажите название сервисного аккаунта.
6. Установите флажок Создать новый закрытый ключ и выберите тип ключа JSON.
7. Установите флажок Включить делегирование доступа к данным в домене G Suite и укажите название продукта для окна запроса доступа.
8. Нажмите Создать . Запустится скачивание файла ключа JSON. Сохраните файл в надежном месте, куда только у вас есть доступ.
9. На странице Сервисные аккаунты появится новый сервисный аккаунт.

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

Проблемы безопасности

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

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

Как предоставить возможности олицетворения

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

Теперь вы можете осуществлять доступ к аккаунту AdWords с использованием сервисного аккаунта в рамках процесса утверждения OAuth2.

Настройка клиентской библиотеки

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

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

Оптимизация запросов OAuth2

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

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

Внимание! Под термином учетные данные здесь понимается вся совокупность атрибутов учетных данных OAuth2, включая токен доступа и его срок действия.

Стратегии распределения учетных данных

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

Стратегия распределения учетных данных зависит от структуры приложения.

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

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

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

Ниже описаны стратегии для аутентификации одного аккаунта AdWords, например управляющего аккаунта верхнего уровня в иерархии.

Затем описывается, как адаптировать эти стратегии для .

Многопоточные приложения

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

На этой схеме показаны потоки, передающие запросы в AdWords API во время выполнения. Применяется общий пул сеансов (пользователей). Обратите внимание, что каждый сеанс должен использовать один и тот же объект учетных данных. В ответ на каждый запрос API поток получает соответствующий сеанс (пользователя). Если требуется обновить токен доступа, это нужно делать синхронно, чтобы исключить состояние гонки. Другими словами, объект учетных данных должен быть потокобезопасным.

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

Например, в клиентской библиотеке Java нужно создать одноэлементный класс Credential и использовать его для всех сеансов.

Многопроцессные и распределенные приложения

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

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

На схеме показано периодическое обновление учетных данных и запись их свойств в хранилище данных. Затем все серверы получают учетные данные, прежде чем осуществлять запрос к API.

Задача обновления

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

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

Примечание. Если срок действия токена доступа учетных данных истечет во время обработки запроса API, этот запрос все равно будет выполнен. Например, если вы создали долго выполняемый запрос и для доступа остается меньше минуты, результаты все равно будут возвращены.

Хранилище данных

Хранилище данных используется для предоставления учетных данных разным процессам и серверам.

Для этого можно использовать существующее хранилище данных или создать специализированное, через которое серверы будут получать учетные данные. В качестве возможных решений можно использовать серверы кеширования (например, Memcached или Infinispan) и хранилища данных NoSQL (например, MongoDB).

Основная задача хранилища данных – обеспечивать надежный интерфейс для всех серверов, обращающихся к API. Его работу необходимо оптимизировать для быстрого чтения данных: серверы и процессы будут считывать учетные данные чаще, чем они будут обновляться.

Помните, что учетные данные нужно хранить в защищенном виде .

При сохранении учетных данных необходимо сохранять свойство expiry_time (текущее время + expires_in) и refresh_token вместе со свойством access_token . Свойство expiry_time (окончание действия токена) рассчитывается по такой формуле: время запроса на обновление access_token + время expires_in (срок действия токена).

Пул серверов

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

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

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

Аутентификация нескольких аккаунтов

Учетные данные, созданные для управляющего аккаунта AdWords, можно использовать для доступа ко всем дочерним аккаунтам. Пользователям с одним управляющим аккаунтом, как правило, достаточно создать учетные данные для управляющего аккаунта верхнего уровня, чтобы авторизовать приложение для всех подчиненных аккаунтов AdWords.

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

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

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

Принцип работы OAuth2

Примечание . AdWords API пока не поддерживает одновременный вход с помощью запроса на доступ к данным (гибридная схема) или делегирование полномочий на уровне домена (2LO).

Область действия

Токен доступа может предоставлять разную степень доступа к данным. Изменяемый параметр scope (область действия) определяет набор ресурсов и операций, к которым токен предоставляет доступ. Во время запроса токена доступа ваше приложение отправляет в параметр scope одно или несколько значений.

Ниже представлены текущая и устаревшая область действия для AdWords API.

Автономный доступ

Клиентское приложение, использующее AdWords API, обычно запрашивает автономный доступ. Это может произойти в том случае, если приложению необходимо запустить пакетные задания, когда пользователь просматривает ваш сайт без подключения к Интернету.

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

Заголовок запроса HTTP

Заголовок HTTP в каждом запросе к серверу AdWords API должен включать в такой форме:

Authorization: Bearer THE_ACCESS_TOKEN

POST … HTTP/1.1 Host: … Authorization: Bearer 1/fFAGRNJru1FTz70BzhT3Zg Content-Type: text/xml;charset=UTF-8 Content-Length: … …

Токены доступа и обновления

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

Когда истекает срок действия токена доступа

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

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our . Java is a registered trademark of Oracle and/or its affiliates.

Обновлено Сентябрь 24, 2018