Ory Kratos — конструктор для сборки цифрового продукта любой сложности

Привет! Я Андрей Баронский, бэкенд-тимлид в KTS.

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

Для тех, кто впервые сталкивается с этим названием, дам немного контекста. Ory Kratos — это система API-first Identity и User Management. Она управляет всеми аспектами работы с пользователями, включая регистрацию, вход, восстановление пароля, многофакторную аутентификацию, верификацию данных и управление профилем. 

Иными словами, Ory Kratos берёт на себя рутинные технические задачи, предлагая готовое, гибкое и удобное в интеграции решение.

Оглавление

• Общая информация

  • Краткое описание

  • Почему Ory Kratos: еще несколько причин

• Как работать с Ory Kratos

  • Верхнеуровневый обзор

    • [BACKEND] Как собирать бэкенд

    • [DB] Как собирать юзера для базы данных

    • [FRONTEND] Как собирать фронтенд

    • Визуализация работы (preview)

  • Углубленный обзор

    • Интеграция с сервисом рассылок

    • Пара слов про API-авторизацию (native/browser)

    • Webhooks и как их использовать

    • Получение пользовательской информации в сервисах бизнес-логики

    • OAUTH2

    • Аутентификация по нескольким id

    • Приятные мелочи

• Небольшое (ленивое) нагрузочное

  • Первый сценарий нагрузки

  • Второй сценарий нагрузки

  • Выводы

• Недостатки Kratos

• Границы применимости и заключение

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

Общая информация

Краткое описание

Ory Kratos распространяется под лицензией Apache-2.0, что даёт свободу его использования, модификации и распространения. Написанный на языке Go, он отличается высокой производительностью, стабильностью и масштабируемостью. Продукт активно развивается, регулярно получая обновления и новые функции. Простота внедрения и отличная документация делают его хорошим выбором для разработчиков.

Разумеется, существуют и альтернативные SSO, но мы отказались от них по своим причинам. 

Мы рассматривали Keycloak (24к звезд на гитхабе) и CAS (11к звезд), однако они нам не подошли, поскольку они написаны на Java и довольно неповоротливы в кастомизации, а ее выполнение требует большого и неудобного стека. К примеру, у Keycloak нет плагина для работы с OTP, и его пришлось бы дописывать самостоятельно.

Также мы смотрели в сторону Authelia (22к звезд) — как и Kratos (11,4к звеад), она написана на Go, и, в целом, тоже подходит под наши задачи. Но в итоге наш выбор пал на Kratos ввиду его простоты, исчерпывающей документации с примерами и возможностями кастомизации UI через разработку.

Почему Ory Kratos: еще несколько причин

Давайте рассмотрим остальные факторы, которые определили наш выбор:

• наш собственный опыт — ранее мы уже экспериментировали с проектами Ory;

• наш стандартный технологический стек — мы понимали, что можем без затруднений доработать приложение под собственные нужды;

• возможность легко кастомизировать клиентскую часть приложения Kratos;

• наличие нативной авторизации через клиентский API;

• синергия Kratos с Hydra (провайдер OAuth 2.0 и ID Connect) и Oathkeeper (API gateway), которые имеют готовые компоненты для интеграции друг с другом без каких-либо доработок. Об этих технологиях я расскажу в следующих статьях;

• удобная и понятная документация;

• готовые Helm-чарты для развертывания приложения на k8s-кластере;

• скорость, с которой можно было поднять пилотную MVP версию приложения;

• легкость и изолируемость компонентов при дальнейшей замене.

Как работать с Ory Kratos

Верхнеуровневый обзор

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

• SSO (Single Sign-On);

• веб- и мобильный клиенты для взаимодействия с пользователем;

• интеграцию с сервисом рассылок (например, для подтверждения email или отправки уведомлений);

• возможную интеграцию с внешним SSO для обеспечения единой точки входа в приложение;

• отдельный бизнес-слой, реализующий специфические сценарии приложения.

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

[BACKEND] Как собирать бэкенд

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

Когда мы знаем ответы на эти вопросы, мы можем описать в рамках приложения, в каких сценариях (flow) система будет использоваться. Всего на выбор Kratos дает шесть сценариев:

• settings (изменение пользовательских данных);

• recovery (восстановление доступов);

• verification (подтверждение пользователя);

• logout;

• login;

• registration.

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

kratos.config

selfservice:  flows:    verification:      enabled: false

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

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

kratos.config

selfservice:  default_browser_return_url: http://127.0.0.1:4455/welcome  flows:    login:      ui_url: http://127.0.0.1:4455/login

Когда вы определились, какие сценарии вам понадобятся, нужно сформулировать, как будет происходить аутентификация пользователя в системе. Рассмотрим ее на примере «email+пароль». Нужно указать это в конфиге следующим образом:

kratos.config

... selfservice:   methods:     password:       enabled: true ...

Система также предлагает альтернативные методы аутентификации — они могут пригодиться, если вам не подходит вариант «логин+пароль»:

• Passwordless + OTP/Magic Links;

• Passkeys и WebAuthN;

• Multi-factor authentication;

• Social sign in.

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

kratos.config

secrets:   cookie:     - PLEASE-CHANGE-ME-I-AM-VERY-INSECURE   cipher:     - 32-LONG-SECRET-NOT-SECURE-AT-ALL  ciphers:   algorithm: xchacha20-poly1305  hashers:   algorithm: bcrypt   bcrypt:     cost: 8

К слову, длительность жизни сессий и OTP гибко настраиваются. Их также можно задать через конфиг.

У бэкенда приложения есть Public и Admin API. В конфиге также нужно указать соответствующие им адреса:

kratos.config

serve:   public:     base_url: http://kratos:4433/   admin:     base_url: http://kratos:4434/

Когда все предыдущие шаги выполнены, остается только сконфигурировать интеграцию с СУБД. Приложение поддерживает работу с реляционными базами данных (PostgreSQL, MySQL, SQLite и CockroachDB). Для ознакомления также доступна возможность работы в режиме in memory:

kratos.config

dsn: memory

Подробнее о сборке бэкенда см.:

• Конфиг Кратоса

• Документация

[DB] Как собирать юзера для базы данных 

В Kratos пользователь — это ключевая сущность. Описать его можно с помощью документа JSON Schema. Для тех, кто раньше не сталкивался, JSON Schema — это декларативный язык для определения структуры и ограничений JSON.

Нам нужно описать основные атрибуты пользователя, указать идентификатор и способ логина. Это делается с помощью расширенных атрибутов ory.sh/kratos, в которых указываются системные зависимости.

Стоит обратить внимание, что title атрибутов пользователя будут использоваться в UI клиентского приложения. Еще при конфигурировании юзера важно помнить, что сервис Kratos отвечает только за работу с пользователем. Следовательно, в его атрибутах не нужно хранить какую-то специфическую бизнес логику, не относящуюся к домену. Храните только те данные, которые будут необходимы во всех компонентах системы. 

Рассмотрим конфигурацию на примере:

identity.schema.json

{  "$schema": "http://json-schema.org/draft-07/schema#",  "type": "object",  "properties": {    "traits": {      "type": "object",      "properties": {        "username": {          "title": "Username",          "type": "string",          "ory.sh/kratos": {            "credentials": {              "password": {                "identifier": true              }            }          }        },        "name": {          "type": "object",          "properties": {            "first": {              "title": "First name",              "type": "string"            },            "last": {              "title": "Last name",              "type": "string"            }          }        }      }    }  } }

Кроме указанных выше атрибутов, есть еще JSON-атрибуты metadata_public (доступные клиенту данные) и metadata_admin (данные, которые можно получить на уровне сервера). За консистентность данных нужно будет отвечать самостоятельно. Валидации этих параметров нет. 

После того, как мы разобрались с «анатомией» пользователя, в конфиге сервера нужно указать путь до схемы.

kratos.config

identity:   default_schema_id: default   schemas:     - id: default       url: file:///etc/config/kratos/identity.schema.json

Подробнее см.:

• Пример конфига

• Описание формата JSON Schema

• Документация:

  • Модель юзера

  • Настройка юзера в Schema

  • Кастомизация Schema для настройки юзера

