Руководство по OAuth 2

Фреймворк OAuth 2 предназначен для ограничения доступа к личным кабинетам, заведенным на ресурсах HTTP. Типичные примеры реализации – DigitalOcean, GitHub, Facebook. Его работа основана на делегировании процесса аутентификации серверу, где расположен аккаунт. Такой подход позволяет запрашивать доступ из сторонних приложений. Например, для регистрации за счет подстановки учетных данных.

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

Роли OAuth

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

Владелец ресурса

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

Сервер (ресурсы, авторизация)

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

Оба серверы логически объединены в единую систему. Именно так их видят внешние сервисы по интерфейсу API. Поэтому мы объединим понятия ресурсного и авторизационного сервера, дадим им единое название: «Сервис», API.

Клиент (приложение)

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

Кратко опишем протокол

Мы провели обзор ролей OAuth 2, теперь рассмотрим открытый протокол авторизации, схему обмена информацией. Для этого приведем перечень (последовательность) типовых операций.

Варианты:

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

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

Зарегистрируем приложение

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

1. Наименование программы.
2. Сайт, на котором она развернута.
3. Callback URL (Redirect URL).

Третий пункт – это ссылка на страницу, которую сервис будет открывать при отказе в доступе (или после успешной авторизации).

Об идентификации клиента

При регистрации приложения будут созданные учетные данные пользователя – это идентификатор Client ID и секрет клиента Client Secret. Первый представляет собой публичную строку, которую использует интерфейс API для определения достоверности программы. И для генерации отдельных URL, куда направляются авторизованные пользователи. Секрет используют при аутентификации в API, поэтому он открыт только интерфейсу и программе.

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

Система OAuth 2 предполагает четыре варианта запроса авторизации исходя из ситуации:

1. Authorization Code (код авторизации) – применяют на серверных приложениях.
2. Implicit (неявный) – подходит для мобильных приложений, включая их веб-версии.
3. Resource Owner Password Credentials (учетные данные владельца) – включают в доверенные программы, например, являющиеся единым целым с онлайн-сервисом.
4. Client Credentials (учетные данные клиента) – необходим для работы через API.

Теперь рассмотрим варианты подробнее.

Тип «Код авторизации»

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

Этап 1. Формируем ссылку с кодом авторизации

Предоставим пользователю ссылку:

https://cloud.example.com/v1/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=CALLBACK_URL&scope=read

Ссылка состоит из компонентов:

• https://cloud.example.com/v1/oauth/authorize – это точка входа для авторизации через API;
• client_id – идентификатор, при помощи которого сервис понимает, что за приложение отправило запрос на API;
• redirect_uri – ссылка, куда система перенаправит браузер пользователя после получения кода авторизации;
• response_type=code – отражает тип обращения, приложение запросило доступ при помощи ввода авторизационного кода;
• scope=read – задаем доступ только для чтения данных.

Этап 2. Происходит авторизация

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

Этап 3. Передаем код авторизации приложению

При выборе варианта «Авторизовать приложение» система перенаправит браузер по ссылке, какую мы внесли на шаге регистрации пользователя. Ссылка будет выглядеть так:

https://example.com/callback?code=AUTHORIZATION_CODE

Этап 4. Получим от приложения запрос токена доступа

Программа отправляет на сервер код авторизации и информацию для аутентификации, включая секрет клиента. Пример POST-запроса:

https://cloud.example.com/v1/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=CALLBACK_URL

Этап 5. Передача токена доступа приложению

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

{"access_token":"ACCESS_TOKEN","token_type":"bearer","expires_in":2592000,"refresh_token":"REFRESH_TOKEN","scope":"read","uid":100101,"info":{"name":"User","email":"info@example.com"}}

Все, программа подключилась к серверу.

Тип «Неявный»

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

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

Этап 1. Сформируем ссылку авторизации

Сервис авторизации предлагает ссылку (сначала ее запрашивают через API на сервере). Ее вид схож с предыдущим вариантом всего с одним исключением – вместо кода система запрашивает токен.

https://cloud.example.com/v1/oauth/authorize?response_type=token&client_id=CLIENT_ID&redirect_uri=CALLBACK_URL&scope=read

Этап 2. Запрашиваем авторизацию пользователя

Первое, что должен сделать пользователь после нажатия ссылки – это произвести вход в систему, чтобы подтвердить личность (при первом входе, если данные ранее не были сохранены). Исходя из корректности введенных данных сервер либо подтверждает вход, либо возвращает отказ.

Этап 3. Передаем токен доступа браузеру (пользовательскому агенту)

Выбор пункта «Авторизовать приложение» вызывает функцию перенаправления с применением токена доступа. Это выглядит так:

https://example.com/callback#token=ACCESS_TOKEN

Этап 4. Переходим по пути перенаправления

Браузер пользователя (или иной пользовательский агент) автоматически переходит по указанному пути, в процессе происходит сохранение токена доступа.

Этап 5. Извлечем токен доступа

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

Этап 6. Передадим токен доступа приложению

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

Тип «Учетные данные владельца ресурса»

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

Процесс авторизации

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

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

При корректности введенных данных сервер автоматически возвращает запрошенный токен. Все, процедура авторизации завершена.

Тип «Учетные данные клиента»

Вариант подразумевает открытие доступа к собственным ресурсам сервиса после ввода корректных логина-пароля. Это иногда необходимо, например, для обновления регистрационной информации или организации доступа к иным данным, размещенным на сервере.

Процесс авторизации

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

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

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

Практический пример

После получения токена доступа программа может обращаться к аккаунту по API с учетом запретов вроде «только для чтения». Такая возможность доступна вплоть до истечения срока действия или запроса на отзыв токена. Приведем пример обращения по API с применением curl:

curl -X POST -H "Authorization: Bearer ACCESS_TOKEN""https://api.example.com/v2/$OBJECT"

При наличии достоверного токена API проведет обработку направленного запроса. При ошибке, например из-за просрочки или повреждения файла, интерфейс вернет сообщение об ошибке Invalid Request.

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

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

https://cloud.example.com/v1/oauth/token?grant_type=refresh_token&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&refresh_token=REFRESH_TOKEN

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

Выводы

Мы завершили рассмотрение способов, как использовать OAuth в приложениях в зависимости от их особенностей. Теперь пользователь имеет представление, каким образом осуществляется доступ к удаленным сервисам, какие детали необходимо учитывать при выборе метода обращения к серверу. В качестве тестовой площадки можно использовать облачные ресурсы провайдера Timeweb Cloud.

Кстати, в официальном канале Timeweb Cloud собрали комьюнити из специалистов, которые говорят про IT-тренды, делятся полезными инструкциями и даже приглашают к себе работать.