Skip to main content

Автоматическая подготовка устройств

Версия: 1.26.0

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

Когда автоматическая подготовка настроена, авторизованное устройство сначала создаст пользователя службы в OpenRemote, если он еще не существует. Во-вторых, он создаст актив в указанной области OpenRemote с атрибутами, используя «Шаблон актива». На основе «Ролей» устройство теперь может взаимодействовать с этим активом.

Терминология​

  • Клиент: относится к инициатору связи с OpenRemote; то же значение, что и в терминологии аутентификации.
  • Актив: любой актив в системе OpenRemote.
  • Обеспечение: создание в системе OpenRemote.

Тип обеспечения​

Существует два основных механизма подготовки клиентов.

Сертификат клиента X.509​

Поддерживает механизм аутентификации сертификата отраслевого стандарта X.509, при котором каждый клиент имеет уникальный сертификат клиента, подписанный сертификатом CA, который также должен быть зарегистрирован в OpenRemote. Сертификат должен содержать уникальный идентификатор в атрибуте CN сертификата. Затем OpenRemote проверяет сертификат и атрибут CN, представленные во время подготовки.

Это наиболее безопасный механизм аутентификации, но он усложняет процесс производства/прошивки.

Симметричный ключ (HMAC-SHA256)​

ЕЩЕ НЕ РЕАЛИЗОВАНО

Использует общий секрет для аутентификации; HMAC защищает целостность и подлинность зашифрованного сообщения; HMAC генерируется на основе уникального идентификатора клиента и общего секрета; Затем OpenRemote проверяет HMAC на основе уникального идентификатора, представленного во время подготовки.

Этот механизм менее безопасен, особенно если общий секрет хранится в доступном виде на клиентском устройстве; от этого защищает использование HSM (Аппаратный модуль безопасности); Кроме того, предварительное создание клиентского HMAC и загрузка его на клиентское устройство перед предоставлением означает, что секрет не нужно передавать, но еще раз усложняет производственный процесс.

TL;DR​

Перейти к:

Реализация​

Подключить поток​

Ниже показан процесс подключения (через MQTT Topics), который клиенты могут использовать для автоматической подготовки пользователя службы и, при необходимости, актива, идентификатор которого генерируется с использованием UNIQUE_ID, предоставленного клиентом; затем клиент аутентифицируется, и актив возвращается клиенту.

Процесс автоматической подготовки устройства между клиентом и UMEC Manager

ОБРАТИТЕ ВНИМАНИЕ, ЧТО «ОТКАЗ БЕЛОГО/ЧЕРНОГО СПИСКА» ЕЩЕ НЕ РЕАЛИЗОВАН. ЭТА ФУНКЦИЯ ПОВЫШАЕТ БЕЗОПАСНОСТЬ, ТОЛЬКО ОПРЕДЕЛЕННЫЕ УСТРОЙСТВА МОГУТ ПОДКЛЮЧИТЬСЯ (БЕЛЫЙ СПИСОК) ИЛИ МОГУТ БЫТЬ ИСКЛЮЧЕНЫ (ЧЕРНЫЙ СПИСОК)

Проверка сертификата клиента X.509​

  1. Найдите конфигурацию области X.509, субъект сертификата CA которой соответствует эмитенту сертификата клиента.
  2. Убедитесь, что сертификат клиента подписан центром сертификации.
  3. Извлеките значение субъекта сертификата клиента «CN».
  4. Убедитесь, что он соответствует UNIQUE_ID.

Проверка симметричного ключа​

ЕЩЕ НЕ РЕАЛИЗОВАНО

  1. Восстановите HMAC, используя общий секрет и UNIQUE_ID, и проверьте его совпадение.
  2. Найдите совпадение конфигурации области, где HMAC сгенерирован с использованием секретных совпадений.

Схема сообщения​

Сообщение запроса на предоставление X.509​

Формат сообщения обеспечения для X.509 следующий:

    {      "type": "x509",      "cert": "..."    }

Поле сертификата должно быть в формате PEM и должно содержать цепочку сертификатов вплоть до сертификата CA, зарегистрированного в OpenRemote.

Сообщение с запросом на предоставление симметричного ключа​

ЕЩЕ НЕ РЕАЛИЗОВАНО

