Skip to main content

Server authentication

Authentication checks possession of a configured key. It is separate from the website's account UI. For local development, start with a private test credential and replace it before deployment.

CLI providers​

Without authentication options, the CLI does not configure a provider. If several are supplied, precedence is file → parameter → Redis. To test without a key list, use local test logins.

An authentication JSON file contains rows [id, key, cid, role, quota]; role and quota are optional:

[["uno3", "uno3-key", "uno3-cid"], ["admin", "admin-key", "admin", "admin"]]

The role is device (default when omitted), service or admin; only admin may use the sudo service. The quota names a server quota profile; when omitted, a device uses basic and service/admin use unlimited (change this with BohoAuth's resolveQuota). From 9.0 a numeric level is no longer read: a fourth field that is not a role is an error when the server starts.

IDs are at most 8 bytes and CIDs at most 12 bytes. Input keys are hashed with SHA-256, but a file containing input keys is still credential material. A JavaScript auth file can export authInfo containing the same rows.

io-server -l 7777 --auth-file ./auth_file.json
io-client -i uno3 -k uno3-key
# Equivalent combined client credential:
io-client -a uno3.uno3-key

Parameter providers use id.key.cid[.role[.quota]] records separated by commas, for example uno3.uno3-key.uno3-cid,admin.admin-key.admin.admin. Command-line secrets may remain in shell history. For supported switches, use the installed CLI's --help and CLI server guide.

Node.js​

import { Server, BohoAuth, FileKeyProvider } from 'iosignal';
const auth = new BohoAuth(new FileKeyProvider('./auth_file.json'));
const server = new Server({ port: 7777, membersOnly: true }, auth);

The relative file path resolves from the process working directory. Available providers include FileKeyProvider, StringKeyProvider, and RedisKeyProvider.

Redis defaults to localhost port 6379 unless configured. The CLI waits up to five seconds, does not automatically reconnect in this startup path, and exits with code 1 on failure. Repository scripts that register sample data and call SAVE are test setup, not a production credential database.

Authentication success does not define application room membership or command permissions. Add those rules in your service or application. See Boho details.

Local test logins (localAuth)​

From IOSignal 8.1.0, the localAuth server option turns on authentication without registering keys. Every non-empty ID logs in, and the login ID becomes the CID.

OptionLoginClient example
'idKey' or { mode: 'idKey' }The key equals the IDio.auth('dev1', 'dev1')
{ mode: 'sharedKey', key }Any ID with the shared keyio.auth('dev1', 'lab2026')
import { Server } from 'iosignal';

const server = new Server({
port: 7777,
congPort: 8888,
localAuth: { mode: 'sharedKey', key: 'lab2026', quota: 'basic' },
membersOnly: true
});
  • role sets the role of every login (default device) and quota its quota profile (default: the resolveQuota result, basic for a device). level was removed in 9.0.
  • Anonymous connections are still served; membersOnly: true drops their signals.
  • duplicateLogin and onAuthEvent work as with any BohoAuth. Passing an authManager together with localAuth throws TypeError.
  • To build it yourself: new BohoAuth(new LocalKeyProvider('idKey')).

In the CLI, use --id-key (key = ID) or --shared-key <key>, and --members-only to drop anonymous signals. This needs iosignal-cli 8.1.0 or later (the 9.0 CLI uses IOSignal 9.0).

io-server -l 7777 -L 8888 --id-key
io-client -i dev1 -k dev1

io-server -l 7777 --shared-key lab2026 --members-only
io-client -i dev1 -k lab2026
warning

Anyone who knows the rule can log in under any ID and take over that CID; with the default keepNew the online connection is replaced. With a shared key every device holds the same key, so connection encryption does not separate the devices from each other. Use it only for tests on a trusted local network.

Duplicate logins​

From IOSignal 8.0.0, duplicateLogin decides what happens when a connection with the same credentials (the same CID) is already online.

ValueBehaviorSuits
'keepNew' (default)Sends AUTH_CLEAR to the old connection, closes it and authenticates the new one.Servers for devices that reboot or lose Wi-Fi often. A half-open old connection does not block reconnection.
'keepOld'Keeps the old connection and rejects the new login.Internal server-to-server services. A process started by mistake with the same key cannot cut off the production connection. A half-open connection reconnects after the heartbeat removes it.
const auth = new BohoAuth(new FileKeyProvider('./auth_file.json'));
const server = new Server({ port: 7777, duplicateLogin: 'keepOld' }, auth);

The default is serverOption.auth.duplicateLogin. The Server option applies only to that server's authentication manager, and values other than 'keepOld' and 'keepNew' throw RangeError. For earlier default behavior, see versions and verification.

A replaced client behaves as follows:

  • JS: emits auth_clear, clears its credentials and calls stop(). It does not reconnect automatically.
  • Arduino: from IOSignal Arduino 7.0.0, clears its credentials and stops in IO_STOP. See the Arduino notes.

To record duplicate logins, use the BohoAuth onAuthEvent callback. It runs right after a duplicate login is handled.

const auth = new BohoAuth(new FileKeyProvider('./auth_file.json'), {
onAuthEvent: event => console.log(event.type, event.did, event.ip, event.oldIp)
});

type is 'replaced' (keepNew) or 'duplicate_rejected' (keepOld), with did, cid, uid, ip (new connection), oldIp (old connection), socketType, oldSocketType, reason and at. Callback errors are logged and never affect authentication. Detection is per server process, so the same device connected to two different servers is not treated as a duplicate. Issue separate credentials for each device.

Choose the server before accepting a login (beforeAccept)​

From 9.19.0, a BohoAuth subclass can implement beforeAccept(peer, authInfo, role, id) to decide whether this server takes a login that passed the key and role checks. Use it when several servers share devices and each device belongs on one of them.

  • Return null to accept the login here (the default).
  • Return a message (Uint8Array) to send it instead of AUTH_RES and close the connection. Usually it is SERVER_REDIRECT, pointing to another server. This happens before quotas and the duplicate login check, so existing connections on this server are not touched.
  • A Promise is allowed. If the hook throws, the login is accepted, so a placement error never locks devices out.
  • authInfo is the key provider's entry (cid, role, quota, ...), id is the login ID, and peer.socketType is 'websocket' or a TCP connection.

SERVER_REDIRECT has two forms, by connection type.

ReceiverMessageAddress it reconnects to
WebSocket (browser, Node.js IO)SERVER_REDIRECT + UTF-8 URLThat URL (wss://b.example.com/ws)
TCP (Arduino, IOCongSocket)SERVER_REDIRECT + 4-byte IPv4 + 2-byte port (big endian)cong://ip:port
import { Server, BohoAuth, FileKeyProvider, IOMsg } from 'iosignal';

const redirectUrl = url => new Uint8Array([IOMsg.SERVER_REDIRECT, ...new TextEncoder().encode(url)]);
const redirectIPv4 = (ip, port) => new Uint8Array([IOMsg.SERVER_REDIRECT, ...ip.split('.').map(Number), port >> 8, port & 0xff]);

class PlacingAuth extends BohoAuth {
beforeAccept(peer, authInfo, role, id) {
if (!id.startsWith('b-')) return null; // accepted here
return peer.socketType === 'websocket'
? redirectUrl('wss://b.example.com/ws')
: redirectIPv4('203.0.113.20', 55488);
}
}

const server = new Server({ port: 7777, congPort: 8888 }, new PlacingAuth(new FileKeyProvider('./auth_file.json')));

The client's state becomes redirecting, then it connects to the new address and logs in again with the same credentials. If the new server does not reply within 15 seconds, it goes back to the original address (JS 9.19.0; Arduino uses 10 seconds). Use the same placement rule on every server so that the new server does not send the client back.