Справка по API — каталог пользователей

Что это

Сервис предоставляет HTTP-API для получения списка пользователей домена: ФИО, должность, телефон, логин и почта. Поле «Должность» хранится в Active Directory в атрибуте description (Описание).

1. Получите ключ

Откройте панель администратора.
В блоке «Настройки» найдите поле API-ключ для каталога.
Нажмите «Новый ключ» — будет сгенерирован новый ключ (старый перестанет работать).
Скопируйте ключ кнопкой «Копировать».

Ключ показывается только в админке и хранится в настройках сервиса. Храните его в секрете.

2. Эндпоинт

GET /api/directory/users

Ключ передаётся в заголовке X-API-Key или параметром ?api_key=.

Примеры запросов

# Заголовком (Linux / macOS / Git Bash)
curl -H "X-API-Key: ВАШ_КЛЮЧ" \
     https://ВАШ_СЕРВЕР/api/directory/users

# Параметром
curl "https://ВАШ_СЕРВЕР/api/directory/users?api_key=ВАШ_КЛЮЧ"

# PowerShell (Windows)
$headers = @{ "X-API-Key" = "ВАШ_КЛЮЧ" }
Invoke-RestMethod -Uri "https://ВАШ_СЕРВЕР/api/directory/users" -Headers $headers

3. Формат ответа

Успешный ответ — JSON со списком пользователей:

{
  "success": true,
  "count": 2,
  "users": [
    {
      "login": "ivanov.i",
      "fio": "Иванов Иван Иванович",
      "position": "Учитель информатики",
      "phone": "+79161234567",
      "email": "ivanov.i@school25.ru"
    }
  ]
}

Если поля нет (не заполнено) — возвращается пустая строка.

Коды ошибок

Код	Значение
200	Успех
401	Неверный или отсутствующий API-ключ
503	Ключ не настроен (сгенерируйте его в админке)
500	Ошибка сервера или недоступен LDAP

4. Описание полей

Поле	Описание	Атрибут AD
`login`	Логин (sAMAccountName)	`sAMAccountName`
`fio`	ФИО	`displayName`
`position`	Должность	`description`
`phone`	Телефон	`telephoneNumber`
`email`	Электронная почта	`mail`

5. Единый вход через GitVerse (SSO)

Внешние сервисы могут делегировать проверку пользователя этому сервису. Пользователь входит через GitVerse, сервис сопоставляет его с учётной записью Active Directory по e-mail и возвращает сервису-источнику логин, ФИО, список групп AD и признак администратора.

Регистрация сервиса

Откройте панель администратора.
В блоке «Сервисы SSO (вход через GitVerse)» задайте название и разрешённые redirect URI.
Скопируйте client_id, client_secret и стартовый URL.

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

Сервис-источник перенаправляет браузер пользователя на стартовый URL:
GET /auth/gitverse/start?service=<id>&redirect_uri=<callback>&state=<csrf>
Пользователь подтверждает вход в GitVerse.
Сервис проверяет пользователя в AD и перенаправляет браузер обратно на redirect_uri, добавив одноразовый code и исходный state.
Сервис-источник обменивает код на данные пользователя серверным запросом.

POST /auth/gitverse/token

curl -X POST "https://ВАШ_СЕРВЕР/auth/gitverse/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "ВАШ_CLIENT_ID",
    "client_secret": "ВАШ_CLIENT_SECRET",
    "code": "ОДНОРАЗОВЫЙ_КОД"
  }'

Ответ:

{
  "success": true,
  "user": {
    "login": "ivanov.i",
    "fio": "Иванов Иван Иванович",
    "email": "ivanov.i@school25.ru",
    "groups": ["Учителя", "Информатика"],
    "isAdmin": false
  }
}

Код одноразовый и действует ограниченное время (по умолчанию 60 секунд). client_secret нельзя передавать в браузер. При ошибке авторизации сервис-источник получает редирект с параметрами error и error_description.