1. Общие проблемы

1.1 Отсутствие информации о совместимости версий компонентов WSO2

• Проблема: Руководство не указывает версии WSO2 API Manager (AM) и WSO2 Identity Server (IS), используемых в нем. Продукты WSO2 имеют различные функции, API и конфигурации в разных версиях (например, WSO2 AM 4.x против 3.x, IS 5.x против 6.x), что может привести к проблемам совместимости или путанице при реализации.

• Рекомендация: Явно указать версии WSO2 AM, IS и любых других компонентов (например, версия SCIM2 API). Предоставить таблицу совместимости, если поддерживаются несколько версий.

1.2 Неопределенные компоненты платформы "Banank"

• Проблема: В руководстве упоминается платформа "Banank" для службы регистрации, службы OTP и удостоверяющего центра (CA) без описания деталей их реализации, API или интеграции с WSO2. Это отсутствие ясности затрудняет понимание архитектуры системы или воспроизведение настроек.

• Рекомендация: Предоставить подробные спецификации компонентов платформы Banank, включая их API, ожидаемые входные/выходные данные и их взаимодействие с WSO2 AM и IS. В качестве альтернативы указать ссылку на отдельную документацию для этих служб.

1.3 Неясность интеграции KYC

• Проблема: В руководстве упоминается интеграция KYC через Veriff, но не предоставлено никаких деталей о том, как она реализована, как интегрируется с WSO2 IS или как назначается область действия "полный доступ" после KYC. Это создает пробел в понимании полного пути пользователя.

• Рекомендация: Описать процесс KYC, включая взаимодействие Veriff с WSO2 IS или службой регистрации, хранение статуса KYC и то, как это влияет на обновление области действия в токенах доступа.

1.4 Непоследовательная терминология

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

• Рекомендация: Определить все ключевые термины в глоссарии или непосредственно в тексте. Обеспечить последовательное использование терминологии в разных разделах (например, "идентификатор устройства" против "did").

2. Проблемы с регистрацией устройства

2.1 Неясное использование mTLS при регистрации

• Проблема: В разделе 2.2 указано, что "взаимный TLS еще не применяется" во время запроса на регистрацию, поскольку устройство не имеет доверенного сертификата. Однако в дальнейшем руководство подчеркивает использование mTLS для всех коммуникаций с API Gateway (раздел 6). Это создает противоречие, так как неясно, как защищен начальный запрос /enroll без mTLS.

• Рекомендация: Уточнить механизм безопасности для конечной точки /enroll (например, является ли она общедоступной или использует другой метод аутентификации?). Если mTLS обходится, объяснить, как запрос защищен от несанкционированного доступа.

2.2 TBD в процессе подписания сертификата

• Проблема: На этапе 4 процесса регистрации указано, что приложение отправляет CSR и токен предоставления "непосредственно в CA (TBD)". "TBD" указывает на незавершенный или неопределенный процесс, что критично для потока регистрации.

• Рекомендация: Определить точный процесс отправки CSR в CA, включая конечную точку, протокол и меры безопасности. Устранить или разрешить все заполнители "TBD", чтобы руководство было применимым.

2.3 Отсутствие деталей обработки ошибок

• Проблема: Процесс регистрации не описывает обработку ошибок для таких сценариев, как недействительные CSR, сбои CA или проблемы с хранилищем NATS.io. Это может привести к неполным реализациям или необработанным краевым случаям.

• Рекомендация: Добавить подраздел об обработке ошибок, описывающий возможные сбои (например, сетевые ошибки, недействительный CSR, истечение срока действия токена) и ожидаемые ответы (например, коды состояния HTTP, сообщения об ошибках).

2.4 Неясность ротации сертификатов

• Проблема: Руководство требует ротации сертификатов каждые 90–180 дней, но не объясняет, как мобильное приложение уведомляется о необходимости ротации, как инициируется процесс или как это влияет на существующие сеансы.

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

3. Проблемы с регистрацией пользователя

3.1 Неполная обработка существующих пользователей

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

• Рекомендация: Уточнить дальнейшие шаги для существующих пользователей, например, перенаправление на процесс аутентификации или запрос другого номера телефона.

3.2 Отсутствие деталей о службе OTP