Формат сообщения подготовки для HMAC следующий:

    {      "type": "hmac-sha256",      "code": "..."    }

Поле кода должно быть в формате HMAC в кодировке Base64, специфичном для этого клиента.

Сообщение об успешном ответе​

    {      "type": "success",      "realm": "REALM_NAME",      "asset": {...}    }

Ответное сообщение об ошибке​

    {      "type": "error",      "error": "ERROR_TYPE"    }
Тип ошибки​
  • MESSAGE_INVALID - Не удалось проанализировать сообщение запроса.
  • CERTIFICATE_INVALID — Сертификат X.509 недействителен.
  • НЕ АВТОРИЗИРОВАНО - Подходящая конфигурация не найдена.
  • ЗАПРЕЩЕНО - Уникальный идентификатор не попадает в белый/черный список.
  • UNIQUE_ID_MISMATCH — уникальный идентификатор, используемый в подписке, не соответствует учетным данным.
  • CONFIG_DISABLED — конфигурация соответствующей области помечена как отключенная.
  • USER_DISABLED — ранее предоставленный пользователь службы отключен.
  • SERVER_ERROR — во время обработки произошло неизвестное исключение.
  • ASSET_ERROR — ранее предоставленный актив не находится в той же области, что и соответствующая конфигурация области.

Генерация сертификата​

Генерация сертификата клиента выполняется с использованием стандартных инструментов, например. опенссл:

  1. Уникальный закрытый ключ клиента и сертификат X.509 должны быть созданы с использованием уникального идентификатора клиента, хранящегося в атрибуте CN сертификата.
  2. Затем сертификат должен быть подписан промежуточным центром сертификации (может быть самоподписанным или подписанным центром сертификации).
  3. Затем промежуточный сертификат CA загружается в конфигурацию области OpenRemote.

Когда клиент публикует свой сертификат в OpenRemote, он должен быть в формате PEM. Генерация сертификата клиента может происходить в производственной среде без каких-либо внешних зависимостей.

Примечание

Безопасность закрытого ключа(ов) CA имеет важное значение: в случае компрометации сертификат может быть помечен как отозванный в OpenRemote, и это потребует замены всех клиентских сертификатов, подписанных этим скомпрометированным сертификатом CA, с приложением значительных усилий.

Несколько полезных команд:​

Создайте самозаверяющий сертификат CA (включая ключ):

openssl req -x509 -sha256 -nodes -newkey rsa:4096 -keyout ca.key -days 730 -out ca.pem

Создать CSR для устройства (включая ключ):

openssl req -nodes --newkey rsa:4096 -keyout deviceN.key -subj "/C=NL/ST=North Brabant/O=OpenRemote/CN=deviceN" -out deviceN.csr

Создайте подписанный сертификат для устройства:

openssl x509 -req -in deviceN.csr -CA ca.pem -CAkey ca.key -CAcreateserial -out deviceN.pem -days 500 -sha256

Предоставление активов​

Когда клиент (устройство) успешно проходит аутентификацию, можно автоматически предоставить актив, который может представлять клиента в OpenRemote; это делается путем предоставления шаблона актива (актив в представлении JSON), который будет гидратирован, сохранен и возвращен клиенту в полезной нагрузке сообщения об успехе. Идентификатор созданного актива получается из UNIQUE_ID, поэтому при будущих проверках подлинности ранее созданный актив можно найти и просто вернуть, а не создать заново. Следующий заполнитель можно использовать в шаблоне актива, чтобы обеспечить автоматическую замену UNIQUE_ID аутентифицированного клиента:

%UNIQUE_ID%

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

Конфигурация​

Настройка автоматической инициализации осуществляется через Manager UI -> Auto Provisioning (верхнее правое меню); пункт меню присутствует только для суперпользователей.

Конфигурация подготовки​

Конфигурации обеспечения используются для обеспечения возможности настройки вышеперечисленного через Manager UI; область может содержать любое количество элементов Provisioning Configuration.

Примечание

Если клиент соответствует более чем одной конфигурации подготовки, нет гарантии, какая из них будет использоваться.

