Ключ API с авторизацией Active Directory

Ключ API с авторизацией Active Directory — режим аутентификации, при котором серверная интеграция, скрипт или агент мониторинга получает доступ к GraphQL API только при одновременном выполнении двух условий: знает значение ключа и проходит Kerberos-аутентификацию под доменной учетной записью. Проверка по Kerberos выполняется однократно — при получении сессии. Дальнейшие запросы передаются по выданной сессии без повторной аутентификации.

Режим подходит, когда интеграционный клиент работает на доменной машине под сервисной учетной записью и нужно ограничить использование ключа конкретным компьютером или учетной записью: утечка значения ключа сама по себе не дает доступа к системе.

На сервере Proceset под Linux доступна только Kerberos-аутентификация (SPNEGO). Тип Стандартная Windows (NTLM) при сервере на Linux не поддерживается.

Что подготовить

На стороне клиента (внешняя система или скрипт)

Перед использованием ключа убедитесь, что выполнены следующие условия:

• Для интеграционного клиента создана доменная учетная запись (или есть keytab для автономного режима).
• На машине клиента настроен файл /etc/krb5.conf — стандартный конфигурационный файл Kerberos. Это файл клиентской машины, а не сервера Proceset.
• Клиент может получить билет Kerberos (TGT): для проверки выполните kinit -kt /path/to/client.keytab client-user@DOMAIN.LOCAL и убедитесь, что klist показывает активный билет.
• Клиент разрешает FQDN-имя сервера Proceset по DNS.
• Сеть открывает доступ к контроллеру домена на порт Kerberos (88/TCP).

На стороне Proceset

Убедитесь, что Kerberos-аутентификация уже настроена: страница Добавление аутентификации должна содержать активную конфигурацию Kerberos. Без этого Kerberos-токены клиента не пройдут проверку. Подробнее — в разделе Добавление аутентификации.

Создание ключа типа Active Directory

Создать ключ можно в интерфейсе Proceset на странице Ключи API, выбрав режим аутентификации Active Directory, или через GraphQL-мутацию.

Через GraphQL:

mutation CreateAdApiKey {
  api_key {
    create(
      name: "Reporting integration",
      type: "ad",
      subsystem_uuid: "com.infomaximum.subsystem.activedirectory",
      privileges: [
        # список привилегий: какие операции в GraphQL сможет выполнять ключ
      ]
    ) {
      id
      value
      type
    }
  }
}

Поля мутации:

После создания назначьте ключу привилегии во вкладке Привилегии его профиля. Подробнее о привилегиях — в разделе Ролевая модель.

Получение сессии и выполнение запросов

Получение идентификатора сессии

Перед выполнением GraphQL-запросов клиент получает идентификатор сессии, однократно пройдя Kerberos-проверку.

Пример на curl (если TGT уже получен через kinit):

kinit -kt /etc/integration.keytab integration-user@CORP.LOCAL

curl --negotiate -u : \
     -c /tmp/ad_session_cookies.txt \
     "https://proceset.corp.local/ad_auth/kerberos?api_key=<значение_ключа>"
# ответ: { "session_uuid": "a8c2e9b4-..." }

Пример на Python (библиотека requests-kerberos):

import requests
from requests_kerberos import HTTPKerberosAuth, OPTIONAL

session = requests.Session()
resp = session.get(
    "https://proceset.corp.local/ad_auth/kerberos",
    params={"api_key": API_KEY_VALUE},
    auth=HTTPKerberosAuth(mutual_authentication=OPTIONAL),
)
resp.raise_for_status()
session_uuid = resp.json()["session_uuid"]

Без действующего Kerberos-билета клиент получит ответ 401 Unauthorized и не сможет продолжить.

Выполнение GraphQL-запросов

После получения идентификатора сессии передавайте его в каждом запросе через параметр api_key_session_uuid:

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"query": "{ ... }"}' \
     "https://proceset.corp.local/graphql?api_key_session_uuid=<session_uuid>"

Если клиент сохранил cookie из ответа на запрос аутентификации, их также можно использовать:

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"query": "{ ... }"}' \
     -b /tmp/ad_session_cookies.txt \
     "https://proceset.corp.local/graphql"

Время жизни сессии

Сессия действует 60 минут (значение по умолчанию, задается в настройках подсистемы Active Directory). Каждое успешное обращение продлевает таймер. При перезапуске сервера Proceset сессии сбрасываются.

При получении ответа 401 клиент должен заново пройти Kerberos-проверку и получить новый идентификатор сессии. Реализуйте логику повторной аутентификации при 401 на стороне интеграционного клиента.

Агент мониторинга и ключ API с авторизацией Active Directory

Агент мониторинга подключается к серверу приложения именно с помощью ключа API с авторизацией Active Directory — как при сервере на Windows, так и при сервере на Linux. Отдельного механизма входа у агента нет.

Это работает так же, как и для любой другой серверной интеграции: агент, установленный на доменной машине, получает Kerberos-билет под сервисной учетной записью и однократно проходит проверку при старте. Ключ с типом "ad" создается тем же способом, что описан выше, и назначается агенту в его настройках.

Подробнее об установке и настройке агента — в разделе Агент мониторинга.

Отзыв ключа

Удаление ключа — единственный способ инвалидировать его. После удаления все активные сессии ключа завершаются немедленно, следующая попытка использовать сессию вернет 401.

Удалить ключ через GraphQL:

mutation {
  api_key {
    remove(ids: [42])
  }
}

Для удаления ключа требуется привилегия Ключи API с операцией доступа Удаление.

У ключа нет встроенного срока истечения. Чтобы ротировать ключ: создайте новый, переключите на него интеграционного клиента, затем удалите старый.

Ограничения

• У ключа нет срока истечения и автоматической ротации. Ротация выполняется вручную через создание нового ключа и удаление старого.
• Значение ключа отображается полностью только при создании. Восстановить его нельзя.
• При перезапуске сервера Proceset сессии сбрасываются — клиент должен уметь переполучать сессию.
• На сервере Proceset под Linux доступна только Kerberos-аутентификация. NTLM не поддерживается.
• Все операции выполняются от имени ключа, а не от имени сотрудника. Права определяются привилегиями ключа.

Диагностика

Ошибки при получении сессии

Ошибки при выполнении GraphQL-запросов