เพิ่มการยืนยันตัวตนให้กับแอป iOS (Swift) ของคุณ
คู่มือนี้ถือว่าคุณได้สร้างแอปพลิเคชันประเภท "Native app" ใน Admin Console แล้ว
การติดตั้ง
ใช้ URL ต่อไปนี้เพื่อเพิ่ม Logto SDK เป็น dependency ใน Swift Package Manager
https://github.com/logto-io/swift.git
ตั้งแต่ Xcode 11 เป็นต้นมา คุณสามารถ นำเข้า Swift package ได้โดยตรง โดยไม่ต้องใช้เครื่องมือเพิ่มเติมใด ๆ
ขณะนี้ เรายังไม่รองรับ Carthage และ CocoaPods เนื่องจากปัญหาทางเทคนิคบางประการ
Carthage
Carthage ต้องการไฟล์ xcodeproj
เพื่อ build แต่ swift package generate-xcodeproj
จะรายงานข้อผิดพลาด เนื่องจากเราใช้ binary targets สำหรับปลั๊กอินโซเชียลแบบ native เราจะพยายามหาวิธีแก้ไขในภายหลัง
CocoaPods
CocoaPods ไม่รองรับ local dependency และ monorepo ดังนั้นจึงยากที่จะสร้าง .podspec
สำหรับ repo นี้
การเชื่อมต่อ
เริ่มต้น LogtoClient
เริ่มต้นไคลเอนต์โดยการสร้างอินสแตนซ์ LogtoClient
ด้วยอ็อบเจกต์ LogtoConfig
import Logto
import LogtoClient
let config = try? LogtoConfig(
endpoint: "<your-logto-endpoint>", // เช่น http://localhost:3001
appId: "<your-app-id>"
)
let client = LogtoClient(useConfig: config)
โดยปกติ เราจะจัดเก็บข้อมูลรับรอง เช่น โทเค็น ID (ID Token) และ โทเค็นรีเฟรช (Refresh Token) ไว้ใน Keychain ดังนั้นผู้ใช้จึงไม่จำเป็นต้องลงชื่อเข้าใช้อีกเมื่อกลับมา
หากต้องการปิดการทำงานนี้ ให้ตั้งค่า usingPersistStorage
เป็น false
:
let config = try? LogtoConfig(
// ...
usingPersistStorage: false
)
ดำเนินการลงชื่อเข้าใช้และออกจากระบบ
ก่อนที่เราจะลงลึกในรายละเอียด นี่คือภาพรวมประสบการณ์ของผู้ใช้ปลายทาง กระบวนการลงชื่อเข้าใช้สามารถสรุปได้ดังนี้:
- แอปของคุณเรียกใช้งานเมธอดลงชื่อเข้าใช้
- ผู้ใช้จะถูกเปลี่ยนเส้นทางไปยังหน้าลงชื่อเข้าใช้ของ Logto สำหรับแอปเนทีฟ ระบบจะเปิดเบราว์เซอร์ของระบบ
- ผู้ใช้ลงชื่อเข้าใช้และถูกเปลี่ยนเส้นทางกลับไปยังแอปของคุณ (ตามที่กำหนดไว้ใน redirect URI)
เกี่ยวกับการลงชื่อเข้าใช้แบบเปลี่ยนเส้นทาง (redirect-based sign-in)
- กระบวนการยืนยันตัวตนนี้เป็นไปตามโปรโตคอล OpenID Connect (OIDC) และ Logto บังคับใช้มาตรการรักษาความปลอดภัยอย่างเข้มงวดเพื่อปกป้องการลงชื่อเข้าใช้ของผู้ใช้
- หากคุณมีหลายแอป คุณสามารถใช้ผู้ให้บริการข้อมูลระบุตัวตน (Logto) เดียวกันได้ เมื่อผู้ใช้ลงชื่อเข้าใช้แอปหนึ่งแล้ว Logto จะดำเนินการลงชื่อเข้าใช้โดยอัตโนมัติเมื่อผู้ใช้เข้าถึงแอปอื่น
หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับเหตุผลและประโยชน์ของการลงชื่อเข้าใช้แบบเปลี่ยนเส้นทาง โปรดดูที่ อธิบายประสบการณ์การลงชื่อเข้าใช้ของ Logto
กำหนดค่า Redirect URI
ไปที่หน้ารายละเอียดแอปพลิเคชันของ Logto Console เพิ่ม Redirect URI io.logto://callback
แล้วคลิก "บันทึกการเปลี่ยนแปลง" (Save changes)