Конфигурация подготовки содержит следующие данные:- Имя — метка, которая будет присвоена этой конфигурации обеспечения для идентификации [ОБЯЗАТЕЛЬНО]

  • Тип - используемый механизм аутентификации (в настоящее время поддерживается только X.509) [ОБЯЗАТЕЛЬНО]
  • Область — область, к которой применяется конфигурация подготовки к [REQUIRED]
  • Роли — роли, которые применяются к каждому пользователю службы автоматической подготовки (по умолчанию: none) [НЕОБЯЗАТЕЛЬНО]
  • Создать пользователя с ограниченными правами. Если пользователю службы автоматической инициализации сделать ограниченный доступ (по умолчанию: false) [НЕОБЯЗАТЕЛЬНО]
  • Отключено - отключена ли эта конфигурация подготовки (ни один клиент не сможет пройти через нее аутентификацию, пока она отключена) (по умолчанию: false) [НЕОБЯЗАТЕЛЬНО]
  • Шаблон актива. Если указано, экземпляр этого актива будет автоматически подготовлен после успешной аутентификации; предоставляется только в том случае, если актив, соответствующий UNIQUE_ID клиента, еще не существует (по умолчанию: none) [НЕОБЯЗАТЕЛЬНО]

Пример шаблона актива (дополнительную информацию о получении шаблона актива см. ниже)

{}

Следующие данные относятся только к механизму X.509:

  • Игнорировать дату истечения срока действия. При необходимости игнорируйте клиентские сертификаты, срок действия которых истек; они все равно должны быть подписаны сертификатом CA (по умолчанию: false) [НЕОБЯЗАТЕЛЬНО]
  • Сертификат ЦС (PEM). Сертификат ЦС подписывающего центра, который должен соответствовать сертификату ЦС, используемому для подписи сертификата каждого клиента, и должен быть в формате PEM. НЕ ВСТАВЛЯЙТЕ ЗДЕСЬ ЧАСТНЫЙ КЛЮЧ [ОБЯЗАТЕЛЬНО]

Пример сертификата PEM CA

