Local Admin Security cho công tơ IAMMETER: Hướng dẫn sử dụng

Mô-đun Local Admin Security có trong firmware i.91.065.3 trở lên.

Trong trang này

Mục đích
Cấu hình Admin Security trong giao diện web
API không yêu cầu Basic Authentication
Tài liệu tham chiếu API
Cách hoạt động của khôi phục mật khẩu
Các tình huống sử dụng

Mục đích

Mô-đun Local Admin Security bảo vệ giao diện web cục bộ và các API cục bộ nhạy cảm của thiết bị khỏi truy cập trái phép.

Sau khi bật tính năng, tên người dùng và mật khẩu quản trị được yêu cầu cho:

tất cả Set API có trên trang WEM API Test;
API GET trả về dữ liệu cấu hình nhạy cảm hoặc thực hiện thao tác nhạy cảm;
thao tác tải lên và nâng cấp firmware OTA cục bộ.

Các thao tác này bao gồm thay đổi cài đặt mạng hoặc tải dữ liệu lên, cập nhật firmware, khởi động lại thiết bị, khôi phục cài đặt gốc và sửa các tham số cấu hình nhạy cảm khác.

Mô-đun cung cấp:

thông tin quản trị có thể cấu hình;
HTTP Basic Authentication cho API cục bộ được bảo vệ;
thay đổi thông tin đăng nhập qua giao diện web hoặc API;
quy trình khôi phục dựa trên chữ ký Ed25519 khi quên mật khẩu quản trị.

Tính năng mặc định tắt để tương thích với firmware cũ. Cần bật và cấu hình trước khi cơ chế bảo vệ truy cập có hiệu lực.

Giao diện web cục bộ hiện dùng HTTP. HTTP Basic Authentication mã hóa biểu diễn thông tin đăng nhập nhưng không mã hóa bảo mật dữ liệu đó. Hãy sử dụng tính năng này trên mạng cục bộ đáng tin cậy, trừ khi truy cập thiết bị qua một cơ chế truyền tải an toàn bổ sung.

Cấu hình Admin Security trong giao diện web

Mở địa chỉ IP của thiết bị trong trình duyệt.
Chọn thẻ Security.
Nhập tên người dùng quản trị.
Nhập và xác nhận mật khẩu quản trị.
Chọn Enable Admin Security.

Tên người dùng và mật khẩu phải đáp ứng các quy tắc sau:

