Snipe-IT + Active Directory, REST API и переезд из Excel

Карта интеграций Snipe-IT — что есть из коробки

В прошлой статье серии мы развернули Snipe-IT в Docker за один день. Система работает, наклейки печатаются — но пока она пустая и одинокая: сотрудников надо заводить руками, исторический учёт лежит в Excel, а с остальной инфраструктурой она не разговаривает. Сегодня — про то, как мы это лечим. Вторая по частоте фраза клиента после «у нас всё в Excel» звучит так: «а можно, чтобы сотрудники сами не заводились?» Можно. И не только сотрудники.

Сначала честная карта: что Snipe-IT умеет из коробки, без единого плагина. Умеет он на удивление много для бесплатной системы:

• LDAP / Active Directory — синхронизация пользователей и вход по доменным паролям. Главная интеграция для наших клиентов: AD есть почти у каждого.
• SAML SSO — единый вход через внешний провайдер идентификации (Keycloak, ADFS и любой другой стандартный IdP).
• CSV-импорт — штатный веб-импортёр для активов, пользователей, лицензий, аксессуаров и расходников. Наш инструмент переезда из Excel.
• REST API — полноценный интерфейс ко всем сущностям: всё, что можно сделать мышкой, можно сделать запросом. База для любых автоматизаций.
• Вебхуки уведомлений — события выдачи и возврата улетают в Slack-совместимый вебхук, то есть практически в любой мессенджер через прослойку.

Чего в Snipe-IT нет и не будет — агентов на рабочих станциях и автосканирования сети. Система не пойдёт сама по подсети искать компьютеры и собирать их конфигурации: разработчики сознательно держат фокус на учёте, а не на discovery. Для кого-то это минус, я считаю это честной архитектурой — но дыру закрывать надо, и в предпоследнем разделе покажу, как мы это делаем связкой с внешним сканером, не превращая чистый реестр в свалку.

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

Синхронизация с Active Directory

У большинства наших клиентов домен уже есть, и это меняет всё: вместо ручного заведения сотрудников Snipe-IT просто отражает кадровую реальность из AD. Новичок вышел на работу — учётка появилась в реестре сама; человек уволился и заблокирован в домене — в Snipe-IT он больше не входит, но вся история его выдач остаётся на месте. Настраивается это за час, работает годами.

Подключение: сервисная учётка и LDAPS

Всё живёт в Admin → Settings → LDAP/AD. Первым делом — не настройки Snipe-IT, а гигиена со стороны домена: заводим в AD отдельную сервисную учётку вида svc-snipeit с обычными правами доменного пользователя (для чтения каталога больше и не нужно) и бессрочным паролем из парольного менеджера. Админскую учётку в интеграции не прописываем никогда: ей достаточно уметь читать каталог, и если пароль однажды утечёт из конфига — ущерб ограничен чтением.

Подключение — только ldaps://dc01.company.local:636, шифрованный вариант протокола. Внутри периметра это может показаться перестраховкой, но доменные пароли пользователей при входе в Snipe-IT проходят именно через это соединение — гонять их открытым текстом по сети не хочется даже в LAN. Если контроллер домена с самоподписанным сертификатом, в настройках есть флажок игнорировать валидацию — рабочий компромисс для внутренних ЦС.

Дальше Base DN — откуда читать пользователей. Мы указываем не корень домена, а OU с живыми сотрудниками: OU=Users,OU=Company,DC=company,DC=local. И фильтр, отсекающий заблокированные и служебные учётки — для AD у нас типовой:

(&(objectCategory=person)(objectClass=user)
  (!(userAccountControl:1.2.840.113556.1.4.803:=2)))

Битовая магия в последней строке — стандартный AD-приём «исключить отключённые учётки». Плюс галочка Active Directory в настройках и домен для построения UPN — тогда вход работает по привычному ivanov@company.local.

Маппинг полей: что тянем из каталога

Snipe-IT позволяет сопоставить поля пользователя атрибутам каталога. Наш типовой маппинг для AD (важная мелочь из документации: имена атрибутов — строчными буквами, даже если в AD они в смешанном регистре):

Здесь же обратная сторона: если у клиента AD заполнен «на отвали» — без отделов, должностей и почты, — синхронизация честно притащит пустоту. Пару раз внедрение Snipe-IT становилось поводом навести порядок в самих атрибутах AD, и это тот случай, когда побочный эффект ценнее основного.

