@inverz/thaid
v1.0.0
Published
Sign in and verify identity with the ThaiD app (DOPA digital ID) — server helper with state and id_token signature checks, plus a React button and callback hook
Readme
@inverz/thaid
ยืนยันตัวตนผ่านแอป ThaiD ของกรมการปกครอง (OpenID Connect) ฝั่ง server เก็บ client secret ตรวจ state และ ตรวจลายเซ็น id_token (ES256) กับกุญแจที่กรมการปกครองเผยแพร่ก่อนเชื่อข้อมูล ฝั่ง React มีปุ่ม hook สำหรับหน้า redirect และการ์ดแสดงข้อมูลที่ยืนยันแล้ว ไม่มี dependency ใช้ได้กับ Node 18+, Firebase / Cloud Functions, Next.js และ edge runtime
ดูตัวอย่าง (Demo) (ใช้ ThaiD จำลอง)
Sign in with ThaiD, Thailand's DOPA digital ID. Server helper with state checks and id_token signature verification, plus a React button, callback hook and profile card.
ต้องลงทะเบียนเป็นผู้ใช้บริการ ThaiD กับกรมการปกครองก่อน จึงจะได้ Client ID, Client Secret และ Redirect URI ที่ใช้ได้จริง แพ็กเกจนี้ไม่ได้เป็นของหรือรับรองโดยกรมการปกครอง
ติดตั้งและตั้งค่า
npm i @inverz/thaid# .env ฝั่ง server เท่านั้น ห้ามใส่ใน VITE_ / NEXT_PUBLIC_
THAIID_CLIENT_ID="…"
THAIID_CLIENT_SECRET="…"
THAIID_REDIRECT_URI="https://your-site.com/thaid/return" # ต้องตรงกับที่ลงทะเบียนทุกตัวอักษรimport { createThaiD } from "@inverz/thaid/server";
const thaid = createThaiD({
clientId: process.env.THAIID_CLIENT_ID,
clientSecret: process.env.THAIID_CLIENT_SECRET,
redirectUri: process.env.THAIID_REDIRECT_URI,
});Scope
ขอเฉพาะที่กรมการปกครองอนุมัติให้แอปของคุณ ค่าเริ่มต้นของแพ็กเกจ (DEFAULT_SCOPE) คือทุกตัวยกเว้น house_address ข้อมูลนี้ export เป็น THAID_SCOPES และ THAID_SCOPE_GROUPS ด้วย
| scope | ได้อะไร | ตัวอย่าง |
|---|---|---|
| openid | จำเป็นต้องมี ทำให้ได้ id_token | |
| pid | เลขประจำตัวประชาชน 13 หลัก | 1101700203450 |
| ial | ระดับความน่าเชื่อถือของการพิสูจน์ตัวตน (Identity Assurance Level) | 2.3 |
| title / title_en | คำนำหน้าชื่อ ไทย / อังกฤษ | นาย / Mr. |
| name / name_en | ชื่อ-นามสกุลเต็ม ไทย / อังกฤษ | สมชาย ใจดี |
| given_name / given_name_en | ชื่อ | สมชาย |
| middle_name / middle_name_en | ชื่อกลาง ถ้ามี | |
| family_name / family_name_en | นามสกุล | ใจดี |
| birthdate | วันเกิด | 1990-03-15 |
| gender | เพศ | |
| address | ที่อยู่ เป็นข้อความเต็มใน address.formatted | |
| house_address | ที่อยู่ตามทะเบียนบ้าน (รูปแบบข้อมูลยังไม่ได้ยืนยัน ลองดู claims จริงก่อนใช้) | |
| smartcard_code | รหัสของบัตรประชาชนใบปัจจุบัน | |
| date_of_issuance / date_of_expiry | วันออกบัตร / วันบัตรหมดอายุ | |
รายชื่อ scope ตรงกับ scopes_supported ใน discovery document ของ ThaiD รูปแบบค่าบางช่อง (วันที่ เพศ ที่อยู่) ขึ้นกับข้อมูลที่ ThaiD ส่งมาจริง
ขั้นตอน
- server:
thaid.createAuthorization()ได้urlและstateToken(state ที่เซ็นด้วย secret มีอายุ 10 นาที) - พาผู้ใช้ไปที่
urlผู้ใช้ยืนยันในแอป ThaiD แล้ว ThaiD พากลับมาที่THAIID_REDIRECT_URI?code=…&state=… - server:
thaid.handleCallback({ code, state, stateToken })ตรวจ state, แลก code เป็น token ด้วย client secret, ตรวจลายเซ็น id_token แล้วคืน{ claims, profile, tokens }
นี่คือ Authorization Code flow ตามมาตรฐาน OpenID Connect ที่ ThaiD รองรับ stateToken ต้องเดินทางจากขั้น 1 ไปขั้น 3:
- แบบมาตรฐาน (server รับ redirect เอง): เก็บใน httpOnly cookie ด้วย
stateCookieหน้าเว็บไม่เคยเห็น code, token หรือ secret (บน Firebase Hosting ต้องใช้ชื่อ cookie__session) - หน้าเว็บกับ API คนละโดเมน: API ส่ง
stateTokenให้หน้าเว็บThaiDButtonเก็บใน sessionStorage และuseThaiDCallbackส่งกลับพร้อม code
Express (แบบมาตรฐาน)
const { createThaiD, stateCookie, ThaiDError } = require("@inverz/thaid/server");
const thaid = createThaiD({
clientId: process.env.THAIID_CLIENT_ID,
clientSecret: process.env.THAIID_CLIENT_SECRET,
redirectUri: process.env.THAIID_REDIRECT_URI, // https://your-site.com/auth/thaid/callback
});
// ปุ่ม "ยืนยันตัวตนด้วย ThaiD" ลิงก์มาที่นี่
app.get("/auth/thaid", async (req, res) => {
const { url, stateToken } = await thaid.createAuthorization();
res.setHeader("Set-Cookie", stateCookie.serialize(stateToken));
res.redirect(url);
});
// THAIID_REDIRECT_URI
app.get("/auth/thaid/callback", async (req, res) => {
try {
const { profile } = await thaid.handleCallback({ ...req.query, stateToken: stateCookie.read(req.headers.cookie) });
req.session.thaid = { pid: profile.pid, name: profile.name }; // เก็บเท่าที่ใช้
res.setHeader("Set-Cookie", stateCookie.clear());
res.redirect("/profile");
} catch (e) {
res.redirect("/login?error=" + (e instanceof ThaiDError ? e.code : "server_error"));
}
});import "@inverz/thaid/style.css";
import { ThaiDButton } from "@inverz/thaid";
<ThaiDButton href="/auth/thaid" />Next.js (แบบมาตรฐาน)
// app/api/thaid/start/route.js
import { createThaiD, stateCookie } from "@inverz/thaid/server";
const thaid = createThaiD({ /* … */ });
export async function GET() {
const { url, stateToken } = await thaid.createAuthorization();
return new Response(null, { status: 302, headers: { Location: url, "Set-Cookie": stateCookie.serialize(stateToken) } });
}
// app/api/thaid/callback/route.js (THAIID_REDIRECT_URI ชี้มาที่นี่)
export async function GET(req) {
const params = Object.fromEntries(new URL(req.url).searchParams);
const { profile } = await thaid.handleCallback({ ...params, stateToken: stateCookie.read(req.headers.get("cookie")) });
// เก็บ profile ใน session แล้วพากลับหน้าเว็บ
return new Response(null, { status: 302, headers: { Location: "/profile", "Set-Cookie": stateCookie.clear() } });
}หน้าเว็บกับ API คนละโดเมน
// API
app.get("/api/thaid/start", async (req, res) => {
const { url, stateToken } = await thaid.createAuthorization();
res.json({ url, stateToken });
});
app.post("/api/thaid/callback", async (req, res) => {
try {
const { profile } = await thaid.handleCallback(req.body); // { code, state, stateToken }
res.json({ name: profile.name }); // บันทึกข้อมูลตัวตนที่ server
} catch (e) {
res.status(400).json({ code: e.code ?? "server_error" });
}
});import { ThaiDButton, useThaiDCallback, thaidErrorMessage } from "@inverz/thaid";
<ThaiDButton getAuthorization={() => fetch(API + "/api/thaid/start").then((r) => r.json())} />
// หน้าที่ตั้งเป็น THAIID_REDIRECT_URI
const ThaiDReturn = () => {
const { status, result, error } = useThaiDCallback((params) =>
fetch(API + "/api/thaid/callback", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(params) })
.then((r) => (r.ok ? r.json() : Promise.reject(r.json()))));
if (status === "loading") return <p>กำลังตรวจสอบ…</p>;
if (status === "error") return <p>{thaidErrorMessage(error)}</p>;
if (status === "success") return <p>ยืนยันตัวตนแล้ว: {result.name}</p>;
return null;
};useThaiDCallback เรียก API ครั้งเดียว (รวมถึงตอน React strict mode) แล้วลบ code ออกจากแถบที่อยู่ เพื่อไม่ให้ reload แล้วส่ง code ซ้ำ
ทดสอบค่าที่ได้จากกรมการปกครอง
หน้า demo มีช่องใส่ Client ID และ Redirect URI แล้วสร้างลิงก์ไปที่ ThaiD จริง บนคอมพิวเตอร์จะเปิดหน้าของกรมการปกครองที่มี QR ให้สแกนด้วยแอป ThaiD บนมือถือจะเปิดแอป ThaiD ถ้าค่าถูกต้อง ยืนยันเสร็จจะถูกพากลับไปที่ Redirect URI พร้อม ?code= ขั้นนี้ไม่ใช้ secret (ห้ามกรอก secret ลงหน้าเว็บ) จากนั้นแลก code บน server หรือในเครื่องตัวเองภายในไม่กี่นาที:
const { profile } = await thaid.exchangeCode("<code>"); // เฉพาะตอนทดสอบ ใช้งานจริงให้ใช้ handleCallback ที่ตรวจ state ด้วยความปลอดภัย
- อย่าเชื่อ id_token ที่ถอดรหัส base64 เอง id_token เป็นข้อความที่ใครก็แก้ได้ ต้องตรวจลายเซ็นก่อน
handleCallbackตรวจให้แล้ว ถ้าต้องรับ id_token จากที่อื่นให้ใช้thaid.verifyIdToken(idToken)ซึ่งตรวจลายเซ็น ES256, ผู้ออก (iss), ผู้รับ (aud= client id ของเรา), วันหมดอายุ และ nonce - บันทึกข้อมูลตัวตนที่ server ตั้งแต่ตรวจเสร็จ ไม่ต้องส่ง id_token ไปหน้าเว็บแล้วรับกลับมาอีกรอบ
stateตรวจทุกครั้ง ป้องกันไม่ให้คนอื่นเอา code ของตัวเองมาผูกกับบัญชีเรา (CSRF)- ข้อมูลจาก ThaiD เป็นข้อมูลส่วนบุคคล (PDPA) อย่า log ทั้งก้อน และเก็บเฉพาะที่จำเป็น
API ฝั่ง server (@inverz/thaid/server)
| | คำอธิบาย |
|---|---|
| createThaiD(options) | clientId, clientSecret, redirectUri (บังคับ), scope (ค่าเริ่มต้นทุก scope ยกเว้น house_address), stateMaxAge (600 วินาที), useNonce (true), fetch |
| thaid.createAuthorization() | { url, state, nonce, stateToken } |
| thaid.handleCallback({ code, state, error, stateToken }) | { claims, profile, tokens } |
| thaid.exchangeCode(code) | แลก code และตรวจ id_token โดยไม่ตรวจ state (handleCallback เรียกตัวนี้หลังตรวจ state) |
| thaid.verifyIdToken(idToken, { nonce }) | claims ที่ตรวจแล้ว |
| thaid.userinfo(accessToken), thaid.refresh(refreshToken), thaid.revoke(token) | endpoint อื่นของ ThaiD |
| stateCookie.serialize / read / clear | cookie สำหรับ stateToken |
| ThaiDError | มี code: access_denied, state_mismatch, state_expired, token_request_failed, invalid_id_token, id_token_expired … |
API ฝั่งเบราว์เซอร์ (@inverz/thaid)
| | คำอธิบาย |
|---|---|
| <ThaiDButton href /> หรือ <ThaiDButton getAuthorization /> | ปุ่มเริ่มยืนยันตัวตน |
| useThaiDCallback(exchange) | สำหรับหน้า redirect URI ได้ { status, result, error } |
| <ThaiDProfile profile fields showPid /> | การ์ดข้อมูลที่ยืนยันแล้ว ซ่อนเลขบัตรเป็นค่าเริ่มต้น |
| toProfile(claims) | แยกชื่อ-นามสกุลไทย/อังกฤษ ที่อยู่ ฯลฯ เป็น object เรียบๆ |
| namesMatch(profile, first, last) | เทียบชื่อที่ผู้ใช้กรอกกับชื่อจาก ThaiD |
| maskPid(pid) | "x-xxxx-xxxxx-45-0" |
| thaidErrorMessage(error, locale) | ข้อความภาษาไทย/อังกฤษสำหรับ error code |
ปรับสีด้วย --tid-brand, --tid-brand-text, --tid-surface, --tid-border, --tid-text, --tid-success, --tid-radius
License
MIT © 2026 Inverz Solutions Co.,Ltd.
