Создание нового клиента#

Клиент – это внешняя интеграционная система, которая будет работать с API Jasper. Одна внешняя интеграционная система – один зарегистрированный в API Jasper клиент. Работа с API Jasper доступна только зарегистрированным и аутентифицированным клиентам. Логин и пароль передаются клиенту после развёртывания и настройки API Jasper и IdentityServer4. По этому логину и паролю клиент авторизуется в API Jasper и получает в IdentityServer4 временный токен, по которому в последующем взаимодействует с API Jasper.

Время действия токена 60 минут. После того как действие токена истекло, клиент должен заново запросить его в IdentityServer4. Запрос должен соответствовать протоколу OIDC.

Примечание

Для работы с OIDC используйте библиотеку OidcClient: C#, JavaScript.

При взаимодействии с API Jasper в заголовке HTTP-запроса [Authorization] необходимо указывать актуальный токен в формате «„Bearer“ + access_token», запрошенный в IdentityServer4.

Схема запроса токена в IdentityServer4 и взаимодействия авторизованного клиента с API Jasper при отправке HTTP-запросов:

../../_images/api1.png

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

  • как внешняя система;

  • как пользователь Geometa.

Добавление клиента как внешней интеграционной системы#

При авторизации используйте:

  • тип авторизации: OAuth 2.0 c Grant Type: Client Credentials;

  • Access Token URL с адресом https://{APIURL}/connect/token.

Чтобы зарегистрировать нового клиента API Jasper в качестве внешней интеграционной системы:

  1. Откройте главное окно приложения и нажмите Добавить нового клиента.

  2. Заполните открывшуюся форму:

../../_images/jasper_new_client1.png

  • [Наименование] – укажите уникальное наименование для клиента;

  • [Тип авторизации] – выберите значение «Как внешняя система»;

  • [Идентификатор клиента] – задайте идентификатор клиента;

  • [Секрет клиента] – задайте надёжный пароль. Требований к содержанию пароля клиента нет;

  • [Описание] – при необходимости укажите дополнительную информацию по клиенту. Поле заполнять необязательно.

Подсказка

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

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

  1. Передайте логин и пароль клиенту, чтобы он мог запросить по ним токен для отправки запросов в API Jasper.

  2. Назначьте права клиенту на создание и редактирование, либо права на просмотр объектов. Вы также можете добавить клиента без настройки прав, а назначить права позже.

  3. Нажмите Сохранить изменения, чтобы добавить клиента.

  4. Создайте для клиента в Системе субъект и свяжите субъект с клиентом в БД. Клиента можно не связывать с субъектом, в таком случае в полях [Кто создал], [Кто обновил] в системных свойствах карточки объекта будет указан идентификатор клиента.

Добавление клиента как пользователя Geometa#

Тип авторизации «Как пользователь Geometa» позволяет отображать изменения в Системе от имени субъекта, к которому привязана учётная запись Geometa. Если к учётной записи не привязан субъект, то отобразится запись: jasperApi_{идентификатор внешнего клиента}.

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

При авторизации используйте:

  • тип авторизации: OAuth 2.0 c Grant Type: Authorization Code (With PKCE);

  • Auth URL с адресом https://{APIURL}/connect/authorize;

  • Access Token URL с адресом https://{APIURL}/connect/token.

Чтобы зарегистрировать нового клиента API Jasper в качестве пользователя Geometa:

  1. Откройте главное окно приложения и нажмите Добавить нового клиента.

  2. Заполните открывшуюся форму:

../../_images/sistem1.png

  • [Наименование] – укажите уникальное наименование для клиента;

  • [Тип авторизации] – выберите значение «Как пользователь Geometa». Потребуется ввести логин и пароль;

  • [Идентификатор клиента] – задайте идентификатор клиента;

  • [Секрет клиента] – задайте надёжный пароль. Требований к содержанию пароля клиента нет;

  • [URI перенаправления или Callback URL] – укажите URI-адрес, на который будет произведено перенаправление для завершения процесса авторизации. Если внешний клиент реализован в виде мобильного приложения, то он может выглядеть так: com.gemsdev.sodalite://callback;

  • [URI перенаправления после выхода из системы] – укажите URI-адрес, на который будет произведено перенаправление после выхода из Системы;

  • [Описание] – при необходимости укажите дополнительную информацию по клиенту. Поле заполнять необязательно.

Подсказка

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

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

  1. Передайте логин и пароль клиенту, чтобы он мог по ним запросить токен для отправки запросов в API Jasper.

  2. Назначьте права клиенту на создание и редактирование, либо права на просмотр объектов. Вы также можете добавить клиента без настройки прав, а назначить права позже.

  3. Нажмите Сохранить изменения, чтобы добавить клиента.