BearPass

Appearance

API ​

Важно

Доступно только для платных тарифов

BearPass предоставляет API для интеграции с внешними системами и автоматизации рабочих процессов.

В этом разделе: ​

Аутентификация в API ​

Для аутентификации запросов поддерживаются два способа:

  • Через JWT-токены внешних OIDC-провайдеров. Предпочтительный способ для автоматизированных сценариев (CI/CD, пайплайны). Не требует создания долгоживущих ключей.
  • Через статичный API-ключ. Классический способ аутентификации. Используется, если внешняя система не поддерживает выпуск JWT-токенов или требуется долгоживущее соединение.

Если ваша инфраструктура использует OIDC-совместимого провайдера (например, GitLab CI, GitHub Actions), рекомендуется применять JWT-аутентификацию.

Аутентификация с использованием JWT-токенов внешних провайдеров ​

JWT-аутентификация (JSON Web Token) — это механизм, позволяющий настроить обмен токенов любой системы, совместимой с протоколом OpenID Connect, на токен доступа к API BearPass. BearPass выступает в роли проверяющей стороны и доверяет информации, содержащейся в JWT, выпущенном внешним провайдером идентификации.

Популярные сценарии использования:

  • Выполнение запросов к API BearPass из пайплайнов CI/CD для получения паролей и других секретов.
  • Интеграция с внутренними системами автоматизации, где уже используется OIDC-провайдер.
  • Предоставление доступа к API внешним сервисам без необходимости создания и хранения долгоживущих API-ключей.

Схема работы ​

  1. Настройка доверенного провайдера. Администратор создает в BearPass конфигурацию внешнего OIDC-провайдера с обязательными параметрами:
  • Issuer — адрес OIDC-провайдера, выпустившего токен (передается в JWT-токене в качестве стандартного claim iss).
  • JWKS URL — адрес, по которому BearPass получит открытые ключи для проверки подписи JWT-токенов.
  • Audience — идентификатор приложения/ресурса, для которого выпущен токен (передается в JWT-токене в качестве стандартного claim aud).

  1. Привязка пользователя. Пользователь, от аккаунта которого будут выполняться запросы к API BearPass, создает персональную привязку. В привязке указывается, какому внешнему субъекту соответствует его учетная запись — уникальному идентификатору пользователя в системе внешнего провайдера (передается в JWT-токене в качестве стандартного claim sub).

  2. Запрос к API. Внешняя система (например, job в GitLab CI или GitHub Actions) формирует JWT-токен и передает его в теле запроса к эндпоинту /api/auth/login-by-jwt. В ответ возвращается токен авторизации BearPass, который указывается в заголовке Authorization: Bearer <token> при вызовах методов API.

  3. Валидация и авторизация. BearPass проверяет:

  • Подлинность токена с помощью публичного ключа, полученного по JWKS URL.
  • Соответствие issuer и audience настройкам доверенного провайдера.
  • Наличие привязки для значения sub из токена к активному пользователю BearPass.
  1. Доступ к ресурсам. Если все проверки пройдены, BearPass исполняет запрос от имени пользователя, найденного по привязке, применяя все его права и ограничения.

Процесс настройки состоит из двух этапов:

  1. Добавление доверенного провайдера
  2. Создание пользовательской привязки к этому провайдеру

Доверенные провайдеры JWT ​

Важно

Раздел доступен только пользователям с правом «Управление доверенными провайдерами».

Просмотр списка доверенных провайдеров ​

Перейдите в раздел «API» и откройте вкладку «Доверенные провайдеры».

Отобразится таблица со списком всех созданных провайдеров:

  • ID — уникальный идентификатор провайдера в системе.
  • Название — наименование провайдера, заданное при создании.
  • Issuer — адрес OIDC-провайдера.
  • Статус — состояние провайдера: Активен или Не активен.
    • Важно: если провайдер отмечен как Не активен, все созданные для него пользовательские JWT-привязки автоматически скрываются из интерфейса и не могут использоваться для доступа к API. При повторной активации провайдера привязки снова становятся доступны без потери данных.
  • Создан — дата и время создания записи.

В правой части каждой строки таблицы расположены иконки для управления:

  • Карандаш — редактирование провайдера.
  • Корзина — удаление провайдера.

Над таблицей расположена кнопка «Добавить провайдера» для создания нового.

Создание доверенного провайдера ​

  1. Нажмите кнопку «Добавить провайдера» над таблицей.
  2. Заполните форму создания:
  • Название — произвольное наименование провайдера.
  • Issuer — введите адрес OIDC-провайдера, выпустившего токен.
  • JWKS URL — введите URL списка публичных ключей OIDC-провайдера.
  • Audience — введите идентификатор получателя токена.
  • Активен — переключатель состояния провайдера. Только активные провайдеры доступны для выбора при создании персональных привязок.
  1. Нажмите «Сохранить».

После сохранения провайдер появится в списке и станет доступен для создания пользовательских привязок.

Пример конфигурации для GitHub Actions ​

Для авторизации через GitHub Actions создайте доверенного провайдера со следующими параметрами:

После сохранения провайдера вы сможете создавать JWT-привязки для пользователей, которые будут использовать токены GitHub Actions для доступа к API.

Редактирование и удаление провайдера ​

Для редактирования:

  • Найдите нужного провайдера в таблице.
  • Нажмите иконку карандаш в правой части строки.
  • Внесите необходимые изменения в форму редактирования.
  • Нажмите «Сохранить».

Для удаления:

  • Найдите нужного провайдера в таблице.
  • Нажмите иконку корзина в правой части строки.
  • Подтвердите удаление в появившемся диалоговом окне.

