API xác thực backend trò chơi độc lập

NBTiktok xác thực tài khoản và ký JWT ngắn hạn; máy khách trò chơi tự chọn tuyến mạng. Backend cục bộ, kiểm thử và chính thức dùng cùng hợp đồng credentials.gameBackend, audience và bộ xác minh JWKS.

#Luồng máy khách

Gọi POST /api/game-client/v2/login chỉ với email, mật khẩu, gameId, mode và clientBuild. Khi xác thực backend độc lập được bật, phản hồi có backendAuth không chứa URL và credentials.gameBackend là JWT Ed25519 có hiệu lực tối đa 30 phút.

Đọc riêng URL HTTP và WebSocket từ cấu hình build đáng tin cậy. Cục bộ có thể dùng NBT_GAME_BACKEND_HTTP_URL=http://127.0.0.1:19101 và NBT_GAME_BACKEND_WS_URL=ws://127.0.0.1:19101/ws. Chỉ localhost, 127.0.0.0/8 hoặc [::1] được dùng HTTP/WS rõ; môi trường từ xa phải dùng HTTPS/WSS. Không tải URL lên NBTiktok và không mang Bearer qua redirect khác Origin.

Backend phải kiểm tra chữ ký, kid, issuer, audience chính xác, gameId, scope=game.session, space, sub, account, iat/nbf/exp và thời hạn tối đa bằng /.well-known/game-backend-jwks.json. Khóa dữ liệu là (gameId, space, sub) và Sandbox phải tách khỏi Production.

SDK Node @nbtiktok/game-backend-auth 0.4.x cung cấp createVerifier; cùng cấu hình hoạt động ở mọi môi trường và từ chối Token dài hơn 1,800 giây.

#WebSocket của backend độc lập

WebSocket này tách biệt với endpoint sự kiện nền tảng /ws/game-client/v2: backend độc lập dùng credentials.gameBackend.token, còn endpoint nền tảng tiếp tục dùng credentials.websocket.ticket một lần. Không được dùng lẫn nhau.

Kết nối URL backend đáng tin cậy bằng subprotocol cố định nbt.game-backend.v1. Không đặt Token trong URL, Cookie hoặc subprotocol. Trong năm giây sau khi mở, gửi text frame không quá 20 KiB:

{"type":"nbt.auth","token":"<credentials.gameBackend.token>"}

Backend chuyển nguyên văn tới SDK verifyWebSocketAuthFrame(text, verifier, currentClaims?). Thành công trả Claims đã xác minh và ACK an toàn:

{"type":"nbt.auth.ok","expiresAt":"2026-09-02T12:30:00.000Z"}

Sau khi refresh Session nền tảng trả Backend JWT mới, gửi lại cùng frame nbt.auth trên kết nối hiện tại. Gia hạn yêu cầu giữ nguyên gameId, space, sub, sid, rồi cập nhật nguyên tử snapshot tài khoản, phiên bản cấu hình và hạn dùng. Không xử lý frame nghiệp vụ trước xác thực đầu tiên hoặc sau frame gia hạn đang chờ theo thứ tự; đóng kết nối khi JWT đã cài hết hạn.

Dùng mã đóng 4401 cho xác thực thiếu, sai hoặc hết hạn; 4403 khi đổi danh tính; 4408 khi quá thời gian; 1009 khi frame quá lớn; 1013 khi JWKS tạm không dùng được. Che Authorization và token trong log. Bản trình duyệt phải kiểm tra Origin chính xác; máy khách native không có Origin vẫn phải xác thực JWT.

Dịch vụ chạy được tại examples/independent-game-backend minh họa HTTP Bearer, xác thực frame đầu, gia hạn tại chỗ, máy khách trình duyệt và Node trên loopback.

#Portal trình duyệt

Trang bên thứ ba tạo state và PKCE S256 rồi mở /game-portal/authorize. Người dùng nhập lại email và mật khẩu chỉ trên trang NBTiktok chính thức. Callback nhận Code dùng một lần trong 60 giây; backend đổi Code tại POST /api/game-portal/v2/token và xác minh portalToken bằng Portal JWKS.

Production dùng callback HTTPS đã đăng ký chính xác. Cục bộ chỉ dùng http://127.0.0.1:<port>/__nbt/callback hoặc loopback IPv6. SDK cung cấp createPortalAuthorizationRequest, exchangePortalCode và createPortalVerifier.

Sau khi xác minh, backend tự tạo Cookie HttpOnly, Secure, SameSite=Lax, tối đa tám giờ và không vượt authorizationExpiresAt. NBTiktok không proxy request nghiệp vụ và không sở hữu Cookie bên thứ ba.