ORDS — security & API specifications Александр Шишков Руководитель отдела разработки CUSTIS

План • Способы передачи параметров запросов • Подходы в версионировании API • Описание REST-сервиса через Swagger • SSL-сертификация • Виды аутентификации в ORDS

Способы передачи параметров запроса

Способы передачи параметров запроса • Через URI (в имени сервиса) • Параметры объявляются на уровне определения rest-сервиса (ORDS.define_template): http://host:/ords/schema_alias/module/template/val1/val2 В URI указываются только значения параметров, порядок строго фиксирован, параметры обязательные • Через URI (в строке параметров) • Параметры объявляются через отдельный обработчик (ORDS.define_parameter): http://host:/ords/...?p1=val1&p2=val2 В URI указываются в конце строки запроса URI в стандартном виде, параметры не обязательные • Параметры используются без их предварительного объявления (актуально только для GET-запросов с источником в виде SQL-запроса) http://host:/ords/...?q=json_query В URI указываются в конце строки запроса в виде JSON-строки: {"p1":{"$oper":"val1"}, "p2":{"$oper":val2}}

Способы передачи параметров запроса Через URI (в имени сервиса)

Способы передачи параметров запроса Через URI (в имени сервиса)

Способы передачи параметров запроса Через URI (в строке параметров)

Способы передачи параметров запроса Через URI (в строке параметров)

Способы передачи параметров запроса Через URI (в строке параметров)

Способы передачи параметров запроса Через URI (в строке параметров, только для фильтрации ResultSet)

Способы передачи параметров запроса Через URI (в строке параметров, только для фильтрации ResultSet) • Используется только в GET-запросах с любым типом источника, кроме plsql/block • В качестве параметров можно использовать только атрибуты из результирующего набора (те, что перечислены в блоке SELECT указанного набора) • Большое количество операторов сравнения, например: ">" : "$gt" ">=" : "$gte" "=" : "$eq" "=" : "$ne" "<" : "$lt" "<=" : "$lte" "is null" : "$null" "is not null" : "$notnull" «like" : "$like" “between" : "$between" • JSON-строка вида {"p1":{"$eq":"val1"}, "p2":{"$qte":val2}} преобразуется в SQL-запрос:

Способы передачи параметров запроса

Способы передачи параметров запроса Через Header • Могут быть как входными, так и выходными • По умолчанию являются необязательными • Параметры задаются в заголовке запроса в виде: p1: val1 p2: val2

Способы передачи параметров запроса Через Header (пример реализации)

Способы передачи параметров запроса Через Header (пример реализации)

Способы передачи параметров запроса Через Header (пример реализации)

Способы передачи параметров запроса Через Header (пример реализации)

Способы передачи параметров запроса CGI variables • Полный список CGI-переменных среды можно вывести в тело запроса при помощи метода OWA_UTIL.print_cgi_env • В CGI- переменной QUERY_STRING можно достать параметры из URI, указанные после знака ? (+): не нужно отдельно объявлять каждый параметр (ORDS.define_parameter) и обращаться к нему через отдельную bind-переменную (-): подходит только для запросов, у которых в качестве обработчика используется pl/sql-блок (-): придется вручную парсить строку параметров вызова для их извлечения • Содержимое CGI-переменной CONTENT_TYPE дублирует содержимое bind-переменной :content_type

Подходы в версионировании API

Подходы в версионировании API Be liberal in what you accept, and conservative in what you send.

Подходы в версионировании API • Либеральный подход потребителя: используйте только те поля в данных, которые вам нужны, не используйте лишнего • Либеральный подход отправителя: при редактировании API придерживайтесь правила обратной совместимости, чтобы потребитель смог работать с новой версией без доработок на своей стороне Было Стало Пример принципа надежности Постела на практике

Подходы в версионировании API Использование разных URI (версия указана в имени сервиса) Response Response Было Стало

Подходы в версионировании API Использование разных URI (версия указана в имени сервиса) • В ORDS при создании новой версии REST-сервиса придется «копипастить» обвязку (template->handler->parameter) и править код pl/sql-блока (или sql-запроса), выступающего в роли обработчика • Технически данный подход противоречит архитектурному стилю RESTful, т.к. ссылка на ресурс меняется • Пользователи могут исполнять GET-запросы с поддержкой версионности в любом браузере • Легко документировать API с учетом его версионности

Подходы в версионировании API Использование разных URI (версия указана в строке параметров) Response Response Было Стало