Важно: при удалении провайдера все созданные пользовательские привязки к этому провайдеру будут автоматически удалены.

JWT-аутентификация пользователей ​

Важно

Данный раздел доступен пользователям с правом «Использование API».

Для управления своими JWT-привязками перейдите в раздел «API» и откройте вкладку «JWT-авторизация».

Просмотр списка привязок ​

Основной интерфейс вкладки содержит таблицу со списком всех созданных вами JWT-привязок.

Таблица состоит из следующих колонок:

  • ID — уникальный идентификатор привязки в системе.
  • Название — название, которое вы задали при создании, для удобства ориентирования в списке.
  • Провайдер — доверенный провайдер, к которому относится данная привязка.
  • Создан — дата и время создания привязки.
  • Последнее использование — дата и время последней успешной аутентификации в API с использованием этой привязки.

Для каждой привязки в правой части строки доступны иконки для ее редактирования (карандаш) и удаления (корзина).

Над списком привязок расположена кнопка «Добавить привязку» для создания новой.

Создание новой JWT-привязки ​

Для создания привязки необходимо, чтобы в системе уже был добавлен и активирован хотя бы один доверенный провайдер. Если активных провайдеров нет, кнопка «Добавить привязку» будет заблокирована.

При нажатии на кнопку «Добавить привязку» открывается форма, состоящая из двух вкладок. Обязательные для заполнения поля находятся на первой вкладке, вторая содержит вспомогательный инструмент для отладки.

Вкладка «Настройка доступа»

На этой вкладке необходимо заполнить следующие поля:

  • Название: Произвольное наименование привязки для идентификации в списке.
  • Провайдер: Выберите из выпадающего списка доверенного провайдера, токенами которого вы планируете пользоваться.
  • Subject: Уникальный идентификатор пользователя в системе внешнего провайдера. Соответствует стандартному claim sub в JWT-токене. Значение можно узнать из документации провайдера или из самого токена.

В нижней части вкладки расположена функция «Заполнить автоматически с помощью токена».

Это необязательный вспомогательный инструмент, который позволяет быстро извлечь Subject из уже готового JWT-токена.

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

  • При нажатии на функцию открывается дополнительное поле для вставки JWT-токена.
  • Если вставить токен с корректной структурой, система автоматически извлечет из него значение sub и перезапишет им текущее содержимое поля Subject.
  • Важно: Перезапись происходит только при успешной проверке токена. Отменить замену можно, нажав кнопку «Отмена» в форме создания привязки. Если нажать «Сохранить», Subject сохранится с новым значением, извлеченным из токена.
  • Поле для токена не сохраняет значение между сессиями — если закрыть форму и открыть ее снова, поле будет пустым, даже если при предыдущем открытии вы вставляли токен.

Если при автозаполнении появилась ошибка:

  • Под полем JWT отобразится техническое сообщение, которое укажет на причину — например, несовпадение issuer, audience, проблемы с подписью или неверный формат токена. Subject при этом не изменится.
  • Для более детального анализа — например, чтобы увидеть, какие именно claims содержит токен (iss, aud, sub и другие) — используйте вкладку «Проверка токена JWT». Это поможет понять, почему токен не проходит проверку, и скорректировать настройки провайдера или выбрать правильный токен.

Вкладка «Проверка токена JWT»

Функционал вкладки опционален и предназначен для отладки. С его помощью можно проверить корректность JWT-токена и его соответствие настройкам выбранного провайдера до создания привязки.

Для проверки:

  1. Выберите из списка того же провайдера, для которого создается привязка.
  2. Вставьте ваш JWT-токен в поле ввода.

Если формат токена корректен, под полем ввода отобразятся данные из токена: iss, aud, sub, алгоритм подписи alg и полное содержимое (Payload).

Если токен не соответствует настройкам выбранного провайдера (например, несовпадение issuer или audience), отобразятся соответствующие сообщения об ошибках. Текст ошибки укажет на источник проблемы: в настройках провайдера или в самом токене.

После того как все обязательные поля на вкладке «Настройка доступа» заполнены (вручную или с помощью автозаполнения), нажмите кнопку «Сохранить». Новая привязка появится в общем списке, и вы сможете использовать JWT-токены для доступа к API BearPass.

Аутентификация с использованием API-ключа ​

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

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

Важно

Пользователь должен иметь право «Использование API».

  1. Перейдите в раздел «API», вкладку «API-ключи».
  2. Нажмите кнопку «Добавить ключ».
  3. Скопируйте созданный ключ — после закрытия диалогового окна он больше не будет доступен.

Использование API ​

После того как вы выбрали способ аутентификации и получили необходимые данные (JWT-токен или API-ключ), вы можете переходить к работе с методами API. Прямая ссылка на документацию API вашего экземпляра BearPass доступна в разделе API — во вкладках API-ключи и JWT-авторизация.

В документации описаны все методы API приложения:

api2.png

Для вызова методов API программно получите токен авторизации с помощью одного из методов:

  • POST /api/auth/login-by-api-key — Авторизация пользователя по ключу API
  • POST /api/auth/login-by-jwt — Авторизация пользователя по JWT

Полученный токен передавайте в заголовке Authorization, используя схему Bearer, например: При использовании JWT-токена:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

При использовании API-ключа:

Authorization: Bearer 2373|aQGpWsAiYqa4qlijYMN45aTaMIIKXmROYPt3gU0e15585f2

С точки зрения вызова методов API оба способа идентичны — вы подставляете разные токены в заголовок. Вся логика проверки происходит на стороне BearPass.