Local Admin Security untuk Meter Energi IAMMETER: Panduan Pengguna

Modul Local Admin Security tersedia pada firmware i.91.065.3 dan versi lebih baru.

Di halaman ini

• Tujuan
• Mengonfigurasi Admin Security di Web UI
• API yang Tidak Memerlukan Basic Authentication
• Referensi API
• Cara Kerja Pemulihan Kata Sandi
• Skenario Penggunaan
  • Skenario 1: Mengatur Nama Pengguna dan Kata Sandi Administrator
  • Skenario 2: Mengakses API yang Dilindungi dengan Basic Authentication
  • Skenario 3: Memulihkan Akses Setelah Lupa Kata Sandi

Tujuan

Modul Local Admin Security melindungi Web UI lokal dan API lokal sensitif perangkat dari akses tanpa izin.

Setelah fitur diaktifkan, nama pengguna dan kata sandi administrator diperlukan untuk:

• semua Set API yang tersedia di halaman WEM API Test;
• API GET yang mengembalikan data konfigurasi sensitif atau menjalankan operasi sensitif;
• operasi unggah dan peningkatan firmware OTA lokal.

Ini mencakup perubahan pengaturan jaringan atau unggahan, pembaruan firmware, memulai ulang perangkat, memulihkan pengaturan pabrik, serta mengubah parameter konfigurasi sensitif lainnya.

Modul ini menyediakan:

• kredensial administrator yang dapat dikonfigurasi;
• HTTP Basic Authentication untuk API lokal yang dilindungi;
• perubahan kredensial melalui Web UI atau API;
• proses pemulihan berbasis tanda tangan Ed25519 jika kata sandi administrator terlupa.

Fitur dinonaktifkan secara default untuk kompatibilitas dengan firmware terdahulu. Fitur harus diaktifkan dan dikonfigurasi sebelum perlindungan akses berlaku.

Web UI lokal saat ini menggunakan HTTP. HTTP Basic Authentication melakukan pengodean kredensial, tetapi tidak mengenkripsinya. Gunakan fitur ini pada jaringan lokal tepercaya, kecuali perangkat diakses melalui mekanisme transportasi aman tambahan.

Mengonfigurasi Admin Security di Web UI

1. Buka alamat IP perangkat di browser.
2. Pilih tab Security.
3. Masukkan nama pengguna administrator.
4. Masukkan dan konfirmasi kata sandi administrator.
5. Pilih Enable Admin Security.

Nama pengguna dan kata sandi harus memenuhi aturan berikut:

• panjang: 1 hingga 32 karakter;
• hanya karakter ASCII yang terlihat;
• titik dua (:), tanda kutip ganda ("), atau garis miring terbalik (\) tidak diperbolehkan.

Setelah Admin Security diaktifkan, browser menampilkan permintaan autentikasi saat halaman atau API yang dilindungi diakses. Masukkan nama pengguna dan kata sandi administrator yang telah dikonfigurasi.

Tab Security juga dapat digunakan untuk:

• mengubah nama pengguna dan kata sandi administrator;
• memverifikasi bahwa autentikasi administrator diaktifkan;
• mengaktifkan atau menonaktifkan layanan Modbus/TCP pada port 502;
• mengaktifkan atau menonaktifkan penemuan SSDP;
• menonaktifkan Admin Security setelah autentikasi dengan kredensial saat ini.

Perubahan status layanan Modbus/TCP atau SSDP memerlukan mulai ulang perangkat. Jika pengaturan ini belum pernah disimpan oleh firmware terdahulu, kedua layanan diaktifkan secara default untuk kompatibilitas mundur.

Browser dapat menyimpan kredensial Basic Authentication untuk alamat perangkat dalam cache. Setelah kata sandi diubah, browser mungkin mencoba kredensial lama terlebih dahulu, lalu menampilkan permintaan autentikasi baru. Menutup semua jendela browser atau menggunakan jendela penjelajahan pribadi juga dapat memaksa login baru.

API yang Tidak Memerlukan Basic Authentication

Endpoint berikut tetap tersedia tanpa header Basic Authentication agar Web UI dapat memuat informasi dasar perangkat dan proses pemulihan bertanda tangan dapat berjalan:

POST /api/admin/enable juga dapat dipanggil tanpa Basic Authentication ketika Admin Security sedang nonaktif, karena endpoint ini digunakan untuk penyiapan awal. Jika Admin Security sudah aktif, kredensial administrator saat ini yang valid diperlukan sebelum endpoint ini dapat mengubah atau menonaktifkan konfigurasi keamanan.

Berkas Web UI statis dan sumber daya GET non-/api/ lainnya bukan endpoint API dan tetap dapat dibaca secara publik. Semua endpoint API lokal lainnya dianggap dilindungi saat Admin Security aktif, termasuk semua Set API, API GET sensitif, dan operasi firmware OTA.

Referensi API

GET /api/admin/status

Mengembalikan status Admin Security saat ini. Autentikasi tidak diperlukan.

Contoh respons:

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

Kolom:

• enabled: 1 ketika Admin Security aktif; selain itu 0.
• hasPassword: 1 ketika kredensial administrator telah dikonfigurasi.
• recoverySupported: 1 ketika firmware mendukung pemulihan administrator bertanda tangan.
• modbusTcpEnabled: 1 ketika layanan Modbus/TCP pada port 502 aktif.
• ssdpEnabled: 1 ketika penemuan SSDP aktif.

POST /api/admin/enable

Mengaktifkan atau menonaktifkan Admin Security.

Aktifkan Admin Security:

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

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

Contoh dengan curl:

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

Nonaktifkan Admin Security:

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

{
  "enable": 0
}

Jika Admin Security sudah aktif, kredensial Basic Authentication saat ini yang valid diperlukan untuk memanggil API ini.

Contoh:

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

POST /api/admin/password

Mengubah nama pengguna dan kata sandi administrator. API ini dilindungi setelah Admin Security diaktifkan.

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

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

Contoh:

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

Setelah permintaan berhasil, gunakan kredensial baru untuk permintaan terlindungi berikutnya.

GET /api/admin/check

Memeriksa apakah kredensial Basic Authentication yang diberikan valid.

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

Respons berhasil:

{
  "successful": 1
}

Kredensial yang tidak ada atau tidak valid menghasilkan HTTP 401 Unauthorized.

GET /api/admin/recovery_challenge

Membuat payload pemulihan sekali pakai khusus perangkat. Autentikasi tidak diperlukan karena endpoint ini sendiri tidak mereset kredensial.

Contoh respons:

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

payload yang dikembalikan harus dikirim ke IAMMETER ketika pemulihan administrator diperlukan.

Meminta challenge baru membatalkan challenge sebelumnya. Challenge juga dibatalkan setelah pemulihan berhasil atau perangkat dimulai ulang.

POST /api/admin/recovery

Mengirim payload pemulihan dan tanda tangan Ed25519 yang diberikan IAMMETER.

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

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

Contoh:

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>"}'

Jika verifikasi tanda tangan berhasil, perangkat menghapus kredensial administrator lokal dan menonaktifkan Admin Security. Nama pengguna dan kata sandi administrator baru kemudian dapat dikonfigurasi.

Jika perangkat tidak memiliki cukup memori bebas untuk menjalankan verifikasi tanda tangan, API mengembalikan respons seperti:

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

Dalam kasus ini, kurangi penggunaan memori dan minta challenge pemulihan baru sebelum mencoba lagi. Jika kata sandi tidak tersedia dan mode operasi tidak dapat diubah, mulai ulang perangkat lalu lakukan pemulihan sebelum koneksi MQTTS atau HTTPS menggunakan memori tambahan.

Cara Kerja Pemulihan Kata Sandi

Desain pemulihan menghindari penambahan perintah reset pabrik tanpa autentikasi yang dapat melewati perlindungan administrator.

Proses ini menggunakan pasangan kunci publik/privat Ed25519:

• firmware perangkat hanya memuat kunci publik pemulihan IAMMETER;
• kunci privat pasangannya disimpan oleh IAMMETER dan tidak disimpan pada perangkat;
• perangkat membuat payload yang memuat operasi yang diminta, SN perangkat, MAC perangkat, dan nonce sekali pakai;
• IAMMETER menandatangani payload yang persis sama dengan kunci privat pemulihan;
• perangkat memverifikasi tanda tangan dengan kunci publik tertanamnya;
• hanya tanda tangan valid untuk perangkat dan nonce saat ini yang dapat menghapus konfigurasi administrator.

Nonce hanya disimpan dalam RAM. Nilainya menjadi tidak valid saat perangkat dimulai ulang, saat challenge lain diminta, atau setelah satu pemulihan berhasil. Karena itu, payload dan tanda tangan lama tidak dapat digunakan lagi pada sesi pemulihan berikutnya.

Skenario Penggunaan

Skenario 1: Mengatur Nama Pengguna dan Kata Sandi Administrator

Metode paling sederhana adalah Web UI:

1. Buka http://<device-ip>/.
2. Buka tab Security.
3. Masukkan nama pengguna dan kata sandi administrator baru.
4. Konfirmasi kata sandi.
5. Aktifkan Admin Security.

Operasi yang sama dapat dilakukan melalui 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"}'

Verifikasi hasilnya:

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

Skenario 2: Mengakses API yang Dilindungi dengan Basic Authentication

Untuk setiap permintaan terlindungi berikutnya, kirim nama pengguna dan kata sandi administrator dalam header HTTP Basic Authentication.

Nilai header dibentuk sebagai berikut:

Authorization: Basic Base64(username:password)

Misalnya, kredensial admin:ExamplePassword digabungkan terlebih dahulu lalu dikodekan dengan Base64. Sebagian besar klien HTTP melakukan ini secara otomatis.

Menggunakan curl:

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

Menggunakan header eksplisit:

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

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

Untuk permintaan JSON POST:

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

Browser menangani header ini secara otomatis setelah administrator memasukkan kredensial pada permintaan Basic Authentication.

Web UI saat ini mengunggah firmware ke POST /api/ota_successful.html. Endpoint lama POST /ota_successful.html tetap tersedia untuk versi Web UI terdahulu dan alat eksternal. Kedua endpoint memerlukan Basic Authentication saat Admin Security aktif.

Perilaku tab Web UI ketika permintaan autentikasi ditutup adalah:

• Settings dan Wi-Fi tidak dapat memuat API konfigurasi yang dilindungi dan menampilkan pesan autentikasi administrator.
• System masih dapat menampilkan SN, MAC, dan versi firmware karena nilai ini diperoleh dari endpoint publik /api/monitor. Unggahan OTA tetap dilindungi.
• Security masih dapat menampilkan status dasar karena /api/admin/status bersifat publik. Perubahan kredensial dan sakelar layanan tetap dilindungi.

Skenario 3: Memulihkan Akses Setelah Lupa Kata Sandi

Perangkat tidak memiliki tombol reset perangkat keras. Untuk menghindari penambahan fungsi reset tanpa autentikasi yang dapat melewati Admin Security, perangkat menggunakan mekanisme pemulihan bertanda tangan yang khusus untuk perangkat tersebut.

Gunakan prosedur ini hanya jika kredensial administrator terlupa. Jika Anda masih mengetahui kredensial saat ini, ubah dari tab Security atau dengan POST /api/admin/password.

Ikuti panduan lengkap langkah demi langkah pemulihan kata sandi Admin Security

Alur pemulihannya adalah:

1. Hasilkan payload sekali pakai dari GET /api/admin/recovery_challenge.
2. Masuk ke aplikasi Admin Recovery dalam sistem IAMMETER Contributor. Layanan memverifikasi bahwa akun Anda berwenang mengelola SN perangkat dan mengembalikan tanda tangan Ed25519 untuk payload yang persis sama.
3. Kirim payload yang tidak diubah beserta tanda tangan ke POST /api/admin/recovery. Setelah verifikasi berhasil, Admin Security dinonaktifkan dan kredensial administrator lokal sebelumnya dihapus.

Jangan memulai ulang perangkat, menyegarkan halaman challenge, atau meminta challenge lain sebelum pemulihan selesai. Tindakan tersebut membatalkan nonce saat ini, sehingga Anda harus memulai lagi dengan payload baru.

Panduan pemulihan khusus mencakup tangkapan layar, perintah curl lengkap, pemecahan masalah penolakan tanda tangan, dan prosedur pemulihan saat memori bebas rendah.