Share
Embed
ORDS — security & API specifications
Выступление Александра Шишкова, нашего руководителя отдела разработки, с докладом на CUSTIS Meetup: Russian Oracle User Group (11 февраля 2020, Москва).
Видеозапись выступления: https://www.youtube.com/watch?v=uUhQG7Cipoo
CUSTIS
February 11, 2020
Transcript
66 slides
-
План • Способы передачи параметров запросов • Подходы в версионировании
API • Описание REST-сервиса через Swagger • SSL-сертификация • Виды аутентификации в ORDS -
Способы передачи параметров запроса • Через URI (в имени сервиса)
• Параметры объявляются на уровне определения rest-сервиса (ORDS.define_template): http://host:<port>/ords/schema_alias/module/template/val1/val2 В URI указываются только значения параметров, порядок строго фиксирован, параметры обязательные • Через URI (в строке параметров) • Параметры объявляются через отдельный обработчик (ORDS.define_parameter): http://host:<port>/ords/...?p1=val1&p2=val2 В URI указываются в конце строки запроса URI в стандартном виде, параметры не обязательные • Параметры используются без их предварительного объявления (актуально только для GET-запросов с источником в виде SQL-запроса) http://host:<port>/ords/...?q=json_query В URI указываются в конце строки запроса в виде JSON-строки: {"p1":{"$oper":"val1"}, "p2":{"$oper":val2}} -
Способы передачи параметров запроса Через 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 -
Способы передачи параметров запроса 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 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 Использование кастомного заголовка запроса • В
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 Что такое 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/<connection>/<schema-alias>/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-сертификация в 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 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 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-сервису, получаем результат