👩🏻‍💻 Springframwork Mig 기록 : Spring Boot에서 Jasypt 자동 암복호화가 동작하는 원리

⟡ 개요

회사에서 담당하고 있는 서비스의 마이그레이션 작업을 높은 완성도로 마무리하기 위한 목적과,

퇴근 후 별도로 진행하는 학습 내용들을 스스로 정리하고 축적하기 위해 작성하는 기록입니다.
초보 개발자 관점에서 정리하는 흐름이지만, 기술적 오류나 더 나은 방향이 있다면

언제든지 피드백을 제안해 주시면 적극 반영하겠습니다.🫶

 

 

 

 

 

 

 

⟡ 설정 파일 암호화는 왜 필요한가 ? 

프로젝트를 진행하다 보면 application.yml에 DB 비밀번호나 API 키 같은 민감 정보를 작성하게 된다.

문제는 이 파일을 Git에 커밋하는 순간, 저장소에 접근할 수 있는 모든 사람이 운영 환경의 접속 정보를 볼 수 있다는 점이다.

Private 저장소라 해도 퇴사자, 협력사 직원, 내부 개발자 등 접근 권한을 가진 사람이 많으면 위험도는 올라간다.

 

실제로 자주 발생하는 시나리오는 이렇게 됨.
로컬에서 개발하던 개발자가 테스트를 위해 운영 DB 정보를 설정 파일에 잠깐 넣었다가, 그대로 커밋해버리는 경우임.
나중에 파일을 되돌리더라도 Git 히스토리에는 평문 비밀번호가 남아있음.
이런 실수 한 번으로 운영 DB가 외부에 노출될 수 있음.

 

Jasypt는 이런 문제를 완화하는 도구임.
설정 파일의 민감 정보를 암호화하여 ENC(암호화된값) 형태로 저장하고,
애플리케이션 실행 시점에만 복호화함. 복호화 키는 환경변수나 외부 설정으로 분리하므로,
설정 파일만 봐서는 실제 비밀번호를 알 수 없는 구조가 됨.

 

 

 

 

⟡ 어떤 정보를 암호화하는가

가장 흔하게 암호화하는 대상은 데이터베이스 접속 정보임.
spring.datasource.username과 spring.datasource.password를 암호화하면 Git에 커밋되어도 실제 값은 노출되지 않음.
외부 API 키도 주요 대상인데, 결제 게이트웨이 Secret Key나 AWS Access Key 같은 정보는 노출 시 금전적 피해로 직결되므로 반드시 암호화해야 함.

OAuth 연동 시 발급받는 Client Secret, 메일 서버 SMTP 비밀번호,
Redis나 Elasticsearch 접속 정보도 암호화 대상이 됨.
이들 정보가 탈취되면 서비스 사칭, 피싱 메일 발송, 캐시 데이터 유출 같은 2차 피해가 발생할 수 있음.

 

 

 

 

 

⟡ Jasypt는 어떻게 프로퍼티를 자동으로 복호화하는가?

의존성만 추가하면 ENC(...) 형태의 암호화된 프로퍼티가 자동으로 복호화된다.
Bean 생성 시점에 평문으로 주입되는 이 과정이 어떻게 가능한지, Spring Boot의 자동 구성 메커니즘 관점에서 정리한다.

 

 

이 시퀀스 다이어그램을 보면 전체적인 흐름을 알 수 있다.

시간 순서대로 컴포넌트 간의 상호작용을 보기 쉽게 정리했는데 이 다이어그램을 보면 Note로 구분된 5개 단계가 있다.

1~4단계가 초기화 과정이고 5단계가 복호화 동작 과정이다.

이 시퀀스 다이어그램을 보면 "누가 누구에게 무엇을 요청하고 반환받는가"를 볼 수 있어 전체적인 맥락 파악이 된다.

 

 

 

 

 

 

 

⟡ Spring Boot 자동 구성과 EnvironmentPostProcessor

1. jasypt-spring-boot-starter의 등록 방식

Spring Boot는 클래스패스의 spring.factories 또는

AutoConfiguration.imports 파일을 스캔하여 자동 구성 대상을 찾음.
jasypt-spring-boot-starter는 이 파일에

JasyptSpringBootAutoConfiguration을 명시해두었고, 애플리케이션 시작 시 자동으로 로드됨.

 

 

 

 

2. EnvironmentPostProcessor의 실행 시점

JasyptSpringBootAutoConfiguration은

EnableEncryptablePropertiesEnvironmentPostProcessor를 등록함.

이 클래스는 EnvironmentPostProcessor 인터페이스를 구현하는데,

이는 Spring의 Environment가 준비된 직후이자 Bean 생성이 시작되기 전에 실행되는 초기 후처리기임.

 