[FRONTEND] Как собирать фронтенд

Для реализации своего собственного пользовательского интерфейса есть 3 варианта репозиториев, но основе которых можно это сделать:

• Node.js

• Next.js/React

• React Native

В данном примере мы будем использовать Next.js/React-приложение из репозитория. Я предлагаю рассмотреть, как указать переменные окружения для конфигурирования фронтенда. В качестве примера возьмем демо веб-приложение:

environment:  - KRATOS_PUBLIC_URL=http://kratos:4433/  - KRATOS_BROWSER_URL=http://127.0.0.1:4433/  - COOKIE_SECRET=changeme  - CSRF_COOKIE_NAME=ory_csrf_ui  - CSRF_COOKIE_SECRET=changeme

Визуализация работы (preview)

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

Схема работы (исходник здесь):

Углубленный обзор

Мы познакомились с базовыми сценариями IdM-решения, и теперь я предлагаю рассмотреть дополнительные возможности инструмента, которые могут пригодиться при интеграции Kratos в проект.

Интеграция с сервисом рассылок

Перед тем, как интегрировать наше приложение с сервисом рассылок, нужно добавить необходимость подтвердить почту в сервисе.

1. Добавляем шаг подтверждения почты во flow верификации:

kratos.config

  flows:     verification:       enabled: true

identity.schema.json (строки 16, 17):

  "properties": {     "traits": {       "type": "object",       "properties": {         "email": {           "type": "string",           "format": "email",           "title": "E-Mail",           "minLength": 3,           "ory.sh/kratos": {             "credentials": {               "password": {                 "identifier": true               }             },             "verification": {               "via": "email"             }           }         }       }     }   }

2. Конфигурируем интеграцию с сервисом рассылок. Это может быть реализовано с помощью протокола SMTP. Для того, чтобы уменьшить объем кода и избыточного контекста, я опущу детали работы с аутентификацией. Отмечу только, что возможности ее настройки в проекте есть.

kratos.config

courier:   smtp:     connection_uri: smtps://test:test@mailslurper:1025

Также в Kratos есть возможность шаблонизации сообщений через Go template engine. Если вы с ними ранее не сталкивались с этим инструментом, тут можно с ним ознакомиться. В этом документе указаны переменные, которые будут переброшены при генерации тела письма.

email.body.gotmpl

Hi, please verify your account by code:  {{ .VerificationCode }}

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

kratos.config

... courier:  delivery_strategy: http  http:    request_config:      url: https://api.sendsrv.com/mail/send      method: POST      body: file:///etc/config/kratos/mail.template.jsonnet      headers:        "Content-Type": "application/json" ...

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

http_courier_template

function(ctx) {     message: {    recipients: [      {        email: ctx.recipient,        substitutions: {          RECOVERY_CODE: ctx.template_data.recovery_code,        },      },    ],    from_email: "no-reply@yourapp.ru",    template_id: "00000000-0000-0000-0000-000000000000"  } }

В итоге получаем следующий результат:

Подробнее см. документацию:

• Кастомные шаблоны писем для рассылки

  • Переменные для шаблонов

• Рассылка для версии self-hosted

• Генерация текстового вывода

• Рассылка через HTTP

• Jsonnet

Пара слов про API-авторизацию (native/browser)

Так как помимо обмена данных Kratos выполняет редиректы, у продукта есть отдельный API для native-клиентов. Разработчики рекомендуют воздержаться от использования native-клиентов в браузерных приложениях, поскольку это это открывает брешь в обороне для CSRF-атак.

Webhooks и как их использовать

В продукте есть возможность кастомизации логики с помощью внешних интеграций через webhook. Для всех основных flow есть хуки before и after, которые позволяют реализовать все необходимые сценации. 

При описании webhook есть возможность сконфигурировать их поведение: до или после выполнения сценария, блокирующий или нет. Это может пригодиться, например, если после успешной регистрации пользователя вам нужно автоматически добавлять его в списки рассылок в отдельном сервисе. Или, наоборот, усложнить регистрацию в систему, добавив дополнительные шаги проверок в других компонентах. Тело запроса описывается аналогично примеру с HTTP-интеграцией рассылок с помощью Jsonnet. 

