ข้อกำหนด Core SDK (Core SDK convention)

ข้อกำหนดพื้นฐาน

• core ควรมีเฉพาะฟังก์ชันที่ไม่ขึ้นกับแพลตฟอร์มเท่านั้น
• core ควรตั้งชื่อเป็น {$language} และอยู่ใต้ root directory ของ repository เช่น logto/js/js, logto/kotlin/kotlin
• core package ควรตั้งชื่อเป็น {$language} ภายใต้ Logto scope เช่น @logto/js, io.logto.sdk:kotlin

ข้อกำหนดหลัก

Core SDK ใด ๆ ควรมี:

• ประเภทข้อมูล (Types)
• ฟังก์ชันอรรถประโยชน์ (Utility functions)
• ฟังก์ชันหลัก (Core functions)

ประเภทข้อมูล (Types)

OidcConfigResponse

การตั้งค่าของผู้ให้บริการข้อมูลระบุตัวตน (Identity provider) ซึ่งสามารถดึงได้ผ่าน API /oidc/.well-known/openid-configuration

คุณสมบัติ

ชื่อ	ประเภท
authorizationEndpoint	string
tokenEndpoint	string
endSessionEndpoint	string
revocationEndpoint	string
jwksUri	string
issuer	string

CodeTokenResponse

ข้อมูลตอบกลับของ /oidc/token (โดย authorization code)

คุณสมบัติ

ชื่อ	ประเภท	จำเป็น
accessToken	string	✅
refreshToken	string
idToken	string	✅
scope	string	✅
expiresIn	number	✅

RefreshTokenResponse

ข้อมูลตอบกลับของ /oidc/token (โดย refresh token) เมื่อรีเฟรชโทเค็นด้วย refresh token

คุณสมบัติ

ชื่อ	ประเภท	จำเป็น
accessToken	string	✅
refreshToken	string	✅
idToken	string
scope	string	✅
expiresIn	number	✅

IdTokenClaims

การอ้างสิทธิ์ (Claims) ที่อยู่ใน id token

คุณสมบัติ

ชื่อ	ประเภท	จำเป็น
sub	string	✅
aud	string	✅
exp	number	✅
iat	number	✅
iss	string	✅
atHash	string
username	string
name	string
avatar	string

ฟังก์ชันอรรถประโยชน์ (Utility functions)

generateCodeVerifier

สร้าง code verifier
ความยาวของ code verifier ถูกกำหนดไว้ที่ 64
ค่าที่คืนกลับ ต้อง ถูกเข้ารหัสเป็นสตริง base64 ที่ปลอดภัยสำหรับ URL

อ้างอิง

• PKCE

พารามิเตอร์

ไม่มี

ประเภทที่คืนกลับ

string

generateCodeChallenge

สร้าง code challenge จาก code verifier
วิธีนี้จะเข้ารหัส code verifier และคืนค่าผลลัพธ์ในรูปแบบ Base64 ที่ปลอดภัยสำหรับ URL
เราใช้ algorithm การเข้ารหัสแบบ SHA-256 แบบกำหนดตายตัวใน Logto V1

อ้างอิง

• PKCE

พารามิเตอร์

ชื่อ	ประเภท	หมายเหตุ
codeVerifier	string	สร้างโดย generateCodeVerifier

ประเภทที่คืนกลับ

string

generateState

"State" ใช้เพื่อป้องกันการโจมตีแบบ CSRF
ความยาวของ "state" ถูกกำหนดไว้ที่ 64
สตริงผลลัพธ์ที่คืนกลับ ต้อง ถูกเข้ารหัสเป็น base64 ที่ปลอดภัยสำหรับ URL

อ้างอิง

• CSRF

พารามิเตอร์

ไม่มี

ประเภทที่คืนกลับ

string

decodeIdToken