즉, application.yml의 프로퍼티를 읽은 직후, 하지만 @Value 주입이 일어나기 전 시점에 개입함.

 

 

 

 

⟡ 자동 복호화 동작 과정

1. PropertySource 래핑

EnableEncryptablePropertiesEnvironmentPostProcessor가 실행되면

Environment의 모든 PropertySource(application.yml,시스템 환경변수 등)를 순회하며

EncryptableMapPropertySourceWrapper 같은 래퍼로 포장함.

 

이 래퍼는 프로퍼티 요청을 가로채는 프록시 역할을 한다.

 

 

 

 

2. StringEncryptor Bean 생성

JasyptSpringBootAutoConfiguration이 jasyptStringEncryptor Bean을 생성함.

이때 jasypt.encryptor.password, jasypt.encryptor.algorithm 같은 설정값을 읽어옴.

프로퍼티 소스가 이미 래핑된 상태이므로 이 설정값들도 암호화되어 있다면 복호화하여 가져올 수 있음

(단, 암호화 키 자체는 보통 평문으로 관리함).

 

 

 

 

3. 프로퍼티 요청 시 즉시 복호화

Spring이 DataSource 같은 Bean을 생성하려고 ${spring.datasource.password} 값을 요청하면?

1. 요청이 래퍼(EncryptableMapPropertySourceWrapper)로 전달됨
2. 래퍼가 값이 ENC(...) 패턴인지 확인
3. 맞다면 StringEncryptor로 복호화하여 평문 반환
4. 아니라면 원본 값 그대로 반환

Spring은 이 과정을 모르고 평문을 받아 Bean을 생성한다.

 

 

 

 

 

 

 

 

 

 

⟡ 실제 적용 시 발생했던 문제

테스트 환경에서 DecryptionException이 발생한 적이 있었다.

원인은 jasypt.encryptor.password에 잘못된 키를 설정했기 때문이였는데

한참 원인을 제대로 파악하지 못해 헤맸다.

 

PropertySource 래핑 → StringEncryptor Bean 생성 → 프로퍼티 복호화 시도 순서로 진행되는데,
세 번째 단계에서 잘못된 키로 복호화를 시도하니 예외가 발생하고 애플리케이션 컨텍스트가 뜨지 못한 경우였다.

 

이처럼 Jasypt는 Spring의 Environment 후처리 메커니즘을 활용하여

기존 코드 수정 없이 프로퍼티 암/복호화를 투명하게 처리한다는 것을 다시 한번 또 이해했다.

 

 

 

 

⟡ 실무 적용 시 주의점

• jasypt.encryptor.password는 환경변수나 외부 설정으로 분리하고, 절대 코드에 하드코딩하지 말 것
• 복호화 실패 시 Bean 생성 자체가 안 되므로, 로컬 환경에서 암호화 키 설정 확인 필수
• ENC(...) 패턴이 아닌 프로퍼티는 복호화를 시도하지 않으니, 민감하지 않은 값은 평문으로 두는 것이 디버깅에 유리함

 

 

 

 

 

⟡ 초기화 과정 및 자동 복호화 동작 과정 플로우차트

이 글을 마무리하며 플로우 차트도 만들어 봤다.
이 플로우 차트는 글 초반에 있던 시퀀스 다이어그램과 동일하게 전체 과정을 담고 있다.
시작 노드부터 중간의 "PropertySource 래핑", "StringEncryptor Bean생성" 부분이 초기화 과정이다.
"Bean 생성 단계 시작" 이후 "ENC 패턴 확인 -> 복호화" 부분이 자동 복호화 동작 과정이다.

이 플로우차트는 "어떤 단계들이 순서대로 진행되는가"를 보여주는 것 이다.
전체적인 흐름 파악에 도움이 되길 바란다!

 

 

 

 

⟡ 참조

Jasypt Spring Boot Maven Repository(최신 버전 확인 및 의존성 추가 방법)

https://mvnrepository.com/artifact/com.github.ulisesbocchio/jasypt-spring-boot-starter

 

Spring Boot Auto-configuration 공식 가이드(자동 구성의 작동 원리, exclude 옵션 등 설명)

https://docs.spring.io/spring-boot/reference/using/auto-configuration.html

Auto-configuration :: Spring Boot

 

EnvironmentPostProcessor API 문서(인터페이스 명세, 등록 방법, 실행 시점)

https://docs.spring.io/spring-boot/api/java/org/springframework/boot/env/EnvironmentPostProcessor.html

EnvironmentPostProcessor (Spring Boot 4.0.1 API)

 

Spring Boot 공식 레퍼런스(Environment 커스터마이징 방법, EnvironmentPostProcessor 등록 설명)

https://docs.spring.io/spring-boot/docs/2.0.6.RELEASE/reference/html/howto-spring-boot-application.html

74. Spring Boot Application