간편인증 건강검진 조회 데모

Spring Boot + Thymeleaf 기반으로 CODEF 건강검진 결과 조회와 간편인증 2-way 흐름을 재현한 공개 샘플 프로젝트입니다.

이 저장소는 학습과 데모를 위한 예제이며, 실제 운영 수준의 인증, 권한, 감사 로그, 비밀 관리, 세션 하드닝까지 포함하지는 않습니다.

포함 내용

• /health-check 입력 화면과 결과 화면
• CODEF OAuth 토큰 발급 및 캐싱
• 1차 조회 후 CF-03002 / continue2Way=true 기반 pending 처리
• 간편인증 방식별 polling 분기
• 카카오톡, PASS 인증수단 예시 설정

기술 스택

• Java 17
• Spring Boot 3.2
• Thymeleaf
• JUnit 5
• Lombok

시작하기

1. .env.example 또는 README의 변수 목록을 기준으로 CODEF 자격증명을 준비합니다.
2. 환경변수를 셸 또는 IDE 실행 설정에 주입합니다.
3. 아래 명령으로 실행합니다.

./gradlew bootRun

브라우저에서 http://localhost:8080/health-check를 엽니다.

테스트

./gradlew test

환경변수

필수 자격증명:

• CODEF_CLIENT_ID
• CODEF_CLIENT_SECRET
• CODEF_DEMO_CLIENT_ID
• CODEF_DEMO_CLIENT_SECRET
• CODEF_PUBLIC_KEY

주요 선택 설정:

• CODEF_API_BASE_URL 기본값 https://development.codef.io
• CODEF_PRODUCT_URL 기본값 /v1/kr/public/pp/nhis-health-checkup/result
• CODEF_SERVICE_TYPE 기본값 DEMO
• CODEF_OAUTH_BASE_URL 기본값 https://oauth.codef.io
• CODEF_TOKEN_PATH 기본값 /oauth/token
• CODEF_ORGANIZATION 기본값 0002
• CODEF_SIMPLE_AUTH 기본값 1
• CODEF_TYPE 기본값 1
• CODEF_INQUIRY_TYPE 기본값 0
• CODEF_LOGIN_TYPE 기본값 5
• CODEF_LOGIN_TYPE_LEVEL 기본값 1
• CODEF_TWO_WAY_TIMEOUT_SECONDS 기본값 90
• CODEF_POLL_INTERVAL_MS 기본값 3000
• CODEF_SIMPLE_AUTH_METHODS_KAKAO_LOGIN_TYPE_LEVEL 기본값 1
• CODEF_SIMPLE_AUTH_METHODS_PASS_LOGIN_TYPE_LEVEL 기본값 5

CODEF_SERVICE_TYPE=SANDBOX인 경우 CODEF_API_BASE_URL는 https://sandbox.codef.io 사용을 권장합니다. CODEF_PRODUCT_URL은 /nhis-health-check가 아니라 /v1/kr/public/pp/nhis-health-checkup/result 경로를 사용해야 합니다.

동작 흐름

1. /health-check에서 이름, 휴대폰번호, 생년월일, 조회연도, 인증수단을 입력합니다.
2. POST /health-check가 CODEF 1차 요청을 보냅니다.
3. 응답이 CF-03002 또는 continue2Way=true이면 pending 화면으로 전환합니다.
4. POST /health-check/status가 2차 요청을 보내 상태를 재확인합니다.
5. 최종 성공 응답이 CF-00000이면 결과 화면을 보여줍니다.
6. 실패 또는 시간 초과 시 오류 화면을 보여줍니다.

twoWayInfo는 추가인증 단계에서만 필요하며, 최종 성공 응답에는 포함되지 않을 수 있습니다.

공개 저장소 기준에서 의도적으로 빠진 것

• 실제 운영용 비밀값과 자격증명
• 인증/인가 체계
• 외부 사용자를 위한 REST API 분리
• 분산 환경용 상태 저장소
• 운영 보안 설정과 모니터링

개발 문서

• 클라이언트 개발자 문서
• 백엔드 개발자 문서
• CODEF 건강검진 참고 메모

보안 메모

• 저장소에는 동작 가능한 CODEF 자격증명이 포함되어 있지 않습니다.
• 민감값은 환경변수 또는 별도 비밀 저장소로 주입해야 합니다.
• 현재 구현은 데모 목적이므로 실서비스 적용 전 추가 보안 검토가 필요합니다.