Версия: 7.0

Токены сессий

Пассворк использует модель аутентификации на основе токенов с парой Access Token / Refresh Token.

Обзор системы токенов

Токен	Назначение	Время жизни
Access Token	Аутентификация API-запросов	~2.8 часа
Refresh Token	Обновление Access Token	36 часов

Почему не JWT?

Токены Пассворка — это случайные строки, а не JWT. Для менеджера паролей такой подход обеспечивает более высокий уровень безопасности:

Характеристика	Токены Пассворка	JWT
Формат	Случайная Base64 строка	JSON с подписью
Информация в токене	Нет	Payload с данными
Валидация	Поиск в базе данных	Проверка подписи
Отзыв токена	Мгновенный (удаление из БД)	Требует blacklist

Преимущества для безопасности:

Мгновенный отзыв сессии. При подозрении на компрометацию администратор или пользователь может немедленно завершить любую сессию — токен удаляется из базы и сразу становится недействительным. JWT продолжает работать до истечения срока действия.
Полный контроль над сессиями. Все активные сессии хранятся на сервере, что позволяет отслеживать устройства, IP-адреса и время последней активности. Администратор видит полную картину и может управлять доступом.
Отсутствие чувствительных данных в токене. JWT содержит payload с информацией о пользователе, которая может быть прочитана (Base64 — это не шифрование). Токены Пассворка — просто случайные идентификаторы без какой-либо информации.
Устойчивость к компрометации ключа. При утечке секретного ключа JWT злоумышленник может создавать валидные токены для любого пользователя. В случае с сессионными токенами такой вектор атаки отсутствует.
Отсутствие секретного ключа подписи. JWT требует хранения приватного ключа на сервере для подписи токенов — это дополнительный секрет, который нужно защищать, ротировать и контролировать. Сессионные токены Пассворка — просто случайные строки, для их генерации не требуется никаких секретных ключей.

Access Token

Характеристики

Параметр	Значение
Длина	256 бит
Формат	Base64
Длина строки	~44 символа
Энтропия	256 бит
Время жизни по умолчанию	10 000 секунд (~2.8 часа)

Генерация

Access Token генерируется криптографически стойким генератором случайных чисел:

token = base64(random_bytes(32))

Валидация

При каждом запросе сервер:

Извлекает токен (из cookie или заголовка, в зависимости от режима)
Ищет токен в базе данных
Проверяет время жизни
Связывает запрос с пользователем

Режимы передачи токена

Пассворк использует два режима передачи Access Token в зависимости от типа клиента:

Browser Mode (веб-приложение)

Для веб-приложения Access Token передаётся через HttpOnly Cookie:

Параметр	Значение
HttpOnly	Да — недоступен для JavaScript (защита от XSS)
Secure	Да — только по HTTPS
SameSite	Strict — защита от CSRF

В этом режиме браузер автоматически прикрепляет cookie к каждому запросу. Access Token не возвращается в теле ответа при аутентификации — только в Set-Cookie заголовке.

API Mode (desktop, extension, mobile)

Для API-клиентов Access Token передаётся в заголовке Authorization:

Authorization: Bearer {access_token}

В этом режиме Access Token возвращается в теле ответа при аутентификации, и клиент самостоятельно управляет его хранением.

Сравнение режимов

Параметр	Browser Mode	API Mode
Клиенты	Веб-приложение	Desktop, Extension, Mobile
Передача токена	HttpOnly Cookie	Authorization header
Защита от XSS	✓ (HttpOnly)	Зависит от клиента
Управление токеном	Браузер (автоматически)	Клиент (вручную)

Refresh Token

Характеристики

Параметр	Значение
Длина	256 бит
Формат	Base64
Длина строки	~44 символа
Энтропия	256 бит
Время жизни по умолчанию	129 600 секунд (36 часов)

Назначение

Refresh Token используется для получения нового Access Token без повторной аутентификации. Подробнее о процессе обновления — в разделе Ротация токенов.

Настройка времени жизни

По ролям пользователей

Время жизни токенов настраивается на уровне роли пользователя:

Настройка	Значение по умолчанию
Время жизни Access Token	10 000 сек (~2.8 часа)
Время жизни Refresh Token	129 600 сек (36 часов)

