เพิ่มการยืนยันตัวตนให้กับแอป Java Spring Boot ของคุณ (Add authentication to your Java Spring Boot application)
คู่มือนี้จะแสดงวิธีผสาน Logto เข้ากับแอป Java Spring Boot ของคุณ
- คุณสามารถดูตัวอย่างโค้ดสำหรับคู่มือนี้ได้ที่ spring-boot-sample ใน github ของเรา
- ไม่จำเป็นต้องใช้ SDK อย่างเป็นทางการในการผสาน Logto กับแอป Java Spring Boot ของคุณ เราจะใช้ไลบรารี Spring Security และ Spring Security OAuth2 เพื่อจัดการโฟลว์การยืนยันตัวตน OIDC กับ Logto
ข้อกำหนดเบื้องต้น
- มีบัญชี Logto Cloud หรือ Logto ที่โฮสต์เอง
- ตัวอย่างโค้ดของเราสร้างขึ้นโดยใช้ Spring Boot securing web starter ทำตามคำแนะนำเพื่อสร้างแอปเว็บใหม่หากคุณยังไม่มี
- ในคู่มือนี้ เราจะใช้ไลบรารี Spring Security และ Spring Security OAuth2 เพื่อจัดการโฟลว์การยืนยันตัวตน OIDC กับ Logto โปรดอ่านเอกสารอย่างเป็นทางการเพื่อเข้าใจแนวคิดต่าง ๆ
ตั้งค่าแอป Java Spring Boot ของคุณ
การเพิ่ม dependencies
สำหรับผู้ใช้ gradle ให้เพิ่ม dependencies ต่อไปนี้ในไฟล์ build.gradle
ของคุณ:
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.boot:spring-boot-starter-security'
implementation 'org.springframework.boot:spring-boot-starter-oauth2-client'
}
สำหรับผู้ใช้ maven ให้เพิ่ม dependencies ต่อไปนี้ในไฟล์ pom.xml
ของคุณ:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>
การตั้งค่า OAuth2 Client
ลงทะเบียนแอป Java Spring Boot
ใหม่ใน Logto Console และรับ client credential และการตั้งค่า IdP สำหรับแอปเว็บของคุณ
เพิ่มการตั้งค่าต่อไปนี้ในไฟล์ application.properties
ของคุณ:
spring.security.oauth2.client.registration.logto.client-name=logto
spring.security.oauth2.client.registration.logto.client-id={{YOUR_CLIENT_ID}}
spring.security.oauth2.client.registration.logto.client-secret={{YOUR_CLIENT_ID}}
spring.security.oauth2.client.registration.logto.redirect-uri={baseUrl}/login/oauth2/code/{registrationId}
spring.security.oauth2.client.registration.logto.authorization-grant-type=authorization_code
spring.security.oauth2.client.registration.logto.scope=openid,profile,offline_access
spring.security.oauth2.client.registration.logto.provider=logto
spring.security.oauth2.client.provider.logto.issuer-uri={{LOGTO_ENDPOINT}}/oidc
spring.security.oauth2.client.provider.logto.authorization-uri={{LOGTO_ENDPOINT}}/oidc/auth
spring.security.oauth2.client.provider.logto.jwk-set-uri={{LOGTO_ENDPOINT}}/oidc/jwks
การนำไปใช้
ก่อนที่เราจะลงลึกในรายละเอียด นี่คือภาพรวมประสบการณ์ของผู้ใช้ปลายทาง กระบวนการลงชื่อเข้าใช้สามารถสรุปได้ดังนี้:
- แอปของคุณเรียกใช้งานเมธอดลงชื่อเข้าใช้
- ผู้ใช้จะถูกเปลี่ยนเส้นทางไปยังหน้าลงชื่อเข้าใช้ของ Logto สำหรับแอปเนทีฟ ระบบจะเปิดเบราว์เซอร์ของระบบ
- ผู้ใช้ลงชื่อเข้าใช้และถูกเปลี่ยนเส้นทางกลับไปยังแอปของคุณ (ตามที่กำหนดไว้ใน redirect URI)
เกี่ยวกับการลงชื่อเข้าใช้แบบเปลี่ยนเส้นทาง (redirect-based sign-in)
- กระบวนการยืนยันตัวตนนี้เป็นไปตามโปรโตคอล OpenID Connect (OIDC) และ Logto บังคับใช้มาตรการรักษาความปลอดภัยอย่างเข้มงวดเพื่อปกป้องการลงชื่อเข้าใช้ของผู้ใช้
- หากคุณมีหลายแอป คุณสามารถใช้ผู้ให้บริการข้อมูลระบุตัวตน (Logto) เดียวกันได้ เมื่อผู้ใช้ลงชื่อเข้าใช้แอปหนึ่งแล้ว Logto จะดำเนินการลงชื่อเข้าใช้โดยอัตโนมัติเมื่อผู้ใช้เข้าถึงแอปอื่น
หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับเหตุผลและประโยชน์ของการลงชื่อเข้าใช้แบบเปลี่ยนเส้นทาง โปรดดูที่ อธิบายประสบการณ์การลงชื่อเข้าใช้ของ Logto
เพื่อเปลี่ยนเส้นทางผู้ใช้กลับมายังแอปของคุณหลังจากลงชื่อเข้าใช้ คุณต้องตั้งค่า redirect URI โดยใช้ property client.registration.logto.redirect-uri
ในขั้นตอนก่อนหน้า
กำหนดค่า Redirect URI
ไปที่หน้ารายละเอียดแอปพลิเคชันใน Logto Console เพิ่ม redirect URI http://localhost:3000/callback