độ dài: 1 đến 32 ký tự;
chỉ dùng ký tự ASCII hiển thị được;
không cho phép dấu hai chấm (:), dấu ngoặc kép (") hoặc dấu gạch chéo ngược (\).

Sau khi bật Admin Security, trình duyệt hiển thị lời nhắc xác thực khi truy cập trang hoặc API được bảo vệ. Nhập tên người dùng và mật khẩu quản trị đã cấu hình.

Thẻ Security cũng có thể dùng để:

thay đổi tên người dùng và mật khẩu quản trị;
kiểm tra xác thực quản trị đã bật hay chưa;
bật hoặc tắt dịch vụ Modbus/TCP trên cổng 502;
bật hoặc tắt khám phá SSDP;
tắt Admin Security sau khi xác thực bằng thông tin hiện tại.

Thẻ Security trong giao diện web cục bộ IAMMETER với điều khiển thông tin quản trị và công tắc dịch vụ Modbus TCP, SSDP

Thay đổi trạng thái dịch vụ Modbus/TCP hoặc SSDP yêu cầu khởi động lại thiết bị. Nếu firmware trước đây chưa từng lưu các cài đặt này, cả hai dịch vụ mặc định bật để tương thích ngược.

Trình duyệt có thể lưu đệm thông tin Basic Authentication cho địa chỉ thiết bị. Sau khi đổi mật khẩu, trình duyệt có thể thử lại thông tin cũ rồi mới hiển thị lời nhắc xác thực mới. Đóng tất cả cửa sổ trình duyệt hoặc dùng cửa sổ riêng tư cũng có thể buộc đăng nhập lại.

API không yêu cầu Basic Authentication

Các endpoint sau vẫn truy cập được mà không có header Basic Authentication, để giao diện web tải thông tin thiết bị cơ bản và quy trình khôi phục có chữ ký hoạt động:

Phương thức	Endpoint	Mục đích
GET	`/api/admin/status`	Trả về trạng thái bật Admin Security và khả năng hỗ trợ khôi phục có chữ ký.
GET	`/api/admin/recovery_challenge`	Tạo payload khôi phục dùng một lần, riêng cho thiết bị.
GET	`/api/getbrand`	Trả về cấu hình thương hiệu của giao diện web cục bộ.
GET	`/api/monitor`	Trả về dữ liệu giám sát thiết bị và công tơ hiện tại dùng trong giao diện web cục bộ.
GET	`/api/monitorjson`	Trả về phản hồi giám sát cũ qua đường dẫn tương thích `/api`.
GET	`/monitorjson`	Trả về phản hồi giám sát cũ.
GET	`/api/sntpstatus`	Trả về trạng thái SNTP hiện tại.
GET	`/info.xml`	Trả về thông tin thiết bị theo kiểu UPnP.
POST	`/api/admin/recovery`	Xác minh chữ ký khôi phục IAMMETER và xóa thông tin quản trị bị quên.

Cũng có thể gọi POST /api/admin/enable mà không cần Basic Authentication khi Admin Security đang tắt, vì endpoint này dùng để thiết lập ban đầu. Nếu Admin Security đã bật, cần thông tin quản trị hiện tại hợp lệ trước khi endpoint có thể thay đổi hoặc tắt cấu hình bảo mật.

Các tệp giao diện web tĩnh và tài nguyên GET khác không thuộc /api/ không phải là endpoint API và vẫn đọc được công khai. Mọi endpoint API cục bộ khác được xem là được bảo vệ khi Admin Security bật, bao gồm tất cả Set API, API GET nhạy cảm và thao tác firmware OTA.

Tài liệu tham chiếu API

GET `/api/admin/status`

Trả về trạng thái Admin Security hiện tại. Không cần xác thực.

Phản hồi ví dụ:

{
  "enabled": 1,
  "hasPassword": 1,
  "recoverySupported": 1,
  "modbusTcpEnabled": 1,
  "ssdpEnabled": 1
}

Các trường:

enabled: 1 khi Admin Security bật; nếu không là 0.
hasPassword: 1 khi thông tin quản trị đã được cấu hình.
recoverySupported: 1 khi firmware hỗ trợ khôi phục quản trị có chữ ký.
modbusTcpEnabled: 1 khi dịch vụ Modbus/TCP trên cổng 502 bật.
ssdpEnabled: 1 khi khám phá SSDP bật.

POST `/api/admin/enable`

Bật hoặc tắt Admin Security.

Bật Admin Security:

POST /api/admin/enable
Content-Type: application/json

{
  "enable": 1,
  "username": "admin",
  "password": "ExamplePassword"
}

Ví dụ với curl:

curl -X POST "http://<device-ip>/api/admin/enable" \
  -H "Content-Type: application/json" \
  -d '{"enable":1,"username":"admin","password":"ExamplePassword"}'

Tắt Admin Security:

POST /api/admin/enable
Authorization: Basic <base64-credentials>
Content-Type: application/json

{
  "enable": 0
}

Nếu Admin Security đã bật, cần thông tin Basic Authentication hiện tại hợp lệ để gọi API này.

Ví dụ:

curl -X POST "http://<device-ip>/api/admin/enable" \
  -u admin:ExamplePassword \
  -H "Content-Type: application/json" \
  -d '{"enable":0}'

POST `/api/admin/password`

Thay đổi tên người dùng và mật khẩu quản trị. API này được bảo vệ sau khi bật Admin Security.

POST /api/admin/password
Authorization: Basic <current-base64-credentials>
Content-Type: application/json

{
  "username": "newadmin",
  "password": "NewExamplePassword"
}

Ví dụ:

curl -X POST "http://<device-ip>/api/admin/password" \
  -u admin:ExamplePassword \
  -H "Content-Type: application/json" \
  -d '{"username":"newadmin","password":"NewExamplePassword"}'

Sau khi yêu cầu thành công, dùng thông tin mới cho các yêu cầu được bảo vệ tiếp theo.

GET `/api/admin/check`

Kiểm tra thông tin Basic Authentication được cung cấp có hợp lệ hay không.

curl -u admin:ExamplePassword \
  "http://<device-ip>/api/admin/check"

Phản hồi thành công:

{
  "successful": 1
}

Thiếu thông tin hoặc thông tin không hợp lệ dẫn đến HTTP 401 Unauthorized.

GET `/api/admin/recovery_challenge`

Tạo payload khôi phục dùng một lần, riêng cho thiết bị. Không yêu cầu xác thực vì endpoint này tự nó không đặt lại thông tin đăng nhập.

Phản hồi ví dụ:

{
  "successful": 1,
  "alg": "ed25519",
  "payload": "reset_admin|DEVICE_SN|DEVICE_MAC|ONE_TIME_NONCE"
}

Khi cần khôi phục quyền quản trị, phải gửi payload được trả về cho IAMMETER.

Yêu cầu challenge mới làm challenge trước đó mất hiệu lực. Challenge cũng mất hiệu lực sau khi khôi phục thành công hoặc khởi động lại thiết bị.

POST `/api/admin/recovery`

Gửi payload khôi phục và chữ ký Ed25519 do IAMMETER cung cấp.

POST /api/admin/recovery
Content-Type: application/json

{
  "payload": "reset_admin|DEVICE_SN|DEVICE_MAC|ONE_TIME_NONCE",
  "signature": "128-hex-character-ed25519-signature"
}

Ví dụ:

curl -X POST "http://<device-ip>/api/admin/recovery" \
  -H "Content-Type: application/json" \
  -d '{"payload":"reset_admin|DEVICE_SN|DEVICE_MAC|ONE_TIME_NONCE","signature":"<signature-from-IAMMETER>"}'

Nếu xác minh chữ ký thành công, thiết bị xóa thông tin quản trị cục bộ và tắt Admin Security. Sau đó có thể cấu hình tên người dùng và mật khẩu quản trị mới.

Nếu thiết bị không có đủ bộ nhớ trống để xác minh chữ ký, API trả về phản hồi tương tự như sau:

{
  "successful": 0,
  "message": "low memory, please change to standalone mode",
  "freeMemory": 18000,
  "minFreeRequired": 28000
}

Trong trường hợp này, giảm mức sử dụng bộ nhớ và yêu cầu challenge khôi phục mới trước khi thử lại. Nếu không có mật khẩu và không thể đổi chế độ hoạt động, hãy khởi động lại thiết bị và khôi phục trước khi kết nối MQTTS hoặc HTTPS tiêu thụ thêm bộ nhớ.

Cách hoạt động của khôi phục mật khẩu

Thiết kế khôi phục tránh bổ sung lệnh khôi phục cài đặt gốc không xác thực có thể vượt qua bảo vệ quản trị.

Quy trình sử dụng cặp khóa công khai/riêng Ed25519:

firmware thiết bị chỉ chứa khóa công khai khôi phục IAMMETER;
khóa riêng tương ứng do IAMMETER giữ, không lưu trên thiết bị;
thiết bị tạo payload chứa thao tác được yêu cầu, SN thiết bị, MAC thiết bị và nonce dùng một lần;
IAMMETER ký chính xác payload đó bằng khóa riêng khôi phục;
thiết bị xác minh chữ ký bằng khóa công khai tích hợp;
chỉ chữ ký hợp lệ cho thiết bị hiện tại và nonce hiện tại mới có thể xóa cấu hình quản trị.

Nonce chỉ lưu trong RAM. Nó mất hiệu lực khi thiết bị khởi động lại, khi yêu cầu challenge khác hoặc sau một lần khôi phục thành công. Vì vậy, payload và chữ ký cũ không thể dùng lại cho phiên khôi phục sau.

Các tình huống sử dụng

Tình huống 1: Thiết lập tên người dùng và mật khẩu quản trị

Cách đơn giản nhất là dùng giao diện web:

Mở http://<device-ip>/.
Mở thẻ Security.
Nhập tên người dùng và mật khẩu quản trị mới.
Xác nhận mật khẩu.
Bật Admin Security.

Có thể thực hiện thao tác tương tự qua POST /api/admin/enable:

curl -X POST "http://<device-ip>/api/admin/enable" \
  -H "Content-Type: application/json" \
  -d '{"enable":1,"username":"admin","password":"ExamplePassword"}'

Kiểm tra kết quả:

curl "http://<device-ip>/api/admin/status"

Tình huống 2: Truy cập API được bảo vệ bằng Basic Authentication

Với mỗi yêu cầu được bảo vệ tiếp theo, gửi tên người dùng và mật khẩu quản trị trong header HTTP Basic Authentication.

Giá trị header được tạo như sau:

Authorization: Basic Base64(username:password)

Ví dụ, thông tin admin:ExamplePassword được ghép trước rồi mã hóa Base64. Hầu hết HTTP client thực hiện việc này tự động.

Sử dụng curl:

curl -u admin:ExamplePassword \
  "http://<device-ip>/api/getadv"

Chỉ định header tường minh:

TOKEN=$(printf '%s' 'admin:ExamplePassword' | base64)

curl "http://<device-ip>/api/getadv" \
  -H "Authorization: Basic ${TOKEN}"

Đối với yêu cầu JSON POST:

curl -X POST "http://<device-ip>/api/setadv" \
  -u admin:ExamplePassword \
  -H "Content-Type: application/json" \
  -d '<setadv-json-body>'

Trình duyệt tự xử lý header này sau khi quản trị viên nhập thông tin trong lời nhắc Basic Authentication.

Giao diện web hiện tải firmware lên POST /api/ota_successful.html. Endpoint cũ POST /ota_successful.html vẫn dùng được cho các phiên bản giao diện web trước đây và công cụ bên ngoài. Cả hai endpoint đều yêu cầu Basic Authentication khi bật Admin Security.

Các thẻ giao diện web hoạt động như sau khi đóng lời nhắc xác thực:

Settings và Wi-Fi không thể tải API cấu hình được bảo vệ và hiển thị thông báo xác thực quản trị.
System vẫn hiển thị SN, MAC và phiên bản firmware vì các giá trị này lấy từ endpoint công khai /api/monitor. Tải OTA vẫn được bảo vệ.
Security vẫn hiển thị trạng thái cơ bản vì /api/admin/status là công khai. Thay đổi thông tin đăng nhập và công tắc dịch vụ vẫn được bảo vệ.

Tình huống 3: Khôi phục quyền truy cập khi quên mật khẩu

Thiết bị không có nút reset phần cứng. Để tránh thêm chức năng reset không xác thực có thể vượt qua Admin Security, thiết bị dùng cơ chế khôi phục có chữ ký, riêng cho từng thiết bị.

Chỉ dùng quy trình này khi quên thông tin quản trị. Nếu vẫn biết thông tin hiện tại, hãy thay đổi từ thẻ Security hoặc bằng POST /api/admin/password.

Làm theo hướng dẫn khôi phục mật khẩu Admin Security đầy đủ từng bước

Quy trình khôi phục như sau:

Tạo payload dùng một lần từ GET /api/admin/recovery_challenge.
Đăng nhập ứng dụng Admin Recovery của hệ thống IAMMETER Contributor. Dịch vụ xác minh tài khoản của bạn có quyền quản lý SN thiết bị và trả về chữ ký Ed25519 cho chính xác payload đó.
Gửi payload không thay đổi và chữ ký đến POST /api/admin/recovery. Sau khi xác minh thành công, Admin Security bị tắt và thông tin quản trị cục bộ trước đó được xóa.

Không khởi động lại thiết bị, làm mới trang challenge hoặc yêu cầu challenge khác trước khi hoàn tất khôi phục. Bất kỳ thao tác nào trong số đó đều làm nonce hiện tại mất hiệu lực, nên bạn phải bắt đầu lại với payload mới.

Hướng dẫn khôi phục riêng bao gồm ảnh chụp màn hình, lệnh curl đầy đủ, cách xử lý chữ ký bị từ chối và quy trình khôi phục khi bộ nhớ trống thấp.

Local Admin Security cho công tơ IAMMETER: Hướng dẫn sử dụng

Mục đích

Cấu hình Admin Security trong giao diện web

API không yêu cầu Basic Authentication

Tài liệu tham chiếu API

GET /api/admin/status

POST /api/admin/enable

POST /api/admin/password

GET /api/admin/check

GET /api/admin/recovery_challenge

POST /api/admin/recovery

Cách hoạt động của khôi phục mật khẩu

Các tình huống sử dụng

Tình huống 1: Thiết lập tên người dùng và mật khẩu quản trị

Tình huống 2: Truy cập API được bảo vệ bằng Basic Authentication

Tình huống 3: Khôi phục quyền truy cập khi quên mật khẩu

Đồng hồ năng lượng Wi-Fi

GET `/api/admin/status`

POST `/api/admin/enable`

POST `/api/admin/password`

GET `/api/admin/check`

GET `/api/admin/recovery_challenge`

POST `/api/admin/recovery`