ข้ามไปยังเนื้อหาหลัก

เพิ่มการยืนยันตัวตนให้กับแอป 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 ของคุณ:

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 ของคุณ:

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 ของคุณ:

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

การนำไปใช้

ก่อนที่เราจะลงลึกในรายละเอียด นี่คือภาพรวมประสบการณ์ของผู้ใช้ปลายทาง กระบวนการลงชื่อเข้าใช้สามารถสรุปได้ดังนี้:

  1. แอปของคุณเรียกใช้งานเมธอดลงชื่อเข้าใช้
  2. ผู้ใช้จะถูกเปลี่ยนเส้นทางไปยังหน้าลงชื่อเข้าใช้ของ Logto สำหรับแอปเนทีฟ ระบบจะเปิดเบราว์เซอร์ของระบบ
  3. ผู้ใช้ลงชื่อเข้าใช้และถูกเปลี่ยนเส้นทางกลับไปยังแอปของคุณ (ตามที่กำหนดไว้ใน redirect URI)

เกี่ยวกับการลงชื่อเข้าใช้แบบเปลี่ยนเส้นทาง (redirect-based sign-in)

  1. กระบวนการยืนยันตัวตนนี้เป็นไปตามโปรโตคอล OpenID Connect (OIDC) และ Logto บังคับใช้มาตรการรักษาความปลอดภัยอย่างเข้มงวดเพื่อปกป้องการลงชื่อเข้าใช้ของผู้ใช้
  2. หากคุณมีหลายแอป คุณสามารถใช้ผู้ให้บริการข้อมูลระบุตัวตน (Logto) เดียวกันได้ เมื่อผู้ใช้ลงชื่อเข้าใช้แอปหนึ่งแล้ว Logto จะดำเนินการลงชื่อเข้าใช้โดยอัตโนมัติเมื่อผู้ใช้เข้าถึงแอปอื่น

หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับเหตุผลและประโยชน์ของการลงชื่อเข้าใช้แบบเปลี่ยนเส้นทาง โปรดดูที่ อธิบายประสบการณ์การลงชื่อเข้าใช้ของ Logto


เพื่อเปลี่ยนเส้นทางผู้ใช้กลับมายังแอปของคุณหลังจากลงชื่อเข้าใช้ คุณต้องตั้งค่า redirect URI โดยใช้ property client.registration.logto.redirect-uri ในขั้นตอนก่อนหน้า

กำหนดค่า Redirect URI

ไปที่หน้ารายละเอียดแอปพลิเคชันใน Logto Console เพิ่ม redirect URI http://localhost:3000/callback

Redirect URI in Logto Console

เช่นเดียวกับการลงชื่อเข้าใช้ ผู้ใช้ควรถูกเปลี่ยนเส้นทางไปที่ Logto เพื่อออกจากเซสชันที่ใช้ร่วมกัน เมื่อเสร็จสิ้นแล้ว ควรเปลี่ยนเส้นทางผู้ใช้กลับไปยังเว็บไซต์ของคุณ ตัวอย่างเช่น เพิ่ม http://localhost:3000/ ในส่วน post sign-out redirect URI

จากนั้นคลิก "Save" เพื่อบันทึกการเปลี่ยนแปลง

สร้าง WebSecurityConfig

สร้างคลาสใหม่ชื่อ WebSecurityConfig ในโปรเจกต์ของคุณ

คลาส WebSecurityConfig จะใช้สำหรับกำหนดค่าความปลอดภัยของแอปของคุณ เป็นคลาสสำคัญที่จัดการโฟลว์การยืนยันตัวตนและการอนุญาต โปรดดู Spring Security documentation สำหรับรายละเอียดเพิ่มเติม

WebSecurityConfig.java
// โค้ดเหมือนเดิม

สร้าง bean idTokenDecoderFactory