-----BEGIN CERTIFICATE-----
MIIF/TCCA+WgAwIBAgIUZ/o8/s1N8dM2kn3jqrzMfoF+/SMwDQYJKoZIhvcNAQEL
BQAwgYwxCzAJBgNVBAYTAk5MMRYwFAYDVQQIDA1Ob3J0aCBCcmFiYW50MRIwEAYD
VQQHDAlFaW5kaG92ZW4xEzARBgNVBAoMCk9wZW5SZW1vdGUxFjAUBgNVBAMMDW9w
ZW5yZW1vdGUuaW8xJDAiBgkqhkiG9w0BCQEWFXN1cHBvcnRAb3BlbnJlbW90ZS5p
bzAgFw0yMTEwMjgxMTA5MjJaGA8yMDcxMDIwODExMDkyMlowgYwxCzAJBgNVBAYT
Ak5MMRYwFAYDVQQIDA1Ob3J0aCBCcmFiYW50MRIwEAYDVQQHDAlFaW5kaG92ZW4x
EzARBgNVBAoMCk9wZW5SZW1vdGUxFjAUBgNVBAMMDW9wZW5yZW1vdGUuaW8xJDAi
BgkqhkiG9w0BCQEWFXN1cHBvcnRAb3BlbnJlbW90ZS5pbzCCAiIwDQYJKoZIhvcN
AQEBBQADggIPADCCAgoCggIBALYNz5ZWMpFu+2K1kNep34Keh2clknA7Rm3Wke7p
HoTpjddqHNvQSVjSOB7CZA1E5+a8O7mU6kvnE3wed/h+DO3cQWihbYTw9lNr9+2M
LS8+jny+lDeuXOMXxcb3og4Cn88mfPihdsUkmI/i7Hk3oSjonyLPycMW/M3d1S6L
6YkgrdkA3jbMtaR9epcCv/g1P9WBKzF05qIs1lVEzGXOyF2Km2rPAdUcUjFplBbE
DyUgzbAYsdUTz0PCvAFi1y82/xreWeZQ8OlW1TnqMOR0elVDf/d8An+a3LV/uSaB
ihmdS4yvxcqZNGU+ShbBO6P+8JjLQNDmPQgjEURCYT4NyHRBChJr31CCvV2QJ2Ik
Hn5by9/KvvnZ/5y3KjYht9V3ooD0ptxIVKhhwuNFeDSC9Pnqr2QL+mawlWq+Wq/q
/PMN034gTqLkYAsm4ltoQj/L0ebRdQ0t9L9FML4+fDtEOWAUz3/vRcN1J2y5dNjZ
Y4H+bTAemGXpD3kz0VyhKWdPGQZgAMJ6gEHHzY4Ooi3UsLXt53knmLjkG3jo6g/Y
WJOiWcn7TlRRj9Pjmj+aTx1/9o8+3MnEm0THAUX1zN5IUfU1OnpcHWee2QbUlaTu
dYYYZQ+dCJImSWgp48FMFwPXLibF/xsAfYAIhw9isfQSe0JmUBv41MsOyzHJBYsA
H29NAgMBAAGjUzBRMB0GA1UdDgQWBBQnxsJQgUOdmW/iSvTJ67WtpHe8ojAfBgNV
HSMEGDAWgBQnxsJQgUOdmW/iSvTJ67WtpHe8ojAPBgNVHRMBAf8EBTADAQH/MA0G
CSqGSIb3DQEBCwUAA4ICAQBIbKYJDzEWn6yP44t3BYLb/1XIW/f+LUCNDIdlXKco
sxcMddWHNLFTC05fd/HKaUWBGEMBpuV2EjZHCxX8b3g5yhEMy2gU3BaMel777vcg
EG7c82+kOzuunuH7vUTi4NhTFko/iIgqlIbQYF/8oWnFH7tn5PMhaiGEMMEOCf1Y
fKedTGM+Or4e/ptddWroucqw9wzIZ9Wi/YYsLxwpdew2Eay7OZhY8qnH5rvkiUjG
SgkSmxyN3F+EZQj00G15yVmFpJ1bhLT4s9a33gqcMUon0eHVlGpLcF/0vxVvZ5zr
UUPb1MKUhxSqpFC7h+2odlDwtfepCCTAvpnqiI794ewvkblcafJ5lbypNUjTSXBA
+Fi1BcJteEBCVGOOLs34bquAtNdPEmc37wZA+5QNdz9WnYLCgvnrPh8VEXTdqqqb
Mf4/Rr0GbUOmRZXk0LordT3IwOq67c2HrbTFD5H6SGgEiyslzGeDjZyMWJ6uy+ae
MydnFVor6diyzew3MwhCZJKxMu/UJYaECuUtazLWhQi3q0YbQlYMcIGHfp7jDpXa
1ibFAeRSri7PXTVqMNuJ1dftG7s08V55N1AB/3w9f8kkOOO2jZpwRauhIUJA++Xh
Iq6M+PLEvBky6g/v6zOf7/68LtseuaSmMw7GxRVXX2BcrEjSLVz24INa24ZxM87P
qQ==
-----END CERTIFICATE-----

Его необходимо отформатировать для использования в полезных данных JSON, заменив символы новой строки встроенными символами новой строки. Пример команды для этого:

awk 'NF {sub(/\r/, ""); printf "%s\n",$0;}'

Получение шаблона актива​

  1. Войдите в Manager UI и перейдите к средству просмотра активов.
  2. Создайте, затем выберите актив того же типа, который вы хотите использовать в шаблоне, затем выберите идентификатор актива в адресной строке (например, https://staging.demo.openremote.io/manager/?realm=smartcity#/assets/false/2K3nSg148fnzlSlaem0kkh -> 2K3nSg148fnzlSlaem0kkh).
  3. Откройте Swagger UI по адресу https://your-installation.example/swagger (например, в демонстрационной среде).
  4. Нажмите «Авторизовать», затем еще раз во всплывающем диалоговом окне, затем войдите в систему с пользователем из главной области.
  5. После аутентификации перейдите к Assets -> Get /asset/{assetId} и вставьте идентификатор актива во входные данные идентификатора актива, затем выполните запрос, после чего вы получите актив, возвращенный в формате json: image
  6. Вы можете скопировать возвращенный json и вставить его в поле ввода Asset template:
    1. Удалите или установите parentId, чтобы определить, где в дереве активов будет создан актив.
    2. не забудьте вставить заполнитель %UNIQUE_ID% везде, где вы хотите его использовать (в значении атрибута, в имени актива и т. д.).

См. также​

Уведомление о лицензии: атрибуция документации OpenRemote