เริ่มต้น

Pi Auth ทำงานอย่างไร

tenant (= องค์กร) สมาชิก ผังองค์กร แอป role และ binding — และเกิดอะไรขึ้นตอนล็อกอิน

Pi Auth ตอบ 3 คำถามที่แอปภายในทุกตัวต้องถาม: คนนี้เป็นใคร ตอนนี้ทำงานในนามองค์กรไหน และทำอะไรได้บ้างที่นั่น แอปได้คำตอบทั้งสามในโทเค็นที่ลงนามใบเดียว โดยไม่ต้องมีตารางผู้ใช้ ผังองค์กร หรือตารางสิทธิ์ของตัวเอง

ส่วนประกอบ

สิ่งที่มี	คืออะไร	อยู่ที่ไหน
Tenant	หนึ่งองค์กร ทุกข้อมูลด้านล่างเป็นของ tenant เดียวเสมอ	Platform console
สมาชิก (Member)	ผู้ใช้ภายใน tenant ผู้ใช้หนึ่งคนเป็นสมาชิกได้หลาย tenant แต่ละ membership มี base role (owner / admin / member) และสถานะ	Console → สมาชิก
หน่วยงาน · ตำแหน่ง · กลุ่ม	ผังองค์กร (ต้นไม้ที่มี path เช่น /acme/eng/it), ตำแหน่งงานที่สมาชิกถือ (มี level) และกลุ่มเฉพาะกิจ; attribute เพิ่มฟิลด์แบบมีชนิดต่อสมาชิก	Console → ผังองค์กร
แอป	OIDC client ที่สมาชิกล็อกอินเข้าใช้ แอปของแพลตฟอร์มลงทะเบียนครั้งเดียวแล้วติดตั้งต่อ tenant; tenant ลงทะเบียนแอปของตัวเองได้ด้วย	Console → แอป
Permission	ข้อความที่แอปประกาศใน manifest เช่น `memo:approve` แอปเป็นคนตัดสินว่ามันหมายถึงอะไร Pi Auth ตัดสินแค่ว่าใครมี	แอปประกาศ
Role	ชุด permission ที่มีชื่อภายใน tenant; system role มากับทุก tenant ส่วนเทมเพลตจากแอปและ role ที่สร้างเองเพิ่มโดยผู้ดูแล	Console → สิทธิ์ → Roles
Binding	Role → subject โดย subject คือสมาชิก กลุ่ม ตำแหน่ง หรือหน่วยงาน (เลือกรวมหน่วยย่อยได้) พร้อมช่วงเวลามีผลถ้าต้องการ	หน้า role

Authorization code flow พร้อม PKCE — เบราว์เซอร์เห็นแค่ code ใช้ครั้งเดียว โทเค็นวิ่งระหว่างเซิร์ฟเวอร์เท่านั้น

แอปส่งเบราว์เซอร์ไปที่ /authorize ของ Pi Auth พร้อม PKCE, state, nonce และ resource indicator urn:pi:app:<client_id>
Pi Auth ยืนยันตัวผู้ใช้ (รหัสผ่าน passkey ลิงก์อีเมล หรือ SSO ขององค์กร — เลือกให้อัตโนมัติจากโดเมนอีเมล) ให้เลือกองค์กรถ้าเป็นสมาชิกมากกว่าหนึ่งแห่ง และบังคับนโยบาย MFA ขององค์กรนั้น
เบราว์เซอร์กลับมาที่ redirect URI ของแอปพร้อม code ใช้ครั้งเดียว
เซิร์ฟเวอร์ของแอปแลก code ที่ /token ตรวจลายเซ็น access token กับ JWKS ของ Pi Auth แล้วเก็บไว้ใน cookie ที่เข้ารหัส จากนี้ทุก request รู้ tenant ตำแหน่งในผัง และสิทธิ์ที่มีผล

ใน access token มีอะไร

access token เป็น JWT ที่ Pi Auth ลงนาม นอกจาก claim มาตรฐาน (iss, sub, aud, exp) ยังมีบริบทของ tenant:

Claim	ความหมาย
`tid`	id ของ tenant ที่โทเค็นผูกอยู่
`tslug`	slug ของ tenant เช่น acme
`mid`	membership id — ใช้ค่านี้ (ไม่ใช่ sub) เป็น key ของข้อมูลต่อ tenant
`trole`	base role ของ membership: owner, admin หรือ member
`org`	หน่วยงาน { id, path, name } ที่สมาชิกสังกัด
`pos`	ตำแหน่ง { id, code, level }
`groups`	code ของกลุ่มที่สมาชิกอยู่
`attrs`	ค่า attribute ที่ติ๊ก “ใส่ในโทเค็น”
`perms`	สิทธิ์ที่มีผลสำหรับแอปนี้ (scope `permissions`) เช่น `["memo:create","memo:approve"]`
`perms_ref`	มาแทน perms เมื่อรายการยาวเกิน — เป็น path บน issuer ให้ไปดึง

access token ที่ถอดแล้ว (ย่อ)

{
  "iss": "https://auth.suphark.com",
  "sub": "usr_7Fk…",
  "aud": "urn:pi:app:AOWrBtppsYLxThsohmXWS7JjCknWiog9",
  "tid": "3770ea5f…", "tslug": "acme", "mid": "68dc9b7a…", "trole": "member",
  "org": { "id": "ou_…", "path": "/acme/eng/it", "name": "IT" },
  "pos": { "id": "pos_…", "code": "ENG", "level": 3 },
  "perms": ["pdf:use"],
  "exp": 1789000000
}

แอปประกาศ องค์กรตัดสิน

แอปส่ง permission manifest มา: รายการสิ่งที่อนุญาตได้ในแอป พร้อมระดับความเสี่ยง และเทมเพลต role ถ้ามี องค์กรติดตั้งแอปแล้วผู้ดูแลตัดสินว่าใครได้อะไร ด้วยการผูก role กับคน ตำแหน่ง กลุ่ม หรือทั้งกิ่งของผังองค์กร เปลี่ยนผังแล้วสิทธิ์ตามไปเอง — ไม่มีใครต้องไปแก้ access list ในแอป

เพราะสิทธิ์คำนวณจากไดเรกทอรี คอนโซลจึงอธิบายได้เสมอว่าทำไมคนนี้ถึงมีสิทธิ์นี้: จาก role ไหน ผ่าน binding ใด ทางตำแหน่งหรือหน่วยงานใด

Tenant คือขอบเขตของทุกสิ่ง

ทุกแถวในฐานข้อมูลมี tenant id และอ่านได้ผ่าน client ที่จำกัด tenant เท่านั้น
โทเค็นผูกกับ tenant เดียว การทำงานในนามองค์กรอื่นคือล็อกอินใหม่ (หรือสลับในคอนโซล) แล้วรับโทเค็นใหม่
ผู้ดูแลของ tenant หนึ่งมองไม่เห็นอีก tenant เลย platform admin จัดการ tenant และแอป แต่เข้าไปทำงานใน tenant ได้ทางเดียวคือสวมสิทธิ์ที่ถูกบันทึก audit

ค่าเริ่มต้นคือแบบปลอดภัย

OIDC authorization code + PKCE เท่านั้น ไม่มี implicit flow ไม่มีโทเค็นในเบราว์เซอร์
key ลงนามหมุนทุก 90 วัน key เก่ายังเผยแพร่ต่ออีก 7 วัน
owner และ admin ต้องเปิด MFA (TOTP หรือ passkey) เป็นค่าเริ่มต้น นโยบายขยายไปทุกคนได้
รหัสผ่าน: อย่างน้อย 10 ตัวอักษรและตรวจกับฐานรหัสรั่ว; ล็อกบัญชีเมื่อล้มเหลวซ้ำ; ลืมรหัสผ่านขอลิงก์ตั้งใหม่ทางอีเมลได้จากหน้าเข้าสู่ระบบ (ลิงก์ใช้ได้ 1 ชั่วโมง)
session เก็บฝั่งเซิร์ฟเวอร์ ถอนได้รายอุปกรณ์โดยสมาชิกเองหรือผู้ดูแล
ทุกการเปลี่ยนแปลงด้านความปลอดภัยลง audit log แบบเพิ่มได้อย่างเดียว