Upgrade to Pro — share decks privately, control downloads, hide ads and more …

ORDS — security & API specifications

CUSTIS
February 11, 2020

ORDS — security & API specifications

Выступление Александра Шишкова, нашего руководителя отдела разработки, с докладом на CUSTIS Meetup: Russian Oracle User Group (11 февраля 2020, Москва).

Видеозапись выступления: https://www.youtube.com/watch?v=uUhQG7Cipoo

CUSTIS

February 11, 2020
Tweet

More Decks by CUSTIS

Other Decks in Programming

Transcript

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  4. Способы передачи параметров запроса
    • Через 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}}

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  11. Способы передачи параметров запроса
    Через 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-запрос:

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  32. Описание 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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  45. 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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide