# Перевоплощение

Перевоплощение — механизм, позволяющий администратору (или пользователю с соответствующими правами) работать в системе **от имени другого пользователя**. Перевоплотившийся видит то же, что видит целевой пользователь; используется для отладки прав, настройки интерфейса и поддержки. **Не путать** с замещением: замещение передаёт права, а перевоплощение создаёт **новую сессию** от имени целевого пользователя. Документ описывает права и порядок их проверки, REST API начала и завершения, механику JWT-сессии, аудит, влияние конфиденциальности и шифрования, интерфейс и действующие ограничения.

## Права на перевоплощение и порядок их проверки

Право перевоплощаться можно получить тремя способами:

| # | Способ | Условие |
|---|---|---|
| 1 | **Системная группа «Администраторы»** | Пользователь в группе Administrators, и группе не выдано спецправо DENYIMPERSONATION |
| 2 | **Право группы на группу** | Право «Перевоплощаться в членов группы». Не-админ не может перевоплощаться в администратора |
| 3 | **EWS (Exchange)** | Для синхронизации календаря. Настройка `CalendarExchangeUseImpersonate` или общая настройка «Использовать перевоплощение» |

Возможность перевоплощения система проверяет по шагам:

1. Если у пользователя есть спецправо `DENYIMPERSONATION` — перевоплощение запрещено.
2. Если пользователь — администратор — перевоплощение разрешено (в любого пользователя).
3. Если целевой пользователь — администратор, а инициатор — нет — запрещено.
4. Иначе проверяется право группы на группу «Перевоплощаться в членов группы».

Спецправо `DENYIMPERSONATION` назначается **группе**. Если пользователь входит хотя бы в одну группу с этим правом — перевоплощение для него **запрещено** (даже если он администратор). **Ограничение:** нельзя назначить DENYIMPERSONATION группе «Администраторы». Право хранится в таблице `GroupPermissionsToSpecialActions`.

## API перевоплощения: начало и завершение

Перевоплощением можно управлять через REST API. Для начала перевоплощения используется запрос:

```
POST /api/auth/{userId}/impersonate
```

**Ответы:**

- `204 No Content` — успешно, последующие запросы идут от имени целевого пользователя;
- `403 Forbidden` — нет прав или попытка вложенного перевоплощения.

**Ограничение:** вложенное перевоплощение запрещено — при попытке перевоплотиться, уже будучи перевоплощённым, возвращается 403.

Завершение перевоплощения делается запросом:

```
POST /api/auth/undotransformation
```

**Ответ:** `204 No Content` — сессия возвращается к реальному пользователю.

## Механика сессии (JWT) при перевоплощении

Что происходит на уровне сессии при перевоплощении (полезно для диагностики):

1. Система создаёт новый JWT-токен.
2. В новом токене `SessionUserId` — целевой пользователь, `OldUserId` — инициатор.
3. Поле `ImpersonatedUserId` доступно всем сервисам для проверки, кто инициатор.
4. Все действия выполняются **от имени** целевого пользователя.
5. При завершении перевоплощения токен возвращается к исходному пользователю.
6. Проверяется наличие действующей лицензии у целевого пользователя. Если лицензии нет — перевоплощение не выполняется.
7. Токен перевыпускается только после успешной проверки лицензии.

### Перепроверка права при продлении сессии

Право на перевоплощение проверяется не только при входе в режим, но и при каждом продлении маркера доступа.

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

## Аудит перевоплощений (таблица TransformationLog)

Каждое перевоплощение логируется в таблицу `TransformationLog`.

| Колонка | Тип | Описание |
|---|---|---|
| `TransformationLogID` | int, PK, Identity | ID записи |
| `OldUserID` | int, FK → Users | Инициатор перевоплощения |
| `NewUserID` | int, FK → Users | Целевой пользователь |
| `TransformationTime` | datetime | Время события |
| `UserComputerName` | varchar(300) | Имя компьютера / IP инициатора |
| `IsReturn` | bit | `0` = перевоплощение, `1` = возврат |
| `UserAgent` | varchar(512), NULL | User-Agent браузера |

**Запись создаётся при:** перевоплощении (`IsReturn = 0`) и возврате (`IsReturn = 1`).

**Просмотр:** вкладка «Журнал» в профиле пользователя. Видят: администраторы (журналы всех пользователей), пользователь (свой журнал).

