Управление API-ключами партнёров

В веб-интерфейсе управления API-ключами партнёр — это конечный пользователь, который использует сервисы, установленные внутри комплекса On-Premise (например, API для работы с картами).

Как администратор, вы можете:

добавлять партнёров в систему и редактировать их данные;
создавать API-ключи для партнёров и редактировать данные API-ключа;
редактировать список сервисов для API-ключа, которые доступны партнёру;
заблокировать и разблокировать API-ключ для настройки доступа к сервисам;
добавить ограничения API-ключа.

Начало работы

Чтобы начать работу с веб-интерфейсом API-ключей, выполните следующие шаги:

Убедитесь, что сервис API-ключей установлен, работает корректно, и в сервис добавлен пользователь с правами администратора с помощью утилиты keysctl. Подробнее см. в инструкции по установке сервиса API-ключей.
Перейдите по ссылке вида https://keys-admin.example.com/, которую вы получили в результате установки сервиса API-ключей.
Войдите в веб-интерфейс, используя учётные данные пользователя с правами администратора.

Интерфейс администратора содержит две вкладки:

Партнёры

Здесь вы можете:
- Добавлять новых партнёров.
- Просматривать список партнёров и фильтровать его по названию, ключу, данным контактного лица, логину менеджера (администратора, добавившего партнёра) и другим параметрам.
- Выгружать список всех партнёров в формате .xlsx: нажмите Скачать partners.xlsx в правом верхнем углу интерфейса. В выгрузку попадают все существующие партнёры, фильтры не применяются.
API-ключи

Здесь вы можете:
- Просматривать список ключей всех партнёров и фильтровать его по номеру ключа, электронной почте контактного лица, логину менеджера (администратора, добавившего партнёра) и другим параметрам.
- Выгружать список всех ключей в формате .xlsx: нажмите Скачать keys.xlsx в правом верхнем углу интерфейса. В выгрузку попадают все существующие ключи, фильтры не применяются.

Добавление партнёра

Перейдите на вкладку Партнёры и нажмите Добавить партнёра.
Заполните информацию о партнёре:
- Название: имя учётной записи, которое будет отображаться в интерфейсе администратора.
- Страна: страна проживания партнёра.
- Город: город проживания партнёра.
- Язык (необязательный параметр): язык коммуникации с партнёром.
- Контактное лицо: данные о контактном лице партнёра: ФИО и электронная почта. По умолчанию данные используются для всех ключей партнёра, если при создании API-ключей не были заданы другие.
Нажмите Добавить.

Редактирование данных партнёра

Перейдите на вкладку Партнёры и выберите карточку нужного партнёра.
Нажмите значок рядом с названием партнёра.
Внесите необходимые изменения и нажмите Сохранить.

Создание API-ключа

Для каждого партнёра вы можете создать несколько ключей с разными ограничениями и набором сервисов.

Перейдите на вкладку Партнёры и выберите карточку нужного партнёра.
Нажмите Создать ключ.
Заполните информацию о ключе:
- Партнёр: партнёр, для которого создаётся ключ (по умолчанию выбран текущий партнёр).
- Режим:
  - Demo: ознакомительный режим с ограничениями в работе сервисов:
    - API для работы с поиском: не более 5 страниц с результатами и не более 20 результатов на странице.
    - API для работы с навигацией: длина маршрута не более 50 км.
  - Prod: режим для полной эксплуатации.
- Назначение ключа: описание назначения ключа.
- Контактное лицо (необязательный параметр): данные о контактном лице для ключа. Если оставить поля пустыми, используются данные о контактном лице партнёра.
Нажмите Создать.

Редактирование данных API-ключа

Выберите нужный ключ на вкладке API-ключи или на вкладке Партнёры в карточке партнёра.
Чтобы изменить описание ключа, контактное лицо или назначить ключ другому партнёру, нажмите значок рядом с ID ключа. Внесите необходимые изменения и нажмите Сохранить.
Чтобы изменить режим работы ключа (Demo/Prod), выберите его в блоке Режим.

Редактирование списка сервисов

Вы можете изменить список сервисов, к которым партнёр сможет получить доступ по API-ключу.

Выберите нужный ключ на вкладке API-ключи или на вкладке Партнёры в карточке партнёра.
Прокрутите страницу ключа вниз до списка доступных сервисов.
Чтобы выдать или отозвать доступ к сервису, используйте переключатель слева от названия сервиса.

Блокировка API-ключа

При блокировке ключа доступ ко всем сервисам этого ключа будет приостановлен, статус изменится на Неактивен.

Выберите нужный ключ на вкладке API-ключи или на вкладке Партнёры в карточке партнёра.
Нажмите Заблокировать рядом с ID ключа.
Чтобы снять блокировку, нажмите Активировать.

Добавление ограничений API-ключа

Важно

Ограничения применяются для всех сервисов, которые указаны в API-ключе.

Выберите нужный ключ на вкладке API-ключи или на вкладке Партнёры в карточке партнёра.
В разделе Ограничения ключа нажмите значок .
Настройте ограничения ключа:
- Deactivation time: дата блокировки ключа.
- По территории: ограничение доступа по территории.
  - Группы сегментов: список доступных географических сегментов (территорий).
  - Вкл. сегменты: дополнительный список доступных сегментов, которые не входят в выбранные группы.
  - Искл. сегменты: список сегментов из выбранных групп, доступ к которым будет закрыт.
