Сервис ключей | Программный комплекс | 2GIS Documentation
Программный комплексbeta

Сервис ключей

Этот сервис позволяет выпускать API-ключи и управлять ими через веб-интерфейс администратора. Конечные пользователи сервисов программного комплекса 2ГИС затем используют предоставленные ключи для получения доступа к развернутым сервисам.

Администратор выпускает один или несколько API-ключей для партнёра. Это именованная сущность, которая хранит в себе сгруппированный набор API-ключей. Например, вы можете создать отдельных партнёров для команд разработки на Android и на iOS, независимо управляя ключами для обеих команд.

При выпуске API-ключа для него задаётся политика использования. Администратор может:

  • Разрешить доступ к определенному набору сервисов программного комплекса 2ГИС (несколько сервисов, все, ни один).
  • Запретить доступ, основываясь на:
    • Диапазоне IP-адресов (в CIDR-нотации).
    • Значениях следующих HTTP-заголовков:
      • Referer.
      • Origin.
      • User-Agent.

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

  • Ведут на своей стороне список выпущенных API-ключей для конечного пользователя, периодически обновляют этот список и связанные политики использования, обращаясь для этого к сервису ключей.
  • Принимают решение о разрешении или блокировке выполнения запросов конечного пользователя, основываясь на всей полученной от сервиса ключей информации.
  • Передают сервису ключей метаданные запросов, которые пытается выполнить пользователь.
Архитектура сервиса ключей

Сервис ключей состоит из двух сервисов: веб-сервиса администратора для выпуска и управления API-ключами и бэкенд-сервиса для взаимодействия с другими сервисами программного комплекса 2ГИС через RESTful API.

Каждый сервис перед выполнением запроса от конечного пользователя отправляет метаданные этого запроса в сервис ключей (включая API-ключ, с которым пришёл запрос). Сервис ключей логирует события, связанные с API-ключами, и хранит эти события в хранилище данных Apache Kafka. Дополнительно ведутся счетчики использования ключей, соответствующие данные хранятся в Redis. Сервис Tasker получает данные о событиях от бэкенда сервиса ключей и выполняет требуемые административные действия над ключами в зависимости от наступивших событий: например, блокирует или разблокирует конкретный API-ключ. Это позволяет сервису ключей контролировать использование API-ключей и управлять доступом, основываясь на квотах: например, можно заблокировать на один час доступ к сервисам карт для определенного API-ключа, если пользователь с этим ключом выполнит более 100 запросов за минуту к сервисам.

Примечание:

Поддержка хранилища данных Apache Kafka находится в стадии разработки и будет добавлена в будущих релизах.

Существующая версия работает без Apache Kafka. Таким образом, нельзя настраивать квоты, так как соответствующие метрики не собираются.

Детали архитектуры программного комплекса 2ГИС приведены в обзорном документе.

Общая инфраструктура:

  • Сервер LDAP для аутентификации пользователей панели администратора. Например, Microsoft Active Directory может выступать в роли сервера LDAP.
  • Хранилище Apache Kafka для событий, связанных с API-ключами.
  • Хранилище Redis для ведения статистики использования ключей.
  • Хранилище PostgreSQL для хранения ключей и связанных с ними данных. Необходимо развернуть PostgreSQL версии 11.

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