ถอดรหัส ID Token โดยไม่ตรวจสอบความถูกต้องของ secret
คืนค่าเป็น IdTokenClaims ซึ่งมีการอ้างสิทธิ์ (claims) ทั้งหมดในส่วน payload

พารามิเตอร์

ชื่อ	ประเภท
token	string

ประเภทที่คืนกลับ

IdTokenClaims

ข้อผิดพลาด

• token ไม่ใช่ JWT ที่ถูกต้อง

verifyIdToken

ตรวจสอบว่า ID Token ถูกต้องหรือไม่

ตรวจสอบ Signing Key

OIDC รองรับ JSON Web Key Set
ฟังก์ชันนี้รับวัตถุ JsonWebKeySet จากไลบรารีภายนอก (jose) เพื่อใช้ตรวจสอบ

// ตัวอย่าง JsonWebKeySet
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "xxxx",
      "e": "xxxx",
      "n": "xxxx"
    }
  ]
}

ตรวจสอบ Claims

• ตรวจสอบว่า iss ใน ID Token ตรงกับผู้ออก (issuer) ของโทเค็นนี้
• ตรวจสอบว่า Claim aud (ผู้รับ) เท่ากับ client ID
• ตรวจสอบว่าเวลาปัจจุบันต้องไม่เกินเวลาหมดอายุ
• ตรวจสอบว่าเวลาที่ออก (iat) ต้องไม่เกิน +/- 1 นาทีจากเวลาปัจจุบัน

อ้างอิง

• OpenID connect core - ID Token Validation

พารามิเตอร์

ชื่อ	ประเภท
idToken	string
clientId	string
issuer	string
jwks	JsonWebKeySet

ประเภทที่คืนกลับ

void

ข้อผิดพลาด

• ตรวจสอบ signing key ล้มเหลว
• ตรวจสอบ claims ล้มเหลว

verifyAndParseCodeFromCallbackUri

ตรวจสอบว่า sign-in callbackUri ถูกต้องหรือไม่ และคืนค่า code ที่ดึงมาจาก callbackUri

ตรวจสอบ Callback URI

• ตรวจสอบว่า callbackUri ต้องขึ้นต้นด้วย redirectUri
• ตรวจสอบว่าไม่มี error ใน callbackUri (ดู Error Response ใน redirect URI)
• ตรวจสอบว่า callbackUri มี state ซึ่งต้องเท่ากับค่าที่คุณระบุใน generateSignInUri
• ตรวจสอบว่า callbackUri มีพารามิเตอร์ code ซึ่งคุณจะใช้เมื่อขอ /oidc/token (โดย refresh token)

พารามิเตอร์

ชื่อ	ประเภท
callbackUri	string
redirectUri	string
state	string

ประเภทที่คืนกลับ

string

ข้อผิดพลาด

• การตรวจสอบล้มเหลว

ฟังก์ชันหลัก (Core functions)

fetchOidcConfig

คืนค่า OidcConfigResponse โดยการร้องขอไปที่ /oidc/.well-known/openid-configuration

พารามิเตอร์

ชื่อ	ประเภท	หมายเหตุ
endpoint	string	จุดเชื่อมต่อบริการ OIDC

ประเภทที่คืนกลับ

OidcConfigResponse

ข้อผิดพลาด

• ดึงข้อมูลล้มเหลว

generateSignInUri

พารามิเตอร์

ชื่อ	ประเภท	จำเป็น	หมายเหตุ
authorizationEndpoint	string	✅
clientId	string	✅
redirectUri	string	✅
codeChallenge	string	✅
state	string	✅
scopes	string[]		การใช้งานอาจแตกต่างตามภาษา
resources	string[]		การใช้งานอาจแตกต่างตามภาษา
prompt	string		ค่าเริ่มต้น: consent

URL จะถูกสร้างขึ้นจาก authorizationEndpoint และมี query params ดังต่อไปนี้:

พารามิเตอร์ Query ของ Sign-In Url

