시큐리티(JWT) 모듈 사용 가이드

Last modified: 21 4월 2025

개요

본 문서에서는 웹사이트에서 사용하는 JWT(Java Web Token) 기반 시큐리티를 사용하기 위한 기능에 대해 설명한다.

인증(Authentication)과 인가(Authorization)에 대한 세부 내용은 세션 기반 캐모마일 시큐리티 문서를 참고한다.

캐모마일 jwt 모듈에서는 다중 로그인 방지 기능 또한 제공한다.

관련 주요 클래스

클래스/컴포넌트명

설명

ChamomileSecurityJwtConfiguration.java

JWT 기반 캐모마일 시큐리티 설정을 관리

AccessTokenFilter.java

최초 로그인 시 사용자 인증 및 토큰을 발급(access, refresh)하여 DB 또는 캐시에 저장

RefreshTokenFilter.java

RefreshToken을 통해 AccessToken과 RefreshToken을 재발급

JwtFilter.java

API 인증 시 토큰 유효성을 검사하며, 실제 사용자 인증은 프로바이더에게 위임

JwtProvider.java

사용자 정보와 토큰을 검증해 실제 인증 과정을 처리

JwtTokenUtils.java

Jwt토큰 생성,삭제, 유효성 등 JWT 관련된 전반적인 유틸

JwtAuthentication.java

AccessToken, RefreshToken, Validate 등의 과정을 담당

사용법

  1. chamomile-sample-boot-basic 프로젝트 생성

  2. dependency 등록(pom.xml)

    <dependency>
  <groupId>net.lotte.chamomile.module</groupId>
  <artifactId>chamomile-security-jwt</artifactId>
</dependency>

  3. yaml 파일 설정(application.yml)

    chmm:
  security:
  loginProcessingUrl: /security/jwt/authenticate  # AeccessToken,RefreshToken 발급
  refreshProcessingUrl: /security/jwt/refresh-token  # 토큰재발급
  defaultPasswordEncoder: sha256  # 패스워드 인코더
  passwordEncoderList: sha256,bcrypt
  rsaPassword:  # 패스워드 RSA 복호화
    use : true
    # true: RSA 복호화 사용
    # false : 일반 평문 사용(RSA 사용X)
    privateKey : sampleKey
  ignorePatterns:  ## Security 제외할 URI
    - /chmm/user/update-password
    - /swagger-ui/**
    - /api-docs/**
    - /swagger-resources/**
    - /v3/api-docs/**
    - /chmm/board/image/download/**
  jwt:
    secret: 0PtD9jRs2Q7Cgw38E8CNSBfxSf/ib/mAElN05fhAUU0FXsB3S8F3rfaaCSHy+NWQZkhDbs1SJm+cjdKQX4eHGA==
    access-expired-time: 18000000 #30분
    refresh-expired-time: 86400000 #24시간
    multiple-login-prevent: NONE # 다중 로그인 방지기능
    # NONE 사용 안함.
    # ONLY_FIRST 처음 로그인만 허용하고 같은 아이디로 로그인시 실패.
    # ONLY_LAST 나중에 같은 아이디로 로그인하면 이전 로그인 계정 로그아웃.

토큰 발급(로그인 요청)

Jwt1

AccessToken

목적

클라이언트가 API 요청 시 사용된다.

특징

  • 유효 기간이 짧다 (기본 30분).

  • application.yml에서 유효 기간 조정 가능.

  • 만료 후, RefreshToken을 사용해 재발급 가능하다.

RefreshToken

목적

AccessToken이 만료되었을 때 새로운 AccessToken, RefreshToken을 발급 받기 위해 사용된다.

특징

  • AccessToken보다 긴 유효 기간을 가진다 (기본 1일).

  • 재발급시 AccessToken, RefreshToken 함께 새로 발급 된다.

발급 절차

  1. 입력 받은 ID 와 Password를 전달 받아 비밀번호 및 사용자 정보 검증 후 AccessToken 과 함께 RefreshToken을 발급한다.

  2. /security/jwt/authenticate로 요청을 보내면 JSON {username: "admin", password: "test"}를 통해 AccessToken과 RefreshToken을 발급할 수 있다.

토큰 재발급

Jwt2

토큰 재발급

목적 AccessToken이 만료되었을 때 RefreshToekn을 새로운 AccessToken, RefreshToken을 발급받기 위해 사용된다.

특징 RefreshToken을 전달하여 신규 AccessToken, RefreshToken 발급

발급 절차:

  1. /security/jwt/refresh-token 통하여 위에AccessTokenFilter에서 생성한 RefreshToekn을 Request Hearder 에

  2. "Authorization": "Bearer YKDuD282j39s8..." 앞의 예시와 같이 Refresh 요청시 AccessToken과 RefreshToken 재발급이 가능하다.

API 인증

Jwt3

인증 매커니즘

기본적인 인증 매커니즘은 Spring Security의 인증 매커니즘을 그대로 사용하며, 아래와 같은 흐름으로 이루어진다.

  1. 인증 요청 전달받은 AccessToken을 JwtFilter을 통해 검증하고, 유효한 토큰인 경우 UsernamePasswordAuthenticationToken을 생성한다.

  2. AuthenticationManager 위임 AuthenticationManager에 AuthenticationToken을 전달하여 인증을 위임한다.

  3. Authentication 정보 획득 AuthenticationManager에 등록된 AuthenticationProvider를 통해 Authentication 정보를 획득한다.

  4. RDB를 통한 인증 정보 획득 RDB를 통해 사용자 아이디를 기반으로 Authentication 정보를 획득하고, 사용자가 가진 권한 및 사용자가 속한 그룹의 권한 정보를 획득한다.

  5. 사용자 상태 확인 및 인증 수행 사용자의 기본적인 상태(계정 잠김, 비활성화, 만료 등)를 확인하고, 정상적인 경우 패스워드를 검사하여 인증을 수행한다. 그 후, 비밀번호 상태(비밀번호 만료 등)를 확인한다.

  6. 인증 성공 후 처리 인증이 성공하면, 원래 요청한 페이지로 redirect 된다.

인증 절차

발급된 AccessToken으로 Request Hearder 에 예제) "Authorization": "Bearer YKDuD282j39s8" 로 API 호출시 인증이 가능하다.

CORS

CORS는 웹 페이지가 다른 도메인의 리소스에 접근할 수 있도록 허용하는 메커니즘 이다.

chmm:
	cors:
	    configurations:
	        - pattern: "/**" # 모든 경로에 대해 CORS 설정을 적용
	          allowed-origins: #  접근을 허용할 출처(origin)를 지정
	              - "http://localhost:8080" # 로컬호스트의 8080 포트에 대한 접근을 허용
	              - "http://localhost:23636" # 로컬호스트의 23636 포트에 대한 접근을 허용
	          allowed-methods: # 허용할 HTTP 메소드를 지정
	              - "GET"
	              - "POST"
	          allowed-headers: # 허용할 HTTP 헤더를 지정합니다.
	              - "Authorization" # Authorization 헤더를 허용합니다 (예: 토큰을 사용한 인증에 사용됩니다).
	              - "Content-Type" # Content-Type 헤더를 허용합니다 (예: 요청 본문의 미디어 타입을 지정합니다).
	          allow-credentials: false # 쿠키나 인증 관련 헤더를 사용하여 사용자 인증 정보를 포함시키지 않도록 합니다.
	          max-age: 3600 # 브라우저가 CORS 관련 설정을 캐시할 시간을 초 단위로 지정합니다 (여기서는 3600초, 즉 1시간입니다).