Расписание и поведение при увольнении

Синхронизация запускается артизан-командой — руками или по расписанию:

docker compose exec snipeit php artisan snipeit:ldap-sync

Мы вешаем её в cron на хосте раз в час: кадровые события не настолько быстрые, чтобы гонять синк чаще. Важно понимать: синхронизация односторонняя — Snipe-IT только читает каталог и никогда в него не пишет, сломать AD этой интеграцией невозможно в принципе.

Самый частый вопрос про увольнения: «человека заблокировали в AD — что с его выдачами?» Правильный ответ, и Snipe-IT ведёт себя именно так: учётка перестаёт входить (фильтр её больше не пропускает), но пользователь и вся его история в системе остаются. Это принципиально: если бы блокировка в AD стирала человека из реестра, вместе с ним исчезала бы история «кому был выдан этот ноутбук в 2024 году» — а она нужна бухгалтерии и через три года после увольнения. Процедура офбординга у нас выглядит так: HR блокирует учётку в AD, а в Snipe-IT офис-менеджер делает checkin всей техники уволенного — система сама подсказывает список того, что за ним числится, вместе с подписанными актами.

SAML SSO — когда стоит заморачиваться

Про единый вход спрашивают часто, поэтому отвечу с позиции практика: для компании до 50 рабочих мест LDAP-входа почти всегда достаточно. Сотрудник вводит доменный логин и пароль — тот же, что для входа в Windows. Это уже «один пароль на всё», просто без модного редиректа. SSO ради SSO — лишняя движущаяся деталь в системе, которую потом сопровождать.

SAML мы включаем в двух случаях. Первый — у клиента уже живёт провайдер идентификации: Keycloak, ADFS или облачный IdP, и все внутренние сервисы заходят через него; тогда Snipe-IT логично встаёт в общий ряд, а бонусом наследует политики IdP — ту же обязательную двухфакторку. Второй — когда доступ к реестру нужен людям вне домена: например, техника разбросана по филиалам без общего AD.

Сама настройка несложная: в Admin → Settings → SAML скармливаем метаданные IdP (URL или XML-файлом), забираем из того же экрана метаданные Snipe-IT как сервис-провайдера, регистрируем их на стороне IdP, маппим атрибут с именем пользователя — и вход работает. На стороне Keycloak это полчаса вместе с тестами.

Резюме раздела: есть работающий IdP — подключайте, полдня с тестами. Нет — не заводите его ради одного Snipe-IT, LDAP закрывает задачу без новых зависимостей.

Миграция из Excel: методика, отработанная на десятках реестров

Теперь самое трудоёмкое. За годы через нас прошли десятки клиентских «Техника_итог_ФИНАЛ_2.xlsx», и я ответственно заявляю: главная работа миграции — не импорт, а уборка. Импорт занимает десять минут; приведение таблицы в пригодный вид — от двух часов до двух дней. Зато это разовая боль: после неё реестр начинает жить по правилам системы, а не файла.

Шаг 1. Подготовка файла

Типовой клиентский реестр выглядит так: колонка «Оборудование» со значениями вроде «Ноутбук Lenovo какой-то, вроде у Наташи», серийники вперемешку с инвентарниками, даты в трёх форматах, объединённые ячейки для красоты. Наша методика уборки:

• Расклеиваем «слепленные» колонки. «Lenovo ThinkPad E14 у Иванова с 2023» — это четыре поля: производитель, модель, держатель, дата выдачи. Разносим по колонкам; где данных нет — оставляем пусто, а не «?», «нету» и «спросить у Олега».
• Нормализуем модели и производителей. «HP», «Хьюлет», «hp inc» — один производитель. Сводим справочник моделей заранее: колонки «производитель», «модель», «категория» должны использовать ровно те написания, которые мы завели в Snipe-IT при внедрении. Помните скелет справочников из прошлой статьи? Вот здесь он окупается.
• Строки-призраки — в отдельный лист. «Ноутбук какой-то, у Наташи» без модели и серийника в систему не поедет: это не данные, это фольклор. Такие строки собираем в лист «на выяснение» — их судьбу решит физическая инвентаризация в конце миграции, а не фантазия при импорте.

Шаг 2. CSV и две классические грабли

