Управление доступом к API

Как администратор, вы можете управлять доступом конечных пользователей к установленным сервисам. В веб-интерфейсе сервиса API-ключей доступны следующие сущности:

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

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

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

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

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

• Партнёры

  

  Здесь вы можете:

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

• API-ключи

  

  Здесь вы можете:

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

Партнёры

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

1. Перейдите на вкладку Партнёры и нажмите Добавить партнёра.

2. Заполните информацию о партнёре:

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

3. Нажмите Добавить.

4. Переходите к созданию подписки для партнёра.

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

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

Подписки

Чтобы предоставить партнёру возможность работать с API, создайте подписку, которая определит доступный ему пакет сервисов и лимиты их использования. Для отображения лимитов использования сервисов должен быть установлен сервис сбора статистики.

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

Создание подписки

1. Перейдите на вкладку Партнёры и выберите карточку нужного партнёра.

2. Откройте панель Подписки.

3. Создайте подписку:

   • Нажмите Создать demo-подписку, чтобы создать подписку для ознакомительного использования с предварительно настроенными ограничениями в работе сервисов.
   • Нажмите Создать prod-подписку, чтобы создать подписку для полной эксплуатации.

   У партнёра может быть одновременно только одна активная подписка каждого типа.

   

4. Укажите дату начала действия подписки.

5. Выберите период действия подписки.

6. Выберите сервисы, которые будут включены в подписку:

   1. Используйте переключатель слева, чтобы добавить сервис в подписку или удалить его.

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

      • Features: возможности сервиса (доступные endpoint-ы) в рамках подписки. Если не указать значения, в рамках подписки будет разрешён доступ ко всем возможностям сервиса. Некоторые обязательные возможности предзаполняются автоматически и не могут быть удалены.

      • Event type: тип сущности, на которую распространяется ограничение: запросы (requests) или получаемые объекты в ответе (objects).

      • Action: событие, которое наступит после исчерпания лимита: замедление (throttle) или блокировка доступа (block). Событие действует до начала следующего периода действия подписки.

        предупреждение

        Уведомление по email (опция notify) недоступно в On-Premise.

      • Limit: лимит использования сущностей, указанных в Event type. Лимиты обнуляются с началом следующего периода действия подписки.

      • Period: временной отрезок, за который учитывается расходование лимитов: минута (minute), день (day) или месяц (month).

      

   3. Нажмите Сохранить.

7. Нажмите Создать подписку.

8. Переходите к созданию API-ключа.

   Если у партнёра ранее не было подписок указанного типа (demo или prod), первый API-ключ создаётся автоматически.

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

Вы можете изменить время действия подписки, набор входящих в неё сервисов и ограничений по работе с ними.

Изменение времени действия подписки

1. Перейдите на вкладку Партнёры и выберите карточку нужного партнёра.

2. В панели Подписки выберите нужную подписку.

3. Нажмите значок рядом с названием подписки и выберите Изменить время действия.

4. Укажите новую дату начала или время действия.

5. Нажмите Сохранить.

   

Изменение сервисов в подписке

предупреждение

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

Чтобы изменить набор сервисов в подписке и ограничения по работе с ними:

1. Перейдите на вкладку Партнёры и выберите карточку партнёра.
2. В панели Подписки выберите подписку.
3. Чтобы добавить сервис в подписку или удалить его, используйте переключатель слева от названия сервиса.

Чтобы изменить ограничения по работе с сервисом, нажмите значок .

Блокировка подписки

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

1. Перейдите на вкладку Партнёры и выберите карточку нужного партнёра.
2. В панели Подписки выберите нужную подписку.
3. Нажмите Заблокировать в правом верхнем углу панели.
4. Чтобы снять блокировку, нажмите Активировать.

---

API-ключи

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

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

1. Перейдите на вкладку Партнёры и выберите карточку нужного партнёра.

2. Создайте ключ в зависимости от типа активной подписки:

   • Нажмите Создать demo-ключ, чтобы создать API-ключ в рамках demo-подписки.
   • Нажмите Создать prod-ключ, чтобы создать API-ключ в рамках prod-подписки.

3. Заполните информацию о ключе:

   
   • Партнёр: партнёр, для которого создаётся ключ (по умолчанию выбран текущий партнёр).
   • Назначение ключа: описание назначения ключа.
   • Контактное лицо (необязательный параметр): данные о контактном лице для ключа. Если оставить поля пустыми, используются данные о контактном лице партнёра.

4. Нажмите Создать.

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

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

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

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

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

Можно управлять доступом только к тем сервисам, которые входят в действующую подписку. Чтобы изменить список доступных сервисов, отредактируйте подписку.

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

Редактирование ограничений сервиса в ключе

Чтобы изменить ограничения в работе сервиса в ключе, в строке с ним нажмите значок .

Ограничения определяются следующими параметрами:

• Features: возможности сервиса (доступные endpoint-ы) в рамках ключа. Если не указать значения, в будет разрешён доступ ко всем возможностям сервиса. Некоторые обязательные возможности предзаполняются автоматически и не могут быть удалены.

• Feature: метод API, на который распространяется ограничение.

• Event type: тип сущности, на которую распространяется ограничение: запрос (request) или получение данных об объекте (object).

• Action: событие, которое наступит после исчерпания лимита:

  • throttle — замедление до начала следующего временного периода;

  • block — блокировка сервиса; при необходимости его можно разблокировать вручную.

    предупреждение

    Уведомление по email (опция notify) недоступно в On-Premise.

• Limit: лимит использования сущностей, указанных в Event type, после исчерпания которого наступает ограничение (Action). Лимиты обнуляются с началом следующего временного периода (Period).

• Period: временной период, за который учитывается расходование лимитов: минута (minute), день (day) или месяц (month).

Разблокировка сервиса

Сервис может быть заблокирован после выполнения действия Блокировка при достижении лимита. Чтобы разблокировать сервис:

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

Дополнительные ограничения API-ключа

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

1. Выберите нужный ключ на вкладке API-ключи или на вкладке Партнёры в карточке партнёра.

2. В разделе Ограничения ключа нажмите значок .

3. Настройте ограничения ключа:

   

   • Deactivation time: дата блокировки ключа.

   • По территории: ограничение доступа по территории.

     • Группы сегментов: список доступных географических сегментов (территорий).
     • Вкл. сегменты: дополнительный список доступных сегментов, которые не входят в выбранные группы.
     • Искл. сегменты: список сегментов из выбранных групп, доступ к которым будет закрыт.

   • По приложению: ограничение доступа по ID мобильного приложения.

   • По IP или подсетям: ограничение доступа по IP-адресам.

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

4. Нажмите Сохранить.

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

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

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

Шаги:

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

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

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

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

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

Шаги:

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

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

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

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

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

Шаги:

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

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

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

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

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

Шаги:

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

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

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

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

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

Шаги:

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

Результат: ключ будет работать только для запросов от приложения с идентификатором 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.

Шаги:

1. В поле CIDR укажите подсеть 192.168.1.0/24.

2. Нажмите Сохранить.

3. Если вы используете прокси или 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.

Шаги:

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

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

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

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

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