![Запись о перевоплощении в журнале пользователя: время и имя инициатора](https://help.1forma.ru/help-images/permissions/alien-04.png)

## Защита данных при перевоплощении: конфиденциальность, шифрование, матрица

С версии 2.268.326 перевоплощение **блокируется** конфиденциальностью. При перевоплощении проверяются права обоих пользователей — инициатора и целевого. Если целевой пользователь — подписчик конфиденциальной задачи, а перевоплощающийся администратор — нет, содержимое скрывается, а задача исключается из основных списков.

**Что скрывается:**

- Текст задачи → `(Текст задачи скрыт)`
- Текст комментариев → `(Комментарий скрыт)`
- Файлы — недоступны (проверка доступа учитывает обоих пользователей)
- Таблицы внутри карточки задачи — блок «Используется» и таблица дополнительного параметра — проверяют доступ к задаче по обоим пользователям: если конфиденциальная задача закрыта для действительного пользователя, запрос данных такой таблицы отклоняется до чтения данных
- Попытка добавить или переслать комментарий к конфиденциальной задаче — отклоняется
- Строки дерева подзадач и панели связей — право считается по обоим пользователям: если задача подписана тому, под кого перевоплотились, но не тому, кто перевоплотился, в строке остаются только номер и место в дереве, а текст, категория, статус, заказчик, исполнитель и сроки показывают «Нет доступа». Правило одинаково для всех выдач дерева подзадач и связей и для канбана задач
- Строка связанной задачи в блоке связанных задач карточки — право на неё тоже считается по обоим пользователям: если связанная задача конфиденциальна и подписана тому, под кого перевоплотились, но не действительному пользователю, строка приходит без описания, состояния, назначившего и исполнителя, а сама связь и место строки в списке остаются видимыми
- Значения дополнительных параметров конфиденциальных задач в реестрах — строковые заменяются на `****`, значения остальных типов (число, дата, дата и время, деньги, чекбокс, выбор пользователей, лукапы) показываются пустыми

**Что фильтруется** (задача исчезает из списков):

- Ленты задач, комментариев и обсуждений
- История просмотров
- Глобальный поиск

**Что остаётся видимым** (известные ограничения текущей версии):

- Избранное — задача остаётся в списке, заголовок заменяется на `(Текст задачи скрыт)`
- Счётчики непрочитанных и сигнальные события — продолжают учитывать конфиденциальные чаты
- Push-уведомления, всплывающие уведомления и события о новом сообщении — не блокируются
- Попытки доступа из-под перевоплощения отдельным журналом не выделяются; отказ по конфиденциальной задаче при импорте значений ДП из CSV попадает в общий журнал отказов по правам (`logs/<дата>/access-denied.log`)

Шифрование также **блокирует** перевоплощение. При перевоплощении проверяются права **обоих** — инициатора и целевого пользователя. Оба должны иметь право «Просмотр зашифрованных задач», чтобы увидеть расшифрованные данные.

**Что скрыто** при отсутствии права хотя бы у одного из двух:

- Зашифрованные ДП — пустые или скрытые
- Виртуальные колонки табличного дополнительного параметра, которые ссылаются на шифрованную задачу, — заглушка `****`, в том числе в множественном выборе; подписка администратора, начавшего перевоплощение, значения не открывает
- Запись дополнительных параметров в шифрованную задачу через `api/mcp/extparams/update` без доступа к содержимому отклоняется до записи
- Текст задачи — не отображается
- Файлы — недоступны для скачивания
- Комментарии — текст скрыт

Сводно по двум механизмам разграничения доступа:

| Защитный механизм | Замещение | Перевоплощение |
|---|---|---|
| **Конфиденциальность** | Заблокировано | Заблокировано (с 2.268.326) |
| **Шифрование** | Заблокировано | Заблокировано (оба должны иметь право) |
| **Конфиденциальность + шифрование** | Заблокировано | Заблокировано |

## Интерфейс перевоплощения: веб и мобильное приложение

В веб-интерфейсе перевоплотиться можно двумя путями. Первый — открыть профиль нужного пользователя (панель навигации → «Сотрудники» → выбрать пользователя) и нажать значок перевоплощения на панели инструментов профиля.

![Пункт «Перевоплощение» в меню профиля пользователя](https://help.1forma.ru/help-images/permissions/impersonate_profile_menu.png)

Второй — прямо в справочнике «Сотрудники»: найти пользователя поиском и навести курсор на строку с ним, после чего в строке появляются кнопки действий, включая перевоплощение.

![Кнопки действий в справочнике «Сотрудники» (появляются при наведении на строку)](https://help.1forma.ru/help-images/permissions/alien-02.png)

Во время перевоплощения в верхней панели показывается зелёный индикатор с именем целевого пользователя; выход из режима — по крестику на индикаторе.

![Зелёный индикатор перевоплощения с именем пользователя и крестиком выхода](https://help.1forma.ru/help-images/permissions/impersonate_indicator.png)

В мобильном приложении перевоплощение также доступно.

## Ограничения и связанные материалы

Перевоплощение работает с рядом ограничений:

| Ограничение | Описание |
|---|---|
| **Вложенное перевоплощение** | Запрещено. Нельзя перевоплощаться, будучи перевоплощённым |
| **Лицензия** | У **целевого пользователя** должна быть действующая лицензия (не-конкурентная). Проверка выполняется при начале перевоплощения; если лицензии нет — перевоплощение блокируется |
| **Не-админ → админ** | Пользователь без прав администратора не может перевоплотиться в администратора |
| **DENYIMPERSONATION** | Блокирует перевоплощение даже для администратора |
| **Отзыв права во время сессии** | Завершает сеанс перевоплощения не позже следующего продления маркера: новый маркер не выпускается |
| **Нельзя применить DENYIMPERSONATION к группе «Администраторы»** | Защита от самоблокировки |
| **Самозащита от снятия запрета** | Администратор с выданным запретом перевоплощения не может сам деактивировать это спецправо и редактировать состав группы, в которой состоит (только для группы с этим правом) |

**Связанные материалы:**

- [Права доступа к задачам](https://help.1forma.ru/domains/permissions/business.md) — конфиденциальность и шифрование
- [FAQ: видимость кнопки «Поставить отсутствие»](https://help.1forma.ru/domains/users-and-groups/faq-absence-button-visibility.md) — специальные права групп