- По приложению: ограничение доступа по ID мобильного приложения.
- По IP или подсетям: ограничение доступа по IP-адресам.
- По HTTP-заголовкам: ограничение доступа по значениям заголовков.
Нажмите Сохранить.

Deactivation time (Запланированная дата блокировки)

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

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

Шаги:

В поле Deactivation time введите дату 31.12.2025. Автоматически подставляется время 12:00:00 в часовом поясе GMT (UTC+3).
Нажмите Сохранить.

Результат: ключ будет активен только до 31.12.2025 12:00:00 по GMT.

По территории (Группы сегментов)

Разрешает доступ группам географических сегментов (территорий). Ключ будет работать только для сегментов из указанных групп (например, Россия), включая все входящие в них сегменты (регионы, города и т. д.).

Пример использования: разрешить доступ для запросов только пользователям из России.

Шаги:

В поле Группы сегментов выберите из выпадающего списка Россия.
Нажмите Сохранить.

Результат: ключ будет работать для всех сегментов в России. Запросы из других стран (например, Египет) будут отклонены.

По территории (Включить сегменты)

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

Пример использования: разрешить доступ для запросов только для Альметьевска.

Шаги:

Оставьте поле Группы сегментов пустым.
В поле Вкл. сегменты выберите almetevsk.
Нажмите Сохранить.

Результат: ключ будет работать только для запросов из Альметьевска. Запросы из других сегментов (например, Казани или Москвы) будут отклонены.

По территории (Исключить сегменты)

Запрещает доступ для сегментов внутри выбранных групп. Например, вы можете выбрать всю территорию страны и ограничить доступ к определённому сегменту внутри неё.

Пример использования: разрешить доступ для запросов по всей территории России, кроме Альметьевска.

Шаги:

В поле Группы сегментов выберите Россия.
В поле Искл. сегменты выберите almetevsk.
Нажмите Сохранить.

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

По приложению

Ограничивает доступ по значению идентификатора мобильного приложения (appId).

Пример использования: разрешить доступ для запросов только от приложения с идентификатором ru.dgis.sdk.app.

Шаги:

В поле App ID укажите ru.dgis.sdk.app.
Нажмите Сохранить.

Результат: ключ будет работать только для запросов от приложения с идентификатором ru.dgis.sdk.app. Запросы от других приложений (например, ru.dgis.test.app) будут отклонены.

По IP или подсетям

Ограничивает доступ по списку IP-адресов или подсетей в формате CIDR (например, 192.168.1.0/24). Ограничение использует IP-адрес клиента, который передаётся в следующих заголовках:

Remote-Addr: IP-адрес источника TCP-соединения или IP-адрес прокси-сервера при использовании прокси или NAT.
X-Forwarded-For: цепочка IP-адресов, где первый адрес — IP клиента. Рекомендуется использовать этот заголовок, так как он поддерживает сложные сетевые конфигурации с прокси.
X-Real-IP: IP-адрес клиента, переданный прокси.

Пример использования: разрешить доступ для запросов только с IP-адресов корпоративной подсети 192.168.1.0/24.

Шаги:

В поле CIDR укажите подсеть 192.168.1.0/24.
Нажмите Сохранить.
Если вы используете прокси или NAT, заголовки могут отсутствовать или содержать неверный IP-адрес клиента, что может нарушить работу ограничения. Убедитесь, что ваша инфраструктура (прокси, балансировщики нагрузки, NAT, Ingress) передаёт заголовки с оригинальным IP-адресом клиента:
- Проверьте конфигурацию Ingress-контроллера Nginx в вашем кластере Kubernetes (например, файл values.yaml в Helm-чарте).
- Проверьте конфигурацию прокси или балансировщика нагрузки (например, директиву proxy_set_header в Nginx).
- Включите логирование HTTP-заголовков (Remote-Addr, X-Forwarded-For, X-Real-IP) в сервисе API-ключей.
- Используйте инструменты анализа трафика для подтверждения, что хотя бы один заголовок содержит правильный IP-адрес клиента (например, Wireshark, tcpdump).

Результат: ключ будет работать только для запросов с IP-адресов из диапазона 192.168.1.0 — 192.168.1.255 при условии, что с IP-адреса клиента корректно передаётся один из заголовков (Remote-Addr, X-Forwarded-For, X-Real-IP). Запросы с других IP-адресов (например, 10.0.0.1) или без корректных заголовков будут отклонены.

При необходимости вы можете обратиться в службу поддержки для уточнения конфигурации или рекомендаций по настройке.

По HTTP-заголовкам

Ограничивает доступ по HTTP-заголовкам в запросе:

Origin: по имени сервера.
Referer: по URL страницы.
User-Agent: по типу приложения, операционной системе и другим параметрам.

Пример использования: разрешить доступ только для запросов с домена example.com и от браузера с настройкой User-Agent Mozilla/5.0.

Шаги:

В поле Origin укажите example.com.
В поле User-Agent укажите Mozilla/5.0.
Нажмите Сохранить.

Результат: ключ будет работать только для запросов с заголовком Origin: example.com и User-Agent: Mozilla/5.0. Запросы с других доменов (например, test.com) или от других клиентов (например, curl/7.0) будут отклонены.