본문으로 건너뛰기

서버 인증 설정

인증과 암호화 개념을 먼저 확인하세요.

서버측 인증 정보 연동​

iosignal-cli 서버는 인증 옵션을 지정하지 않으면 인증 제공자를 설정하지 않습니다. 인증을 사용하려면 JSON·JavaScript 파일, 명령 인자 또는 Redis로 인증 정보를 공급합니다. CLI의 인증 옵션을 함께 지정하면 --auth-file → --auth-param → --auth-redis 순서로 하나만 선택됩니다. 키 목록 없이 시험하려면 로컬 테스트 로그인을 사용합니다.

인증정보를 기록한 JSON 파일을 사용하는 인증방식​

iosignal-cli 저장소의 auth_file_sample/auth_file.json에 예제가 있습니다. 전역 설치 후에는 별도로 준비한 인증 파일의 경로를 지정합니다. 서버 포트도 함께 지정해야 합니다.

io-server -l 7777 --auth-file ./auth_file.json

인증파일의 구조와 제한​

JSON 파일은 [id, key, cid, role, quota] 배열들의 목록입니다. ID, 공유 키, CID와 선택 항목인 역할·쿼터 프로필을 기록합니다. 키는 파일에 평문으로 저장됩니다.

  • 장치 ID는 최대 8바이트입니다. 예제처럼 ASCII 문자를 사용하면 최대 8문자입니다.
  • 장치 키는 SHA-256으로 변환되어 사용됩니다.
  • CID는 IOSignal의 SIZE_LIMIT.CID 기준 최대 12바이트입니다.
  • 역할은 device(생략 시 기본값), service, admin입니다. admin만 sudo 서비스를 쓸 수 있습니다.
  • 쿼터는 서버의 쿼터 프로필 이름입니다. 생략하면 device는 basic, service·admin은 unlimited를 씁니다(BohoAuth의 resolveQuota로 바꿀 수 있습니다).
  • 9.0부터 숫자 레벨은 읽지 않습니다. 네 번째 칸이 역할이 아니면 서버가 시작할 때 오류가 납니다.
  • JSON은 주석을 지원하지 않으며 문자열은 큰따옴표로 묶습니다.
[
["id", "key", "cid"],
["did2", "did2key", "did2-cid", "device", "pro"],
["uno3", "uno3-key", "uno3-cid"],
["admin", "admin-key", "admin", "admin"]
]

JavaScript 인증 파일은 같은 배열 목록을 export const authInfo = [...] 형태로 제공합니다. 예제는 auth_file_sample/auth_file.js에 있습니다.

명령 인자는 id.key.cid[.role[.quota]] 형식이고 여러 항목은 쉼표로 구분합니다.

io-server -l 7777 --auth-param 'uno3.uno3-key.uno3-cid,admin.admin-key.admin.admin'

명령행 인자는 셸 이력이나 프로세스 목록에 남을 수 있으므로 서버 인증 정보는 파일 사용을 권장합니다.

Redis 및 기타 데이터베이스 연동​

Redis가 실행 중이고 인증 자료가 등록되어 있어야 합니다. iosignal-cli 저장소의 test_auth_redis/에 인증 데이터 등록 예제와 서버 예제가 있습니다. 아래 명령은 해당 저장소 디렉터리에서 실행합니다.

node test_auth_redis/redis_addAdmin.js admin admin-key admin
node test_auth_redis/redis_addMultipleDevice.js uno 10
node test_auth_redis/redis_add_get_device.js
node test_auth_redis/server-auth-redis.js

앞의 세 스크립트는 Redis에 예제 데이터를 기록합니다. 관리자·다중 장치 예제는 Redis SAVE도 호출합니다. 관리자 예제는 admin 역할로 등록합니다. 다중 장치 예제는 <기본 ID> [개수] [쿼터]를 받아 ID와 같은 키의 device를 생성합니다. 서버 예제의 기본 WebSocket 포트는 7777입니다.

라이브러리에서 인증을 구성할 때는 BohoAuth와 FileKeyProvider, StringKeyProvider, RedisKeyProvider를 참고하세요.

Redis 인증 서버 구동​