Подходы в версионировании API Использование разных URI (версия указана в строке параметров) • В ORDS при создании новой версии REST-сервиса потребуется только внести изменения в код pl/sql-блока (или sql-запроса), выступающего в роли обработчика для формирования ответа • Архитектурный стиль RESTful соблюдается • Пользователи могут исполнять GET-запросы с поддержкой версионности в любом браузере • Многие PHP-фреймворки игнорируют строку запроса, отправленную любым способом, кроме GET • Сложнее документировать API с версионностью на основе использования параметра запроса

Подходы в версионировании API Использование кастомного заголовка запроса Response Response Было Стало

Подходы в версионировании API Использование кастомного заголовка запроса • В ORDS при создании новой версии REST-сервиса потребуется только внести изменения в код pl/sql-блока (или sql-запроса), выступающего в роли обработчика для формирования ответа • Архитектурный стиль RESTful соблюдается • Пользователи НЕ могут исполнять GET-запросы с поддержкой версионности в любом браузере • Системы кеширования могут запутаться • Разработчики системы-потребителя API могут запутаться (если они не знают про ваши заголовки) • Сложнее документировать API с версионностью на основе использования заголовка запроса

Подходы в версионировании API • Использование заголовка запроса Accept Было: Стало: Response: Response:

Подходы в версионировании API Использование заголовка запроса Accept • В ORDS при создании новой версии REST-сервиса потребуется только внести изменения в код pl/sql-блока (или sql-запроса), выступающего в роли обработчика для формирования ответа • Архитектурный стиль RESTful соблюдается • Пользователи НЕ могут исполнять GET-запросы с поддержкой версионности в любом браузере • Кэш-совместимый • Разработчики системы-потребителя API могут запутаться (если они не знают про ваши заголовки) • Сложнее документировать API с версионностью на основе использования заголовка запроса

Описание REST-сервиса через Swagger

Описание REST-сервиса через Swagger Что такое Swagger • Swagger — это фреймворк для описания REST-сервиса и экосистема вокруг него с такими возможностями, как: • просмотр документации по веб-сервису в интерактивном режиме (с возможностью выполнять запросы) • онлайн-редактирование описания сервиса в режиме WYSIWYG • кодогенерация для серверного и клиентского кода • OpenApi specification (OAS) — это спецификация для определения REST-сервиса в формате, дружественном к пользователю и компьютеру (JSON или YAML). Текущая версия – 3.0

Описание REST-сервиса через Swagger ORDS и Swagger specification (OpenApi 2.0) • Начиная с версии 17.4 ORDS выполняет автогенерацию спецификации REST-сервисов / в формате OpenApi 2.0, доступную по следующей ссылке: шаблон: http(s)://server:port/ords///open-api-catalog/ пример: http(s)://localhost:8443/ords/test/open-api-catalog/ • Рассмотрим результат автогенерации на примере трех способов реализации REST API: • Manual Rest Service • Auto PL/SQL • AutoREST

Описание REST-сервиса через Swagger Manual Rest Service • На примере модуля monit, который создается в тестовых целях в рамках данной презентации • http://localhost:8888/ords/test/open-api-catalog/monit/

Описание REST-сервиса через Swagger Manual Rest Service • На примере модуля monit, который создается в тестовых целях в рамках данной презентации • После копирования ответа в swagger editor с онлайн преобразованием в YAML получаем • Рассмотрим результат автогенерации на примере 3-х способов реализации REST API: Manual Rest Service Auto PL/SQL AutoREST

Описание REST-сервиса через Swagger Manual Rest Service • На примере модуля monit, который создается в тестовых целях в рамках данной презентации

Описание REST-сервиса через Swagger Manual Rest Service • На примере модуля monit, который создается в тестовых целях в рамках данной презентации

Описание REST-сервиса через Swagger Manual Rest Service • На примере модуля monit, который создается в тестовых целях в рамках данной презентации

Описание REST-сервиса через Swagger AutoRest • На примере таблицы t_fix_rest_log, который создается в тестовых целях в рамках данной презентации

Описание REST-сервиса через Swagger AutoRest • На примере таблицы t_fix_rest_log, который создается в тестовых целях в рамках данной презентации

Описание REST-сервиса через Swagger AutoRest • На примере таблицы t_fix_rest_log, который создается в тестовых целях в рамках данной презентации

