05.03 Auth, Sessions And Invitations

Статус: черновик для обсуждения

1. Назначение документа

Этот документ описывает authentication и session management для Back Office.

Документ покрывает:

• login;
• 2FA;
• user invitations;
• forgot password;
• sessions;
• remember me;
• session termination;
• bootstrap first admin user.

2. Login

Login выполняется по:

• email;
• password.

После успешной проверки email/password система должна пройти 2FA step.

Back Office login общий для:

• platform users;
• merchant users.

После login доступные sections/pages/actions определяются permissions.

User type выбирается при создании user-а:

• platform user;
• merchant user.

User не может одновременно быть platform user и merchant user.

User не может одновременно иметь platform role и merchant access.

User type после создания не меняется в MVP.

Минимальные поля user-а:

• email;
• first name;
• last name;
• status;
• user type.

Phone в MVP не нужен.

Email должен быть уникальным и не может быть переиспользован после soft-delete user-а.

3. 2FA

2FA обязательна для всех users в MVP.

2FA обязательна во всех Back Office environments:

• dev;
• stg;
• prod.

Login without 2FA в dev/stg для тестирования не разрешается на product level.

2FA реализуется через authenticator app.

Примеры:

• Google Authenticator;
• Microsoft Authenticator;
• 1Password;
• Authy;
• другие TOTP-compatible apps.

Email code не используется как основной 2FA метод для login.

OTP для sensitive actions также берется из authenticator app.

В MVP OTP confirmation для sensitive actions требуется только для:

• API key rotation;
• API key revoke.

OTP confirmation должен запрашиваться каждый раз при sensitive action.

Remember / trusted confirmation window для sensitive actions в MVP не нужен.

Backup recovery codes для 2FA в MVP не нужны.

4. 2FA setup

User должен настроить authenticator app во время initial account activation или первого login, если 2FA еще не настроена.

Минимальный flow:

1. User открывает invite link или проходит first login.
2. User задает password, если account activation еще не завершен.
3. Система показывает QR code / setup key для authenticator app.
4. User сканирует QR code или копирует setup key в authenticator app.
5. User вводит code из authenticator app.
6. Система подтверждает 2FA setup.
7. User получает доступ в Back Office.

Точный UX должен быть описан в design.

Если user не настроил 2FA, он не должен получить полноценный доступ в Back Office.

После password reset 2FA должна быть reset.

После reset password user должен заново настроить authenticator app:

1. Система показывает новый QR code / setup key.
2. User заново сканирует QR code или копирует setup key.
3. User подтверждает setup через OTP code.

Старый authenticator setup после password reset больше не должен работать.

5. Invitations

Users приглашаются через email link.

Invite link используется для:

• подтверждения email;
• initial account activation;
• задания password;
• настройки 2FA.

Temporary password в MVP не используется.

Merchant user создается и активируется через invite link:

1. Platform user или merchant user с permission отправляет invite.
2. User получает email link.
3. User открывает link.
4. User задает password.
5. User настраивает 2FA.
6. User получает доступ только после завершения activation.

Platform user при создании user-а выбирает user type.

Merchant user может быть создан без merchant / merchant group access.

Если user залогинился, но у него нет access context, он должен видеть пустой Back Office без merchant-scoped данных.

Если merchant user-у выдается доступ, доступ должен быть выдан через context:

• merchant context с обязательной role в этом merchant;
• merchant group context as access scope.

Merchant role в MVP назначается только в context конкретного merchant. Merchant role не назначается в context merchant group.

Merchant group access может назначать только platform user с соответствующей permission.

Merchant user с permission может приглашать других merchant users только в merchant context, где у него есть право управлять users.

Merchant user не может приглашать platform users. Merchant user не может выдавать merchant group access.

Повторный invite на email, который уже существует как user или pending invite, должен вернуть ошибку.

Если активному user-у добавляют новый merchant / merchant group access, email notification в MVP не отправляется.

Если user удаляется из merchant context, active sessions завершать не нужно. Система должна сразу пересчитать permissions/access.

Если role или permissions role изменились, изменения должны примениться сразу, включая active sessions.

Если merchant добавили в merchant group или убрали из merchant group, users с group access должны сразу получить или потерять доступ к этому merchant.

Invite link lifetime:

72 hours

Invite lifetime должен быть configurable через environment variables.