Примеры конфигураций

Сценарий	Access TTL	Refresh TTL
Стандартный пользователь	10 000 сек	129 600 сек
Высокая безопасность	1 800 сек (30 мин)	14 400 сек (4 часа)
Удобство	28 800 сек (8 часов)	604 800 сек (7 дней)

Жизненный цикл сессии

Полный жизненный цикл

T=0: Аутентификация. Пользователь вводит учётные данные. Сервер создаёт Access Token (TTL: 2.8 часа) и Refresh Token (TTL: 36 часов).

T=2.8h: Access Token истёк. Клиент отправляет Refresh Token. Сервер выдаёт новые токены. Старый Refresh Token инвалидируется.

T=36h: Refresh Token истёк. Требуется повторная аутентификация. Пользователь вводит учётные данные заново.

Альтернативный сценарий — Выход. Пользователь нажимает «Выйти». Оба токена инвалидируются. Сессия завершена.

Инвалидация токенов

Все токены сессии инвалидируются при:

Выходе пользователя из системы
Смене мастер-пароля
Сбросе мастер-пароля администратором

Ротация токенов

Стандартный режим (приложения)

Для веб-приложения, браузерного расширения, мобильного и desktop приложений действует строгая политика ротации токенов.

При обновлении сессии клиент отправляет Access Token и Refresh Token одновременно, и в ответ получает новую пару токенов. Таким образом происходит постоянная ротация обоих токенов, что предотвращает повторное использование украденного токена.

Режим для автоматизации (API)

Для DevOps-задач и автоматизации строгая ротация часто неудобна. Поэтому для сессий, созданных через генерацию API-токенов, предусмотрен альтернативный режим:

Обновление только Access Token без смены Refresh Token
Отдельное обновление Refresh Token при необходимости

Это позволяет использовать долгоживущие Refresh Token в скриптах и CI/CD пайплайнах.

HTTP-эндпоинты ротации описаны в документации API-токенов.

Безопасность токенов

Защита от перехвата

Угроза	Защита
Перехват в сети	HTTPS/TLS обязателен
XSS-атака	HttpOnly cookies (Browser Mode)
CSRF	CSRF Token + SameSite cookies

CSRF Token

Назначение

CSRF Token защищает от атак межсайтовой подделки запросов. Обязателен для всех модифицирующих операций.

Характеристики

Параметр	Значение
Размер	256 бит
Формат	Hexadecimal (64 символа)
Энтропия	256 бит
Генератор	Криптографически стойкий

Использование

CSRF Token передаётся в заголовке каждого запроса:

X-CSRF-Token: {csrf_token}

Требования по типам клиентов

Тип клиента	CSRF Token
Веб-приложение (Browser Mode)	✓ Обязателен (генерируется и проверяется автоматически)
Браузерное расширение	Опционально (по запросу клиента)
Mobile приложение	Опционально (по запросу клиента)
API	— (не используется)

Назначение

Опциональная функция дополнительной защиты для Browser Mode. Привязывает сессию к контексту клиента, защищая от кражи cookie и session hijacking.

Как работает

При включении функции сервер вычисляет подпись на основе:

IP-адрес клиента
User-Agent браузера
Идентификатор сессии
Секретный ключ (60 символов, ~357 бит энтропии)

Подпись вычисляется по формуле:

cookieSign = HMAC-SHA512(IP + UserAgent + SessionID, secret)

Подпись сохраняется в отдельном HttpOnly cookie и проверяется при каждом запросе.

Защита от атак

Атака	Защита
Session Hijacking	Украденная cookie не работает с другого IP
Cookie Theft	Cookie бесполезна без совпадения IP + User-Agent

Ограничения

Смена IP (VPN, мобильная сеть) требует повторной аутентификации
Обновление браузера может изменить User-Agent

Включение

Функция включается администратором в настройках системы. По умолчанию отключена для совместимости с пользователями с динамическим IP.

Типы клиентов

Пассворк различает четыре типа клиентов с разными механизмами безопасности:

Функция	Web	Browser Extension	Mobile	API
Режим передачи токена	Browser Mode	API Mode	API Mode	API Mode
Access Token	Cookie	Header	Header	Header
CSRF Token	✓ Обязателен	Опционально	Опционально	—
Cookie Sign	Опционально	—	—	—
PIN-код	—	✓ Поддерживается	—	—

Browser Extension — единственный тип клиента с поддержкой серверного PIN-кода. PIN-код проверяется на сервере, который открывает временное окно для использования API. По истечении времени сессия блокируется до повторного ввода PIN-кода. При нескольких неверных попытках ввода сервер немедленно разрывает сессию. Это защищает от кражи токенов — даже при компрометации токена злоумышленник не сможет использовать API без знания PIN-кода.

HTTP-заголовки

Заголовки аутентификации

Заголовок	Описание	Режим
`Authorization`	Access Token (`Bearer {token}`)	API Mode
`Cookie`	Access Token (автоматически)	Browser Mode
`X-CSRF-Token`	CSRF защита	Все режимы
`X-Master-Key-Hash`	Хеш мастер-ключа	При необходимости

Хранение токенов на клиенте

Каждый тип клиента реализует безопасное хранение токенов в соответствии с возможностями платформы:

Веб-приложение — Access Token хранится в HttpOnly Cookie, недоступной для JavaScript (защита от XSS)
Desktop и Mobile приложения — токены хранятся в защищённых хранилищах операционной системы с ограниченным доступом
Браузерное расширение — используется изолированное хранилище браузера, недоступное для веб-страниц

Множественные сессии

Параллельные сессии

Пассворк поддерживает множественные одновременные сессии:

Пользователь может быть авторизован на нескольких устройствах
Каждое устройство имеет свою пару токенов
Выход на одном устройстве не влияет на другие

Управление сессиями

Пользователь может:

Просмотреть список активных сессий
Завершить конкретную сессию
Завершить все сессии (кроме текущей)

Администратор может:

Принудительно завершить все сессии пользователя

Обзор системы токенов​

Почему не JWT?​

Access Token​

Характеристики​

Генерация​

Валидация​

Режимы передачи токена​

Browser Mode (веб-приложение)​

API Mode (desktop, extension, mobile)​

Сравнение режимов​

Refresh Token​

Характеристики​

Назначение​

Настройка времени жизни​

По ролям пользователей​

Примеры конфигураций​

Жизненный цикл сессии​

Полный жизненный цикл​

Инвалидация токенов​

Ротация токенов​

Стандартный режим (приложения)​

Режим для автоматизации (API)​

Безопасность токенов​

Защита от перехвата​

CSRF Token​

Назначение​

Характеристики​

Использование​

Требования по типам клиентов​

Подпись Cookie (Cookie Sign)​

Назначение​

Как работает​

Защита от атак​

Ограничения​

Включение​

Типы клиентов​

HTTP-заголовки​

Заголовки аутентификации​

Хранение токенов на клиенте​

Множественные сессии​

Параллельные сессии​

Управление сессиями​

Рекомендации по настройке​

Высокая безопасность​

Баланс безопасности и удобства (по умолчанию)​

Максимальное удобство​

Обзор системы токенов

Почему не JWT?

Access Token

Характеристики

Генерация

Валидация

Режимы передачи токена

Browser Mode (веб-приложение)

API Mode (desktop, extension, mobile)

Сравнение режимов

Refresh Token

Характеристики

Назначение

Настройка времени жизни

По ролям пользователей

Примеры конфигураций

Жизненный цикл сессии

Полный жизненный цикл

Инвалидация токенов

Ротация токенов

Стандартный режим (приложения)

Режим для автоматизации (API)

Безопасность токенов

Защита от перехвата

CSRF Token

Назначение

Характеристики

Использование

Требования по типам клиентов

Подпись Cookie (Cookie Sign)

Назначение

Как работает

Защита от атак

Ограничения

Включение

Типы клиентов

HTTP-заголовки

Заголовки аутентификации

Хранение токенов на клиенте

Множественные сессии

Параллельные сессии

Управление сессиями

Рекомендации по настройке

Высокая безопасность

Баланс безопасности и удобства (по умолчанию)

Максимальное удобство