• Проблема: Поведение службы OTP (например, логика генерации OTP, механика счетчика попыток, конфигурация TTL) не описана полностью. Например, неясно, что происходит, если счетчик попыток достигает нуля, или как интегрируется служба уведомлений.

• Рекомендация: Предоставить подробную спецификацию службы OTP, включая формат OTP, длину, политики повторных попыток и интеграцию со службой уведомлений (например, протоколы доставки SMS/email).

3.3 Отсутствие поддержки многофакторной OTP

• Проблема: Руководство упоминает только проверку номера телефона через OTP, а проверка по email упомянута кратко, но не детализирована. Это ограничивает гибкость многофакторной проверки (например, поддержка OTP по телефону и email).

• Рекомендация: Расширить процесс регистрации, включив проверку OTP по email как альтернативный или дополнительный шаг, с четкими шагами для обоих вариантов.

4. Проблемы с аутентификацией пользователя

4.1 Неясность JWT утверждения клиента

• Проблема: Полезная нагрузка JWT утверждения клиента (раздел 4.2) включает заявку did (идентификатор устройства), но неясно, как она генерируется, хранится или связывается с пользователем в WSO2 IS. Кроме того, в примере JWT используются одинаковые значения для iss и sub, что необычно и потенциально некорректно.

• Рекомендация: Уточнить генерацию и назначение заявки did. Убедиться, что iss и sub соответствуют лучшим практикам JWT (например, iss должен идентифицировать службу регистрации, sub — пользователя). Предоставить реалистичный пример JWT.

4.2 Отсутствие деталей о пользовательском плагине аутентификации

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

• Рекомендация: Включить ссылку на документацию плагина или описать его функциональность, включая проверку подписи JWT и сопоставление устройства с пользователем в NATS.io.

4.3 Неполный процесс выдачи токена

• Проблема: Руководство не указывает тип предоставления OAuth 2.0, используемый для выдачи токена (например, учетные данные клиента, пользовательское предоставление). Это влияет на то, как разработчики настраивают WSO2 IS и мобильное приложение.

• Рекомендация: Явно указать тип предоставления OAuth 2.0 и предоставить полную полезную нагрузку запроса токена, включая любые дополнительные параметры (например, grant_type, scope).

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

5.1 Неясность доступа к общедоступным ресурсам

• Проблема: В разделе 5.1 упоминаются общедоступные конечные точки, такие как GET /public-data, которые "могут быть защищены общим сертификатом, встроенным в приложение (TBD)". "TBD" и отсутствие ясности о назначении сертификата создают путаницу в требованиях безопасности.

• Рекомендация: Определить, являются ли общедоступные конечные точки действительно незащищенными или используют определенный сертификат. Если используется встроенный сертификат, объяснить его генерацию, распространение и процесс проверки.

5.2 Отсутствие деталей управления областями

• Проблема: Руководство упоминает "области" для ограниченного и полного доступа, но не описывает, как области определяются, назначаются или проверяются в WSO2 AM и IS. Например, неясно, как предоставляется "полная область" после KYC.

• Рекомендация: Предоставить детали конфигурации областей в WSO2 AM и IS, включая их сопоставление с токенами и то, как завершение KYC запускает обновление областей.

5.3 Неполный процесс обновления токена

• Проблема: Процесс обновления токена упомянут кратко, но отсутствуют детали о конечной точке обновления токена, формате запроса или обработке ошибок (например, что происходит, если токен обновления недействителен).

• Рекомендация: Описать процесс обновления токена, включая конечную точку (/oauth2/token), параметры запроса и возможные ответы на ошибки (например, 401 Unauthorized).

6. Проблемы безопасности

6.1 Использование заголовка mTLS

• Проблема: В руководстве указано, что клиентские сертификаты передаются в заголовке X-WSO2-CLIENT-CERTIFICATE, что нестандартно для mTLS. В mTLS сертификат обычно проверяется во время рукопожатия TLS, а не передается в заголовке.

• Рекомендация: Уточнить, проверяется ли сертификат через рукопожатие mTLS или пользовательский заголовок. Если используется заголовок, объяснить, почему выбран этот нестандартный подход и как он интегрируется с WSO2 AM.

6.2 Риски безопасности привязки к устройству

• Проблема: В руководстве указано, что токены доступа привязаны к устройству через заявку did, но не описано, как эта привязка обеспечивается или защищается от кражи токена (например, может ли украденный токен использоваться с другого устройства?).

