เอกสาร API

เอกสารอ้างอิงสำหรับระบบปลายทางที่เชื่อมต่อกับ Ecox SSO — เข้าถึงได้แบบสาธารณะ ไม่ต้องมีบัญชี

มีรูปแบบคล้าย OIDC แต่ไม่ใช่ OIDC/OAuth2 เต็มรูปแบบ Ecox SSO ทำหน้าที่เพียง authentication คือพิสูจน์ว่าผู้ใช้คือใคร แต่ไม่ได้ implement OAuth2 authorization-code flow (/authorize, /token, PKCE, refresh tokens, scopes). นำเข้าไฟล์ openapi.yaml ไปใช้กับเครื่องมือของคุณเอง (Swagger UI, Postman หรือ codegen client ต่าง ๆ) เพื่อดู contract แบบเต็มที่เครื่องอ่านได้

Discovery และคีย์

เรียกใช้งาน endpoint เหล่านี้ได้เลย เป็นแบบ cacheable และทำงานแบบ machine-to-machine ทั้งนี้ควร bootstrap การเชื่อมต่อของคุณจาก discovery document แทนการ hardcode ค่า issuer หรือคีย์

เมธอด	เส้นทาง	วัตถุประสงค์
GET	`/.well-known/openid-configuration`	Issuer พร้อม `jwks_uri` และ alg/claims ที่รองรับ
GET	`/.well-known/jwks.json`	คีย์สาธารณะสำหรับเซ็นชื่อ (signing key) ที่ใช้งานอยู่ในปัจจุบัน — ระหว่างช่วง rotation จะเผยแพร่ทั้งคีย์เก่าที่กำลังจะหมดอายุและคีย์ใหม่พร้อมกัน

curl https://sso.wewillapp.com/.well-known/openid-configuration

curl https://sso.wewillapp.com/.well-known/jwks.json

ขั้นตอน login — เป็นการ redirect browser ไม่ใช่การเรียก API

ส่ง browser ของผู้ใช้มาที่นี่ด้วยสถานะ 302 — endpoint เหล่านี้ไม่ใช่สิ่งที่โค้ดฝั่งแอปของคุณเรียกโดยตรง

เมธอด	เส้นทาง	วัตถุประสงค์
GET	`/login?redirect=...`	แสดงฟอร์ม login หรือออก token ใหม่แบบเงียบ ๆ หาก browser มีเซสชันที่ยังใช้งานได้อยู่แล้ว (single sign-on)
GET	`/renew?redirect=...`	ต่ออายุ token แบบเงียบ ๆ ก่อนจะหมดอายุ (อายุสั้นเพียง ≤ 15 นาที).
GET/POST	`/logout`	ยืนยันการออกจากระบบ แล้ว revoke session พร้อมล้าง cookie

redirect จะถูกใช้งานก็ต่อเมื่อเป็น URL แบบเต็ม (absolute) https:// ที่มี host ตรงกับ wewillapp.com หรือเป็น subdomain ของ *.wewillapp.com โดยไม่มี userinfo ส่วนค่าอื่นใดนอกเหนือจากนี้ (host นอกโดเมน, http:, หรือแบบ protocol-relative //host) จะ fallback ไปหน้า default ที่ปลอดภัยเสมอ — ค่าที่ไม่ผ่านการตรวจสอบจะไม่เกิด error ใด ๆ

การตรวจสอบ token

อ่าน cookie __Secure-sso_token แล้วตรวจสอบ: ลายเซ็น RS256 (เลือกคีย์จาก JWT header kid โดยเทียบกับ JWKS ที่ cache ไว้), exp, iss (https://sso.wewillapp.com), และตรวจว่า aud มี wewillapp-internal. Fail closed เมื่อเกิดข้อผิดพลาดใด ๆ (invalid/expired/unknown-kid/เข้าถึง JWKS ไม่ได้) — ให้ถือว่ายังไม่ได้ authenticate แล้ว redirect (302) browser ไปที่ /login?redirect=<your app URL>.

Claim	ความหมาย
`iss`	https://sso.wewillapp.com — คงที่ตลอดไป ต้องตรวจสอบเสมอ (MUST verify)
`sub`	user id ที่คงที่ (uuid) — ใช้ค่านี้เป็นหลักในการ map role ฝั่งแอปของคุณ
`aud`	wewillapp-internal (audience คงที่) ควรตรวจสอบ (SHOULD verify)
`exp` / `iat` / `nbf`	timestamp มาตรฐานของ JWT — อายุใช้งานสูงสุด 15 นาที.
`jti`	รหัส token ที่ไม่ซ้ำกัน (ใช้เชื่อมโยงกับ audit log)
`sid`	รหัสเซสชันฝั่งเซิร์ฟเวอร์ (ใช้เชื่อมโยงข้อมูล)
`preferred_username` / `name` / `email`	มีอยู่เสมอ

ไม่มี claim role / admin / permission ใด ๆ — เป็นการออกแบบโดยตั้งใจ Ecox SSO ทำหน้าที่ authenticate เท่านั้น แต่ละแอปต้อง authorize เองโดยอิงจาก sub อย่าคาดหวังว่าจะมีข้อมูล authorization อยู่ใน token

Cookie

__Secure-sso_token — JWT แบบ RS256 ที่แอปปลายทางต้องตรวจสอบ ต้องอ่านตัวนี้
__Host-sso_session — รหัสเซสชันฝั่งเซิร์ฟเวอร์แบบทึบ (opaque) ใช้ภายใน SSO เท่านั้น แอปอื่นไม่ต้องสนใจ
__Host-sso_csrf — CSRF cookie แบบ double-submit ที่เซ็นชื่อไว้ ใช้กับฟอร์ม login ในช่วงก่อน authenticate เท่านั้น ไม่เกี่ยวข้องกับแอปปลายทาง

Health และ liveness

เมธอด	เส้นทาง	วัตถุประสงค์
GET	`/health`	ตรวจสอบเชิงลึก (DB, migrations, signing-key canary) จะคืนค่า 200 ก็ต่อเมื่อผ่านทุกการตรวจสอบ มิฉะนั้นจะคืนค่า 503
GET	`/livez`	ตรวจสอบ liveness แบบพื้นฐาน ไม่ตรวจสอบ dependency ใด ๆ

แหล่งข้อมูลจริงคือค่าที่ใช้งานอยู่จริง (live) ไม่ใช่หน้านี้ — ควร bootstrap จาก discovery endpoint ด้านบนเสมอ แทนการ hardcode คีย์ ดูข้อกำหนด (contract) ฉบับเต็มที่เครื่องอ่านได้ที่: /docs/openapi.yaml.