별도 io-server-redis 명령은 없습니다. io-server의 --auth-redis 옵션을 사용합니다.

io-server -l 7777 --auth-redis

기본 Redis 주소는 localhost:6379이며 REDIS_HOST, REDIS_PORT 환경변수로 변경합니다. 다음 구문은 macOS·리눅스 셸 기준입니다.

REDIS_HOST=127.0.0.1 REDIS_PORT=6379 io-server -l 7777 --auth-redis

Redis 연결 완료 후 서버가 시작됩니다. 연결 제한 시간은 5초이며 자동 재접속은 사용하지 않습니다. 연결 실패 시 오류와 종료 코드 1을 반환합니다.

클라이언트의 인증​

위 JSON 예제로 서버를 실행한 뒤 다른 터미널에서 다음 명령으로 연결합니다.

io-client -i uno3 -k uno3-key
# 같은 인증 정보의 단축 표기
io-client --auth-idKey uno3.uno3-key

-i와 -k를 모두 지정하면 --auth-idKey보다 우선합니다. 인증 성공 후 id를 입력하면 등록한 CID인 uno3-cid와 연결 상태를 확인할 수 있습니다.

실행 중 auth uno3 uno3-key는 자동 로그인용 인증 정보를 설정합니다. login uno3 uno3-key는 서버의 인증 challenge를 이용해 로그인을 시도합니다. 둘 다 단일 id.key 인자를 받을 수 있습니다.

Node.js에서 JSON 인증 파일 사용​

위 auth_file.json을 실행 디렉터리에 준비하고 server.mjs를 작성합니다.

import { Server, BohoAuth, FileKeyProvider } from 'iosignal';

const auth = new BohoAuth(new FileKeyProvider('./auth_file.json'));
const server = new Server({ port: 7777, membersOnly: true }, auth);
server.on('ready', () => console.log('인증 서버 준비'));

node server.mjs로 실행한 뒤 io-client -i uno3 -k uno3-key로 연결합니다. membersOnly: true는 익명 이용을 허용하지 않는 구성입니다. 파일의 예제 키는 실습용이며 실제 장치에는 별도 키를 발급하세요.

로컬 테스트 로그인 (localAuth)​

IOSignal 8.1.0부터 localAuth 서버 옵션으로 키를 등록하지 않고 인증을 켤 수 있습니다. 비어 있지 않은 모든 ID가 로그인하며 로그인 ID가 그대로 CID가 됩니다.

옵션로그인 조건클라이언트 예
'idKey' 또는 { mode: 'idKey' }키가 ID와 같음io.auth('dev1', 'dev1')
{ mode: 'sharedKey', key }아무 ID + 공통 키io.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(기본 device), 쿼터 프로필은 quota(기본은 resolveQuota 결과, device는 basic)로 정합니다. 9.0에서 level은 없어졌습니다.
  • 익명 연결도 계속 받습니다. membersOnly: true를 주면 익명 연결의 시그널을 버립니다.
  • duplicateLogin, onAuthEvent는 일반 BohoAuth와 같이 동작합니다. localAuth와 authManager 인자를 함께 주면 TypeError입니다.
  • 직접 구성하려면 new BohoAuth(new LocalKeyProvider('idKey'))를 사용합니다.

