Перейти к основному содержимому

Identity Admin API — реестр методов и общие правила области

Реестр admin-методов identity (контекст identity, сервис Pin.Identity.Api, area admin) и общий дом правил этой области: модель актора администраторов платформы (m2m, ADR-0053), policy AdminSystemOnly, обязательные заголовки, deep audit мутаций, соответствие permission-каталогу. Область обслуживает администраторов платформы, которые живут в отдельной системе администрирования и обращаются к identity через m2m-API — самих администраторов и их MFA identity не хранит (ADR-0053). Документы методов ссылаются сюда и описывают только свою дельту; общий конверт ответа/ошибок — в ../README.md; дома полей — ../../domain/.

Metadata​

ПолеЗначение
Сервис/контекстidentity
API areaadmin (m2m, ADR-0053)
Тип документаapi (area-registry, не единичная операция)
Статусdraft
OwnerPIN Platform Core
Область действияadmin-операции над учётками (блокировка/удаление/сброс факторов/отзыв сессий); public- и internal-области — отдельные реестры (../README.md, ../internal/, ../company-user/)
Assumptionsсистема администрирования платформы (ADR-0053) — единственный клиент области; permission-каталог — ../../domain/permission.md, для неё каталог справочный

Реестр методов​

Route-префикс области — /api/admin/v1/. Все проверки — каталожное соответствие поверх policy AdminSystemOnly (см. ниже).

МетодRouteFeature groupPermission (каталожное соответствие)Документ
POST/api/admin/v1/users/{userId}/block · /unblockadmin-usersidentity.users.block + identity.users.view-allblock-user.md (unblock — симметричная дельта)
DELETE/api/admin/v1/users/{userId}admin-usersAdminSystemOnly (+AdminPrivilegedOnly для Purge)delete-user.md (архив vs полное удаление)
POST/api/admin/v1/users/{userId}/security/resetadmin-usersAdminSystemOnly (после ручной верификации)reset-user-security.md
POST/api/admin/v1/users/{userId}/sessions/revokeadmin-sessionsAdminSystemOnly (+ user-activity.sessions.* для витрины)revoke-user-sessions.md

Модель актора и доступ (общий дом)​

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

ПроверкаЗначение
Actor typeExternalSystem — система администрирования платформы
AuthOAuth2 client-credentials (m2m), клиент pin-admin-system — ADR-0053
Auth policyAdminSystemOnly: токен выдан клиенту pin-admin-system; иначе 403
PrivilegedAdminPrivilegedOnly для необратимых операций (Purge) — требует MFA/второго approve на стороне системы администрирования (граница admin-identity, ADR-0053)
Записи о вызывающем администратореidentity знает систему; конкретного администратора несёт заголовок X-Admin-User-Id (actor-stamping)

Обязательные заголовки области​

ЗаголовокГде обязателенНазначение
X-Admin-User-Idвсе методыGuid администратора-инициатора внутри системы администрирования. Actor-stamping (UpdatedByUserId/DeletedByUserId) и subject deep audit: m2m-токен идентифицирует систему, заголовок — человека. Пустой/отсутствует → ValidationError/401.
Idempotency-Keyмутации (все методы области — POST/DELETE)Guid; клиент ретраит по таймауту. Повтор с тем же ключом → сохранённый результат (replay), шаги не повторяются. Ключ идемпотентности — admin:<operation>:{Idempotency-Key}.
traceparentвсеOpenTelemetry trace для correlation.

Deep audit admin-мутаций​

Каждая мутация области попадает в deep audit — блокировки/удаления/сбросы факторов и отзыв сессий помечены как чувствительные:

  • actor — X-Admin-User-Id (+ m2m-клиент pin-admin-system);
  • объект — UserEntity + UserId;
  • диф полей — before/after изменённых полей (значения секретов не логируются — только факт сброса);
  • результат — success либо код ошибки.

Запись audit фиксируется в одном согласованном изменении вместе с мутацией агрегата, отзывом RefreshSession и публикацией событий. Audit не tenanted (инвестор вне tenant; учётки менеджеров — по CompanyId).

Интеграционные последствия и окно согласованности (общий дом)​

Единые правила распространения эффектов admin-мутаций — что закладывать при интеграции:

  • Эффекты асинхронны. Мутация в identity видна сразу после коммита; downstream (gateway, crm/messenger/notifications/user-activity) применяет изменение по событиям pin.identity.* с лагом в секунды. До применения потребитель может краткий промежуток видеть прежний snapshot.
  • Немедленная защита доступа. Вход и refresh блокируются немедленно (проверка Status/отозванных сессий). Уже выданные access-JWT дорабатывают TTL (≤ 15 мин), но привилегированные операции gateway отклоняет раньше — по кэшу отозванных sid (вытеснение ≤ 60 сек) и internal permission-check.
  • Кто побеждает при гонке. Мутации версионированы: конфликт с консюмером синка Talent или второй admin-операцией даёт CONCURRENCY_CONFLICT (409); система администрирования перечитывает актуальную версию и повторяет с тем же Idempotency-Key (replay защищает от двойного эффекта). Для Talent- управляемых учёток PII-операции (Purge) уступают источнику — Talent Identity (см. delete-user).
  • Erasure-контракт. При анонимизации PII потребители обязаны перезаписать свои PII-реплики по UserUpsertedKafkaEvent с анонимизированным снапшотом; полнота перезаписи контролируется runbook.

Общий конверт и коды ошибок​

  • Успех — типизированная модель результата; дом моделей конверта — ../README.md.
  • Ошибка — RestApiErrorResponse с машинным message-кодом и traceId; enum сериализуются строкой.
КодHTTPУсловиеRetry
ValidationError400Синтаксис/enum; пустой X-Admin-User-Id/Idempotency-Keyno retry
UNAUTHORIZED401Нет/просрочен m2m client-credentials токенno retry
FORBIDDEN403Клиент не pin-admin-system либо нет privileged-подтверждения (Purge)no retry
IDENTITY_USER_NOT_FOUND404Целевой UserId не существуетno retry
CONCURRENCY_CONFLICT409Гонка версий (Version) с консюмером синка или вторым админомretry с тем же Idempotency-Key после перечитки

Method-specific коды IDENTITY_* — в документах методов и разделе «Инварианты» дома ../../domain/user.md.

Связанные документы​