จำเป็นต้องทำเพราะ Logto ใช้ ES384 เป็นอัลกอริทึมเริ่มต้น เราต้องเขียนทับ OidcIdTokenDecoderFactory เริ่มต้นเพื่อใช้อัลกอริทึมเดียวกัน

WebSecurityConfig.java
// โค้ดเหมือนเดิม

สร้างคลาส LoginSuccessHandler เพื่อจัดการเหตุการณ์เข้าสู่ระบบสำเร็จ

เราจะเปลี่ยนเส้นทางผู้ใช้ไปยังหน้า /user หลังจากเข้าสู่ระบบสำเร็จ

CustomSuccessHandler.java
// โค้ดเหมือนเดิม

สร้างคลาส LogoutSuccessHandler เพื่อจัดการเหตุการณ์ออกจากระบบสำเร็จ

ล้าง session และเปลี่ยนเส้นทางผู้ใช้ไปยังหน้าแรก

CustomLogoutHandler.java
// โค้ดเหมือนเดิม

อัปเดตคลาส WebSecurityConfig ด้วย securityFilterChain

securityFilterChain คือชุดของฟิลเตอร์ที่รับผิดชอบในการประมวลผล request และ response ที่เข้ามา

เราจะกำหนดค่า securityFilterChain เพื่ออนุญาตเข้าถึงหน้าแรก และต้องยืนยันตัวตนสำหรับ request อื่น ๆ ทั้งหมด ใช้ CustomSuccessHandler และ CustomLogoutHandler เพื่อจัดการเหตุการณ์เข้าสู่ระบบและออกจากระบบ

WebSecurityConfig.java
// โค้ดเหมือนเดิม

สร้างหน้าแรก

(คุณสามารถข้ามขั้นตอนนี้ได้หากมีหน้าแรกอยู่แล้วในโปรเจกต์ของคุณ)

HomeController.java
// โค้ดเหมือนเดิม

คอนโทรลเลอร์นี้จะเปลี่ยนเส้นทางผู้ใช้ไปยังหน้าผู้ใช้หากผู้ใช้ได้รับการยืนยันตัวตนแล้ว มิฉะนั้นจะแสดงหน้าแรก เพิ่มลิงก์เข้าสู่ระบบในหน้าแรก

resources/templates/home.html
<body>
<h1>ยินดีต้อนรับ!</h1>

<p><a th:href="@{/oauth2/authorization/logto}">เข้าสู่ระบบด้วย Logto</a></p>
</body>

สร้างหน้าผู้ใช้

สร้างคอนโทรลเลอร์ใหม่เพื่อจัดการหน้าผู้ใช้:

UserController.java
// โค้ดเหมือนเดิม

เมื่อผู้ใช้ได้รับการยืนยันตัวตนแล้ว เราจะดึงข้อมูล OAuth2User จาก principal ที่ได้รับการยืนยัน โปรดดู OAuth2AuthenticationToken และ OAuth2User สำหรับรายละเอียดเพิ่มเติม

อ่านข้อมูลผู้ใช้และส่งไปยังเทมเพลต user.html

resources/templates/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:

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 หรือไม่?
substringตัวระบุที่ไม่ซ้ำของผู้ใช้ไม่

profile

ชื่อการอ้างสิทธิ์ประเภทคำอธิบายต้องใช้ userinfo หรือไม่?
namestringชื่อเต็มของผู้ใช้ไม่
usernamestringชื่อผู้ใช้ของผู้ใช้ไม่
picturestringURL ของรูปโปรไฟล์ของผู้ใช้ปลายทาง URL นี้ ต้อง อ้างอิงถึงไฟล์รูปภาพ (เช่น ไฟล์ PNG, JPEG หรือ GIF) ไม่ใช่หน้าเว็บที่มีรูปภาพ โปรดทราบว่า URL นี้ ควร อ้างอิงถึงรูปโปรไฟล์ของผู้ใช้ปลายทางที่เหมาะสมสำหรับการแสดงผลเมื่ออธิบายผู้ใช้ปลายทาง ไม่ใช่รูปภาพใด ๆ ที่ผู้ใช้ถ่ายเองไม่
created_atnumberเวลาที่สร้างผู้ใช้ปลายทาง เวลานี้แสดงเป็นจำนวนมิลลิวินาทีตั้งแต่ Unix epoch (1970-01-01T00:00:00Z)ไม่
updated_atnumberเวลาที่ข้อมูลของผู้ใช้ปลายทางถูกอัปเดตล่าสุด เวลานี้แสดงเป็นจำนวนมิลลิวินาทีตั้งแต่ 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 หรือไม่?
emailstringอีเมลของผู้ใช้ไม่
email_verifiedbooleanอีเมลได้รับการยืนยันแล้วหรือไม่ไม่