Описание REST-сервиса через Swagger Auto PL/SQL • На примере процедуры fix_rest_log, которая создается в тестовых целях в рамках данной презентации

Описание REST-сервиса через Swagger Auto PL/SQL • На примере процедуры fix_rest_log, которая создается в тестовых целях в рамках данной презентации

SSL-сертификация

SSL-сертификация в ORDS HTTPS и SSL • HTTPS — защищенный вариант протокола HTTP (данные передаются в зашифрованном виде) • SSL-протокол использует ассиметричный шифр с двумя видами ключей: • Публичный (для шифрования данных, используется при передачи данных) • Приватный (для расшифровки сообщения на сервере, он всегда остается на сервере) • SSL-сертификат необходим владельцу сайта, что он успешно обрабатывал передачу данных по HTTPS Доверенные и недоверенные сертификаты • Сертификат считается доверенным, если он выдан официальным удостоверяющим центром (Certification authority, CA) • Самоподписанные сертификаты (владелец сайта выдает себе сам), сертификаты с истекшим сроком годности или сертификаты, выданные центром, который потерял доверие считаются недоверенными. При переходе на такой сайт будет выдано соответствующее предупреждение

SSL- сертификация в ORDS Классификация SSL - сертификатов • По способу проверки платформы: • DV (domain validation) – подтверждение домена, доступен для физлиц и юрлиц • OV (organization validation) – проверка подлинности компании • EV (Extended Validation) – расширенная проверка деятельности компании (налоговая отчетность) • По количеству доменных и субдоменных имен: • WildCard SSL – защищает домен и поддомены, вплоть до 3-го уровня (shop.mos.example.ru) • MD (Multidomain, SAN) – защищает до 100 доменов (example1.ru, example2.ru, …) • IDN (Internationalized Domain Name) – для корректной защиты нацдоменов (пример.рф) • SGC (Server Gated Cryptography) – помогает повысить безопасность клиентов, использующих старые браузеры • SSL-сертификат необходим владельцу сайта, что он успешно обрабатывал передачу данных по HTTPS

SSL-сертификация в ORDS Auto SSL • ORDS автоматически создаст самоподписанный сертификат, если в файле standalone.properties внести следующие изменения: • Далее с помощью одной из утилит, например, openssl, переконвертировать файлы с приватным ключом и сертификатом в формат DER и в файле standalone.properties внести следующие изменения: • После выполнения этих шагов перезапустить сервис

SSL- сертификация в ORDS Доверенный сертификат (CA) • Достаточно убедиться, что сертификат и ключ лежат в формате DER и прописать путь к ним в файле standalone.properties • После выполнения этих шагов перезапустить сервис

Виды аутентификации в ORDS

Виды аутентификации в ORDS Basic Authentication • Простейший способ аутентификации, уже устарел, используется в основном во внутрикорпоративных сетях • Логин и пароль передаются в заголовке (Authorization) в незашифрованном виде в формате base64

Виды аутентификации в ORDS OAuth 2.0 • Открытая схема авторизации, которая позволяет третьей стороне предоставить ограниченный доступ к защищенным ресурсам пользователя без необходимости передавать ей логин и пароль • Общая схема приложения, использующего OAuth, такова: 1) получение авторизации (token) 2) обращение к защищенным ресурсам

Виды аутентификации в ORDS Basic Authentication - реализация Определить ORDS-роль • Дать ей привилегии (на модули, URI pattern) • Создать пользователя на уровне сервера приложений и ассоциировать его с ORDS-ролью

Виды аутентификации в ORDS Basic Authentication - реализация Определить ORDS-роль Дать ей привилегии (на модули, URI pattern) • Создать пользователя на уровне сервера приложений и ассоциировать его с ORDS-ролью

Виды аутентификации в ORDS Basic Authentication — реализация Определить ORDS-роль Дать ей привилегии (на модули, URI pattern) Создать пользователя на уровне сервера приложений и ассоциировать его с ORDS-ролью

Виды аутентификации в ORDS Basic Authentication — пример вызова

Виды аутентификации в ORDS Basic Authentication – пример вызова

Виды аутентификации в ORDS OAuth: Client Credentials Не требует участия пользователя, может быть полностью автоматизирована Создаем клиента и наделяем его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии • На первом шаге, используя client credentials, получаем временный токен • На втором шаге, подставляя токен в заголовке запроса при каждом обращении к REST-сервису, получаем результат