Импортёр Snipe-IT ест CSV. Сохраняем подготовленный лист как CSV — и вот две грабли, о которые бьются все, кто мигрирует из русского Excel:

• Кодировка. Русский Excel по кнопке «Сохранить как CSV» любит выдавать cp1251, и тогда в предпросмотре импорта вместо «Иванов» — крокозябры. Файл должен быть в UTF-8: в свежем Excel выбирайте явно «CSV UTF-8», а надёжнее всего прогнать файл через iconv -f cp1251 -t utf-8 или пересохранить в LibreOffice с явным выбором кодировки.
• Даты. «01.03.2023», «март 23», «1/3/23» — импортёр не телепат. Приводим все даты покупки и выдачи к ISO-формату 2023-03-01 одной формулой в Excel — импорт съедает его без разночтений и не путает день с месяцем.

Шаг 3. Пилот на 10 строках, потом всё остальное

Загружаем через Admin → Import: файл затягивается в веб-интерфейс, дальше — экран маппинга, где колонки CSV сопоставляются полям системы, включая кастомные (наш «инвентарный номер бухгалтерии» отлично импортируется). Но никогда, ни разу, не заливайте сразу весь файл. Наш порядок:

1. Пилот: первые 10 строк. Импортируем, открываем карточки, проверяем руками: модель подцепилась к правильному справочнику, даты не съехали, кириллица целая, держатель нашёлся по имени.
2. Правим маппинг по итогам пилота — почти всегда что-то да всплывает: то колонка съехала, то формат тега не тот.
3. Полный импорт. Импортёр умеет и обновлять существующие записи при повторной загрузке — если пилотные строки попали в основной файл, дублей не будет.
4. Физическая сверка. Финал миграции — инвентаризация с наклейками: обходим офис, клеим QR-теги, сканируем, сверяем таблицу с реальностью. Именно здесь решается судьба «ноутбука у Наташи»: он либо находится и получает карточку, либо честно списывается. После этого обхода реестр совпадает с физическим миром — впервые за годы.

REST API на практике

API — то, что отличает систему учёта от электронной картотеки. В Snipe-IT он полноценный: любая операция интерфейса доступна запросом. Токен выпускается за минуту: меню профиля → Manage API Keys → Create New Token. Дальше стандартно — заголовок Authorization: Bearer, JSON туда и обратно. Для скриптов мы заводим отдельного пользователя-робота с минимальными правами и выпускаем токен ему, а не личной учётке админа: люди увольняются, роботы остаются.

Несколько живых примеров из наших автоматизаций. Забрать список активов (ответы пагинированы — по умолчанию отдаются первые записи, дальше двигаемся limit и offset, за один запрос больше 500 не отдаст):

curl -s "https://assets.company.ru/api/v1/hardware?limit=100&offset=0" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

Создать актив — например, из скрипта закупки, когда серийники новой партии приезжают файлом от поставщика:

curl -s -X POST "https://assets.company.ru/api/v1/hardware" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"asset_tag":"ITF-0201","model_id":12,"status_id":1,
       "serial":"PF-3K7XQ2","purchase_date":"2026-07-15","warranty_months":36}'

Выдать актив сотруднику (тот же checkout, что мышкой, — с письмом и актом на подпись):

curl -s -X POST "https://assets.company.ru/api/v1/hardware/42/checkout" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"checkout_to_type":"user","assigned_user":17}'

А теперь любимая автоматизация наших клиентов — еженедельный отчёт «гарантии заканчиваются». Скрипт на десяток строк Python раз в неделю выгружает активы постранично, по полям «дата покупки» и «месяцев гарантии» считает дату окончания, отбирает всё, что истекает в ближайшие 60 дней, и шлёт таблицу на почту клиенту. Эффект непропорционален затратам: ремонт ноутбука, успевший в гарантийное окно, — это 15–30 тысяч рублей, оставшиеся в бюджете, а скрипт писался один раз за вечер. Такой же паттерн — «выгрузи, посчитай, доложи» — закрывает отчёты по лицензиям, простаивающей технике и активам без наклеек.

Единственное, обо что можно споткнуться, — лимит запросов: по умолчанию API отдаёт до 120 запросов в минуту, при постраничной выгрузке большого реестра жадный цикл в это упирается. Лечится паузой в полсекунды между страницами; порог настраивается переменной окружения, но нам ни разу не потребовалось.