CLI에서는 --id-key(키 = ID) 또는 --shared-key <key>로 켜고 --members-only로 익명 시그널을 막습니다. iosignal-cli 8.1.0 이상이 필요합니다(9.0의 CLI는 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
경고

규칙을 아는 누구나 임의 ID로 로그인해 그 CID를 가져갈 수 있습니다. 기본 keepNew에서는 접속 중인 연결도 교체됩니다. 공통 키를 쓰면 모든 장치가 같은 키를 가지므로 연결 암호화가 장치 사이를 구분해 보호하지 않습니다. 신뢰하는 로컬 네트워크의 테스트에만 사용하세요.

같은 ID 중복 로그인​

IOSignal 8.0.0부터 같은 인증 정보(같은 CID)로 이미 접속한 연결이 있을 때의 처리를 duplicateLogin으로 정합니다.

값동작적합한 경우
'keepNew'(기본)기존 연결에 AUTH_CLEAR를 보내 닫고 새 연결을 인증합니다.재부팅이나 Wi-Fi 끊김이 잦은 장치가 접속하는 서버. 반쯤 끊긴 이전 연결 때문에 재접속이 막히지 않습니다.
'keepOld'기존 연결을 유지하고 새 연결의 인증을 거부합니다.서버끼리 연결하는 내부 서비스. 같은 키로 실수로 실행한 프로세스가 운영 연결을 끊지 않습니다. 반쯤 끊긴 연결은 heartbeat가 정리한 뒤 재접속됩니다.
const auth = new BohoAuth(new FileKeyProvider('./auth_file.json'));
const server = new Server({ port: 7777, duplicateLogin: 'keepOld' }, auth);

기본값은 serverOption.auth.duplicateLogin입니다. Server 옵션은 그 서버의 인증 관리자에만 적용되며 'keepOld', 'keepNew' 외의 값은 RangeError입니다. 이전 버전의 기본 동작은 버전과 검증 기준을 참고하세요.

교체된 클라이언트의 동작은 다음과 같습니다.

  • JS: auth_clear 이벤트 후 인증 정보를 지우고 stop()합니다. 자동 재접속하지 않습니다.
  • Arduino: IOSignal Arduino 7.0.0부터 인증 정보를 지우고 IO_STOP 상태로 멈춥니다. Arduino 안내를 참고하세요.

중복 로그인을 기록하려면 BohoAuth의 onAuthEvent를 사용합니다. 중복 로그인 처리 직후 호출됩니다.

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

type은 'replaced'(keepNew) 또는 'duplicate_rejected'(keepOld)이며 did, cid, uid, ip(새 연결), oldIp(기존 연결), socketType, oldSocketType, reason, at을 함께 받습니다. 콜백의 오류는 기록만 되고 인증에 영향을 주지 않습니다. 중복 감지는 서버 프로세스별이므로 서로 다른 서버에 접속한 같은 장치는 중복으로 판정되지 않습니다. 장치마다 별도 인증 정보를 발급하세요.

로그인을 받기 전에 서버 고르기 (beforeAccept)​

9.19.0부터 BohoAuth의 하위 클래스가 beforeAccept(peer, authInfo, role, id)를 구현하면, 키와 역할 검사를 통과한 로그인을 이 서버에서 받을지 정할 수 있습니다. 서버를 여러 대 두고 장치마다 붙을 서버를 정할 때 씁니다.

  • null을 돌려주면 이 서버가 받습니다(기본).
  • 메시지(Uint8Array)를 돌려주면 AUTH_RES 대신 그 메시지를 보내고 연결을 닫습니다. 보통 SERVER_REDIRECT로 다른 서버를 안내합니다. 이때 쿼터 적용과 중복 로그인 검사 전이므로 이 서버의 기존 연결은 바뀌지 않습니다.
  • Promise도 돌려줄 수 있습니다. 훅에서 오류가 나면 로그인을 받아들입니다(서버 배치 오류로 장치가 접속하지 못하는 일을 막기 위해서입니다).
  • authInfo는 키 제공자의 항목(cid, role, quota 등), id는 로그인 ID, peer.socketType은 'websocket' 또는 TCP 연결입니다.

SERVER_REDIRECT는 연결 종류에 따라 두 형식이 있습니다.

받는 쪽메시지다시 접속하는 주소
WebSocket(브라우저, Node.js IO)SERVER_REDIRECT + UTF-8 URL그 URL(wss://b.example.com/ws)
TCP(Arduino, IOCongSocket)SERVER_REDIRECT + IPv4 4바이트 + 포트 2바이트(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; // 이 서버가 받음
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')));

클라이언트는 상태가 redirecting으로 바뀐 뒤 새 주소로 접속하고 같은 인증 정보로 다시 로그인합니다. 안내받은 서버가 15초 안에 응답하지 않으면 원래 주소로 돌아갑니다(JS 9.19.0, Arduino는 10초). 안내받은 서버가 다시 같은 곳으로 안내하지 않도록 서버들이 같은 배치 규칙을 써야 합니다.