Виды аутентификации в ORDS OAuth: Client Credentials Создаем клиента и наделяем его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии На первом шаге, используя client credentials, получаем временный токен • На втором шаге, подставляя токен в заголовке запроса при каждом обращении к REST-сервису, получаем результат

Виды аутентификации в ORDS OAuth: Client Credentials Создаем клиента и наделяем его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии На первом шаге, используя client credentials, получаем временный токен На втором шаге, подставляя токен в заголовке запроса при каждом обращении к REST-сервису, получаем результат

Виды аутентификации в ORDS OAuth: Authorization Code Создаем клиента и наделяем его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии и ссылкой для определения токена • На первом шаге, используя client credentials, отправляем запрос на получение кода авторизации, попадаем на страницу авторизации (вводим пользователя/пароль, заведенного на уровне сервера приложений), а после вытаскиваем код авторизации из строки запроса, подставляемую в редиректную ссылку • На втором шаге вызываем метод для получения токена (по коду авторизации и client credentials) • На третьем шаге, подставляя токен в заголовке запроса при каждом обращении к REST-сервису, получаем результат

Виды аутентификации в ORDS OAuth: Authorization Code Создаем клиента и наделяем его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии и ссылкой для определения токена На первом шаге, используя client credentials, отправляем запрос на получение кода авторизации, попадаем на страницу авторизации (вводим пользователя/пароль, заведенного на уровне сервера приложений), а после вытаскиваем код авторизации из строки запроса, подставляемую в редиректную ссылку • На втором шаге вызываем метод для получения токена (по коду авторизации и client credentials) • На третьем шаге, подставляя токен в заголовке запроса при каждом обращении к REST-сервису, получаем результат

Виды аутентификации в ORDS OAuth: Authorization Code Создаем клиента и наделяем его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии и ссылкой для определения токена На первом шаге, используя client credentials, отправляем запрос на получение кода авторизации, попадаем на страницу авторизации (вводим пользователя/пароль, заведенного на уровне сервера приложений), а после вытаскиваем код авторизации из строки запроса, подставляемую в редиректную ссылку На втором шаге вызываем метод для получения токена (по коду авторизации и client credentials) • На третьем шаге, подставляя токен в заголовке запроса при каждом обращении к REST-сервису, получаем результат

Виды аутентификации в ORDS OAuth: Authorization Code Создаем клиента и наделяем его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии и ссылкой для определения токена На первом шаге, используя client credentials, отправляем запрос на получение кода авторизации, попадаем на страницу авторизации (вводим пользователя/пароль, заведенного на уровне сервера приложений), а после вытаскиваем код авторизации из строки запроса, подставляемую в редиректную ссылку На втором шаге вызываем метод для получения токена (по коду авторизации и client credentials) На третьем шаге, подставляя токен в заголовке запроса при каждом обращении к REST-сервису, получаем результат

Виды аутентификации в ORDS OAuth: Implicit Создаем клиента и наделяем его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии • На первом шаге, используя client credentials, отправляем запрос на получение токена, попадаем на страницу авторизации (вводим пользователя/пароль, заведенного на уровне сервера приложений), а после вытаскиваем токен из строки запроса, подставляемую в редиректную ссылку • На втором шаге, подставляя токен в заголовке запроса при каждом обращении к REST-сервису, получаем результат

Виды аутентификации в ORDS OAuth: Implicit Создаем клиента и наделяем его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии На первом шаге, используя client credentials, отправляем запрос на получение токена, попадаем на страницу авторизации (вводим пользователя/пароль, заведенного на уровне сервера приложений), а после вытаскиваем токен из строки запроса, подставляемую в редиректную ссылку • На втором шаге, подставляя токен в заголовке запроса при каждом обращении к REST-сервису, получаем результат

Виды аутентификации в ORDS OAuth: Implicit Создаем клиента и наделяем его ORDS-привилегиями для доступа к нужным ему данным Ассоциируем клиента с ролью, которая содержит в себе данные привилегии На первом шаге, используя client credentials, отправляем запрос на получение токена, попадаем на страницу авторизации (вводим пользователя/пароль, заведенного на уровне сервера приложений), а после вытаскиваем токен из строки запроса, подставляемую в редиректную ссылку На втором шаге, подставляя токен в заголовок запроса при каждом обращении к REST-сервису, получаем результат

Спасибо за внимание! Вопросы? Александр Шишков Руководитель отдела разработки