Новая система НСК
- Топология размещения и взаимодействия сервисов НСК
- Механизмы CI/CD
- Порядок подготовки проекта к системе сборки
- Порядок работы с корпоративным GitLab репозиторием
- Аутентификация, Авторизация, Аудит
- Попроектная кадрово-организационная структура
- Технические требовния на систему управления задачами
Топология размещения и взаимодействия сервисов НСК
Механизмы CI/CD
Базовые механизмы конвеера постоянной интеграции и развертывания программных продуктов АО "Национальные квалификации" состоят из следующих технологических этапов:
Тестовая эксплуатация
- Публикация изменений исходного кода
- Запуск по триггеру GitLab процесса сборки ПО в Jenkins CI
- Запуск набора автотестов (юнит-тестирование) - при наличии тестов
- Упаковка установочного пакета в формате debian
- Передача собранного deb пакета в репозиторий ПО "Тестовая эксплуатация" (testing)
- Автоматическая установка пакета в тестовой эксплуатации в течение 30-40 минут после сборки пакета
После успешного завершения всех этапов программное обеспечение доступно в среде тестовой эксплуатации. Если хотя бы один этап завершается с ошибкой, владельцу проекта отправляется отчет с уведомлением о возникшей ошибке.
Опытная и промышленная эксплуатация
- После успешного тестирования ПО в тестовом контуре тестировщик подписывает Акт тестирования. В Акте фигурирует версия ПО, включающая номер коммита (зафиксированных изменений)
- После подписания акта коммит фиксируется в ветке stage проектного репозитория
- Запускается процесс сборки ПО ветки для ветки stage
- Формируется журнал изменений из событий между тегами. в журнал попадают только события отмеченные символами +/-/* в начале каждой строки описания изменений
- Запускается набор автотестов (юнит-тестирование) - при наличии тестов
- Упаковка установочного пакета в формате debian
- Передача собранного deb пакета в репозиторий ПО "Опытная эксплутаация" (stage)
- Отправка уведомлений кураторам и владельцам среды опытной эксплуатации об обновлении ПО
- Обновление ПО в среде опытной эксплуатации при помощи агента Puppet на начало следующих суток
- После завершения тестирования ПО ведущий разработчик, технический директор или начальник отдела технической поддержки совместно с двумя кураторами регионов подписывают Акт тестирования. Всего устанавливается 3 подписи разными видами уполномоченных лиц.
- После подписания акта тестирования происходит слияние изменений ветки stage с веткой production
- Процесс сборки для ветки production осуществляется аналогично пунктам 3-9
Документация
Документация должна автоматически собираться на дату сборки и формирования пакетов в формате PDF с использованием системы справки и поддержки АО НК. Файл документации должен автоматически формировать шапку, подвал, типографику, сноски, версию документа и иные параметры верстки и допечатной подготовки, согласно заданному шаблону.
ТРЕБУЕТ РЕАЛИЗАЦИИ
Сборка программного обеспечения
Для каждого разрабатываемого продукта АО НК должен формироваться Debian пакет программного обеспечения для целей быстрого точеченого развертывания, контроля версионности, зависимостей и целостности распространяемого ПО.
Требования к формируемым пакетам:
- Имя ПО является базовой частью имени пакета: <software>
- Если пакет содержит компилируемую часть, то все компилируемые файлы должны входить в пакет <software>-bin
- Если пакет содержит набор данных отдельно от программной части - изображения, шрифты, база данных, то все компоненты должны входить в пакет <software>-data
- Если пакет содержит набор типовых настроек, такие настройки включаются в базовый пакет <software>, если вараинтов настройки пакета несколько, создаются соответствующие конфигурационные пакеты вида: <software>-config-<kind>, где kind - разновидонсть предоставляемых настроек.
- Документация на пакет ПО упаковывается в пакет <software>-doc
- При наличии SDK, такие файлы должны помещаться в пакет <software>-dev
- Если пакет имеет изменяемую структуру БД (миграции), то такие миграции должны быть включены в базовый пакет <software>
- Версия пакета формируется автоматически из последнего тега + порядкового номера коммита относительно тега. ХЭШ коммита попадает в сведения о сборке пакета.
- Список изменений проекта формируется автоматически из строк фиксации изменений кода в git, при этом учитываются только строки начинающиеся с символов +/-/*
- Правила формирования пакетов описываются DevOps инженером совместно с руководителем проекта или тимлидом.
Формирование Docker контейнера
Docker файл формирует образ программного обеспечения как результат сборки debian пакета. Docker файл должен предоставлять simple контейнер, из одного или нескольких образов ФС:
- Базовая ОС
- Необходимые зависимости
- Образ с распакованынм ПО
- Сценарии при запуске контейнера (преинит)
Итоговый контейнер должен соответствовать следующим принципам:
- Монолитность Отсуствие сборки ПО при установке контейнера
- Стабильность Отсуствие скачивания дополнительных компонент из сети интернет
- Повторяемость Возможность многократно развернуть контейнер в средах отличных от Docker
- Атомарность Иметь отдельные образы контейнеров для нужд БД и рабочей нагрузки
- Масштабируемость Иметь поддержку горизонтального масштабирования (NLB) с общей БД, разделяемой ФС и конфигурацией
- Управляемость Контейнер должен содержать базовый набор Unix Shell утилит, на уровне не ниже Busybox 1.7
Репозиторий образов
Для целей поддержки инфраструктуры Kubernetes для программного обеспечения выделяется общий разделяемый репозиторий корпоративного ПО. Перед передачей ПО в ГосТех или иные сторонние площадки оркестрации и управления ПО должно пройти все необходимые процедуры тестирования и приемки в среде Тестовой и Опытной эксплуатации.
Порядок подготовки проекта к системе сборки
Любой проект должен быть подготовлен для автоматической сборки с использованием конвеера CI/CD. Для этого в структуру проекта должны быть внесены соответствующие изменения. Код проекта должен поддерживать конфигурирование через переменные окружения, с использованием dotenv или аналогичной библиотеки.
Начальное пополнение проекта
В структуру проекта должны быть добавлены следующие файлы и директории:
- contrib - набор вспомогательных файлов для сборки пакета - шаблоны сервисов, конфигурации веб серверов и т.п.
- debian - набор рецептов для сборки Debian пакета
- Makefile - основной сборочный сценарий проекта
- build.sh - специальный файл обновляющий историю изменений и запускающий сборку. Может использоваться для локальной сборки пакетов
- .env - Переменные окружения, используемые при сборке проекта в распространяемый debian пакет
- .env.develop - Переменные окружения, используемые при настройке стенда, дополняют собой значения переменных, объявленных в файле .env
- .env.example - Все доступные переменные окружения. Может включаться в документацию проекта.
- .env.local - Локальные переменные при локальной сборке и запуске проекта
Набор файлов шаблонов доступен для скачивания с корпоративного GIT репозитория. В шаблонах файлов в качестве имени проекта используется слово dummy, его требуется заменить на корректное имя проекта согласно его пути в репозитории GitLab. Путь анализируется от корня репозитория и не учитывает лидирующие пути содержащие слова back и front в имени проекта. Все прямые слеши (символ /) заменяются на тире (символ -). Если в пути проекта присутствует суффикс, содержащий слова front или back, то к имени проекта добавляется суффикс -frontend или -backend, соответственно. Например, если репозиторий имеет путь cok/lms/front то полное имя проекта будет иметь вид cok-lms-frontend, а если репозиторий имеет путь cok/video-store, то полное имя проекта будет иметь вид cok-video-store. Имя проекта, его тип, ветка репозитория отражаются при сборке как соответствующие переменные окружения и могут использоваться в шаблонах конфигурации.
Переменные окружения
При сборке проекта определен ряд переменных окружения, которые автоматически подставляются в файлы конфигурации и файлы .env с параметрами окружения проекта. Основные переменные при сборке проекта:
- PROJECT_NAME - Короткое имя проекта, без суффикса
- PROJECT_FULL_NAME - Полное имя проекта с суффиксом типа проекта
- PROJECT_TYPE - Тип проекта - пустое значение, значения frontend или backend
- PROJECT_BRANCH - Собираемая ветка проекта. Для стендов - имя ветки указывается без префикса stand/
- DB_HOST - Адрес сервера баз данных
- DB_PORT - Порт сервера баз данных
- DB_NAME - Наименование базы данных на сервере
- DB_USER - Имя пользователя для сервера баз данных
- DB_PASSWORD - Пароль пользователя для сервера баз данных
- DB_SCHEME - Схема на сервере баз данных. Параметр задан только для баз данных совместимых с PostgreSQL!
- BACKEND_SERVICE - Адрес бакенд сервера, значение берется из файла конфигурации .env после сборки проекта
- PUBLISH_TYPE - Тип публикации проекта, возможные значения: none, public, private.
- PUBLISH_DOMAIN - Домен публикации - пустое значение, dev.ao-nk.site или dev.ao-nk.ru в зависимости от типа публикации, задаваемого переменной PUBLISH_TYPE
Если требуется провести подстановку переменных в файл конфигурации времени сборки, используется синтаксис %VAR%, где VAR - имя переменной.
Если требуется задать пользовательскую переменную, которая будет использоваться в файлах contrib/ingress.yaml или contrib/watchdog.yaml, используется ключевое слово export перед именем переменной, например:
export MY_VAR="Text based value"
Секреты и служебная информация
Информация представляющая собой конфиденциальные данные, такие как логины, пароли, ключи и идентификаторы сервисов не должна напрямую фигурировать в файлах конфигурации проекта. Все служебные данные, которые требуется помещать в переменыне окружения на этапе сборки, задаются в виде секретов Jenkins.
Для обращения к секрету используется следующий синтаксис .env файла - %SECRET_<NAME>%, где <NAME> - имя секрета для собираемого проекта. Секреты в Jenkins имеют формат именования <PROJECT_NAME>_<NAME> в нижнем регистре. Таким образом, использование подстановки %SECRET_AUTH_ID% для проекта cok/lms/frontend будет искать значение секрета Jenkins с именем cok-lms_auth_id.
Рекомендуется выделять отдельный домен Jenkins для каждого сервиса/группы сервисов в Jenkins для точечного управления полномочиями на их просмотр и изменение. Тип секрета Jenkins указывается как Text Secret.
Служебные файлы для публикации в Kubernetes
Для публикации сервиса в Kubernetes, в особенности для создания стенда, используются следующие служебные файлы:
- contrib/Dockerfile - Рецепт для упаковки образа контейнера (Docker Image). Упакованный образ размещается в корпоративном Docker Registry по адресу registry.ao-nk.ru с именем <PROJECT_FULL_NAME>:<PROJECT_BRANCH>.
- contrib/ingress.yaml - Опциональный файл, указывающий правила публикации сервиса. Возможна подстановка переменных во время стадии подготовки контейнера. Переменные подставляются с использованием синтаксиса Bourne Shell - ${VAR}.
- contrib/watchdog.yaml - Опциональный файл, для проверки активности сервиса, согласно спецификации k18s.
- contrib/dummy.sql - Опциональный файл дампа начального состояния базы данных. Используется если сервис не предоставляет миграции или требуется определенное начальное состояние базы данных при первичном запуске сервиса или очистке стенда. SQL сценарий должен соответствовать используемой РСУБД.
Пример содержимого файла contrib|wathcdog.yaml:
httpGet:
path: /healthz
port: 8080
httpHeaders:
- name: Custom-Header
value: Awesome
initialDelaySeconds: 3
periodSeconds: 3
Файл contrib/ingress.yaml описывает параметры публикации сервиса в корпоративной сети или сети интернет:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: ${PROJECT_NAME}-${PROJECT_BRANCH}-ingress
namespace: dev
annotations:
nginx.ingress.kubernetes.io/configuration-snippet: |
proxy_set_header Upgrade "websocket";
proxy_set_header Connection "Upgrade";
nginx.ingress.kubernetes.io/proxy-read-timeout: '3600'
nginx.ingress.kubernetes.io/proxy-send-timeout: '3600'
nginx.ingress.kubernetes.io/rewrite-target: /$1
nginx.ingress.kubernetes.io/use-regex: 'true'
nginx.org/websocket-services: "${BACKEND_SERVICE}"
spec:
ingressClassName: nginx
rules:
- host: ${PROJECT_NAME}-${PROJECT_BRANCH}.${PUBLISH_DOMAIN}
http:
paths:
- backend:
service:
name: ${PROJECT_NAME}-${PROJECT_TYPE}-${PROJECT_BRANCH}
port:
number: 80
path: /(.*)$
pathType: ImplementationSpecific
- backend:
service:
name: ${BACKEND_SERVICE}
port:
number: 80
path: /api/(.*|)$
pathType: ImplementationSpecific
Секция Metadata
-
name:
${PROJECT_NAME}-${PROJECT_BRANCH}-ingress
Имя ресурса Ingress генерируется динамически с использованием переменных:-
${PROJECT_NAME}
: Название проекта -
${PROJECT_BRANCH}
: Название ветки Git
-
-
namespace:
dev
Ingress развертывается в namespacedev
, что указывает на использование для разработки.
Аннотации
-
Поддержка WebSocket:
nginx.ingress.kubernetes.io/configuration-snippet: | proxy_set_header Upgrade "websocket"; proxy_set_header Connection "Upgrade"; nginx.org/websocket-services: "${BACKEND_SERVICE}"
-
Активирует поддержку WebSocket для backend-сервиса
-
Устанавливает необходимые заголовки для WebSocket-соединений
-
${BACKEND_SERVICE}
указывает, какой сервис обрабатывает WebSocket-соединения
-
-
Настройки таймаутов:
nginx.ingress.kubernetes.io/proxy-read-timeout: '3600' nginx.ingress.kubernetes.io/proxy-send-timeout: '3600'
-
Устанавливает таймауты чтения и отправки в 3600 секунд (1 час)
-
Полезно для длительных соединений, таких как WebSocket или загрузка файлов
-
-
Обработка путей:
nginx.ingress.kubernetes.io/rewrite-target: /$1 nginx.ingress.kubernetes.io/use-regex: 'true'
-
Включает обработку путей на основе регулярных выражений
-
Перезаписывает целевой URL, сохраняя совпавший путь (
$1
)
-
Спецификация (spec)
-
Класс Ingress:
ingressClassName: nginx
-
Используется NGINX Ingress Controller
-
-
Правила маршрутизации:
-
Хост:
${PROJECT_NAME}-${PROJECT_BRANCH}.${PUBLISH_DOMAIN}
Динамическое имя хоста, состоящее из:-
Названия проекта
-
Названия ветки
-
Базового домена
-
-
Маршруты:
-
Основное приложение:
path: /(.*)$ backend: service: name: ${PROJECT_NAME}-${PROJECT_TYPE}-${PROJECT_BRANCH} port: 80
-
Перехватывает весь трафик по корневому пути (
/(.*)
) -
Направляет на фронтенд-сервис с именем из проекта, типа и ветки
-
-
-
-
API-эндпоинты:
path: /api/(.*|)$ backend: service: name: ${BACKEND_SERVICE} port: 80
-
Направляет весь трафик
/api/
на backend-сервис -
Поддерживает как сегменты пути (
/api/something
), так и корень (/api/
)
-
Переменные
Переменная | Описание |
---|---|
${PROJECT_NAME} |
Название развертываемого проекта |
${PROJECT_BRANCH} |
Название ветки Git (для изоляции сред) |
${PROJECT_TYPE} |
Тип проекта ("frontend" или "backend") |
${PUBLISH_DOMAIN} |
Базовый домен для среды |
${BACKEND_SERVICE} |
Название backend-сервиса для API и WebSocket |
Примеры использования
-
Веб-приложение:
-
URL:
https://myapp-feature.example.com
-
Отдает фронтенд-приложение
-
API-запросы на
https://myapp-feature.example.com/api/
направляются на бэкенд
-
-
WebSocket-соединения:
-
Тот же backend-сервис обрабатывает WebSocket-соединения
-
Обновление соединений корректно поддерживается через аннотации
-
Порты и постоянные тома экземпляра сервиса в Kubernetes
Для автоматического определения портов сервиса и постоянных томов сервиса используются ключевые слова Dockerfile - EXPOSE и VOLUME.
EXPOSE определяет номер и тип порта (TCP или UDP) сервиса, например:
EXPOSE 80/tcp
EXPOSE 5000/udp
VOLUME опеределяет путь, внутри контейнера, содержимое которого сохраняется между сборками сервиса (стенда). По умолчанию размер такого тома ограничен квотой в 2 гигабайта. Пример:
VOLUME /var/www/service/runtime/uploads
VOLUME /var/spool/crontab
SSH доступ к стенду
По окончанию сборки тестового стенда к нему возможен доступ по протоколу SSH, с под логином root с использованием SSH ключа:
-----BEGIN OPENSSH PRIVATE KEY-----
b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAABFwAAAAdzc2gtcn
NhAAAAAwEAAQAAAQEAjPw9pRxAhQr6TZMSKpBxWz4GSFMu/SS8ZtL6Hsb90vonm4K0/Dcz
gIkP7rMTX2yAf4e/5qjuAn66sdi3Kpn234djunXh3Zb1XzjQ+/nF+sS4EQc73j3YFw14oT
N6dZnsRXKUfbV14qSMGoOR2/Taia0NRnYwvu85pxS4Ru5YUBvrktLxc7qp3T+fD6D/dThe
HavMv93MKqLh4lIsMYR10ccRX8bkpz98NU6ZTf9gbfx+JxCq2ya0jksdEt81IzVHdaGI8y
SEQ5V9GS19xsLV3wkCskDmopEXrAFf5Q2WzL/pJosPmtyA39Cc0dm+Z/ADBMD835KmI8ma
8ZAIhoJPuwAAA8BXAkYaVwJGGgAAAAdzc2gtcnNhAAABAQCM/D2lHECFCvpNkxIqkHFbPg
ZIUy79JLxm0voexv3S+iebgrT8NzOAiQ/usxNfbIB/h7/mqO4Cfrqx2Lcqmfbfh2O6deHd
lvVfOND7+cX6xLgRBzvePdgXDXihM3p1mexFcpR9tXXipIwag5Hb9NqJrQ1GdjC+7zmnFL
hG7lhQG+uS0vFzuqndP58PoP91OF4dq8y/3cwqouHiUiwxhHXRxxFfxuSnP3w1TplN/2Bt
/H4nEKrbJrSOSx0S3zUjNUd1oYjzJIRDlX0ZLX3GwtXfCQKyQOaikResAV/lDZbMv+kmiw
+a3IDf0JzR2b5n8AMEwPzfkqYjyZrxkAiGgk+7AAAAAwEAAQAAAQAettchMNH3igg0vT0g
a75eT9ljiUe723R1/DGEYfqrK1dUoDmYltgQAQwpBvdJ+yPVZLgQYq4TehNnKlzhGZC4at
D1rrfJpBkJqSGSO3x/oLqu7wICbTu17ffhOotLsoBQMuGZr14ixZFGN3Kf1iyEAODbAGWn
Owu21CM/RK6VqOSycAoqmnlsaOqaf71FzbNCbgo9eAQjY0Zo7Oxil2RBOV24ZwazEDiue+
XTsSSe/yrJ0p4nJyBdSaLAFiJsCnG66w63ZJY8yleg389OsUEM2B1UTFe4RUPhinXoXjXy
d8+VvE8MfR3uF8xlB4MwN4j9qqfyApWHhO9/cwtr7tiBAAAAgEixCMxVmen36NMPXzepBS
nuxBmevaKWViHpIYxmKzfFhMPmhK6ix07UyFqc/47Q6p6qPyQQj3AZNnz8Ycibaco0Oi+B
RfzvxpaxIADWIrJBx3AbgU7iB6xqZ1kvQLjeP9o2OqsAZ2b5ni2M/CAmGhPcWXYxpEHjWm
b3tRLDnaBQAAAAgQDB9yoFfLtwdSyUmeuY3Yd8MbKA2BJpUv7Wbw8xCX+0mncDmXZ+O8L8
MPEYw/4Rn0W5YDpnhB4cUuvkKVmsqHEbDARMSJybkPVGbcfLjake3mYq1bW1cF5njPGHgm
PbSIhN/ilOdwUSa/6nr46YeA3E/WZ0x3jjvpnYJzV5VZcHgQAAAIEAuhNZcZsXt3DWEY/M
zcxzjP4WRx4udUbD9JFMQ27iFtlh8wJEwvBMLGnN9uLwotFDixqizbHBhMLadzK3F6QWzz
aY6dHtZGay0VUeIhA1kv8lGpKhxB+9MByCeYKfJeA40wux/Mw7Jv8SYaIjaSULCft9d4Fw
z3ANjvud08QWFTsAAAAJREVWX2FkbWluAQI=
-----END OPENSSH PRIVATE KEY-----
Порядок работы с корпоративным GitLab репозиторием
Для корректного процесса CI/CD, структуризации и прослеживаемости разработки для всех кодовых репозиториев разрабатываемых проектов применяется следующий набор правил:
- Все проекты должны быть группированы по принципу <подсистема/мастер проект>[/подпроект]/<frontent/backend> или <подсистема/мастер проект>/подпроект, например: cok/lms/backend или cok/video-store
- Все проекты имеют три обязательные ветки: main (по умолчанию), stage и production.
Ветка main используется для сборки ПО в репозиторий testing
Ветка stage используется для сборки ПО в репозиторий staging
Ветка production используется для сборки ПО в репозиторий stable - Все три обязательных ветки являются защищенными (protected) ветками репозитория. Прямая фиксация изменений (Push) в эти ветки разрешена только мейтнерам (владельцам) проекта. Запрос на слияние (Merge request) другим разработчикам разрешен только в ветку main.
- Репозиторий может содержать дополнительные служебные ветки имеющие формат именования stand/<feature>. Такие ветки используются для автоматической сборки и развертывания стенда в среде Kubernetes. По окончанию сборки, разработчику осуществляющему фиксацию изменений отправляется сообщение с адресом стенда или ошибкой сборки контейнера на электронную почту, указанную в свойствах профиля GitLab, как Private Email.
- Репозиторий может содержать иные ветки с наименованием разрабатываемого функционала. Наименование должно состоять из 1-2 слов на английском языке, разделенных символом тире.
- Каждая фиксация изменений должна сопровождаться комментарием со сведениями о вносимом изменении. Если изменения не значительны, проводятся только для форматирования кода или для запуска процесса сборки стенда, допускается указывать прочерк (символ тире) в качестве текста комментария. Комментарии, за исключением служебных, попадают в журнал изменений проекта (changelog).
- Если требуется провести очистку базы данных и постоянных томов стенда, используется слияние изменений с ключевым словом CleanStand в качестве значения комментария.
Аутентификация, Авторизация, Аудит
Общие положения
Основной задачи системы AAA/IAM является управление базой учетных записей пользователей, выдача разрешений и аудит доступа к ресурсам связанных с IAM подсистем.
Основные механизмы аутентификации базируются на принципах протокола Kerberos v5 с расширениями (Claims), применительно к системам веб аутентификации (jwt), включая возможности делегирования, пересылки токена, двусторонней аутентификации, запроса расширений авторизации по сервисному имени принципала (SPN).
Использование механизмов, завязанных на принципала, с использованием технологии электронных подписей совместимых со стандартом JWT позволяют проводить следующие способы аутентификации пользователя:
- Аутентификация по логину-паролю (ключевая пара)
- Сквозная аутентификация по сертификатам электронной подписи
- Аутентификация по одноразовому ключу (SMS, OTP)
- Аутентификация по оффлановому токену (QR-код) без доступа к IAM
- Аутентификация по сохраненному токену (Progressive Web Application, HTML5 Offline Application)
- Прокси-аутентификация со стороннего сервиса (OAuth2/SAML 2.0)
Общий формат записи токена аутентификации:
{
"principal": "User Principal Name",
"uid": "GUID",
"displayName": "User Published Name",
"groups": [...],
"claims": [...],
"principalSignature": "jwt digest/RSA|ECDSA 2048bit",
"signature": "jwt digest/RSA|ECDSA 2048bit"
}
Поля Groups, Claims и PrincipalSignature могут отсутствовать. В качестве обязательного идентификатора пользователя выступают поля Principal и UID
Архитектура
Архитектура сервиса IAM предполагает наиличие модульного механизма работы с поддержкой горизонтального масштабирования. Сервис IAM состоит из нескольких независимых максштабируемых сервисов:
- AAA — Сервис аутентификации, авторизации и аудита. Отвечает за выдачу токенов, производных токенов (для каждого SPN) и запись событий доступа.
- Profile — Сервис управления профилем пользователя, хранит сведения о профиле пользователя, позволяет хранить ряд дополнительных данных, таких как связаныне документы, изображения, дополнительные реквизиты и т.п.
- Permission — Сервис управления доступом. Управляет видами групп доступа для каждого сервиса и ролями доступными пользователю.
Общая схема работы OAuth2 сервиса:
Сервер поддерживает как обязательные (базовые) механизмы OAuth2, так и расширенные (опциональные) механизмы аутентификации и делегирования токена. В качестве расширений механизмов аутентификации вводятся дополнительные сущности - UserPrincipalName, OrganizationPrincipalName и ServicePrincipalName, где UPN и OPN относятся к категории субъекта аутентификации, а SPN - к категории конечной точки аутентификации. OAuth2 токен (Bearer) формируется по стандарту JWT и может использоваться в оффлайн операциях в течение всего срока (времени жизни) такого токена.
При прохождении процедуры аутентификации в системе цифрового паспорта пользователь получает базовый цифровой ключ доступа в виде JWT токена, кодированного в Base64 для передачи по техническим каналам связи или в открытом виде для формирования оффлайн QR кода. Допускается использовать формирование QR кода на основе Base64 кодированного JWT токена, для поддержки данного требовани рекомендуется использовать следующий алгоритм:
- Попытка расшифровать JSON
- Если расшифровать JSON не удается (ошибка в 1 символе) - производится декодирование Base64 в строку
- Осуществляется повторная попытка декодирования JSON
- Проверяется корректность подписи JWT
- Проверяется срок действия JWT
После того как базовый токен аутентификации получен, он может использоваться для доступа к различным сервисам, с минимальным уровнем гарантированных привилегий. В случае если сервис поддерживает механизмы работы оффлайн, он может содерждать реплику групп безопасности сервиса для аутентификации пользователя. Для получения полного доступа к ресурсам после процедуры аутентификации производится:
- Выбор роли пользователя в системе - присвоение UID или OID и расширенных атрибутов (расширенный JWT токен) - утверждений
- Расширенная аутентификация в сервисе - получение SPN для запрашиваемого ресурса
- Получение специального токена для запрашиваемого ресурса по его SPN
Общий набор полей всех JWT токенов является одинаковым, но для каждого типа токенов характерны выделенные специальные поля. Состав и форматы полей JWT токенов описаны ниже.
Набор функций сервиса зависит от совпадения набора требований и утверждений сервиса и JWT токена для доступа к тому или иному функционалу приложения. Любой полученный токен имеет свой срок действия, может быть обновлен в преедах окна обновления и содержит валидную (проверяемую) цифровую подпись системы цифрового паспорта АО НК. Любой токен может быть использован оффлайн для аутентификации пользователя, например для каждого сервиса может быть сгенерирован отдельный временный оффлайн токен доступа в виде QR кода. Стандартный период действия токена составляет 2 часа, базового токена - 8 часов. При необходимости может быть запрошен токен расширенного срока действия, но не более 168 часов (7 дней) с момента получения такого токена.
При делегировании токена нижестоящей системе, промежуточный узел может как передать токен в режиме "как есть" (прокси-токен) или получить на его основании новый SPN токен для конечного сервиса. В этом случае для получения нового SPN сервис обращается к системе цифрового паспорта за делегированием токена передавая:
- Токен пользователя (SPN JWT)
- Адрес конечного сервиса
Срок действия делегированного токена сервиса не должен превышать срок использования оригинального токена пользователя.
Возможность продления истекшего JWT токена не допускается, из такого токена могут быть получены основные реквизиты для запроса подтверждения (аутентификации) со стороны пользователя с целью выпуска нового JWT токена с теми же условиями (Владелец, Организация, Сервис).
Попроектная кадрово-организационная структура
Технические требовния на систему управления задачами
Цели создания системы
Основной целью создания системы является систематизация управленческих и рабочих задач в рамках существующих процессов и реализующихся проектов компании. Сопутствующей целью создания системы - является прослеживаемость выполняемых задач сотрудниками компании для оптимизации трудовых ресурсов.
Вводимые термины и определения
В рамках настоящей технической спецификации вводятся основные термины и определения:
- Процесс — Решаемая глобальная задача имеющая одну или несколько целей, несколько исполнителей, характеризующаяся отсутствием конечного срока и набора подзадач. Подзадачи процесса формируются по мере поступления информации от участников такого процесса или явлсются следствием выполнения других (связанных) подзадач. Каждая подзадача процесса всегда направлена на достижение конкретной цели и имеет свой приоритет выполнения. Может затрагивать проекты и формировать дополнительные промежуточные цели проектов.
- Проект — Любое разрабатываемое решение, такое как: программное обеспечение, аппаратный комплекс, инженерное сооружение, законодательный акт или иной субьект права собственности, являющийся конечным продуктом проекта. Проект всегда завершается созданием артефакта в форме нематериального актива или основного средства. Проект может быть заранее подергнут процессу декомпозиции на промежуточные цели, задачи, подзадачи, проектные команды. В рамках проекта формируются и закреплаются артефакты, такие как техничекие спецификации, технические задания, архитектурные планы, дизайн-макеты и иные сопутствуюшие документы необходимые для целей реализации проекта.
- Промежуточная цель — Этап Процесса или разработки Проекта имеющий собственное описание, точные или оценочные сроки выполнения цели и набор вводных и результирующих документов (артефактов) цели.
- Задача — Сформулированное конечное требование для одного или нескольких исполнителей. Задача имеет следующий набор атрибутов:
- Наименование задачи
- Описание задачи
- Вложенные документы
- Дата постановки задачи
- Дедлайн задачи
- Состояние задачи
- Приоритет задачи
- Проект/Процесс задачи
- Промежуточная цель задачи
- Автор задачи
- Ответственный по задаче
- Исполнители задачи
- Родительская задача
Задача может иметь декомпозицию в виде дерева подзадач, для каждой из которых могут быть назначены свои ответственные и исполнители. Список исполнителей и документов всех подзадач всегда отражается в родительской задаче.
- Календарь — Датированное представление задач в разрезе сохраненного фильтра, имеющий ссылку для доступа по протоколу CalDAV для чтения расписания и управления задачами. Цели обозначаются выделенной датой на календаре специальной рамкой и цветом.
- KanBan Доска — Постолбцовое представление задач в разрезе сохраненного фильтра. Столбец определяется условием группировки задач, может быть одним из атрибутов задачи (Состояние, Приоритет, Проект/Процесс, Цель, Автор, Ответственный, Дата постановки, Дедлайн), при этом для дат используется округление до недели, месяца или квартала по выбору пользователя. Задачи могут быть отсортированы по дате постановки, дедлайну, состоянию, приоритету, автору или ответственному. Цель выводится как одно из полей задачи.
- Диаграмма Ганта — Линейное представление задач в разрезе сохраненного фильтра. Данная диаграмма имеет вид хронологического горизонтального представления календаря, разделенного на Годы, Кварталы, Месяцы, Недели, Дни недели, где задачи представлены в виде плашек, распространяющихся от даты постановки задачи до её дедлайна или назначенной промежуточной цели. Порядок пересекающихся задач, приходящихся на один период времени может быть отсортирован по дате постановки, состоянию, приоритету, автору или ответственному. Цели отображаются в виде сплошных вертикальных плашек, затрагивающих дату завершения промежуточной цели.
- Список задач — Представление задач в виде таблицы с указанием наименования задачи, автора, ответственного, исполнителей, цели, приоритета и сроков выполнения задачи. Задачи выстраиваются в рамках иерархии подзадач. Сортировка может осуществляться по любому столбцу с учетом иерархии задач. Задачи могут быть сгруппированы аналогично KanBan доске.
- Дашборд — Специальное представление, задач, имеющее набор настроек внешнего вида: Гант, Доска, Календарь, Список; а так же набора фильтров по статусу, сотрудникам, датам, целям, проектам/процессам, приоритету, состоянию. Набор фильтров и внешний вид дашборда может быть сохранен как публичное или приватное представление, а так же иметь публичную ссылку в режиме "Только для чтения". Публичное представление может быть назначено на группу пользователей. При переключении настройк внешнего вида параметры фильтра и группировки сохраняются и применяются к выбранному внешнему виду.
- Группа пользователей — Выделенная группа пользователей, имеющих одинаковые настройки интерфейса, перечень доступных проектов и процессов, представлений и набор привилегий. Привилегии назначенные для разных групп пользователей суммируются для каждого конкретного пользователя, в случае их пересечения. Группа пользователей может иметь фильтр автодобавления, при котором все новые пользователи, соответствующие критериям фильтра автоматически будут добавлены в группу (автопополняемая группа).
- Пользователь — Сотрудник организации или внешний контрагент прошедший процедуру аутентификации и входящий в одну или несколько групп пользователей. Если пользователь не имеет ни одной назначенной группы, такой пользователь относится к служебной группе "Гости" и может просматривать только публичные представления.
- Отчет — Формируемый по расписанию срез задач, согласно заданному фильтру задач, содержит ссылку на интерактивный дашборд с применением указанного фильтра, в котором можно изменять внешний вид задач: Список, Календарь, Гант, Доска. Отчет может быть направлен по любому каналу уведомлений.
- Уведомления — Системное сообщение отправляемое по одному или нескольким каналам связи: Мгновенное сообщение (Telegram), Электронная почта, Push уведомление и т.п. Уведомления вызываются по триггеру события. Типы получаемых уведомлений настраиваются для каждого пользователя индивидуально. Уведомления по событиям могут аккумулироваться для пользователя, и отправляться одним сообщением, если для данного типа уведомлений указан период группировки сообщений и время отправки уведомления.
- Журнал — Системный журнал событий, включающий в себя действия пользователя, от момента аутентификации, до момента получения уведомления. Все операции изменения задачи пользователем попадают в журнал и могут быть отслежены как в отдельной задаче, так и формировать уведомление пользователя или группы по условию. По каждой задаче ведется контроль наличия изменений, относительно последней даты доступа пользователя к задаче и отображается пользователю путем цветового выделения задачи более ярким цветом или рамкой.
- Чат — Внутренняя система обмена мгновенными сообщениями. Чат является самостоятельным представлением, но может быть открыт в качестве виджета или отображаться в рамках задачи, к которой он относится. У каждой задачи может быть свой чат, который становится доступен всем участникам задачи (Автор, Ответственный, Исполнители) при отправке первого сообщения. Чаты группируются по проекту и задаче к которой они относятся. Для выполненных (завершенных) задач чат скрывается из общего списка чатов, список чатов включает в себя только активные/действующие задачи пользователя, связанного с такой задачей. Количество новых сообщений отображается в виде цифры в круглом блоке поверх соответствующещй задачи, в заголовке страницы и в окне чата для каждого чата сответственно.
Технические требования к реализации системы
Система управления задачами должна обладать набором слудующих обязательных характеристик:
- Аутентификация
- Доменная
- OAuth2
- Реактивность (Интерфейс зависит от поступаемых данных и отрисовывается на стороне клиента)
- Интерактивность (Все изменения задач в системе отражаются в виде событий и доставляются активным сессиям пользователей)
- Адаптивность (Возможность взаимодействия с основными функциями интерфейса как на мобильных устройствах, так и на ПК)
- Масштабируемость (Возможность запуска множества экземпляров Backend и Frontend серверов с общим центральным хранилищем, например с использованеим брокера RabbitMQ Stream)
- Поддерживаемость (Наличие сборочного сценария и документации на систему разработки и сборки проекта)
- Переносимость (Возможность развертывания в виде OnPermisse или облачного решения на стороне конечного заказчика)