เช่นเดียวกับการลงชื่อเข้าใช้ ผู้ใช้ควรถูกเปลี่ยนเส้นทางไปที่ Logto เพื่อออกจากเซสชันที่ใช้ร่วมกัน เมื่อเสร็จสิ้นแล้ว ควรเปลี่ยนเส้นทางผู้ใช้กลับไปยังเว็บไซต์ของคุณ ตัวอย่างเช่น เพิ่ม http://localhost:3000/
ในส่วน post sign-out redirect URI
จากนั้นคลิก "Save" เพื่อบันทึกการเปลี่ยนแปลง
สร้าง WebSecurityConfig
สร้างคลาสใหม่ชื่อ WebSecurityConfig
ในโปรเจกต์ของคุณ
คลาส WebSecurityConfig
จะใช้สำหรับกำหนดค่าความปลอดภัยของแอปของคุณ เป็นคลาสสำคัญที่จัดการโฟลว์การยืนยันตัวตนและการอนุญาต โปรดดู Spring Security documentation สำหรับรายละเอียดเพิ่มเติม
// โค้ดเหมือนเดิม
สร้าง bean idTokenDecoderFactory
จำเป็นต้องทำเพราะ Logto ใช้ ES384
เป็นอัลกอริทึมเริ่มต้น เราต้องเขียนทับ OidcIdTokenDecoderFactory
เริ่มต้นเพื่อใช้อัลกอริทึมเดียวกัน
// โค้ดเหมือนเดิม
สร้างคลาส LoginSuccessHandler เพื่อจัดการเหตุการณ์เข้าสู่ระบบสำเร็จ
เราจะเปลี่ยนเส้นทางผู้ใช้ไปยังหน้า /user
หลังจากเข้าสู่ระบบสำเร็จ
// โค้ดเหมือนเดิม
สร้างคลาส LogoutSuccessHandler เพื่อจัดการเหตุการณ์ออกจากระบบสำเร็จ
ล้าง session และเปลี่ยนเส้นทางผู้ใช้ไปยังหน้าแรก
// โค้ดเหมือนเดิม
อัปเดตคลาส WebSecurityConfig
ด้วย securityFilterChain
securityFilterChain คือชุดของฟิลเตอร์ที่รับผิดชอบในการประมวลผล request และ response ที่เข้ามา
เราจะกำหนดค่า securityFilterChain
เพื่ออนุญาตเข้าถึงหน้าแรก และต้องยืนยันตัวตนสำหรับ request อื่น ๆ ทั้งหมด ใช้ CustomSuccessHandler
และ CustomLogoutHandler
เพื่อจัดการเหตุการณ์เข้าสู่ระบบและออกจากระบบ
// โค้ดเหมือนเดิม
สร้างหน้าแรก
(คุณสามารถข้ามขั้นตอนนี้ได้หากมีหน้าแรกอยู่แล้วในโปรเจกต์ของคุณ)
// โค้ดเหมือนเดิม
คอนโทรลเลอร์นี้จะเปลี่ยนเส้นทางผู้ใช้ไปยังหน้าผู้ใช้หากผู้ใช้ได้รับการยืนยันตัวตนแล้ว มิฉะนั้นจะแสดงหน้าแรก เพิ่มลิงก์เข้าสู่ระบบในหน้าแรก
<body>
<h1>ยินดีต้อนรับ!</h1>
<p><a th:href="@{/oauth2/authorization/logto}">เข้าสู่ระบบด้วย Logto</a></p>
</body>
สร้างหน้าผู้ใช้
สร้างคอนโทรลเลอร์ใหม่เพื่อจัดการหน้าผู้ใช้:
// โค้ดเหมือนเดิม
เมื่อผู้ใช้ได้รับการยืนยันตัวตนแล้ว เราจะดึงข้อมูล OAuth2User
จาก principal ที่ได้รับการยืนยัน โปรดดู OAuth2AuthenticationToken และ OAuth2User สำหรับรายละเอียดเพิ่มเติม
อ่านข้อมูลผู้ใช้และส่งไปยังเทมเพลต user.html
<body>
<h1>รายละเอียดผู้ใช้</h1>
<div>
<p>
<div><strong>ชื่อ:</strong> <span th:text="${username}"></span></div>
<div><strong>อีเมล:</strong> <span th:text="${email}"></span></div>
<div><strong>รหัส:</strong> <span th:text="${sub}"></span></div>
</p>
</div>
<form th:action="@{/logout}" method="post">
<input type="submit" value="ออกจากระบบ" />
</form>
</body>
ขอข้อมูลการอ้างสิทธิ์เพิ่มเติม
คุณอาจพบว่าข้อมูลผู้ใช้บางอย่างหายไปในอ็อบเจกต์ที่ส่งคืนจาก principal (OAuth2AuthenticationToken)
สาเหตุเนื่องจาก 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
หากต้องการดึงข้อมูลผู้ใช้เพิ่มเติม คุณสามารถเพิ่ม scope เพิ่มเติมในไฟล์ application.properties
ตัวอย่างเช่น หากต้องการขอ scope email
, phone
และ urn:logto:scope:organizations
ให้เพิ่มบรรทัดต่อไปนี้ในไฟล์ application.properties
:
spring.security.oauth2.client.registration.logto.scope=openid,profile,offline_access,email,phone,urn:logto:scope:organizations
จากนั้นคุณสามารถเข้าถึงข้อมูลการอ้างสิทธิ์เพิ่มเติมในอ็อบเจกต์ OAuth2User
รันและทดสอบแอปพลิเคชัน
รันแอปพลิเคชันและไปที่ http://localhost:8080
- คุณจะเห็นหน้าแรกพร้อมลิงก์เข้าสู่ระบบ
- คลิกที่ลิงก์เพื่อเข้าสู่ระบบด้วย Logto
- หลังจากยืนยันตัวตนสำเร็จ คุณจะถูกเปลี่ยนเส้นทางไปยังหน้าผู้ใช้พร้อมรายละเอียดของคุณ
- คลิกปุ่มออกจากระบบเพื่อออกจากระบบ คุณจะถูกเปลี่ยนเส้นทางกลับไปยังหน้าแรก
ขอบเขต (Scopes) และ การอ้างสิทธิ์ (Claims)
Logto ใช้มาตรฐาน ขอบเขต (scopes) และ การอ้างสิทธิ์ (claims) ของ OIDC เพื่อกำหนดขอบเขตและการอ้างสิทธิ์สำหรับดึงข้อมูลผู้ใช้จากโทเค็น ID (ID token) และ OIDC userinfo endpoint ทั้ง "ขอบเขต (scope)" และ "การอ้างสิทธิ์ (claim)" เป็นคำศัพท์จากข้อกำหนดของ OAuth 2.0 และ OpenID Connect (OIDC)
โดยสรุป เมื่อคุณร้องขอขอบเขต (scope) ใด คุณจะได้รับการอ้างสิทธิ์ (claim) ที่เกี่ยวข้องในข้อมูลผู้ใช้ เช่น หากคุณร้องขอขอบเขต email
คุณจะได้รับข้อมูล email
และ email_verified
ของผู้ใช้
ต่อไปนี้คือรายการขอบเขต (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
เพิ่มขอบเขตและการอ้างสิทธิ์เพิ่มเติมในไฟล์ application.properties
เพื่อร้องขอข้อมูลผู้ใช้เพิ่มเติม ตัวอย่างเช่น หากต้องการร้องขอขอบเขต urn:logto:scope:organizations
ให้เพิ่มบรรทัดต่อไปนี้ในไฟล์ application.properties
:
spring.security.oauth2.client.registration.logto.scope=openid,profile,offline_access,urn:logto:scope:organizations
การอ้างสิทธิ์ขององค์กรผู้ใช้จะถูกรวมอยู่ในโทเค็นการอนุญาต (authorization token)