phone

ชื่อการอ้างสิทธิ์ประเภทคำอธิบายต้องใช้ userinfo หรือไม่?
phone_numberstringหมายเลขโทรศัพท์ของผู้ใช้ไม่
phone_number_verifiedbooleanหมายเลขโทรศัพท์ได้รับการยืนยันแล้วหรือไม่ไม่

address

โปรดดูรายละเอียดของการอ้างสิทธิ์ที่อยู่ได้ที่ OpenID Connect Core 1.0

custom_data

ชื่อการอ้างสิทธิ์ประเภทคำอธิบายต้องใช้ userinfo หรือไม่?
custom_dataobjectข้อมูลกำหนดเองของผู้ใช้ใช่

identities

ชื่อการอ้างสิทธิ์ประเภทคำอธิบายต้องใช้ userinfo หรือไม่?
identitiesobjectข้อมูลตัวตนที่เชื่อมโยงของผู้ใช้ใช่
sso_identitiesarrayข้อมูล SSO ที่เชื่อมโยงของผู้ใช้ใช่

roles

ชื่อการอ้างสิทธิ์ประเภทคำอธิบายต้องใช้ userinfo หรือไม่?
rolesstring[]บทบาทของผู้ใช้ไม่

urn:logto:scope:organizations

ชื่อการอ้างสิทธิ์ประเภทคำอธิบายต้องใช้ userinfo หรือไม่?
organizationsstring[]รหัสองค์กรที่ผู้ใช้สังกัดไม่
organization_dataobject[]ข้อมูลขององค์กรที่ผู้ใช้สังกัดใช่

urn:logto:scope:organization_roles

ชื่อการอ้างสิทธิ์ประเภทคำอธิบายต้องใช้ userinfo หรือไม่?
organization_rolesstring[]บทบาทของผู้ใช้ในแต่ละองค์กรในรูปแบบ <organization_id>:<role_name>ไม่

เพื่อประสิทธิภาพและขนาดข้อมูล หาก "ต้องใช้ userinfo หรือไม่?" เป็น "ใช่" หมายความว่าการอ้างสิทธิ์นั้นจะไม่ปรากฏในโทเค็น ID แต่จะถูกส่งกลับใน response ของ userinfo endpoint

เพิ่มขอบเขตและการอ้างสิทธิ์เพิ่มเติมในไฟล์ application.properties เพื่อร้องขอข้อมูลผู้ใช้เพิ่มเติม ตัวอย่างเช่น หากต้องการร้องขอขอบเขต urn:logto:scope:organizations ให้เพิ่มบรรทัดต่อไปนี้ในไฟล์ application.properties:

application.properties
spring.security.oauth2.client.registration.logto.scope=openid,profile,offline_access,urn:logto:scope:organizations

การอ้างสิทธิ์ขององค์กรผู้ใช้จะถูกรวมอยู่ในโทเค็นการอนุญาต (authorization token)

อ่านเพิ่มเติม

กระบวนการสำหรับผู้ใช้ปลายทาง: กระบวนการยืนยันตัวตน, กระบวนการบัญชี, และกระบวนการองค์กร ตั้งค่าตัวเชื่อมต่อ การอนุญาต (Authorization)