Выполните следующие шаги:

  1. Настройте хранилище PostgreSQL:

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

    2. Создайте пользователей (также известны как роли) для этой базы данных:

      1. Пользователь с правами только на чтение (read-only).
      2. Пользователь с правами на чтение и запись (read-write). Этот пользователь должен быть владельцем базы (owner) или суперпользователем (superuser).
    3. Измените привилегии по умолчанию (либо от имени владельца базы, либо от имени суперпользователя):

      ALTER DEFAULT PRIVILEGES FOR ROLE <read-write user name> IN SCHEMA public GRANT SELECT ON TABLES TO <read-only user name>;
      ALTER DEFAULT PRIVILEGES FOR ROLE <read-write user name> IN SCHEMA public GRANT SELECT ON SEQUENCES TO <read-only user name>;
      
  2. Создайте конфигурационный файл values-keys.yaml:

    dgctlDockerRegistry: <Docker Registry hostname and port>/2gis-on-premise
    
    db:
        ro:
            host: <hostname or IP address of PostgreSQL>
            port: <PostgreSQL port>
            name: <database name>
            username: <read-only user name>
            password: <read-only user password>
        rw:
            host: <hostname or IP address of PostgreSQL>
            port: <PostgreSQL port>
            name: <database name>
            username: <read-write user name>
            password: <read-write user password>
    
    ldap:
        host: <hostname or IP address of LDAP server>
        port: <LDAP port>
    
        useStartTLS: <true or false>
        useLDAPS: <true or false>
        skipServerCertificateVerify: <true or false>
        serverName: <server name>
        clientCertificatePath: <path to client certificate>
        clientKeyPath: <path to client key>
        rootCertificateAuthoritiesPath: <path to the root certificate authorities file>
    
        bind:
            dn: <user distinguished name>
            password: <password>
    
        search:
            baseDN: <base distinguished name>
            filter: <filter expression>
    
    tasker:
        resources:
            requests:
                cpu: 10m
                memory: 32Mi
            limits:
                cpu: 100m
                memory: 64Mi
    
        delay: 30s
    
    admin:
        apiUrl: <API Keys service API URL>
        appHost: <API Keys service web UI URL>
    ##
    ## Manually specify the administrator user(s) credentials if no LDAP servers are configured.
    ##
    # api:
    #    adminUsers: username1:password1,username2:password2,...
    

    Где:

    1. dgctlDockerRegistry: эндпоинт вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС.

    2. db: настройки доступа к серверу PostgreSQL.

      Сервис ключей работает с данными в двух режимах: только чтение (ro) и чтение-запись (rw). В обоих режимах сервис работает с одной базой, но от имени пользователей с разными правами (см. подробности в шаге 1).

      Задайте:

      1. Настройки, общие для обоих режимов:

        1. host: имя хоста или IP-адрес сервера.
        2. port: порт, на котором слушает сервер. Например, 5432.
        3. name: имя базы данных.
      2. Реквизиты для доступа к базе пользователя с правами только на чтение (секция ro).

      3. Реквизиты для доступа к базе пользователя с правами на чтение и запись (секция rw).

      Для хранения настроек password в группах ro и rw Helm-чарт использует Kubernetes Secrets.

    3. ldap: настройки доступа к серверу LDAP.

      1. host: имя хоста или IP-адрес сервера.

      2. port: порт, на котором слушает сервер. Например, 3268.

      3. Группа настроек для обеспечения защищенного соединения с сервером LDAP:

        1. useStartTLS: флаг, определяющий, использовать ли StartTLS (по умолчанию: false).
        2. useLDAPS: флаг, определяющий, использовать ли Secure LDAP (по умолчанию: false).
        3. skipServerCertificateVerify: флаг, определяющий, пропускать ли проверку сертификата сервера (по умолчанию: false).
        4. serverName: строка с именем сервера. Используется при проверке сертификата сервера.
        5. clientCertificatePath: путь к сертификату клиента.
        6. clientKeyPath: путь к ключу клиента.
        7. rootCertificateAuthoritiesPath: путь к файлу с корневыми сертификатами от центров сертификации (root certificate authorities).
      4. bind: реквизиты для доступа к серверу LDAP:

        1. dn: уникальное имя пользователя (distinguished name).
        2. password: пароль пользователя.
      5. search: настройки поиска LDAP:

        1. baseDN: основное относительное уникальное имя (base relative distinguished name). Например, dc=2gis.
        2. filter: фильтр LDAP, используемый для идентификации записей в поисковых запросах. Например, (&(objectClass=user)(sAMAccountName=%s)).
    4. tasker: настройки сервиса Tasker, который выполняет административные задачи, связанные с API-ключами.

      1. resources: настройки вычислительных ресурсов для сервиса. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. таблицу с минимальными системными требованиями.
      2. delay: период (в секундах). Эта настройка определяет, с каким периодом проверять задачи, которые связаны с настроенными отложенными действиями (например, блокировкой API-ключа).
    5. admin: настройки веб-сервиса администратора (предоставляет доступ к веб-интерфейсу для администрирования сервиса).

      1. apiUrl: URL бэкенда сервиса ключей. Например, http://keys-api.host. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
      2. appHost: URL фронтенда сервиса ключей. Например, https://keys-ui.host. Этот URL должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.
    6. api.adminUsers: список реквизитов пользователей с административными правами в формате username1:password1,username2:password2,.... Раскомментируйте и используйте эту настройку, если нет настроенных серверов LDAP.

      Для хранения этой настройки Helm-чарт использует Kubernetes Secrets.

      Примечание:

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

  3. Разверните сервис ключей с помощью Helm, используя подготовленный конфигурационный файл values-keys.yaml:

    helm upgrade --install --version=1.0.3 --atomic --wait-for-jobs --values ./values-keys.yaml keys 2gis-on-premise/keys
    

    Helm выполнит развертывание сервиса.

  4. Добавьте пользователей в сервис с помощью утилиты keysctl. Этим пользователям будет назначена роль администратора сервиса ключей.

    Важное примечание:

    Выполните этот шаг вне зависимости от выбранного механизма аутентификации: с помощью LDAP или через список реквизитов открытым текстом (настройка api.adminUsers).

    При использовании LDAP достаточно добавить одного пользователя. При использовании списка реквизитов необходимо добавить всех пользователей из этого списка.

    Чтобы добавить одного пользователя, выполните эту команду из любого пода keys-api:

    keysctl users add "admin username" "Display Name"
    

Каждый сервис, который интегрируется с сервисом ключей, обязан отправлять информацию об использовании API-ключей конечными пользователями на бэкенд сервиса ключей. Чтобы сервис мог взаимодействовать с этим бэкендом, нужно во время конфигурации сервиса задать сервисный API-ключ.

Чтобы получить список сервисных ключей, которые нукжно использовать для взаимодействия с развернутым сервисом ключей, выполните эту команду из любого пода keys-api:

keysctl services

Детальную информацию см. в обзорном документе.

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

helm upgrade --version=1.0.3 --atomic --wait-for-jobs --values ./values-keys.yaml keys 2gis-on-premise/keys

Чтобы проверить работоспособность сервиса ключей:

  1. Окройте в браузере веб-интерфейс для администрирования сервиса (используйте значение настройки appHost из конфигурационного файла values-keys.yaml):

    https://app.host/
    
  2. Войдите в веб-интерфейс, используя учетные данные пользователя с правами администратора (это пользователь, которому была назначена роль администратора с помощью утилиты keysctl). Вы должны увидеть веб-интерфейс для управления API-ключами.