• Рекомендация: Объяснить, как обеспечивается привязка к устройству при проверке токена и как это предотвращает неправомерное использование токена. Рассмотреть дополнительные меры безопасности, такие как шифрование токена или более строгие проверки устройства.

6.3 Отсутствие ограничения скорости или защиты от атак методом перебора

• Проблема: Руководство не упоминает ограничение скорости или защиту от атак методом перебора для конечных точек, таких как /verify (проверка OTP) или /oauth2/token. Это может сделать систему уязвимой для злоупотреблений.

• Рекомендация: Добавить политики ограничения скорости и защиты от атак методом перебора для критически важных конечных точек, указав, как они настраиваются в WSO2 AM или службе регистрации.

7. Технические и реализационные пробелы

7.1 Использование хранилища ключ-значение NATS.io

• Проблема: Руководство ссылается на NATS.io для хранения метаданных устройства и данных OTP, но не предоставляет деталей о его конфигурации, безопасности или интеграции с другими компонентами.

• Рекомендация: Описать настройку NATS.io (например, аутентификация, шифрование), способ хранения данных (например, структура ключей, TTL) и его интеграцию с WSO2 IS и службой регистрации.

7.2 Отсутствие деталей о службе уведомлений

• Проблема: Служба уведомлений для доставки OTP через SMS/email упомянута, но не описана. Разработчикам нужны детали ее реализации и интеграции.

• Рекомендация: Предоставить обзор службы уведомлений, включая ее API, методы доставки (например, SMS через Twilio, email через SMTP) и обработку ошибок.

7.3 Отсутствие примеров кода или конфигураций

• Проблема: Руководство включает некоторые JSON-полезные нагрузки (например, CSR, JWT), но отсутствуют полные примеры запросов API, конфигураций WSO2 или фрагментов кода мобильного приложения. Это затрудняет реализацию системы для разработчиков.

• Рекомендация: Включить полные примеры запросов API (например, команды cURL), фрагменты конфигурации WSO2 AM/IS (например, настройки OAuth, конечные точки SCIM2) и примеры кода мобильного приложения для ключевых процессов.

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

8.1 Отсутствие диаграмм или схем

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

• Рекомендация: Добавить диаграммы последовательности для каждого основного процесса (регистрация, аутентификация, доступ к ресурсам) для повышения ясности.

8.2 Неполные коды ошибок

• Проблема: Некоторые коды ошибок (например, 409, 400, 410) упоминаются, но в руководстве отсутствует полный список возможных ответов об ошибках для каждой конечной точки API.

• Рекомендация: Включить таблицу кодов ошибок, описаний и рекомендуемых действий для каждой конечной точки.

8.3 Отсутствие рекомендаций по тестированию и валидации

• Проблема: Руководство не предоставляет рекомендаций по тестированию реализации, таких как проверка mTLS, симуляция сбоев OTP или тестирование интеграции KYC.

• Рекомендация: Добавить раздел о тестировании и валидации, включая инструменты (например, Postman для тестирования API, OpenSSL для генерации сертификатов) и сценарии тестирования.

Резюме ключевых рекомендаций

1. Указать версии WSO2: Уточнить версии WSO2 AM и IS, чтобы избежать проблем совместимости.

2. Определить компоненты платформы Banank: Предоставить подробные спецификации для службы регистрации, службы OTP и CA.

3. Устранить TBD: Завершить все заполнители (например, процесс отправки в CA, сертификаты для общедоступных конечных точек).

4. Уточнить использование mTLS: Объяснить, как защищена конечная точка /enroll без mTLS и проверяются ли сертификаты через заголовки или рукопожатие TLS.

5. Улучшить обработку ошибок: Документировать сценарии ошибок и ответы для всех процессов.

6. Детализировать интеграцию KYC: Описать, как Veriff интегрируется с WSO2 IS и обновляет области.

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

8. Предоставить примеры кода: Включить полные запросы API, конфигурации WSO2 и фрагменты кода мобильного приложения.

9. Усилить безопасность: Добавить ограничение скорости, защиту от атак методом перебора и более четкое обеспечение привязки к устройству.

10. Улучшить документацию: Добавить глоссарий, полные таблицы кодов ошибок и рекомендации по тестированию.