Snipe-IT + сетевой сканер: закрываем отсутствие autodiscovery

Обещанный честный ответ на вопрос «а оно само найдёт наши компьютеры?». Нет, не найдёт — и я считаю это правильным. Но проверять полноту реестра чем-то надо, иначе через год в сети живёт техника, которой нет в учёте. Наша связка выглядит так: реестр остаётся ручным и чистым, а сканер работает контролёром.

Источники данных о реальности у нас два. Для доменных машин — сам AD плюс PowerShell: скрипт раз в неделю обходит компьютеры домена и собирает серийники прямо из BIOS:

Get-ADComputer -Filter * | ForEach-Object {
  Get-CimInstance Win32_BIOS -ComputerName $_.Name |
    Select-Object @{n='Host';e={$_.PSComputerName}}, SerialNumber
} | Export-Csv fact.csv -Encoding UTF8

Для всего остального — принтеров, коммутаторов, точек доступа — обычный nmap -sn по подсетям или, у клиентов с нашим мониторингом, готовые данные обнаружения из Zabbix: он и так уже знает всё, что отвечает в сети. Дальше маленький скрипт сверяет «факт» с реестром через API по серийному номеру и выдаёт два списка: есть в сети — нет в Snipe-IT (незаведённая техника, кандидат на заведение) и есть в Snipe-IT со статусом «выдан» — не появлялся в сети месяц (повод спросить, где ноутбук).

Почему мы сознательно не даём сканеру самому создавать активы, хотя через API это делается тривиально? Потому что видели, чем это кончается. Автосоздание тащит в реестр всё подряд: виртуалки, телефоны сотрудников из гостевого Wi-Fi, соседский телевизор с DLNA. Через пару месяцев в базе сотни объектов-призраков без моделей и владельцев, офис-менеджер перестаёт ей доверять — и учёт умирает второй раз, теперь уже в красивой системе. Мусор в реестре хуже ручного ввода: расхождение из отчёта сверки должен разбирать человек, потому что каждое из них — это событие («купили в обход процедуры», «принесли из дома»), а не строчка для автозаведения.

Уведомления и вебхуки

Последний штрих интеграционного контура — чтобы система сама напоминала о важном, а не ждала, пока в неё заглянут. Здесь у Snipe-IT два механизма.

Почтовые алерты (Admin → Settings → Notifications): системные письма об истекающих гарантиях и сроках лицензий и о падении остатков расходников ниже порога. Наши типовые пороги: гарантии и лицензии — предупреждать за 60 дней (успеть согласовать продление через бухгалтерию — это не два дня), расходники — порог на каждый ходовой картридж, чтобы заказ уезжал до того, как бухгалтерия останется без печати. Письма шлём не в личный ящик админа, а на алиас, за которым следит дежурный, — личные ящики уходят в отпуск вместе с владельцами.

Вебхуки — события выдачи и возврата в реальном времени. Интеграция в настройках называется Slack, но формат сообщений стандартный, поэтому через любую совместимую прослойку события приезжают куда угодно — у нас это Telegram-канал «Техника» на стороне клиента: офис-менеджер сделал checkout — в канале мгновенно появляется «ноутбук ITF-0042 выдан Петрову». Звучит как игрушка, но даёт неожиданный эффект прозрачности: выдачи перестают быть тихим делом одного человека, и руководитель видит движение техники без всяких отчётов.

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

Итог: типовая схема интеграций для компании до 50 РМ

Соберём конструктор. Вот схема, которую мы в том или ином составе настраиваем каждому клиенту со Snipe-IT, — с честными трудозатратами инженера:

Итого связанный со всей инфраструктурой Snipe-IT — это один-два дня работы поверх базового внедрения, из которых львиная доля уходит на уборку Excel, а не на технику. После этого система перестаёт требовать ручной дисциплины: людей приносит AD, полноту контролирует сканер, о сроках напоминают алерты. Ровно в этот момент учёт техники превращается из «обязанности, которую забывают» в фоновый процесс, который просто работает.

Следующая статья серии — про то, как поддерживать это состояние годами: регламент обновлений при темпе «релиз каждые несколько недель», трёхуровневые бэкапы с учебным восстановлением и харденинг инсталляции. А если хочется получить всю связку сразу и без самостоятельных граблей — это ровно то, что мы делаем клиентам на аутсорсинге.