​Заботясь о своих клиентах, команда сервиса Invola реализовала прямое подключение к почте по технологии OAuth 2.0.

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

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

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

Что такое OAuth?

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

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

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

В коммуникации между Invola и почтовым сервером используется токен доступа access token (шаг 4-5), который автоматически устаревает через час и обновляется по необходимости (автоматически, без участия пользователя, программным обеспечением Invola).

Теперь поговорим о безопасности, и почему авторизация по OAuth предпочтительнее, чем по логину-паролю .

Когда вы предоставляете любому сервису логин и пароль для доступа к аккаунту (mail.ru, gmail.com), вы фактически предоставляете пароль от всей учетной записи (таким образом можно получить доступ, например, к диску, фотоальбомам и другим личным данным).

Предоставляя доступ через OAuth вы сами выбираете, к каким ресурсам аккаунта вы даете доступ . То есть, пользователь сам контролирует к каким ресурсам он готов дать доступ. Рассмотрим пример запрашиваемых прав при подключении к Invola:

"Просмотр и управление почтой " - для автоматического получения счетов и КП, "просмотр адреса " – для получения e-mail ящика, "просмотр профиля " – для получения имени пользователя (требуется на этапе регистрации).

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

Немного о безопасности .

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

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

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

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

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

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.

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

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

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

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

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

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

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

Стоит отметить, что, хотя стандарт 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)