คีย์ Query	จำเป็น	หมายเหตุ
client_id	✅
redirect_uri	✅
code_challenge	✅
code_challenge_method	✅	กำหนดตายตัวเป็น S256
state	✅
scope	✅	scope จะมี openid และ offline_access เสมอ แม้ input scope จะเป็น null หรือว่าง
resource		สามารถเพิ่ม resource ใน uri ได้มากกว่าหนึ่งครั้ง backend จะรวมเป็น list เช่น resource=a&resource=b
response_type	✅	กำหนดตายตัวเป็น code
prompt	✅

ประเภทที่คืนกลับ

string

generateSignOutUri

พารามิเตอร์

ชื่อ	ประเภท	จำเป็น
endSessionEndpoint	string	✅
idToken	string	✅
postLogoutRedirectUri	string

URL ที่จะสร้างขึ้นจะอิงจาก endSessionEndpoint และมี query parameters ดังนี้:

พารามิเตอร์ Query ของ Sign-Out Url

คีย์ Query	จำเป็น	หมายเหตุ
id_token_hint	✅	พารามิเตอร์ idToken ที่รับเข้ามา
post_logout_redirect_uri		พารามิเตอร์ postLogoutRedirectUri ที่รับเข้ามา

ประเภทที่คืนกลับ

string

fetchTokenByAuthorizationCode

ดึงโทเค็น (CodeTokenResponse) โดยร้องขอไปที่ /oidc/token (โดย authorization code)

พารามิเตอร์

ชื่อ	ประเภท	จำเป็น
tokenEndpoint	string	✅
code	string	✅
codeVerifier	string	✅
clientId	string	✅
redirectUri	string	✅
resource	string

HTTP Request

• Endpoint: /oidc/token
• Method: POST
• Content-Type: application/x-www-form-urlencoded
• Payload:

คีย์ Query	ประเภท	จำเป็น
grant_type	string: 'authorization_code'	✅
code	string	✅
code_verifier	string	✅
client_id	string	✅
redirect_uri	string	✅
resource	string

ประเภทที่คืนกลับ

CodeTokenResponse

ข้อผิดพลาด

• ดึงข้อมูลล้มเหลว

fetchTokenByRefreshToken

ดึงโทเค็น (RefreshTokenTokenResponse) ผ่าน /oidc/token (โดย refresh token)

พารามิเตอร์

ชื่อ	ประเภท	จำเป็น
tokenEndpoint	string	✅
clientId	string	✅
refreshToken	string	✅
resource	string
scopes	string[]

HTTP Request

• Endpoint: /oidc/token
• Method: POST
• Content-Type: application/x-www-form-urlencoded
• Payload:

คีย์ Query	ประเภท	จำเป็น	หมายเหตุ
grant_type	string: 'refresh_token'	✅
refresh_token	string	✅
client_id	string	✅
resource	string
scope	string		นำค่าใน scopes มาต่อกันด้วยช่องว่างเพื่อสร้างสตริง scope

ประเภทที่คืนกลับ

RefreshTokenTokenResponse

ข้อผิดพลาด

• ดึงข้อมูลล้มเหลว

revoke

ร้องขอไปยัง API /oidc/token/revocation เพื่อแจ้งเซิร์ฟเวอร์การอนุญาต (authorization server) ว่า refresh หรือ access token ที่ได้รับมาก่อนหน้านี้ไม่จำเป็นต้องใช้อีกต่อไป

พารามิเตอร์

ชื่อ	ประเภท	หมายเหตุ
revocationEndpoint	string
clientId	string
token	string	โทเค็นที่ต้องการเพิกถอน

HTTP Request

• Endpoint: /oidc/token/revocation
• Method: POST
• Content-Type: application/x-www-form-urlencoded
• Payload:

คีย์ Query	ประเภท
client_id	string
token	string

ประเภทที่คืนกลับ

void

ข้อผิดพลาด

• การเพิกถอนล้มเหลว