OAuth 2.0 Authentication

ภาพรวม (Overview)

HMS Auth Server เป็น OAuth 2.0 / OpenID Connect (OIDC) Authentication Server สำหรับระบบ HumanSoft ที่พัฒนาตามมาตรฐาน RFC 6749 (The OAuth 2.0 Authorization Framework) รองรับ:

OAuth 2.0 Grant Types: authorization_code, refresh_token, client_credentials
OpenID Connect (OIDC) พร้อม JWT tokens (RS256) ตาม OpenID Connect Core 1.0
PKCE Support สำหรับ SPA และ Mobile Apps ตาม RFC 7636

Base URL สำหรับ OAuth 2.0 endpoints ทั้งหมดคือ https://auth.humansoft.co.th/oauth2/v1

การตั้งค่า OAuth 2.0

เข้าสู่หน้าตั้งค่า

เข้าสู่ระบบ HumanSoft แล้วไปที่เมนู:

ตั้งค่า → ตั้งค่าการเชื่อมต่อ → OAuth 2.0

หรือเข้าผ่านลิงก์โดยตรง: HMS Settings - OAuth 2.0

สร้าง OAuth 2.0 Client

กดปุ่ม “เพิ่มการเชื่อมต่อ OAuth 2.0” แล้วกรอกข้อมูลดังนี้:

ฟิลด์	Required	คำอธิบาย
ชื่อ Client	Yes	ชื่อแอปพลิเคชันของคุณ
โลโก้	No	รูปสี่เหลี่ยมจัตุรัส ขนาดไม่เกิน 2MB (PNG, JPG)
Scopes	Yes	เลือก scope ที่ต้องการ: `openid`, `profile`, `email`
Redirect URIs	Yes	URL ที่จะรับ authorization callback

กดปุ่ม + เพิ่ม Redirect URI เพื่อเพิ่ม URL เช่น:


https://your-domain.com/callback

ข้อกำหนด Redirect URI: (ตาม RFC 6749 Section3.1.2 )

ต้องเป็น HTTPS เท่านั้น (ยกเว้น http://localhost สำหรับ development)
ต้องเป็น absolute URI ห้ามมี fragment component (#)
ต้องตรงกับ redirect_uri ที่ส่งใน authorization request ทุกประการ (exact match ไม่รองรับ wildcard)
สามารถเพิ่มได้หลาย URI

กรอกข้อมูลครบแล้วกดปุ่ม “บันทึก”

คัดลอก Client Secret

หลังจากบันทึกสำเร็จ ระบบจะแสดง Client Secret ให้คัดลอก เพียงครั้งเดียวเท่านั้น


f94d2697xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

สำคัญ: Client Secret จะแสดงเพียงครั้งเดียว หากปิดหน้านี้แล้วจะไม่สามารถดู Secret นี้ได้อีก

คัดลอกและเก็บไว้ในที่ปลอดภัย
ห้ามเปิดเผยใน client-side code หรือ public repositories
หากทำ Secret หาย สามารถกดปุ่ม “Rotate Secret” เพื่อสร้างใหม่ได้

ตรวจสอบข้อมูล Client

หลังจากสร้างสำเร็จ จะเห็นข้อมูล Client ที่สร้าง:

ฟิลด์	คำอธิบาย
Client ID	ใช้ส่งใน authorization request (เปิดเผยได้)
Scopes	Scopes ที่เลือกไว้
Redirect URIs	URL ที่อนุญาตให้ redirect

สามารถกดปุ่ม “แก้ไข” เพื่อแก้ไขข้อมูล หรือ “Rotate Secret” เพื่อสร้าง Client Secret ใหม่

Authorization Code Flow

การ Authentication

Client Authentication Methods

1. Client Secret (Confidential Clients)

สำหรับ server-side applications ที่สามารถเก็บ client secret ได้อย่างปลอดภัย:


Authorization: Basic base64(client_id:client_secret)

2. PKCE (Public Clients - SPA/Mobile)

สำหรับ Single Page Applications และ Mobile Apps ที่ไม่สามารถเก็บ client secret ได้:


code_challenge=BASE64URL(SHA256(code_verifier))
code_challenge_method=S256

แนะนำให้ใช้ PKCE สำหรับ SPA และ Mobile Apps เสมอ โดยใช้ S256 เป็น code_challenge_method เพื่อความปลอดภัยสูงสุด

Token Types

Token Type	ใช้สำหรับ	อายุ
Access Token	เข้าถึง protected resources	1 ชั่วโมง
Refresh Token	ขอ access token ใหม่	30 วัน
ID Token	ข้อมูล user identity (OIDC)	1 ชั่วโมง

Available Scopes

Scope	Description
`openid`	Required สำหรับ OIDC (ได้รับ id_token)
`profile`	ข้อมูล user profile (first_name, last_name, photograph, employee_code, user_type, instance_server_code)
`email`	User email address

API Endpoints

OAuth 2.0 Endpoints

Endpoint	Description	มาตรฐาน
Authorization Code Flow	เริ่มต้น authorization flow เพื่อขอ authorization code	RFC 6749 Section4.1
Token Endpoint	แลก authorization code เป็น tokens หรือ refresh token	RFC 6749 Section3.2
Token Introspection	ตรวจสอบว่า token ยังใช้งานได้หรือไม่	RFC 7662
Token Revocation	ยกเลิก token	RFC 7009
User Info	ดึงข้อมูล user จาก access token	OIDC Core Section5.3

JWKS Management

Endpoint	Description	มาตรฐาน
Get JWKS (Public Keys)	ดึง public keys สำหรับ verify JWT tokens	RFC 7517

มาตรฐานที่รองรับ (Standards)

มาตรฐาน	คำอธิบาย
RFC 6749	The OAuth 2.0 Authorization Framework
RFC 6750	The OAuth 2.0 Authorization Framework: Bearer Token Usage
RFC 7009	OAuth 2.0 Token Revocation
RFC 7517	JSON Web Key (JWK)
RFC 7519	JSON Web Token (JWT)
RFC 7636	Proof Key for Code Exchange (PKCE)
RFC 7662	OAuth 2.0 Token Introspection
OpenID Connect Core 1.0	OpenID Connect Authentication