• Поток с предоставлением клиенту пароля (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 .

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

Эта статья предназначена для разработчиков приложений и предоставляет обзор ролей, типов авторизации и типичных сценариев использования OAuth 2.

Начнём с ролей OAuth!

Роли OAuth

OAuth определяет четыре роли:

• Владелец ресурса
• Клиент
• Сервер ресурсов
• Авторизационный сервер

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

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

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

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

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

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

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

Теперь, когда у нас есть представление о ролях, используемых в OAuth, рассмотрим диаграмму их взаимодействия друг с другом.

Рассмотрим описание последовательности шагов на этой диаграмме:

1. Приложение запрашивает у пользователя авторизацию на доступ к серверу ресурсов.
2. Если пользователь авторизует запрос, приложение получает разрешение на авторизацию (authorization grant).
3. Приложение запрашивает авторизационный токен у сервера авторизации (API) путём предоставления информации о самом себе и разрешении на авторизацию от пользователя.
4. Если подлинность приложения подтверждена и разрешение на авторизацию действительно, сервер авторизации (API) создаёт токен доступа для приложения. Процесс авторизации завершён.
5. Приложение запрашивает ресурс у сервера ресурсов (API), предоставляя при этом токен доступа для аутентификации.
6. Если токен действителен, сервер ресурсов (API) предоставляет запрашиваемый ресурс приложению .

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

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

Перед тем, как начать использовать OAuth в вашем приложении, вам необходимо зарегистрировать своё приложения в сервисе. Это делается путём регистрации в разделе "developer" или "API" сайта сервиса, где вам необходимо предоставить следующую информацию (возможно, включая некоторые детали о вашем приложении):

• Название приложения
• Сайт приложения
• Redirect URL или callback URL

Redirect URL - это URL, на который сервис будет перенаправлять пользователя после авторизации (или отказа в авторизации) вашего приложения.

Идентификатор клиента и секрет клиента

После регистрации приложения сервис создаст учётные данные клиента - идентификатор клиента (client ID) и секрет клиента (client secret). Идентификатор клиента представляет собой публично доступную строку, которая используется API сервиса для идентификации приложения, а также используется для создания авторизационных URL для пользователей. Секрет клиента используется для аутентификации подлинности приложения для API сервиса, когда приложение запрашивает доступ к аккаунту пользователя. Секрет клиента должен быть известен только приложению и API.

Разрешение на авторизацию

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

• Код авторизации (Authorization Code) : используется с серверными приложениями (server-side applications).
• Неявный (Implicit) : используется мобильными или веб-приложениями (приложения, работающие на устройстве пользователя).
• Учётные данные владельца ресурса (Resource Owner Password Credentials) : используются доверенными приложениями, например приложениями, которые являются частью самого сервиса.
• Учётные данные клиента (Client Credentials) : используются при доступе приложения к API.

Тип разрешения на авторизацию: Код авторизации

Код авторизации является одним из наиболее распространённых типов разрешения на авторизацию, поскольку он хорошо подходит для серверных приложений , где исходный код приложения и секрет клиента не доступны посторонним. Процесс в данном случае строится на перенаправлении (redirection), что означает, что приложение должно быть в состоянии взаимодействовать с пользовательским агентом (user-agent), например, веб-браузером, и получать коды авторизации API, перенаправляемые через пользовательский агент.

Опишем процесс на диаграмме:

Шаг 1: Ссылка с кодом авторизации

• https://cloud.?response_type=code&client_id=CLIENT_ID &redirect_uri=CALLBACK_URL &scope=read

• : входная точка API авторизации (API authorization endpoint).
• client_id= CLIENT_ID : идентификатор клиента приложения (с помощью этого идентификатора API понимает, какое приложение запрашивает доступ).
• redirect_uri= CALLBACK_URL : URL, на который сервис перенаправит пользовательского агент (браузер) после выдачи авторизационного кода.
• response_type=code : указывает на то, что приложение запрашивает доступ с помощью кода авторизации.
• scope=read : задаёт уровень доступа приложения (в данном случае - доступ на чтение).

Шаг 3: Приложение получает код авторизации

Если пользователь выбирает "Авторизовать приложение", сервис перенаправляет пользовательский агент (браузер) по URL перенаправления (redirect URL), который был задан на этапе регистрации клиента (вместе с кодом авторизации ). Ссылка будет выглядеть похожим образом (в данном примере приложение называется "dropletbook.com"):

• https://dropletbook.com/callback?code=AUTHORIZATION_CODE

Шаг 4: Приложение запрашивает токен доступа

Приложение запрашивает токен доступа у API путём отправки авторизационного кода и аутентификационной информации (включая секрет клиента ) сервису. Ниже представлен пример POST-запроса для получения токена DigitalOcean:

• https://cloud.?client_id=CLIENT_ID &client_secret=CLIENT_SECRET &grant_type=authorization_code&code=AUTHORIZATION_CODE &redirect_uri=CALLBACK_URL

Шаг 5: Приложение получает токен доступа

• {"access_token":"ACCESS_TOKEN ","token_type":"bearer","expires_in":2592000,"refresh_token":"REFRESH_TOKEN ","scope":"read","uid":100101,"info":{"name":"Mark E. Mark","email":"[email protected]"}}

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

Тип разрешения на авторизацию: Неявный

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

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

Шаг 1: Ссылка для неявной авторизации

При неявном типа разрешения на авторизацию пользователю предоставляется ссылка, запрашивающая токен у API. Эта ссылка выглядит почти так же, как ссылка для предыдущего способа (с кодом авторизации), за исключением того, что запрашивается токен вместо кода (обратите внимание на response type "token"):

• https://cloud.?response_type=token&client_id=CLIENT_ID &redirect_uri=CALLBACK_URL &scope=read

Шаг 2: Пользователь авторизует приложение

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

Шаг 3: Пользовательский агент получает токен доступа с URI перенаправления

• https://dropletbook.com/callback#token=ACCESS_TOKEN

Шаг 4: Пользовательский агент следует по URI перенаправления

Пользовательский агент следует по URI перенаправления, сохраняя при этом токен доступа.

Шаг 5: Приложение выполняет скрипт извлечения токена доступа

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

Шаг 6: Токен доступа передаётся приложению

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

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

Тип разрешения на авторизацию: учётные данные владельца ресурса

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

Процесс с учётными данными владельца ресурса

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

• https://oauth.example.com/token?grant_type=password&username=USERNAME &password=PASSWORD &client_id=CLIENT_ID

Внимание: DigitalOcean в настоящее время не поддерживает тип разрешения на авторизацию с использованием учётных данных владельца ресурса, поэтому ссылка выше ведёт на воображаемый авторизационный сервер "oauth.example.com".

Тип разрешения на авторизацию: Учётные данные клиента

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

Процесс с учётными данными клиента

Приложение запрашивает токен доступа путём отправки своих учётных данных, своего идентификатора клиента и секрета клиента авторизационному серверу. Пример POST-запроса может выглядеть следующим образом:

• https://oauth.example.com/token?grant_type=client_credentials&client_id=CLIENT_ID &client_secret=CLIENT_SECRET

Внимание: DigitalOcean в настоящее время не поддерживает тип разрешения на авторизацию с использованием учётных данных клиента, поэтому ссылка выше ведёт на воображаемый авторизационный сервер "oauth.example.com".

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

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

Ниже представлен пример запроса к API с использованием curl . Обратите внимание, что он содержит токен доступа:

• curl -X POST -H "Authorization: Bearer ACCESS_TOKEN ""https://api.сайт/v2/$OBJECT "

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

Обновление токена доступа

После истечения срока действия токена доступа все запросы к API с его использованием будут возвращать ошибку "Invalid Token Error". Если при создании токена доступа был создан и токен для обновления токена доступа (refresh token), последний может быть использован для получения нового токена доступа от авторизационного сервера.

Ниже представлен пример POST-запроса, использующего токен для обновления токена доступа для получения нового токена доступа:

• https://cloud.?grant_type=refresh_token&client_id=CLIENT_ID &client_secret=CLIENT_SECRET &refresh_token=REFRESH_TOKEN

Заключение

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

Если вы хотите узнать больше об OAuth 2, рекомендуем ознакомиться со следующими статьями.

Шаг 1. Регистрация сайта

Переходим по ссылке http://api.mail.ru/sites/my/add и регистрируем наш сайт. Далее скачиваем и заливаем на ftp файл receiver.html, который нужен для верификации нашего сайта.
После регистрации нам выдадут 3 параметра:

• Приватный ключ
• Секретный ключ

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

$APP_ID; $APP_SECRET;

Шаг 2. Получение Code

Для получения Code нужно обратиться по адресу connect.mail.ru/oauth/authorize , передав ему $_GET параметры:

• client_id - ID сайта
• response_type - 3 варианта на выбор. token - доступ к API будет предоставлен только через javascript, code_and_token - доступ к API через сервер и javascript, code - доступ к API через сервер. В нашем случае это будет code .
• redirect_uri - Адрес страницы получения response_type
• scope - Привилегии приложения. Параметр необязателен для заполнения и в нашем случае избыточен. Если вы решили запросить привилегии, то учтите, что далеко не все пользователи захотят передать вам их приватные данные, поэтому просто для авторизации параметр scope использовать не надо.

Для удобства разделим логику генерации ссылки на получение code и его обработки:
example.com/login.php - генерируем ссылку для получения code (по-сути ссылка для авторизации).
example.com/auth.php - обработка code.

Итоговый запрос будет выглядеть так:

$redirect_uri = urlencode("http://example.com/auth.php"); $login_url = "https://connect.mail.ru/oauth/authorize?client_id={$APP_ID}&response_type=code&redirect_uri={$redirect_uri}";

Перейдя по этому адресу неавторизованный на Mail.ru пользователь увидит:

Если пользователь авторизован на Mail.ru, то он увидит такое же окно, но без ввода логина и пароля.
Теперь у пользователя 2 варианта действий: разрешить и запретить. Запретив, пользователь будет перенаправлен на страницу указанную в redirect_uri с указанием ошибки.

Если всё прошло как надо и пользователь разрешил сайту доступ к своим данным, то пользователь будет перенаправлен на страницу redirect_uri (http://example.com/auth.php), с $_GET параметром code.
Сохраним его под именем

$APP_CODE;

Шаг 3. Получение token и uid

Для этого надо обратиться по адресу connect.mail.ru/oauth/token , передав ему параметры:

• client_id ($APP_ID)
• client_secret ($APP_SECRET)
• grant_type (authorization_code)
• code ($APP_CODE)
• redirect_uri ($redirect_uri из шага 2)

Все параметры обязательтны. redirect_uri должен точно совпадать с тем, который мы использовали на 2-ом шаге.

Запрос на получения token может быть выполнен только через POST запрос, поэтому cURL в помощь:

$ch = curl_init(); $url = "https://connect.mail.ru/oauth/token"; $fields = Array("client_id" => $APP_ID, "client_secret" => $APP_SECRET, "grant_type" => "authorization_code", "code" => $APP_CODE, "redirect_uri" => urlencode(redirect_uri)); foreach($fields as $key => $value){ $fields_string .= $key . "=" . $value . "&"; } rtrim($fields_string, "&"); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $fields_string); $result = curl_exec($ch); curl_close($ch); $arr = json_decode($result, true); //или $arr = (array) json_decode($result). Кстати кто-нибудь знает, есть ли разница? $token = $arr["access_token"]; $uid = $arr["x_mailru_vid"];

Шаг 4. Получаем пользовательские данные

После получения token и uid сайт получает долгожданный доступ к API Mail.ru по адресу www.appsmail.ru/platform/api .
Но не всё так просто, каждый запрос к API должен быть подписан. Подпись (в нашем случае) представляет собой хэш, рассчитанный по алгоритму md5 из отсортированной в алфавитном порядке строки из передаваемых API параметров без разделителя & и Секретного ключа .
Например:

Md5("app_id=423004method=friends.getsession_key=be6ef89965d58e56decdfacb9b62bdaa" . $APP_SECRET);

Mail.ru предусматривает 2 варианта подписи: клиент-сервер и сервер-сервер. Отличие заключается в большей безопасности 2-го подхода. Его мы и будем использовать. Для этого в запросе к API надо указывать secure=1 .

Выполним запрос на получение анкетной информации пользователя Mail.ru, воспользовавшись методом users.getInfo .

$request_params = Array("app_id" => $APP_ID, "uids" => $uid, "method" => "users.getInfo", "secure" => 1, "session_key" => $token); //Параметры обязательно должны быть отсортированы в алфавитном порядке ksort($request_params); $params = ""; foreach ($request_params as $key => $value) { $params .= "$key=$value"; } //В модели сервер-сервер подпись выглядит так $sig = md5($params . $APP_SECRET); //Формируем запрос $url = "http://www.appsmail.ru/platform/api?method=users.getInfo&app_id={$APP_ID}&session_key={$token}&sig={$sig}&uids={$uid}&secure=1"; $response = file_get_contents($url); $info = (array) json_decode($response); $info = $info; //весь результат print_r($info);

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

PROFIT!!1 Всем добра. Если статья окажется интересной, то могу так же разобрать процесс серверной oAuth 2.0 авторизации для Vkontakte и Facebook.