Более того, в Kratos даже есть возможность обновлять атрибуты identity через webhook — как UI-параметры пользователя, так и metadata (публичные и приватные). 

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

Расширим конфиг сервиса настройками flow регистрации:

kratos.config

selfservice:  flows:    registration:      after:        password:          hooks:            - hook: web_hook              config:                url: http://wiremock:8443/webhook                method: "POST"                body: "file:///etc/config/kratos/reg_webhook.jsonnet"                response:                  parse: true

Приведем пример ответа, который будет обрабатывать Kratos и информировать о проблеме с регистрацией, и замокаем ответ на вебхук. В данном случае "instance_ptr": "#/traits/email" (4 строка) является атрибутом, с которым ассоциируется ошибка:

{    "messages": [        {            "instance_ptr": "#/traits/email",            "messages": [                {                    "id": 12356,                    "text": "Мы решили не пускать тебя в систему!(",                    "type": "error",                    "context": {                        "value": "Мы решили не пускать тебя в систему!("                    }                }            ]        }    ] }

На видео можно посмотреть пример блокирующего вебхука c информацией об ошибке в UI:

Подробнее см. документацию:

• Конфигурация хуков

• Интеграция через вебхуки

Получение пользовательской информации в сервисах бизнес-логики

Можно, конечно, реализовать мидлвар в наших микросервисах для получения информации о пользователях, но я предлагаю использовать для этого Oauthkeeper — AGW, за которым можно скрыть все компоненты приложения. В нем же можно сконфигурировать, какие пользовательские данные мы будем передавать в микросервисы. Так мы избавляемся от необходимости дублировать интеграцию с Kratos в каждом сервисе и можем легко настраивать это на стороне AGW.

OAUTH2

Стоит отметить, что Ory Kratos из коробки поддерживает вход через внешние сервисы с помощью OAuth2 и OpenID Connect. Вам остается только сконфигурировать их. Не буду погружаться в детали, просто оставлю ссылку на соответствующий раздел документации, если вам интересно узнать об этом больше.

Аутентификация по нескольким id

В Kratos есть возможность настроить несколько identifiers и указать различные варианты аутентификации для них. Зачем это нужно? Например, для того, чтобы пользователь мог логиниться в системе не только по адресу электронной почты, но и по номеру телефона. Рассмотрим этот пример подробнее.

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

Выше мы уже добавили возможность входить в наше приложение через связку «email + password». Добавим также связку «phone + password». Для этого нужно расширить схему пользователя. Доработаем ее:

Identity.schema.json

 {  "$id": "https://schemas.ory.sh/presets/kratos/identity.email.schema.json",  "title": "Person",  "type": "object",  "properties": {    "traits": {      "type": "object",      "properties": {        "phone": {          "type": "string",          "format": "tel",          "title": "Phone number",          "ory.sh/kratos": {            "credentials": {              "password": {                "identifier": true,              }            }          }        }      }    }  } }

Приятные мелочи

Отдельно хочу подсветить небольшие детали, которые нередко упрощают жизнь при работе с Kratos.

• Во-первых, в системе есть возможность запускать Cleanup jobs, чтобы чистить устаревшие сессии и освобождать данные с диска. Подробнее про них можно почитать в документации.

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

• В-третьих, в Kratos предусмотрена миграция пользователей через import, причем при миграции можно сохранять их прежние пароли. По традиции, детали в документации.

• Можно задать ограничение на уровне конфига — не более одной активной сессии на пользователя.

• К слову об активной поддержке и расширении функциональности: пока я писал эту статью, появилась возможность реализовать passwordless flow для логина и регистрации через sms.

Небольшое (ленивое) нагрузочное 

Предлагаю посмотреть, как Kratos справляется с нагрузками. Здесь я не преследую цели провести полноценное испытание в условиях, максимально приближенных к реальным, а просто тестирую технологию «в вакууме», чтобы проверить основные паттерны.

Проверим систему двумя простыми сценариями. Тестировать будем следующую конфигурацию:

• 1 запущенный инстанс приложения на k8s-кластере;

