provisioning

README

Сервис настроек

Параметры запуска сервиса

При старте сервис запускает два HTTP-сервера: административный и пользовательский.

Адрес и/или порт, на котором отвечает административный сервер, задаются с помощью параметра -admin <[addr]:port> при запуске сервиса:

• ./provisioning -admin localhost:8000
• ./provisioning -admin :8000
• ./provisioning -admin 10.0.0.1:8000

Для пользовательского сервера адрес и порт задаются с помощью -port <addr>.

Если указано имя хоста -letsencrypt <host>, то оно используется для автоматического получения сертификатов Let's Encrypt. В этом случае всегда используется порт 443 (по умолчанию, не указывается) для защищенных соединений и 80 для автоматического редиректа на 443 порт.

• ./provisioning -port localhost:8080
• ./provisioning -letsencrypt config.connector73.net

Полученные сертификаты кешируются и автоматически обновляются, когда истекает их срок действия.

В качестве хранилища данных используется файл в бинарном формате. Его имя и путь к нему можно задать с помощью параметра -db <filename>:

• ./provisioning -db test.db

Административный API

Описание сервисов

• PUT /services/<name> - задает описание сервиса. В качестве данных передается JSON или HTTP-form со списком параметров сервисов, используемых по умолчанию
• DELETE /services/<name>- удаляет описание сервиса с указанным именем
• GET /services/<name>- возвращает описание сервиса с указанным именем
• GET /services- возвращает список всех имен зарегистрированных сервисов

Например:
PUT /services/mx

{
  "address": "89.185.256.135",
  "port": "7778",
  "secure": true,
  "version": 6
}

Именованные группы сервисов

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

• PUT /groups/<name> - задает описание группы. В качестве данных передается JSON или HTTP-form со списком имен сервисов, используемых данной группой. Для каждого сервиса так же можно переопределить или добавить параметры сервиса внутри такого объекта
• DELETE /groups/<name>- удаляет описание группы с указанным именем
• GET /groups/<name>- возвращает описание группы с указанным именем
• GET /groups- возвращает список всех имен зарегистрированных групп

Например:
PUT /groups/test

{
  "mx": {
    "test": true,
    "version": 7
  },
  "store": null,
  "push": null
}

Пользователи

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

• PUT /users/<name> - задает описание пользователя. В качестве данных передается JSON или HTTP-form с параметрами, описывающими пользователя
• DELETE /users/<name>- удаляет описание пользователя с указанным именем
• GET /users/<name>- возвращает описание пользователя с указанным именем
• GET /users- возвращает список всех имен зарегистрированных пользователей
• GET /users/<name>/config- возвращает объединенную конфигурацию сервисов пользователя

Для описания пользователя используются следующие поля данных:

• name - задает необязательное отображаемое имя пользователя
• password - пароль пользователя, который может быть представлен в открытом виде либо в виде строки с хешом bcrypt. При сохранении пароля в открытом виде он автоматически заменяется соответствующем хешом. Пароль не может быть пустым.
• tenant - идентификатор Azure AD, к которому привязан пользователь
• group - задает название группы, не может быть пустым
• services - JSON с дополнительными параметрами сервисов с настройками пользователя

Пример:
PUT /users/maximd@xyzrd.com

{
  "password": "$2a$10$OC8LKbl.fU6xVh.o0bVktejzQwvkzGtkOSZ73GYZBAI1Q872FUUPK",
  "group": "test",
  "services": {
    "mx": {
      "login": {
        "password": "password",
        "user": "dmitrys"
      }
    }
  }
}

Пользовательские данные

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

• PUT /users/<name>/data - задает дополнительные данные пользователя, заменяя предыдущее значение
• PATCH /users/<name>/data- заменяет только указанные в запросе пользовательские данные, остальные оставляя неизменными. Если значение ключа null, то такие данные удаляются.
• DELETE /users/<name>/data- удаляет описание пользовательских данных с указанным именем
• GET /users/<name>/data- возвращает описание пользовательских данных с указанным именем

Администраторы

Если для сервиса задан хотя бы один администратор, то все обращения к API требуют авторизации в заголовке HTTP Basic.

• PUT /admins/<name> - задает пароль администратора с указанным в запросе именем; пароль задается с помощью JSON {"password": "password"} или HTML-form.
• DELETE /admins/<name> - удаляет администратора
• GET /admins/<name> - возвращает хеш от пароля администратора
• GET /admins - возвращает список зарегистрированных администраторов

Почта