Если invite expired:

• user не может активировать account по старой ссылке;
• platform/merchant admin должен использовать resend invite action, если permission позволяет.

Resend invite должен быть доступен как отдельная action/button на user/invite record.

Отдельный invite status CANCELED в MVP не нужен.

Default merchant admin role должна автоматически создаваться seed/bootstrap logic-ой.

Platform admin может потом изменить permissions этой role, если имеет permission manage roles.

6. Forced password change

Forced password change после invite/login в MVP не нужен.

Причина:

• user получает invite link на email;
• user сам задает password во время activation;
• нет временного password, который нужно принудительно менять.

7. Forgot password

Forgot password flow:

1. User вводит email.
2. Система отправляет code на email.
3. User вводит code.
4. User задает новый password.
5. Система reset-ит текущую 2FA настройку user-а.
6. User заново настраивает authenticator app.
7. Старые sessions могут быть invalidated по security policy.

Password reset code lifetime:

30 minutes

Lifetime должен быть configurable через environment variables.

Количество attempts:

3 attempts by default

Attempts count должен быть configurable через environment variables.

8. Session lifetime

Session lifetime должен соответствовать стандартным security practices.

Product baseline:

• regular session имеет limited lifetime;
• inactive session должна истекать после inactivity timeout;
• remember me session может жить дольше regular session;
• API key rotate/revoke требуют OTP confirmation каждый раз.

Рекомендуемый baseline для technical/security discussion:

• access/session lifetime: несколько часов;
• inactivity timeout: 30-60 minutes;
• remember me lifetime: 7-30 days;
• refresh/remember token rotation, если используется token-based auth.

Exact значения должны быть предложены development/security team и зафиксированы в technical design.

9. Remember me

Remember me нужен в MVP.

Если user включает remember me:

• session может жить дольше обычной session;
• устройство должно отображаться в active sessions list;
• user должен иметь возможность terminate эту session.

Remember me не отменяет requirement на 2FA при первичном login/setup.

Точное поведение повторного 2FA prompt при remember me должно быть описано development/security team.

10. Active sessions

User должен видеть свои active sessions в profile.

Session list должна показывать:

• device/browser;
• IP address, если доступно;
• country/location, если доступно;
• created at;
• last active at;
• remember me flag;
• current session marker.

User может terminate любую одну свою session.

Если user terminates current session, его нужно logout.

Если user получает status DISABLED или DELETED, все его active sessions должны быть terminated автоматически.

Кроме active sessions, user должен видеть history завершенных sessions / login sessions в profile.

Session/login history должна показывать доступные безопасные данные:

• device/browser;
• IP address, если доступно;
• country/location, если доступно;
• created at;
• last active at / ended at;
• termination reason, если доступно.

User должен видеть security events в profile:

• login failed;
• password reset;
• 2FA reset;
• new device/IP login notification.

Точный состав security events может быть уточнен technical/security team, но эти события должны быть видимы user-у в MVP.

11. Platform admin session management

Platform admin с permission может terminate sessions других users.

Это нужно для:

• security incidents;
• offboarding;
• suspicious activity;
• support operations.

Terminating another user's session должно попадать в audit log.

OTP confirmation для session termination не нужен в MVP.

12. 2FA reset by admin

2FA user-а может reset-ить:

• platform admin с permission;
• merchant admin с permission для своих merchant users в доступном merchant scope.

После 2FA reset user должен заново настроить authenticator app при следующем login.

2FA reset должен попадать в audit/security log.

13. New device/IP notification

Если user login происходит с нового device/IP, система должна отправить email notification.

Email notification не должна блокировать login сама по себе.

Цель:

• security awareness;
• early detection of compromised account;
• user visibility of suspicious access.

Exact definition of new device/IP должен предложить development/security team.

14. Bootstrap first platform admin

При первом deployment, если в системе нет ни одного user, должна быть возможность создать первого platform user.

Bootstrap flow:

1. Система определяет, что users отсутствуют.
2. Показывает initial setup / create first admin flow.
3. Создается first platform user.
4. Создается platform role:

Admin

5. Role Admin получает все permissions системы.
6. First platform user получает role Admin.
7. User задает email, personal data, password и настраивает 2FA.

После создания первого user bootstrap flow должен быть недоступен.

15. Audit log