Redirect URI ใน iOS SDK ใช้สำหรับการทำงานภายในเท่านั้น ไม่จำเป็นต้อง เพิ่ม Custom URL Scheme จนกว่าจะมีตัวเชื่อมต่อร้องขอ
การลงชื่อเข้าใช้และออกจากระบบ
ก่อนเรียก .signInWithBrowser(redirectUri:)
โปรดตรวจสอบให้แน่ใจว่าคุณได้กำหนดค่า Redirect URI ใน Admin Console อย่างถูกต้องแล้ว
คุณสามารถใช้ client.signInWithBrowser(redirectUri:)
เพื่อให้ผู้ใช้ลงชื่อเข้าใช้ และ client.signOut()
เพื่อออกจากระบบ
ตัวอย่างเช่น ในแอป SwiftUI:
struct ContentView: View {
@State var isAuthenticated: Bool
init() {
isAuthenticated = client.isAuthenticated
}
var body: some View {
VStack {
if isAuthenticated {
Button("Sign Out") {
Task { [self] in
await client.signOut()
isAuthenticated = false
}
}
} else {
Button("Sign In") {
Task { [self] in
do {
try await client.signInWithBrowser(redirectUri: "${
props.redirectUris[0] ?? 'io.logto://callback'
}")
isAuthenticated = true
} catch let error as LogtoClientErrors.SignIn {
// เกิดข้อผิดพลาดระหว่างการลงชื่อเข้าใช้
} catch {
// ข้อผิดพลาดอื่น ๆ
}
}
}
}
}
}
}
จุดตรวจสอบ: ทดสอบแอปพลิเคชันของคุณ
ตอนนี้คุณสามารถทดสอบแอปพลิเคชันของคุณได้แล้ว:
- รันแอปพลิเคชันของคุณ คุณจะเห็นปุ่มลงชื่อเข้าใช้
- คลิกปุ่มลงชื่อเข้าใช้ SDK จะเริ่มกระบวนการลงชื่อเข้าใช้และเปลี่ยนเส้นทางคุณไปยังหน้าลงชื่อเข้าใช้ของ Logto
- หลังจากที่คุณลงชื่อเข้าใช้แล้ว คุณจะถูกเปลี่ยนเส้นทางกลับไปยังแอปพลิเคชันของคุณและเห็นปุ่มลงชื่อออก
- คลิกปุ่มลงชื่อออกเพื่อเคลียร์ที่เก็บโทเค็นและออกจากระบบ
รับข้อมูลผู้ใช้
แสดงข้อมูลผู้ใช้
หากต้องการแสดงข้อมูลของผู้ใช้ คุณสามารถใช้เมธอด client.getIdTokenClaims()
ตัวอย่างเช่น ในแอป SwiftUI:
// ตัวอย่างนี้แสดงชื่อผู้ใช้หลังจากลงชื่อเข้าใช้สำเร็จ
struct ContentView: View {
@State var isAuthenticated: Bool
@State var name: String?
init() {
isAuthenticated = client.isAuthenticated
name = try? client.getIdTokenClaims().name
}
var body: some View {
VStack {
if isAuthenticated {
Text("Welcome, \(name)")
} else {
Text("Please sign in")
}
}
}
}
ขอการอ้างสิทธิ์เพิ่มเติม
คุณอาจพบว่าข้อมูลผู้ใช้บางอย่างหายไปในอ็อบเจกต์ที่ส่งคืนจาก client.getIdTokenClaims()
สาเหตุเนื่องจาก OAuth 2.0 และ OpenID Connect (OIDC) ถูกออกแบบมาให้สอดคล้องกับหลักการสิทธิ์น้อยที่สุด (principle of least privilege; PoLP) และ Logto ถูกสร้างขึ้นบนมาตรฐานเหล่านี้
โดยปกติแล้ว จะมีการส่งคืนการอ้างสิทธิ์ (claim) แบบจำกัด หากคุณต้องการข้อมูลเพิ่มเติม คุณสามารถร้องขอขอบเขต (scope) เพิ่มเติมเพื่อเข้าถึงการอ้างสิทธิ์ (claim) ที่มากขึ้นได้
"การอ้างสิทธิ์ (Claim)" คือการยืนยันข้อมูลบางอย่างเกี่ยวกับผู้ถูกอ้างถึง (subject); "ขอบเขต (Scope)" คือกลุ่มของการอ้างสิทธิ์ (claim) ในกรณีนี้ การอ้างสิทธิ์ (claim) คือข้อมูลบางอย่างเกี่ยวกับผู้ใช้
ตัวอย่างที่ไม่เป็นทางการของความสัมพันธ์ระหว่างขอบเขต (scope) กับการอ้างสิทธิ์ (claim) มีดังนี้:
การอ้างสิทธิ์ (claim) "sub" หมายถึง "ผู้ถูกอ้างถึง (subject)" ซึ่งคือตัวระบุที่ไม่ซ้ำของผู้ใช้ (เช่น user ID)
Logto SDK จะร้องขอขอบเขต (scope) สามรายการเสมอ ได้แก่ openid
, profile
และ offline_access
หากต้องการขอขอบเขต (scopes) เพิ่มเติม คุณสามารถส่ง scopes ไปยังอ็อบเจกต์ LogtoConfig
ตัวอย่างเช่น:
let config = try? LogtoConfig(
endpoint: "<your-logto-endpoint>", // เช่น http://localhost:3001
appId: "<your-app-id>",
scopes: [
UserScope.Email.rawValue,
UserScope.Phone.rawValue,
]
)
จากนั้นคุณสามารถเข้าถึงการอ้างสิทธิ์เพิ่มเติมในค่าที่คืนมาจาก client.getIdTokenClaims()
:
let claims = try? client.getIdTokenClaims()
// ตอนนี้คุณสามารถเข้าถึงการอ้างสิทธิ์เพิ่มเติม เช่น `claims.email`, `claims.phone` เป็นต้น
การอ้างสิทธิ์ (Claims) ที่ต้องใช้การร้องขอผ่านเครือข่าย
เพื่อป้องกันไม่ให้โทเค็น ID (ID token) มีขนาดใหญ่เกินไป การอ้างสิทธิ์บางรายการจำเป็นต้องร้องขอผ่านเครือข่ายเพื่อดึงข้อมูล ตัวอย่างเช่น การอ้างสิทธิ์ custom_data
จะไม่ถูกรวมอยู่ในอ็อบเจกต์ผู้ใช้ แม้ว่าจะร้องขอไว้ในขอบเขต (scopes) ก็ตาม หากต้องการเข้าถึงการอ้างสิทธิ์เหล่านี้ คุณสามารถใช้เมธอด client.fetchUserInfo()
:
let userInfo = try? client.fetchUserInfo()
// ตอนนี้คุณสามารถเข้าถึงการอ้างสิทธิ์ `userInfo.custom_data`
ขอบเขตและการอ้างสิทธิ์
Logto ใช้มาตรฐาน ขอบเขต (scopes) และ การอ้างสิทธิ์ (claims) ของ OIDC เพื่อกำหนดขอบเขตและการอ้างสิทธิ์สำหรับดึงข้อมูลผู้ใช้จากโทเค็น ID (ID token) และ OIDC userinfo endpoint ทั้ง "ขอบเขต (scope)" และ "การอ้างสิทธิ์ (claim)" เป็นคำศัพท์จากข้อกำหนดของ OAuth 2.0 และ OpenID Connect (OIDC)
ต่อไปนี้คือรายการขอบเขต (Scopes) ที่รองรับและการอ้างสิทธิ์ (Claims) ที่เกี่ยวข้อง:
openid
ชื่อการอ้างสิทธิ์ | ประเภท | คำอธิบาย | ต้องใช้ userinfo หรือไม่? |
---|---|---|---|
sub | string | ตัวระบุที่ไม่ซ้ำของผู้ใช้ | ไม่ |
profile
ชื่อการอ้างสิทธิ์ | ประเภท | คำอธิบาย | ต้องใช้ userinfo หรือไม่? |
---|---|---|---|
name | string | ชื่อเต็มของผู้ใช้ | ไม่ |
username | string | ชื่อผู้ใช้ของผู้ใช้ | ไม่ |
picture | string | URL ของรูปโปรไฟล์ของผู้ใช้ปลายทาง URL นี้ ต้อง อ้างอิงถึงไฟล์รูปภาพ (เช่น ไฟล์ PNG, JPEG หรือ GIF) ไม่ใช่หน้าเว็บที่มีรูปภาพ โปรดทราบว่า URL นี้ ควร อ้างอิงถึงรูปโปรไฟล์ของผู้ใช้ปลายทางที่เหมาะสมสำหรับการแสดงผลเมื่ออธิบายผู้ใช้ปลายทาง ไม่ใช่รูปภาพใด ๆ ที่ผู้ใช้ถ่ายเอง | ไม่ |
created_at | number | เวลาที่สร้างผู้ใช้ปลายทาง เวลานี้แสดงเป็นจำนวนมิลลิวินาทีตั้งแต่ Unix epoch (1970-01-01T00:00:00Z) | ไม่ |
updated_at | number | เวลาที่ข้อมูลของผู้ใช้ปลายทางถูกอัปเดตล่าสุด เวลานี้แสดงเป็นจำนวนมิลลิวินาทีตั้งแต่ Unix epoch (1970-01-01T00:00:00Z) | ไม่ |
การอ้างสิทธิ์มาตรฐาน อื่น ๆ เช่น family_name
, given_name
, middle_name
, nickname
, preferred_username
, profile
, website
, gender
, birthdate
, zoneinfo
, และ locale
จะถูกรวมอยู่ในขอบเขต profile
ด้วยโดยไม่ต้องร้องขอ endpoint userinfo ความแตกต่างเมื่อเทียบกับการอ้างสิทธิ์ข้างต้นคือ การอ้างสิทธิ์เหล่านี้จะถูกส่งกลับมาเฉพาะเมื่อค่าของมันไม่ว่างเปล่า ในขณะที่การอ้างสิทธิ์ข้างต้นจะส่งกลับ null
หากค่าเป็นค่าว่าง
ต่างจากการอ้างสิทธิ์มาตรฐาน การอ้างสิทธิ์ created_at
และ updated_at
ใช้หน่วยเป็นมิลลิวินาทีแทนที่จะเป็นวินาที
email
ชื่อการอ้างสิทธิ์ | ประเภท | คำอธิบาย | ต้องใช้ userinfo หรือไม่? |
---|---|---|---|
string | อีเมลของผู้ใช้ | ไม่ | |
email_verified | boolean | อีเมลได้รับการยืนยันแล้วหรือไม่ | ไม่ |
phone
ชื่อการอ้างสิทธิ์ | ประเภท | คำอธิบาย | ต้องใช้ userinfo หรือไม่? |
---|---|---|---|
phone_number | string | หมายเลขโทรศัพท์ของผู้ใช้ | ไม่ |
phone_number_verified | boolean | หมายเลขโทรศัพท์ได้รับการยืนยันแล้วหรือไม่ | ไม่ |
address
โปรดดูรายละเอียดของการอ้างสิทธิ์ที่อยู่ได้ที่ OpenID Connect Core 1.0
custom_data
ชื่อการอ้างสิทธิ์ | ประเภท | คำอธิบาย | ต้องใช้ userinfo หรือไม่? |
---|---|---|---|
custom_data | object | ข้อมูลกำหนดเองของผู้ใช้ | ใช่ |
identities
ชื่อการอ้างสิทธิ์ | ประเภท | คำอธิบาย | ต้องใช้ userinfo หรือไม่? |
---|---|---|---|
identities | object | ข้อมูลตัวตนที่เชื่อมโยงของผู้ใช้ | ใช่ |
sso_identities | array | ข้อมูล SSO ที่เชื่อมโยงของผู้ใช้ | ใช่ |
roles
ชื่อการอ้างสิทธิ์ | ประเภท | คำอธิบาย | ต้องใช้ userinfo หรือไม่? |
---|---|---|---|
roles | string[] | บทบาทของผู้ใช้ | ไม่ |
urn:logto:scope:organizations
ชื่อการอ้างสิทธิ์ | ประเภท | คำอธิบาย | ต้องใช้ userinfo หรือไม่? |
---|---|---|---|
organizations | string[] | รหัสองค์กรที่ผู้ใช้สังกัด | ไม่ |
organization_data | object[] | ข้อมูลขององค์กรที่ผู้ใช้สังกัด | ใช่ |
urn:logto:scope:organization_roles
ชื่อการอ้างสิทธิ์ | ประเภท | คำอธิบาย | ต้องใช้ userinfo หรือไม่? |
---|---|---|---|
organization_roles | string[] | บทบาทของผู้ใช้ในแต่ละองค์กรในรูปแบบ <organization_id>:<role_name> | ไม่ |
เพื่อประสิทธิภาพและขนาดข้อมูล หาก "ต้องใช้ userinfo หรือไม่?" เป็น "ใช่" หมายความว่าการอ้างสิทธิ์นั้นจะไม่ปรากฏในโทเค็น ID แต่จะถูกส่งกลับใน response ของ userinfo endpoint
ทรัพยากร API
เราแนะนำให้อ่าน 🔐 การควบคุมการเข้าถึงตามบทบาท (RBAC) ก่อน เพื่อทำความเข้าใจแนวคิดพื้นฐานของ RBAC ใน Logto และวิธีตั้งค่าทรัพยากร API อย่างถูกต้อง
กำหนดค่าไคลเอนต์ Logto
เมื่อคุณตั้งค่า ทรัพยากร API (API resources) เรียบร้อยแล้ว คุณสามารถเพิ่มทรัพยากรเหล่านี้ขณะกำหนดค่า Logto ในแอปของคุณได้:
let config = try? LogtoConfig(
endpoint: "<your-logto-endpoint>", // เช่น http://localhost:3001
appId: "<your-app-id>",
resources: ["https://shopping.your-app.com/api", "https://store.your-app.com/api"], // เพิ่มทรัพยากร API (API resources)
)
let client = LogtoClient(useConfig: config)
แต่ละ ทรัพยากร API (API resource) จะมี สิทธิ์ (scopes) ของตัวเอง
ตัวอย่างเช่น ทรัพยากร https://shopping.your-app.com/api
มีสิทธิ์ shopping:read
และ shopping:write
และทรัพยากร https://store.your-app.com/api
มีสิทธิ์ store:read
และ store:write
หากต้องการร้องขอสิทธิ์เหล่านี้ คุณสามารถเพิ่มขณะกำหนดค่า Logto ในแอปของคุณได้:
let config = try? LogtoConfig(
endpoint: "<your-logto-endpoint>",
appId: "<your-app-id>",
// scopes: ขอบเขตการอนุญาตที่ต้องการ
scopes: ["shopping:read", "shopping:write", "store:read", "store:write"],
// resources: ทรัพยากร API ที่ต้องการเข้าถึง
resources: ["https://shopping.your-app.com/api", "https://store.your-app.com/api"],
)
let client = LogtoClient(useConfig: config)
คุณอาจสังเกตได้ว่า ขอบเขต (scopes) ถูกกำหนดแยกจาก ทรัพยากร API (API resources) นี่เป็นเพราะ Resource Indicators for OAuth 2.0 ระบุว่า ขอบเขตสุดท้ายสำหรับคำขอจะเป็นผลคูณคาร์ทีเซียนของขอบเขตทั้งหมดในบริการเป้าหมายทั้งหมด
ดังนั้น ในกรณีข้างต้น ขอบเขต (scopes) สามารถทำให้เรียบง่ายขึ้นจากการกำหนดใน Logto โดยทั้งสอง ทรัพยากร API (API resources) สามารถมีขอบเขต read
และ write
ได้โดยไม่ต้องมีคำนำหน้า จากนั้น ในการตั้งค่า Logto:
let config = try? LogtoConfig(
endpoint: "<your-logto-endpoint>",
appId: "<your-app-id>",
scopes: ["read", "write"], // ขอบเขตที่ร้องขอ
resources: ["https://shopping.your-app.com/api", "https://store.your-app.com/api"], // ทรัพยากร API ที่ร้องขอ
)
let client = LogtoClient(useConfig: config)
สำหรับแต่ละ ทรัพยากร API (API resource) จะร้องขอทั้งขอบเขต read
และ write
คุณสามารถร้องขอขอบเขต (scopes) ที่ไม่ได้กำหนดไว้ใน ทรัพยากร API (API resources) ได้ เช่น คุณสามารถร้องขอขอบเขต email
ได้ แม้ว่า ทรัพยากร API (API resources) จะไม่มีขอบเขต email
ให้ ขอบเขตที่ไม่มีจะถูกละเว้นอย่างปลอดภัย
หลังจากลงชื่อเข้าใช้สำเร็จ Logto จะออกขอบเขตที่เหมาะสมให้กับ ทรัพยากร API (API resources) ตามบทบาทของผู้ใช้
ดึงโทเค็นการเข้าถึง (Access token) สำหรับทรัพยากร API
เพื่อดึงโทเค็นการเข้าถึง (Access token) สำหรับทรัพยากร API เฉพาะ คุณสามารถใช้เมธอด getAccessToken
ได้ดังนี้:
let accessToken = try await client.getAccessToken(for: "https://shopping.your-app.com/api")
// ดึงโทเค็นการเข้าถึง (access token)
เมธอดนี้จะส่งคืนโทเค็นการเข้าถึง (JWT access token) ที่สามารถใช้เข้าถึงทรัพยากร API ได้เมื่อผู้ใช้มีสิทธิ์ที่เกี่ยวข้อง หากโทเค็นการเข้าถึงที่แคชไว้หมดอายุแล้ว เมธอดนี้จะพยายามใช้โทเค็นรีเฟรช (Refresh token) เพื่อขอโทเค็นการเข้าถึงใหม่โดยอัตโนมัติ
แนบโทเค็นการเข้าถึงกับ request headers
ให้นำโทเค็นใส่ในฟิลด์ Authorization
ของ HTTP headers ในรูปแบบ Bearer (Bearer YOUR_TOKEN
) ก็พร้อมใช้งาน
ขั้นตอนการเชื่อมต่อ Bearer Token อาจแตกต่างกันไปตาม framework หรือ requester ที่คุณใช้ เลือกวิธีที่เหมาะสมในการใส่ request header Authorization
await LogtoRequest.get(
useSession: session,
endpoint: userInfoEndpoint,
headers: ["Authorization": "Bearer \(accessToken)"]
)