Чтобы задать настройки для отправки почты через Gmail, нужно выполнить несколько шагов:

1. Задать идентификатор клиента и секретную строку, которую необходимо получить в Google
   PUT /gmail:

   {
     "id": "392045688696-...1i5.apps.googleusercontent.com",
     "secret": "Tr2na...IyuDcitAR"
   }
   

2. В ответ будет возвращен URL, по которому необходимо перейти и скопировать код подтверждения авторизации.

3. Добавить полученный код в запрос и передать это не сервер
   PUT /gmail:

   {
     "id": "392045688696-...1i5.apps.googleusercontent.com",
     "secret": "Tr2na...IyuDcitAR",
     "code": "4/Upw0Q2e...GTShpM"
   }
   

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

• PUT /gmail - задает или изменяет настройки почты (описано выше)
• GET /gmail - возвращает информацию о настройках почты

Почтовые шаблоны

• PUT /templates/<name> - задает именованный шаблон почтового сообщения
• DELETE /templates/<name> - удаляет именованный шаблон сообщения
• GET /templates/<name> - возвращает информацию о шаблоне почтового сообщения
• GET /templates - возвращает список зарегистрированных имен почтовых шаблонов
• POST /templates/<name>/send/<email> - отправляет почтовое сообщение с использованием указанного шаблона; именованные параметры, передающиеся при запросе, могут использоваться для заполнения шаблона

Шаблон почтового сообщения описывается следующими полями:

• subject задает заголовок сообщения
• template описывает текстовый шаблон сообщения
• html - флаг, указывающий на то, что письмо отправляется не в текстовом, а HTML формате

Пример шаблона:
PUT /templates/test

{
  "subject": "Тема письма",
  "template": "<h2>Приветствую тебя, о великий {{.name}}!<h2>\n<p>Тебе необходимо установить приложение <a href=\"{{.url}}\">{{.app}}</a>.</p>",
  "html": true
}

В качестве разметки шаблона используется нотация Golang Templates.

По умолчанию в шаблоне доступны следующие значения:

• {{.email}} - адрес пользователя
• {{.name}} - имя пользователя (может быть пустым)
• любые дополнительные именованные параметры, переданные в запросе

Для того, чтобы отправить письмо пользователю с помощью данного шаблона, необходимо выполнить следующий запрос:
POST /templates/test/send/maximd@xyzrd.com

{
  "app": "Connector73",
  "url": "app-info://9340234234"
}

Пользовательский API

Обобщенная конфигурация пользователя

• GET /config - возвращает обобщенную конфигурацию пользователя, собранную на основании группы и описания сервисов.

Для запроса необходима авторизация пользователя, которая передается в заголовке запроса HTTP Basic или HTTP Bearer для авторизации пользователей Azure AD.

Смена пароля пользователя

• POST /password - изменяет пароль пользователя на новый.

Новый пароль передается в теле запроса в виде HTTP-form или JSON:

{"password": "new password"}

Для запроса необходима авторизация пользователя, которая передается в заголовке запроса HTTP Basic. Т.е. пользователь может сменить пароль только в том случае, если он знает текущий свой пароль.

Для пользователей Azure AD смена пароля не поддерживается.

Токен для сброса пароля

• POST /reset/<email>

Для сброса пароля необходимо обратиться по адресу с указанием email пользователя. Авторизации данный запрос не требует.

По этому запросу создается специальный токен, с помощью которого можно сбросить пароль пользователя. Во избежание проблем с безопасностью и возможной блокировкой пользователя, новый пароль будет сгенериров только после того, как данный токен будет передан на сервер.

Токен отправляется пользователю с помощью почты. Для этого используется шаблон с предопределенным именем resetPassword, который должен быть зарегистрирован. Сам токен доступен в шаблоне в виде {{.token}}.

Для пользователей Azure AD смена пароля не поддерживается.

Сброс пароля

• POST /password/<token> - генерирует и возвращает новый пароль пользователя, для которого был создан этот токен.

Если в запросе указан параметр ?email, то новый пароль дополнительно отправляется на почтовый адрес пользователя. Для этого используется шаблон с предопределенным именем newPassword, который должен быть зарегистрирован. Сам пароль доступен в шаблоне в виде {{.password}}.

Дополнительные данные пользователя

• GET /data - возвращает дополнительные данные пользователя.

Для запроса необходима авторизация пользователя, которая передается в заголовке запроса HTTP Basic или HTTP Bearer для авторизации пользователей Azure AD.