Auth/session actions должны попадать в audit/security log.

Минимально:

• invite created;
• invite accepted;
• invite expired;
• invite resent;
• invite rejected because email already exists;
• user merchant access added;
• user merchant access removed;
• user merchant role changed;
• user merchant group access added;
• user merchant group access removed;
• login success;
• login failed;
• 2FA setup completed;
• 2FA reset requested;
• 2FA reset completed;
• 2FA failed;
• password reset requested;
• password reset completed;
• session created;
• session terminated by owner;
• session terminated by platform admin;
• sessions terminated automatically after user disabled/deleted;
• new device/IP login notification sent;
• user locked;
• user disabled;
• user soft-deleted.

Sensitive auth data не должна попадать в audit log.

User profile data может редактировать:

• сам user для своего profile;
• admin с соответствующей permission.

В MVP это относится к:

• first name;
• last name.

Email change в MVP не описывается и должен быть рассмотрен отдельно, если понадобится.

User в status DISABLED можно вернуть в ACTIVE.

User в status DELETED нельзя восстановить.

16. Acceptance Criteria

Auth / Sessions / Invitations считаются согласованными для MVP, если:

• Login выполняется по email/password.
• Back Office login общий для platform users и merchant users.
• User type выбирается при создании user-а.
• User не может одновременно быть platform user и merchant user.
• User не может одновременно иметь platform role и merchant access.
• User type после создания не меняется в MVP.
• User email уникален и не переиспользуется после soft-delete.
• Минимальные поля user-а: email, first name, last name, status, user type.
• 2FA обязательна для всех users.
• 2FA обязательна in dev/stg/prod.
• Login without 2FA in dev/stg не разрешается.
• 2FA реализуется через authenticator app.
• OTP для API key rotate/revoke берется из authenticator app.
• OTP для sensitive actions запрашивается каждый раз.
• Backup recovery codes для 2FA не входят в MVP.
• Если user не настроил 2FA, он не получает полноценный доступ в Back Office.
• Password reset сбрасывает 2FA setup.
• После password reset user должен заново настроить authenticator app.
• Invite отправляется через email link.
• Invite link lifetime 72 hours и configurable через env.
• User задает password сам во время invite activation.
• Forced password change после invite не нужен.
• Temporary password не используется.
• Merchant user может быть создан без merchant / merchant group access.
• User без access context видит пустой Back Office.
• Merchant group access может назначать только platform user с permission.
• Повторный invite на существующий email возвращает ошибку.
• Expired invite можно отправить повторно через resend invite action.
• Отдельный invite status CANCELED в MVP не нужен.
• Добавление user-у нового access context не отправляет email notification.
• Удаление user-а из merchant context не завершает active sessions, а сразу пересчитывает permissions.
• Изменение role/permissions применяется сразу.
• Изменение состава merchant group сразу влияет на group-based access.
• Forgot password работает через email code.
• Password reset code lifetime 30 minutes и configurable через env.
• Password reset attempts default 3 и configurable через env.
• Remember me нужен в MVP.
• User видит свои active sessions.
• User видит history завершенных sessions / login sessions.
• User видит security events в profile.
• User может terminate любую свою session.
• DISABLED/DELETED user автоматически теряет все active sessions.
• DISABLED user можно вернуть в ACTIVE.
• DELETED user нельзя восстановить.
• User может редактировать свои first name / last name.
• Admin с permission может редактировать first name / last name user-а.
• Platform admin с permission может terminate sessions других users.
• OTP для terminate sessions не нужен в MVP.
• Platform admin с permission может reset 2FA user-а.
• Merchant admin с permission может reset 2FA своих merchant users.
• Login from new device/IP отправляет email notification.
• Если в системе нет users, можно создать first platform admin.
• First platform admin получает role Admin со всеми permissions.
• Default merchant admin role создается автоматически.
• Merchant role не назначается в merchant group context в MVP.
• Auth/session actions пишутся в audit/security log.

17. Open Questions

Product open questions отсутствуют.

Technical/security follow-up:

1. Определить exact session lifetime.
2. Определить exact inactivity timeout.
3. Определить exact remember me lifetime.
4. Определить lockout/rate limit policy для failed login/2FA attempts.
5. Определить whether password reset invalidates all active sessions.
6. Определить exact definition of new device/IP.