ChamomileGuides 3.0.3 Help

로그인 모듈 사용 가이드

개요

캐모마일 로그인 서비스에서는 기본적으로 Spring Security를 통해 인증/인가를 처리한다.

  • 로그인 서비스를 개발하기 이전에 시큐리티 개발가이드를 통해 Spring Security의 인증/인가에 대한 개념을 이해했다는 전제하에 로그인 기능 개발에 대해 중점적으로 설명한다.

  • 캐모마일에서 가이드하는 로그인 서비스 개발은 Ajax를 통한 로그인 호출이며 성공/실패에 대한 에러 처리 및 다국어 처리를 위한 다양한 API를 제공하고 있다.

시큐리티 세션 인증 프로세스

Untitled

시큐리티 세션 인증 프로세스

Untitled

사용법

로그인 서비스 API

로그인 서비스에서는 인증 성공과 실패에 따른 후처리에 필요한 다양한 기능을 메서드로 제공한다.

로그인 서비스 API를 사용하기 위해서는 LoginService 빈이 등록되어 있어야 하며 DI를 통한 객체 주입이 선행 되어야 한다.

다음과 같은 기능을 제공한다.

메서드

설명

loginService.getLockCountLimit()

시스템에 설정된 락카운트 임계치 조회

loginService.checkLockCnt(userId)

유저의 현재 락카운트 조회

loginService.increaseLockCnt(userId)

유저 락카운트 증가

loginService.resetLockCnt(userId)

유저 락카운트 초기화

loginService.lockAccount(userId)

유저 계정 잠금

loginService.unLockAccount(userId)

유저 계정 잠금 해제

loginService.checkUser(userId)

계정의 유무 확인 (계정이 있으면 ‘1’ return, 없으면 ‘0’ return)

loginService.lockProcessAccount(userId, exception)

유저의 락카운트를 증가시키며 락카운트 임계치가 넘으면 계정을 잠금는 일괄 작업

AuthenticationSuccessHandler

앞서 등록했던 sampleLoginSuccessHandler Bean을 만든다.

AuthenticationSuccessHandler 상속 받아 구현한다.

상속 또는 별도의 @Configration을 설정하여 Bean 등록 후 사용 할 수 있다.

이 핸들러는 인증 성공시 onAuthenticatioinSuccess 메서드를 호출한다

인증에 성공시에 필요한 후처리 로직을 작성한다.