• порты проброшены на локальную машину;

• лимиты по памяти —  512 MB.

Первый сценарий нагрузки

N пользователей (в нашем случае — 50) проходят flow аутентификации из двух шагов: создание flow и отправка данных (логин + пароль).. Задержка между шагами — от одной до трех секунд. Разумеется, в действительности типовая нагрузка будет не такой, но сценарий дает нам представление о том, как сервис будет справляться с наплывом новых пользователей в начале своей работы.

Получаем следующие результаты:

• С заданной конфигурацией Kratos успевает обрабатывать чуть больше 20 запросов в секунду.

• Больше половины полученных запросов на пике обрабатываются быстрее, чем за две секунды; 95 % запросов обрабатываются быстрее, чем за четыре секунды.

Второй сценарий нагрузки

Пользователь проходит flow аутентификации и начинает в цикле запрашивать информацию о профиле. Также этот запрос может использовать API Gateway для проверки сессии пользователя. Именно такой и будет основная нагрузка на сервис.

Получаем следующие результаты:

• Как и предполагалось, пик нагрузки происходит в момент, когда пользователи активно логинятся: 100 одновременных юзеров входят в систему примерно за 20 секунд, на протяжении которых RPS не поднимается выше 100.

• После того, как все пользователи получают активную сессию, проходит пик нагрузки. При 100 пользователях Response Time для 95% запросов не превышает 400 мс. RPS при этом держится чуть меньше 600.

• Минимальное время обработки запроса — 30 мс.

Выводы

Судя по результатам, «узкое горлышко» системы — это момент активного наплыва пользователей, которые одновременно хотят залогиниться. С запросами информации о профиле Kratos справляется намного эффективнее при прочих равных. Горизонтальное масштабирование системы (увеличение количества инстансов) может помочь решить эту проблему в критические моменты.

Недостатки Kratos

Разумеется, в работе мы столкнулись и с негативными аспектами системы. Поговорим про некоторые из них.

• Нет ограничений на отправку кода верификации и восстановления доступов, и сделано это не будет. Нужно самостоятельно решать вопрос с ограничениями на стороне AGW и других интеграций.

• Нет готовой admin-панели. Ее не очень сложно реализовать самостоятельно с помощью кодогенерации поверх схемы базы данных; к примеру, мы используем django + sdk для интеграции с API. Однако отсутствие готовой панели все же несколько огорчает.

• Заблокированным пользователям может быть неочевидно, что они заблокированы. Они могут начать восстанавливать пароль или попробовать залогиниться в систему с помощью OTP, получить код от системы, и только при его вводе узнать о блокировке. Можно попробовать это решить с помощью блокирующего before-вебхука с парсингом ответа.

Границы применимости и заключение

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

• вы не хотите тратить время разработчиков на создание своих кастомных велосипедов и согласны пользоваться сценариями, предложенными системой (или готовы вводить кардинальные изменения системы через fork проекта);

• вас устраивает заложенный UI готового решения;

• вы готовы завести отдельное реляционное хранилище пользователей и можете синхронизировать его с мастер-данными;

• вам не нужна интеграция с AD (если нужна, то решение вам не подойдет).

На случай, если система вам интересна и вы захотели протестировать ее самостоятельно, оставляю ссылки на полезные материалы:

1. Туториал по быстрому старту (и соответствующий раздел репозитория на GitHub)

2. API

3. Структура валидатора конфига (берите конфиг из Quickstart и уже дальше докручивайте при необходимости)

4. Helm chart, который можно использовать для начала

5. Postman collection

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

Более конвенциональным разработчикам, которые используют Keycloak, я рекомендую почитать статью моего коллеги из DevOps-юнита о том, как прикрутить к нему Firezone. Также советую ознакомиться с материалами из нашего блога для бэкендеров и DevOps-инженеров:

• JupyterHub на стероидах: реализация KubeFlow фич без масштабных интеграций

• Поднимаем динамические окружения (фича-стенды) для stateless- и stateful-сервисов

• В чем силиум, брат? Обзор ключевых фишек Cilium и его преимущества на фоне других CNI-проектов

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

Удачи!