BlueTalk 인증 구조 > BlueTalk::블루톡 무료 실시간 채팅 위젯 · 1:1 DM

인증 구조

1. 개요

BlueTalk는 다음 4가지 정보를 기반으로 인증을 수행합니다.

site_key
BlueTalk에서 발급하는 사이트 식별용 키입니다.
하나의 도메인(또는 서비스)에 1개 이상의 site_key를 발급할 수 있으며, 도메인 + site_key의 조합으로 사이트를 구분합니다.
user_id
사이트 내에서 사용자를 구분할 수 있는 값입니다.
예) 그누보드라면 $member['mb_id'], 다른 서비스라면 자체 회원 PK/아이디 등을 사용할 수 있습니다.
nickname
채팅창에 표시할 닉네임입니다.
사이트 회원 닉네임, 별명, 또는 비회원용 임시 닉네임을 사용합니다.
user_key
서버에서 생성하는 서명/토큰 값입니다.
user_id, 가입일, 비밀키, site_key 등을 섞어서 생성하며, 클라이언트에서 위조할 수 없도록 해야 합니다.

결국, 클라이언트에서 JS SDK 초기화를 수행할 때 site_key + user_id + user_key + nickname 네 가지를 함께 전달하게 됩니다.

2. site_key · 도메인 매칭 규칙

BlueTalk 서버(DB)에는 sites 테이블이 있으며, 여기에 각 사이트 도메인과 site_key, 옵션들이 저장됩니다.

domain
사이트의 기본 도메인입니다. 예: example.com
서브도메인 허용 여부에 따라 aaa.example.com과 같이 매칭할 수 있습니다.
site_key
해당 도메인에 부여된 식별키입니다. 예: site_123456
guest_mode
비회원(로그인하지 않은 사용자) 사용 허용 여부입니다.
guest_global / guest_channel
게스트가 전체 채널 / 개별 채널에서 채팅을 작성할 수 있는지 여부입니다.
auth_url
(선택) 사이트의 회원 인증 API URL입니다. 필요 시 서버에서 세션/토큰 검증에 사용합니다.

소켓 연결 시 클라이언트에서 전송한 site와 실제 접속 도메인(Origin / Referer)을 이용하여
sites 테이블에서 해당 사이트를 조회하고, ▷ 존재하지 않으면 연결을 거부 ▷ 존재하면 추가 인증을 진행합니다.

3. user_key 생성 개념

user_key는 다음과 같은 원칙을 따르는 값입니다.

항상 서버에서만 생성됩니다.
클라이언트(자바스크립트)에서 user_key를 직접 만들거나 수정할 수 없어야 합니다.
서버에서 사용하는 비밀 문자열(SECRET)을 포함하여 생성합니다.
가능하면 일정 시간(예: 하루) 등으로 만료되도록 구성하는 것이 좋습니다.

가장 중요한 점은 user_key가 항상 서버에서만 생성되고, 클라이언트 단에서 임의로 바꿀 수 없어야 한다는 점입니다.

4. 예시: PHP에서 user_key 만들기

// config 또는 별도 설정 파일에 비밀키를 보관합니다.
$blt_site_key = '발급받은_site_key';
$blt_secret   = '서버_내부_비밀문자열_또는_ENV값';

// 로그인 여부에 따라 user_id / nickname 정리
if ($is_member) {
    $user_id  = $member['mb_id'];          // 예: 'testuser'
    $nickname = get_text($member['mb_nick']);
} else {
    $user_id  = 'guest';
    $nickname = '손님';
}

// user_key 생성 (예시: SHA-256)
$payload  = $user_id.'|'.$blt_site_key.'|'.$blt_secret;
$user_key = hash('sha256', $payload);

위 예시는 가장 단순한 형태이며, 필요하다면 가입일, 만료시간, 기타 정보를 추가하여 payload를 구성할 수 있습니다.

5. 예시: Node.js(Express)에서 user_key 만들기

// 예: config.js
const BLT_SITE_KEY = process.env.BLT_SITE_KEY;
const BLT_SECRET   = process.env.BLT_SECRET;

// 예: Express 라우터
const crypto = require('crypto');

app.get('/', (req, res) => {
    const isLogin  = !!req.session.user;
    const userId   = isLogin ? req.session.user.id   : 'guest';
    const nickname = isLogin ? req.session.user.nick : '손님';

    const payload = userId + '|' + BLT_SITE_KEY + '|' + BLT_SECRET;
    const userKey = crypto
        .createHash('sha256')
        .update(payload)
        .digest('hex');

    res.render('index', {
        bltSiteKey: BLT_SITE_KEY,
        userId,
        nickname,
        userKey,
    });
});

위 예시는 세션에서 req.session.user를 참조하는 형태이며, 실제 서비스의 로그인 구조에 맞게 userId / nickname을 가져오면 됩니다.

6. 예시: Python(FastAPI 등)에서 user_key 만들기

import os
import hashlib

BLT_SITE_KEY = os.getenv("BLT_SITE_KEY", "발급받은_site_key")
BLT_SECRET   = os.getenv("BLT_SECRET", "서버_비밀문자열")

def make_user_key(user_id: str) -> str:
    payload = f"{user_id}|{BLT_SITE_KEY}|{BLT_SECRET}"
    return hashlib.sha256(payload.encode("utf-8")).hexdigest()

# 예: FastAPI 엔드포인트 내부
user_id  = "guest"
nickname = "손님"
# 로그인 시:
# user_id  = request.session["user"]["id"]
# nickname = request.session["user"]["nick"]

user_key = make_user_key(user_id)

실제 서비스의 세션/인증 구조에 맞추어 user_id와 nickname을 가져온 뒤, 위와 같이 user_key를 생성하여 템플릿에 넘기면 됩니다.

7. JS SDK 초기화에 값 전달하기

위에서 만든 site_key, user_id, nickname, user_key는 HTML 템플릿 속 JS SDK 초기화에 그대로 전달하면 됩니다.

<script src="https://bluetalk.kr/talk/bluetalk.js"></script>

<div id="bluetalk"></div>

<script>
window.SITE_KEY          = "";
window.GLOBAL_USER_ID    = "";
window.GLOBAL_USER_KEY   = "";
window.GLOBAL_NICKNAME   = "";

const bt = new BlueTalk({
    mode: 'global',
    targetId: 'bluetalk'
});
bt.init();
</script>

실제로는 사이트 구조에 맞게 별도 JS 파일로 분리하거나, 템플릿 상단/하단에 공통 스크립트를 두는 방식으로 관리하면 됩니다.

8. 정리