@Override public void onAuthenticationSuccess(HttpServletRequest request, HttpServletResponse response, Authentication authentication) throws IOException, ServletException { String userID = authentication.getName(); LOGGER.info("Account that succeeded authentication : {}", userID); //인증 성공 후처리 로직 개발 //락카운트 초기화 resetLockCount(userID); //writeSuccessResponse(response); //로그인 성공시 이전페이지 호출 resultRedirectStrategy(request, response); }

AuthenticationFailureHandler

앞서 등록했던 sampleLoginFailureHandler Bean을 만든다.

AuthenticationFailureHandler 상속받아 구현한다.

상속 또는 별도의 @Configration을 설정하여 Bean 등록 후 사용 할 수 있다.

이 핸들러는 인증 실패시 onAuthenticatioinFailure 메서드를 호출한다.

인증에 실패시에 필요한 후처리 로직을 작성한다.

@Override public void onAuthenticationFailure(HttpServletRequest request, HttpServletResponse response, AuthenticationException exception) throws IOException, ServletException { String userID = request.getParameter("username"); //인증에 실패한 계정의 락카운트를 증가시키며 //카운트 임계치를 넘으면 계정을 잠그는 일괄작업 processLockAccount(userID, exception); sendFailureResponse(response); LOGGER.info("Authentication failure message: {}: ", exception.getMessage()); LOGGER.info("Account that failed authentication: {}", userID); }

2단계 인증

개요

본 문서에서는 캐모마일에서 제공하는 2단계 인증 구현에 관한 가이드를 설명한다.

사용법

chamomile-security 모듈에서 세션 혹은 jwt 토큰을 발행하기 전 이메일, 문자 메시지 등 개발자가 직접 구현한 인증을 통과한 사용자를 체크하는 기능을 제공한다.

이를 통해 개발자는 2단계 인증 구현 시 기존 캐모마일의 세션 혹은 jwt 토큰 기반 로그인 기능을 수정 없이 custom한 전 단계 인증을 기능을 간단하게 구현할 수 있다.

또한 1차 인증하였을 때 ip와 최종 ip가 같은지 체크하며, 1차 인증 후 세션 만료 시간 동안만 로그인 할 수 있도록 기능을 제공한다.

사용방법은 다음과 같다.

<!-- 세션 기반 혹은 jwt 기반 로그인을 위한 모듈을 선택하여 추가한다. --> <!--기본 세션 기반 로그인을 할 떄 추가하는 chamomile-security--> <dependency> <groupId>net.lotte.chamomile.module</groupId> <artifactId>chamomile-security</artifactId> </dependency> <!--jwt 토큰 기반 로그인을 할 떄 추가하는 chamomile-security-jwt--> <dependency> <groupId>net.lotte.chamomile.module</groupId> <artifactId>chamomile-security-jwt</artifactId> </dependency>
// application.properties의 옵션을 수정한다. chmm.security.2fa.prelogin.check=true // 최종 인증전 1차 인증 체크 기능을 옵션에서 킨다. (기본값을 false)
// chamomile-security 모듈에 PreLoginService 서비스를 임포트 import net.lotte.chamomile.module.security.login.PreLoginService; @Slf4j @RestController @RequestMapping(path = "/chmm/user") @RequiredArgsConstructor public class UserController implements UserControllerDoc { // 1차 인증을 검증하는 PreLoginService 컴포넌트 private final PreLoginService preLoginService; // chamomile admin 샘플 코드에 존재하는 이메일 인증을 위한 코드 검증 서비스. private final VerificationService verificationService; // 이메일 인증 코드 발송 api @PostMapping("/send-verify-code") public ChamomileResponse<Void> sendVerifyCodeEmail(@RequestBody PasswordResetRequest request) { verificationService.isUserExist(request.getId(),request.getEmail()); verificationService.sendVerificationCodeEmail(request.getId(),request.getEmail(),request.getRequestTime()); return new ChamomileResponse<>(); } // 이메일 인증 검증 api @PostMapping("/check-verify-code") public ChamomileResponse<Void> verifyCode(@RequestBody VerifyCodeRequest request) { // admin sample 코드에 있는 이메일 인증 코드 체크 서비스 String userId = verificationService.checkVerifyCode(request.getEmail(), request.getVerifyCode(), LocalDateTime.now()); /* 1차 인증을 성공한 user id를 저장한다. user id와 ip를 저장하여 (ip는 내부 구현으로 파라미터로 전달하지 않아도 자동 저장됨) 기존 캐모마일 로그인 api로 로그인 시도시 아이디와 ip를 검증한후 로그인한다. */ preLoginService.preLoginSuccess(userId); return new ChamomileResponse<>(); }

위와 같이 이메일을 통한 1차 인증을 시도한 후

기존 캐모마일 로그인 api로 동일한 방식의 로그인을 시도하면 세션 및 토큰이 발행된다.

만일 chmm.security.2fa.prelogin.check=true인 상태에서

  • preLoginSuccess을 통해 등록하지 않은 id로 로그인 시도한 경우.

  • 1차 로그인시 아이피와 최종 로그인 시도시 아이피가 다른 경우.

  • 1차 로그인후 세션 만료 시간 만큼 지난 후 로그인을 시도한 경우.

아래와 같은 에러가 발생하며 로그인이 되지 않는다.

{ code:41003 message: "Attempted to log in without completing the previous authentication step!" data:"" }

제공하는 메서드 설명.

public class PreLoginService { /** * pre-login 성공 시 키(아이디)와 값(아이피)를 저장하는 메서드 * @param userId 사용자 아이디 */ public void preLoginSuccess(String userId); /** * pre-login을 체크하는 메서드 * * @param userId 사용자 아이디 */ public void checkPreLogin(String userId); /** * pre-login한 아이디의 아이피를 체크하는 메서드 (최종 로그인을 직접 구현하고 싶을떄 사용 가능하다) * * @param userId 사용자 아이디 * @throws ChamomileException 아이디를 찾지 못하거나 IP가 일치하지 않을 경우 예외 발생 (에외 코드 41003) PREVIOUS_AUTHENTICATION_REQUIRED(41003, "Attempted to log in without completing the previous authentication step!") */ public String getCachedIp(String userId); }
Last modified: 19 11월 2024